/ 目录 / 演练场 / Azure AI Gateway
● 官方 Azure-Samples 🔑 需要你的密钥

Azure AI Gateway

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

微软基于 APIM 的 AI Gateway 模式 — 通过 Azure API Management 路由、计量和治理 LLM 流量(包括 MCP)。

Azure AI Gateway 是微软提供的参考实现库,展示如何将 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. 查看当前配额
    列出 APIM 订阅及其针对 AOAI 产品的当前 TPM 和 RPM 配额。✓ 已复制
    → 按团队的配额表
  2. 限制高流量团队
    团队'growth'每日 TPM 消耗量达 90%。将其配额从 200k → 100k TPM 降低。保持其他团队不变。✓ 已复制
    → 配额已更新;确认
  3. 更改后监控
    在接下来的一小时内,拉取每个订阅的 429(速率受限)计数。确认 growth 被限流但生产关键团队不受影响。✓ 已复制
    → 执行在指标中可见

结果: 控制共享 AOAI 支出,同时不影响合法的高优先级流量。

注意事项
  • 设置配额过低会让合法工作流量饥饿 — 先以影子模式(仅日志)推出,一旦了解真实模式后再执行

为 Azure OpenAI 部署配置多区域故障转移

👤 运行生产 AI 工作负载的 SRE ⏱ ~45 min advanced

何时使用: 区域 AOAI 中断(罕见但真实)应该透明地故障转移到另一区域。

前置条件
  • ≥2 个区域中的 AOAI 部署(例如 East US、West Europe) — 通过 Azure 门户配置;匹配模型 + 版本
步骤
  1. 检查当前后端池
    显示我们 AOAI API 的 APIM 后端池。有多少个后端,优先级和熔断器配置是什么?✓ 已复制
    → 当前池配置
  2. 添加辅助区域
    添加 West Europe AOAI 端点作为 priority=2,熔断器配置为:1 分钟内 5 次故障 → 打开 5 分钟。保持 East US 为主。✓ 已复制
    → 池已更新,配置了 2 个后端
  3. 测试故障转移
    通过禁用 East US 后端 2 分钟来模拟主区域中断。确认流量转移到 West Europe,然后回滚。✓ 已复制
    → 观察到流量转移;回滚已验证

结果: 透明故障转移,在需要前已验证其有效。

注意事项
  • 不同区域部署的模型版本不同 — 固定到两个区域都存在的模型版本;不匹配的版本会无声地返回不同的质量

部署语义缓存以降低重复提示成本

👤 成本意识强的平台团队 ⏱ ~30 min advanced

何时使用: 你的用户一遍遍地问类似的问题;30-60% 的调用实际上是缓存命中。

步骤
  1. 打开语义缓存策略
    在 AOAI completions API 上启用 APIM semantic-cache-lookup 策略,相似度阈值为 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 在 10:02 显示应用 X 中的 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 个 token
费用
APIM 定价从 ~$40/月(基础层)开始;生产环境推荐标准层
提示
如果你的流量重复,语义缓存通常会多倍抵消 APIM 的成本。通过测量命中率来证明其合理性。

安全

权限、密钥、影响范围

最小权限: 目标 APIM 实例上的 APIM Contributor
凭据存储: 环境中的 Azure 服务主体凭据(client id/secret/tenant)
数据出站: 对 management.azure.com 的 ARM API 调用;提示/响应正文遍历 APIM 本身
切勿授予: 订阅所有者 全局管理员

故障排查

常见错误与修复

ARM API 调用上的 401

服务主体缺少资源组上的 APIM Contributor 角色。通过门户或 az cli 授予。

验证: az role assignment list --assignee <sp>
策略应用失败 — XML 验证错误

APIM 策略 XML 很严格;使用门户的策略编辑器进行验证,然后复制粘贴。

提高 TPM 配额后 429 持续存在

底层 AOAI 部署本身可能是瓶颈。检查部署 TPM,而不仅仅是 APIM 订阅 TPM。

语义缓存命中率为 0%

缓存查询的嵌入后端未配置;检查缓存策略中的嵌入引用。

替代方案

Azure AI Gateway 对比其他方案

替代方案何时用它替代权衡
Cloudflare AI Gateway你在 Cloudflare 上并想要开箱即用的多提供商 LLM 路由与 Azure 托管模型的集成深度不足
Portkey / LiteLLM你想要一个提供商无关的网关和仪表板第三方 SaaS;数据离开你的云

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills