適用於：AI Gateway 層級（預覽）
Important
AI Gateway 層級目前處於公開預覽階段。 在公開預覽期間，AI Gateway 層級可在以下地區提供：
- 美國 - 東美國2號公路
- 歐洲-瑞典中部
在這個快速入門中，你會建立一個 AI 閘道層（預覽）實例，新增聊天模型，呼叫閘道器，建立執行時存取金鑰，並查看遙測數據。
Azure API 管理 的 AI Gateway 層是專門用於 AI 工作負載的層級。 它支援管理來自 Microsoft Foundry、Azure OpenAI、AWS Bedrock、Google Vertex、OpenAI、Anthropic 或其他供應商的模型流量，以及由現有 MCP 伺服器、OpenAPI 定義或連接器所建立的工具。 AI 閘道層佈建的速度很快，通常在一分鐘內就會完成。
完成時間： 大約20到30分鐘。 你建立： 一個閘道器、一個聊天模型、一個執行時存取金鑰，以及一個成功的聊天完成請求。
Note
AI Gateway 層級目前處於公開預覽階段。 預覽功能在沒有服務層級協議的情況下提供，除非您的組織接受預覽條款，否則不應用於實際執行工作負載。
先決條件
- 具有 Microsoft Entra ID 的 Azure 帳戶。 目前僅限使用 Microsoft Entra ID 登入的 Azure 用戶才能使用 AI Gateway 層級預覽。
- Azure 訂用帳戶，以及在資源群組中建立資源的權限（例如，Contributor 角色）。
- 至少可存取一個支援的模型提供者，例如已部署於 Microsoft Foundry 或 Azure OpenAI 中的模型。
- 如果你的供應商需要 API 金鑰，請準備好金鑰。
- 要呼叫閘道器，請使用 curl（無需安裝）或 OpenAI SDK - Python 3.9 或更新版本，或 Node.js 18 或更新版本，搭配
openai套件使用。
1. 登入 AI Gateway 層級入口網站
AI Gateway 層級入口網站是獨立的網頁體驗——你不需要 Azure 入口網站。
- 請前往位於
ai.gateway.azure.com的 AI Gateway 層級入口網站。 - 選擇登入並使用 Microsoft Entra ID 進行驗證。
使用入口網站，根據您的 Entra ID 權限管理模型、MCP 伺服器、執行階段存取金鑰、原則及監控。 執行階段呼叫端不會登入入口網站，而是使用您稍後建立的執行階段存取金鑰來呼叫閘道。
2. 建立閘道
在入口網站中，選擇 建立閘道器。 若要改用現有閘道器，選擇該閘道器並跳到下一步。
輸入名稱。 名稱會成為執行時端點的一部分：
https://<gateway>.azure-api.net選擇您的 訂閱 及支援的預覽區域（East US 2 或 Sweden Central）。
可選擇將 資源群組 設為 進階。 根據預設，入口網站會幫您建立一個。
選取 ，創建。 啟動通常不到一分鐘。
閘道器是你 Azure 訂閱中的專用資源。 你不會在新增模型前先選擇容量或增加比例單位。 自動化方面，預覽管理 API 版本為2026-05-01-preview;執行時請求使用閘道主機名稱，而非 Azure Resource Manager。
3. 新增模型
建立模型最快的方式是從 Microsoft Foundry 帳號匯入。
在 「首頁>」設定你的閘道器時，選擇 「開始 」選項，或直接在路由處
/settings/start開啟設定頁面。
選擇一個或多個 訂閱 來掃描。 可選擇性地套用 資源群組 篩選器來縮小結果範圍。
檢視已發現的帳戶。 部署依其父 Foundry 帳號（Azure 資源）分組。 選取是以帳戶為單位：當你選取某個帳戶時，精靈會匯入該帳戶的所有模型部署。
為此匯入選擇後端 認證方法 ：
-
以金鑰為基礎（預設）。 閘道器會儲存帳號的 API 金鑰，並以
api-key標頭方式傳送。 精靈會在匯入時取回金鑰。 - 受控識別 (Microsoft Entra ID). 閘道器會以其受管理身份進行認證。 若閘道器沒有受管理身份，精靈會啟用系統指派的身份。 如果已經有可用的身分，你可以選擇要使用哪個身分。 精靈會在每個選取的帳戶上，授與該身分識別 Foundry 使用者角色。
-
以金鑰為基礎（預設）。 閘道器會儲存帳號的 API 金鑰，並以
選擇 匯入。
當你選取 匯入 時，精靈會在建立任何內容之前，針對每個選取的帳戶執行 驗證需求 檢查。 此檢查確認驗證設定正確，且型號名稱不會與閘道上現有的型號衝突。 會匯入通過的帳戶；會略過失敗的帳戶，並顯示內嵌警示，其餘的執行會繼續進行。
若要連接非 Foundry 供應商（AWS Bedrock、Google Vertex、OpenAI 或 Anthropic），請選擇「新增自訂模型」。 請參閱 「管理模型與工具」。
呼叫者會在 OpenAI 相容請求欄位中傳遞型號名稱 model 。 這個快速入門會使用gpt-5.6-sol；將其替換成您註冊的模型。
Tip
要立即試用模型，請打開 「探索 」頁面，選擇模型在內建遊樂場中調用。 遊樂場使用閘道內建的金鑰，讓你在建立執行時存取金鑰前，可以探索並測試新增的模型或工具。
4. 呼叫閘道
閘道器會暴露後端模型所支援的 API。 來自 OpenAI 相容供應商的模型——如 Microsoft Foundry、Azure OpenAI、AWS Bedrock、Google Vertex 和 OpenAI——會被提供在 OpenAI 相容端點上。 將任何 OpenAI 用戶端指向閘道基站 URL，發送 api-key 標頭，並在欄位 model 中傳遞模型名稱。 Anthropic 模型改用 Anthropic Messages API;請參見管理模型與工具。
為了快速測試，可以使用閘道內建 的金鑰 ——也就是 Discover 遊樂場使用的那把鑰匙。 從 Keys 頁面複製，該頁面列出內建 Key 與 API 金鑰，這些 API 金鑰可讓閘道器中每個資產在執行時存取。 對於你自己的應用程式，請建立一個執行時存取金鑰（見下一節）。
將這些值設定一次：
export AI_GATEWAY_BASE_URL="https://<gateway>.azure-api.net/default/models/openai/v1"
export AI_GATEWAY_API_KEY="<gateway-key>"
Tip
從你的閘道概覽頁面複製精確的基礎網址，而不是手動建置。
與您選擇的客戶進行首次通話：
curl "$AI_GATEWAY_BASE_URL/chat/completions" \
-H "Content-Type: application/json" \
-H "api-key: $AI_GATEWAY_API_KEY" \
-d '{
"model": "gpt-5.6-sol",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Give me three benefits of using an AI gateway." }
]
}'
若要將代幣串流為伺服器發送事件，請在請求主體中加入 "stream": true 。
來自 /chat/completions 端點的每個回應都使用 OpenAI Chat Completions 格式，無論該模型是由哪個與 OpenAI 相容的供應商提供支援。
非串流呼叫會傳回聊天完成結果：
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "gpt-5.6-sol",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "1. Centralized governance ...\n2. ...\n3. ..." },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}
啟用串流時，閘道會回傳 chat.completion.chunk 事件：
{
"id": "chatcmpl-...",
"object": "chat.completion.chunk",
"model": "gpt-5.6-sol",
"choices": [
{ "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
]
}
同一基礎網址同時也提供 OpenAI 回應 API 於 /responses。
若請求失敗，閘道器會回傳標準的 HTTP 狀態碼：
| 現況 | Meaning | 要檢查的事項 |
|---|---|---|
| 400 | 無效請求 | 請查看請求書。 |
| 400 | 被內容安全或 IP 過濾器封鎖，或被後端拒絕 | 內容安全政策可以阻擋提示或回應;也要檢查任何 IP 過濾政策。 針對受控識別，請在後端資源上將 Foundry 使用者角色指派給閘道身分識別。 請參見 「使用管理身份來進行後端認證」。 |
| 401 | 缺少或無效的執行時存取金鑰 | 把金鑰放到 api-key 標頭，確認金鑰是否有效。 |
| 404 | 未知型號 | 請確認 model 該價值是否與 模型 頁面上的型號名稱相符。 |
| 429 | 因速率限制原則或後端而遭到節流 | 檢視令牌與請求速率限制政策，並尊重 Retry-After 回應標頭。 |
| 5xx | 後端錯誤 | 確認後端提供者是否健康且提供者憑證有效。 |
OpenAI SDK 會對這些狀態碼設置類型例外，所以你現有的錯誤處理方式是有效的：
from openai import AuthenticationError, RateLimitError, APIStatusError
try:
response = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "Hello"}],
)
except AuthenticationError:
... # 401 — check the api-key header and that the key is active
except RateLimitError:
... # 429 — back off and honor the Retry-After header
except APIStatusError as e:
... # inspect e.status_code for 400, 403, 404, or 5xx
5. 建立執行時存取金鑰
應用程式以執行時存取金鑰（Runtime Access Key）而非內建金鑰來認證閘道器。 為每個應用程式和環境建立獨立的金鑰。
- 選取按鍵。
- 選取 [建立 API 金鑰]。
- 輸入一個名稱，例如
quickstart-client。 - 選取 ，創建。
- 複製鍵值並安全儲存。 你也可以稍後在 Keys 頁面再次查看。
在閘道層建立執行時存取金鑰。 這些金鑰可存取閘道器中的所有模型與工具。 把它們當成秘密來對待。 將金鑰儲存在應用程式的秘密儲存庫中，定期輪換，並撤銷不再需要的金鑰。 若要使用執行時存取金鑰呼叫閘道器，請將 AI_GATEWAY_API_KEY 此設定為先前所示呼叫中的值。
6. 參見遙測
AI Gateway 層級會發布 OpenTelemetry 代幣使用指標。 要查看這些資料，請先設定遙測目的地，然後發送請求：
- 為閘道設定遙測目的地，例如 Application Insights。 請參閱 治理、安全與運作。
- 如前述「 呼叫閘道」所示，透過閘道器發送一個或多個請求。
- 打開你的遙測目的地來檢視代幣使用情況。 如果你使用 Application Insights，入口網站會內建代幣使用儀表板。
因為遙測只有在你連接目的地後才會發射，所以在依賴它之前，先設定好監控。 目前唯一會發出的指標是代幣使用量;模型和工具的日誌、追蹤及其他指標即將推出。 呼叫者使用閘道層級的執行時存取金鑰，因此你可以監控流量，而不會暴露提供者憑證給客戶端應用程式。 要設定遙測目的地，請參見 Govern、Secure 和 operation。
清理資源
完成後，刪除不再需要的資源。 移除你僅為評估而建立的 AI 閘道層實例、提供者測試部署，以及執行時存取金鑰。