/ 目錄 / 演練場 / Azure AI Gateway
● 官方 Azure-Samples 🔑 需要你的金鑰

Azure AI Gateway

作者 Azure-Samples · Azure-Samples/AI-Gateway

Microsoft 的 APIM 為基礎的 AI 閘道模式——透過 Azure API Management 路由、計量並治理 LLM 流量(包含 MCP)。

Azure AI Gateway 是 Microsoft 提供的參考實作專案,示範如何將 Azure API Management(APIM)置於 LLM/MCP 端點前方,實現驗證、配額管理、快取、路由、日誌記錄與熔斷保護。此 MCP 暴露這些閘道操作,讓代理程式能夠進行設定與監控。

為什麼要用

核心特性

即時演示

實際使用效果

azure-ai-gateway.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "azure-ai-gateway",
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "azure-ai-gateway": {
      "command": {
        "path": "uvx",
        "args": [
          "azure-ai-gateway-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add azure-ai-gateway -- uvx azure-ai-gateway-mcp

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: Azure AI Gateway

跨 Azure OpenAI 部署強制執行每個團隊的 Token 配額

👤 負責治理 LLM 支出的中央平台團隊 ⏱ ~30 min advanced

何時使用: 多個產品團隊共用 AOAI 時,某個團隊的失控迴圈不應耗盡共用的 TPM 預算。

前置條件
  • 已套用 AI-Gateway 模式的 APIM 執行個體 — 從 Azure-Samples/AI-Gateway 專案部署參考架構
  • 每個團隊各自的 APIM 訂閱金鑰 — 每個團隊取得一組獨立的 APIM 訂閱(金鑰),並在 Ocp-Apim-Subscription-Key 標頭中帶入
步驟
  1. 檢視目前配額
    列出 AOAI 產品中各 APIM 訂閱目前的 TPM 和 RPM 配額。✓ 已複製
    → 各團隊配額表格
  2. 調降問題團隊的配額
    「growth」團隊每日 TPM 消耗量達 90%。請將其配額從 200k 降至 100k TPM,其他團隊保持不變。✓ 已複製
    → 配額已更新;確認訊息
  3. 變更後持續監控
    接下來一小時內,拉取每個訂閱的 429(速率限制)次數。確認 growth 已受到限流,但高優先級的正式環境團隊不受影響。✓ 已複製
    → 指標中可見限流效果

結果: 在不影響合法高優先級流量的前提下,有效控制共用 AOAI 支出。

注意事項
  • 配額設定過低會讓合法工作負載無法正常運作 — 先以影子模式(僅記錄日誌)上線,待了解實際使用模式後再正式執行限流

為 Azure OpenAI 部署設定多區域故障轉移

👤 負責維運正式 AI 工作負載的 SRE ⏱ ~45 min advanced

何時使用: 當某個區域的 AOAI 發生故障(雖不常見但確實存在)時,應能自動透明地切換至其他區域。

前置條件
  • 至少 2 個區域的 AOAI 部署(例如美國東部、西歐) — 透過 Azure 入口網站佈建;模型與版本需一致
步驟
  1. 檢視目前後端集區
    顯示我們 AOAI API 的 APIM 後端集區。包含後端數量、優先級與熔斷器設定。✓ 已複製
    → 目前集區設定
  2. 新增次要區域
    將西歐 AOAI 端點以 priority=2 加入,熔斷器設定為:1 分鐘內 5 次失敗即開路,持續 5 分鐘。保留美國東部為主要節點。✓ 已複製
    → 集區已更新,2 個後端設定完成
  3. 測試故障轉移
    停用美國東部後端 2 分鐘以模擬主要節點故障。確認流量切換至西歐後,再執行回滾。✓ 已複製
    → 觀察到流量切換;回滾已確認

結果: 在真正需要之前,事先驗證透明故障轉移能正常運作。

注意事項
  • 不同區域可能部署了不同版本的模型 — 鎖定兩個區域都存在的模型版本;版本不一致會在不知不覺中回傳品質不同的結果

部署語意快取以降低重複提示的費用

👤 重視成本控制的平台團隊 ⏱ ~30 min advanced

何時使用: 使用者反覆詢問相似問題,30–60% 的呼叫實際上都是可快取的重複請求。

步驟
  1. 啟用語意快取原則
    在 AOAI completions API 上啟用 APIM 語意快取查詢原則,相似度閾值設為 0.95,TTL 設為 1 小時。✓ 已複製
    → 原則已套用
  2. 觀察命中率
    24 小時後,從 App Insights 取得快取命中率與節省的 Token 數量。✓ 已複製
    → 命中率百分比 + 節省的 Token 數
  3. 調整閾值
    若命中率低於 20%,將閾值降至 0.92 後再次觀察。若出現品質抱怨,則調回 0.97。✓ 已複製
    → 以量測數據為依據進行迭代調整

結果: 在不降低輸出品質的前提下,對重複查詢達到可量測的成本節省。

注意事項
  • 過於激進的快取設定會對相似但不同的問題回傳錯誤答案 — 從高閾值(0.97)開始,僅在觀察到實際品質問題後才調低

組合

與其他 MCP 搭配,撬動十倍槓桿

azure-ai-gateway + sentry

將 APIM 5xx 異常飆升與應用程式端錯誤相互關聯

若 Sentry 顯示應用程式 X 在 10:02 出現 5xx 飆升,拉取同一時間窗口的 APIM 指標,判斷是否為閘道所導致。✓ 已複製
azure-ai-gateway + notion

將每週 AI 流量治理報告發布至 Notion

彙整本週各團隊的 TPM 使用量、429 次數與快取命中率,發布為一個 Notion 頁面。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
list_subscriptions product_id? 盤點使用閘道的各團隊 free (ARM API call)
update_quota subscription_id, tpm?, rpm? 調整某個團隊的 Token/請求數限制 free
get_backend_pool api_id 檢視路由與故障轉移設定 free
update_backend_pool api_id, backends, policies 變更優先級、熔斷器與負載平衡設定 free
apply_policy api_id, policy_xml 部署 APIM 原則(快取、驗證、日誌記錄) free
get_metrics api_id, since, until 觀察各 API 的流量狀況 free

成本與限制

運行它的成本

API 配額
Azure Resource Manager 速率限制(每個租用戶的限制相當充裕)
每次呼叫 Token 數
原則/後端集區讀取:500–2000 tokens
費用
APIM 定價從約 $40/月起(Basic 層級);正式環境建議使用 Standard 層級
提示
若您的流量具有重複性,語意快取通常能節省數倍於 APIM 本身的費用。請量測命中率以作為合理性依據。

安全

權限、密鑰、影響範圍

最小權限: APIM Contributor on the target APIM instance
憑證儲存: Azure 服務主體憑證(client id/secret/tenant)存放於環境變數中
資料出站: ARM API 呼叫至 management.azure.com;提示/回應內容會經過 APIM 本身傳輸
切勿授予: Owner on the subscription Global admin

故障排查

常見錯誤與修復

401 on ARM API calls

服務主體缺少資源群組上的 APIM Contributor 角色。請透過入口網站或 az cli 授予。

驗證: az role assignment list --assignee <sp>
Policy apply fails — XML validation error

APIM 原則 XML 格式要求嚴格;請使用入口網站的原則編輯器進行驗證後再複製貼上。

429s persist after raising TPM quota

瓶頸可能出在 AOAI 部署本身而非 APIM 訂閱。請檢查部署層級的 TPM,而非僅看 APIM 訂閱的 TPM。

Semantic cache hit rate is 0%

快取查詢所需的嵌入後端尚未設定;請檢查快取原則中的 embeddings 參考設定。

替代方案

Azure AI Gateway 對比其他方案

替代方案何時用它替代權衡
Cloudflare AI Gateway您使用 Cloudflare 平台,且希望直接取得開箱即用的多供應商 LLM 路由功能與 Azure 代管模型的整合深度較低
Portkey / LiteLLM您希望使用具備儀表板介面、不綁定特定供應商的閘道方案屬於第三方 SaaS 服務;資料會離開您自己的雲端環境

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills