Microsoft Foundry 與 Azure OpenAI API 接入指南

適用範圍與呼叫前檢查

本指南從已獲授權的 Azure 訂閱、資源和模型部署開始，使用 OpenAI Python SDK 呼叫 Microsoft 的 v1 聊天介面。它不建立雲端資源，也不表示每個模型都支援相同功能。先在控制台記錄資源名稱、實際模型版本、部署名稱、部署類型、配額與網路存取方式；model 填部署名稱，不是從其他供應商目錄猜出的模型名稱。

確認該部署支援 Chat Completions 和範例中的 max_completion_tokens。Responses、工具呼叫、影像、推論參數與串流能力均要分別核對；模型不支援 Responses 時，不應只替換路徑反覆重試。Azure OpenAI 與 Foundry 的非 OpenAI 模型存在能力和授權差異，專案管理端點也不能直接作為模型推論端點。

核對端點與身分權限

v1 的 base_url 採用資源的 /openai/v1/ 路徑；官方也支援相應的 services.ai.azure.com 資源網域形式。複製你的資源控制台設定，不能把專案 URL、舊 /deployments/... 路徑和 v1 混用。v1 不要求日期式 api-version，這不代表舊版介面也可刪除版本參數。

處理位置取決於部署類型，Global、Data Zone 與區域部署不能只按資源名稱推斷。若有資料邊界要求，先核對部署方式及適用條件。由有權限的管理員授予推論身分權限：Azure OpenAI 模型可核對 Cognitive Services OpenAI User；Foundry 非 OpenAI 模型按相應文件核對 Cognitive Services User。訂閱 Owner 或 Contributor 不自動等於模型呼叫權限。也應確認服務端的代理、私有端點、DNS 和防火牆設定一致。

安裝並設定最小請求

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

以下均為占位值，先換成自己的資源和部署。AZURE_OPENAI_API_KEY 由授權的服務端執行環境安全注入；不要把金鑰寫進網頁、儲存庫或終端共用記錄。

export AZURE_OPENAI_BASE_URL='https://YOUR-RESOURCE.openai.azure.com/openai/v1/'
export AZURE_OPENAI_DEPLOYMENT='YOUR-DEPLOYMENT-NAME'

儲存下面程式為 azure_chat.py。只在確認允許模型費用後，用一般測試句執行 python azure_chat.py；128是此例的輸出限制，30秒為用戶端逾時範例，均不是平台配額或支援承諾。SDK自動重試暫設為0，便於先觀察原始失敗。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
request = {
    "model": os.environ["AZURE_OPENAI_DEPLOYMENT"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_completion_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

使用 Entra ID，避免長期靜態金鑰

服務端正式應用可採用受控識別或其他獲核准的 Entra 認證鏈。安裝相依套件後，用下列初始化替換前例的client，保留其餘請求邏輯。先完成角色指派，再驗證執行身分；不要印出存取權杖。當前官方 v1 範例的 scope 為 https://ai.azure.com/.default。

python -m pip install --upgrade azure-identity

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=token_provider,
    timeout=30.0,
    max_retries=0,
)

串流解析與錯誤處理

確認部署支援串流聊天後，用以下程式替換非串流呼叫。先檢查 choices 再取索引，按增量文字拼接；usage如有回傳則單獨讀取。部分部署需要支援的usage選項才能回傳用量，未收到usage不能當作零費用。Responses使用不同事件結構，不能套用這個解析器。

usage = None
with client.chat.completions.create(**request, stream=True) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        text = part.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
print()
print(usage.model_dump() if usage else "usage unavailable")

• 401/403：核對認證來源、資源範圍、角色及網路政策，不在日誌印出金鑰或權杖。
• 404：核對資源網域、v1路徑與部署名稱，避免呼叫管理端點。
• 400：檢查該模型的API、參數與內容限制；刪減可選參數定位原因。
• 429：核對配額和並行量，結合服務回傳的等待提示進行有限退避；逾時/5xx不無限重試。

驗收、費用與資料邊界

保留去識別化的請求編號、模型／部署版本、finish reason、耗時和用量，對照Azure帳單；確認截斷、拒答與連線中斷時的應用行為。輸出費用、快取、部署容量和第三方服務應按實際計費方式分別核對，不能套用其他渠道單價。資料保留、內容安全處理與Global部署的處理範圍須按實際服務條款審查，應用端也應控制日誌和存取權限。

本範例僅作離線語法檢查，沒有使用你的訂閱、讀取金鑰或真實呼叫模型；帳號可用性、品質和費用須由獲授權的環境實測。

Claude：先核對原生介面與採購資格

Claude 使用獨立的 Messages API。以 AnthropicFoundry 連接資源的 https://YOUR-RESOURCE.services.ai.azure.com/anthropic，HTTP Messages 目標路徑為 /anthropic/v1/messages。請求中的 model 必須是實際部署名稱，可以與目錄中的模型 ID 不同。前面的 OpenAI v1 範例僅適用於明確支援該 API 的部署。Foundry 專案管理 URL、OpenAI v1 路徑和 Claude 原生路徑各有用途；列入合作夥伴模型目錄並不代表模型都相容 OpenAI API。

設定用戶端前依序確認：

1. 訂閱為符合資格的 Azure 付費訂閱，帳單國家受支援，並具有購買 Marketplace 產品的權限。微軟目前的 Claude 文件明確排除 Cloud Solution Provider（CSP）訂閱，另有其他訂閱限制；擁有 Azure 帳戶本身不代表可以採購。
2. 從模型卡和部署詳細資料記錄模型、託管版本、部署類型與目前支援的部署區域。版本 1 執行於 Anthropic 基礎設施，版本 2 託管於 Azure。兩者均提供 Global Standard；僅部分 Azure 託管模型版本提供 Data Zone Standard（US）。必須核對精確的模型、版本、類型組合，不能按資源所屬國家推斷可用性。
3. 複製原生端點與部署名稱。使用 Entra 推論時，核對 Foundry 資源範圍的 Cognitive Services User 角色和實際執行身分。Azure OpenAI 專用角色或資源管理角色不能取代這項檢查；網路存取也要單獨確認。
4. 核對部署支援的驗證方式、Messages 參數、串流能力與配額。部分受限模型只接受 Entra ID。Files、Skills、工具等進階能力會隨託管和模型版本變化，不要直接沿用另一個 Claude 部署的參數。

Anthropic 託管的 v1 請求可能在 Azure 及所選 Azure 區域之外處理。Azure 託管的 v2 也要分別核對 Global 或 Data Zone 的處理範圍與靜態儲存位置。兩種設定下，Anthropic 都是銷售方、營運方，並作為提示詞與輸出的獨立資料處理方。應採用 Claude Marketplace 與資料處理條款；Azure OpenAI 的保留或 SLA 說明不會自動涵蓋 Claude。

Claude：獨立的 API Key 最小請求

對支援 API Key 的部署，在獲授權的伺服器端安裝相依套件並設定這些佔位項目。金鑰由安全的伺服器端環境提供，不要寫入瀏覽器程式碼或複製範例。將下列 Python 另存為獨立 Claude 範例。本次僅做離線檢查，沒有執行套件安裝或雲端請求。輸出上限與逾時是範例控制值，SDK 自動重試已關閉。

下列 API Key 與 Entra 範例都明確設定 base_url。SDK 仍會自動讀取 ANTHROPIC_FOUNDRY_RESOURCE，因此設定用戶端前應取消該環境變數。另一種選擇是以 resource 初始化，不傳入 base_url，同時取消 SDK 會自動讀取的 ANTHROPIC_FOUNDRY_BASE_URL 設定。

python -m pip install --upgrade anthropic azure-identity
# Explicit base_url must not be combined with the SDK resource-name fallback.
unset ANTHROPIC_FOUNDRY_RESOURCE
# Copy both values from your actual Foundry deployment in the console.
export FOUNDRY_CLAUDE_BASE_URL='https://YOUR-RESOURCE.services.ai.azure.com/anthropic'
export FOUNDRY_CLAUDE_DEPLOYMENT='YOUR-CLAUDE-DEPLOYMENT-NAME'
# Supply FOUNDRY_CLAUDE_API_KEY through the approved server secret environment.

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    api_key=os.environ["FOUNDRY_CLAUDE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
message = client.messages.create(
    model=os.environ["FOUNDRY_CLAUDE_DEPLOYMENT"],
    max_tokens=128,
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)
print(message.stop_reason)
print(message.usage.model_dump())

回應傳回具類型的 content 內容區塊，只輸出文字區塊，並檢查 stop_reason 和 usage 後再驗收。原生 HTTP 使用 x-api-key 和 anthropic-version: 2023-06-01，回應不是 OpenAI 的 choices 結構。先確認部署支援的組合，再加入 thinking 或工具參數。

Claude：以 Entra ID 取代金鑰

保留前例的 import os、AnthropicFoundry 和 Messages 請求，只以下列程式碼取代用戶端初始化。採用獲核准的認證鏈，優先使用應用程式的受控識別，並先核對資源角色。azure_ad_token_provider 取得 scope 為 https://ai.azure.com/.default 的權杖，原生 HTTP 對應 Authorization: Bearer ...。每次僅設定一種驗證方式；使用此 provider 時，移除明確設定的 API Key 及 SDK 會自動讀取的 ANTHROPIC_FOUNDRY_API_KEY 設定，不要印出權杖。

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    azure_ad_token_provider=token_provider,
    timeout=30.0,
    max_retries=0,
)

Claude：串流、故障與驗收

支援串流的部署可在 Messages 中設定 stream=True，接收 SSE。原生事件流程為 message_start，按索引傳輸的 content_block_start / content_block_delta / content_block_stop，再到 message_delta 和 message_stop。文字增量的 delta.type == "text_delta"；工具與 thinking 使用其他內容區塊類型。分別處理 ping、未知事件和錯誤，保留最終用量與停止資訊，完成前中斷的串流應標為不完整。OpenAI 的 choices[].delta 或 Responses 事件剖析器不能用於此協定。HTTP 狀態成功並不保證串流會完整結束。

Claude 的 401/403 應核對所選驗證方式、權杖 scope 和資源角色；404 應核對 /anthropic 與正確部署名稱。400 可能來自不支援的參數或特定模型的資料保留要求，後者應按適用條款複核。採購或區域錯誤應檢查訂閱資格與模型版本可用性。遇到 429，應檢查訂閱、模型、版本對應的配額並限制重試；換區域建立資源仍可能共用同一個 Global 配額池。依實際 Marketplace Claude Consumption Unit（CCU）計量、輸入輸出與快取用量核對帳單，不要沿用前面 OpenAI 部署的價格。在獲授權環境中分別測試無敏感內容的正常輸出、截斷和串流中斷，再驗收整合。

官方依據

核驗日期：2026-10-17。使用前複核當前文件與控制台。

• Microsoft v1 API與版本
• Foundry模型端點與部署名稱
• Entra身分與角色
• 部署類型與處理範圍
• Claude 部署、原生端點與驗證
• Claude 託管版本、採購與處理邊界
• Claude 模型能力與部署類型
• Claude 配額與速率限制
• Claude 資料處理
• Claude Consumption Unit 計費
• Anthropic 原生 Messages 串流事件
• AnthropicFoundry SDK 用戶端選項