azure-aigateway

Azure AI 网关

将 Azure API Management（APIM）配置为 AI 网关，用于治理 AI 模型、MCP 工具和 Agent。

要部署 APIM，请使用 azure-prepare 技能。请参阅 APIM 部署指南。

何时使用此技能

类别	触发条件
模型治理	“语义缓存”、“令牌限制”、“AI 负载均衡”、“跟踪令牌使用量”
工具治理	“限制 MCP 速率”、“保护我的工具”、“配置我的工具”、“将 API 转换为 MCP”
Agent 治理	“内容安全”、“越狱检测”、“过滤有害内容”
配置	“添加 Azure OpenAI 后端”、“配置我的模型”、“添加 AI Foundry 模型”
测试	“测试 AI 网关”、“通过网关调用 OpenAI”

---

快速参考

策略	用途	详情
azure-openai-token-limit	成本控制	模型策略
azure-openai-semantic-cache-lookup/store	节省 60-80% 的成本	模型策略
azure-openai-emit-token-metric	可观测性	模型策略
llm-content-safety	安全与合规	Agent 策略
rate-limit-by-key	MCP/工具保护	工具策略

---

获取网关详情

# Get gateway URL
az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv

# List backends (AI models)
az apim backend list --service-name <apim-name> --resource-group <rg> \
  --query "[].{id:name, url:url}" -o table

# Get subscription key
az apim subscription keys list \
  --service-name <apim-name> --resource-group <rg> --subscription-id <sub-id>

---

测试 AI 终结点

GATEWAY_URL=$(az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv)

curl -X POST "${GATEWAY_URL}/openai/deployments/<deployment>/chat/completions?api-version=2024-02-01" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <key>" \
  -d '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'

---

常见任务

添加 AI 后端

完整步骤请参阅 references/patterns.md。

# Discover AI resources
az cognitiveservices account list --query "[?kind=='OpenAI']" -o table

# Create backend
az apim backend create --service-name <apim> --resource-group <rg> \
  --backend-id openai-backend --protocol http --url "https://<aoai>.openai.azure.com/openai"

# Grant access (managed identity)
az role assignment create --assignee <apim-principal-id> \
  --role "Cognitive Services User" --scope <aoai-resource-id>

应用 AI 治理策略

<inbound> 中建议的策略顺序：

1. 身份验证 - 使用托管标识访问后端
2. 语义缓存查找 - 调用 AI 前检查缓存
3. 令牌限制 - 成本控制
4. 内容安全 - 过滤有害内容
5. 后端选择 - 负载均衡
6. 指标 - 跟踪令牌使用量

完整示例请参阅 references/policies.md。

---

故障排除

问题	解决方案
令牌限制导致 429	增大 tokens-per-minute 或添加负载均衡
没有缓存命中	将 score-threshold 降至 0.7
内容误报	提高类别阈值（5-6）
后端身份验证 401	为 APIM 授予“Cognitive Services User”角色

详情请参阅 references/troubleshooting.md。

---

参考资料

• 详细策略 - 完整的策略示例
• 配置模式 - 分步模式
• 故障排除 - 常见问题
• AI-Gateway 示例
• GenAI 网关文档

SDK 快速参考

• 内容安全：Python | TypeScript
• API Management：Python | .NET