Azure AI 网关配置指南：使用 APIM 治理 AI 模型、MCP 工具与智能体

azure-aigateway by microsoft/azure-skills

76,500 周安装量

497 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/microsoft/azure-skills --skill azure-aigateway

🇨🇳中文介绍

Azure AI 网关

配置 Azure API 管理 (APIM) 作为 AI 网关，用于治理 AI 模型、MCP 工具和智能体。

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

何时使用此技能

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

快速参考

策略	目的

🇺🇸English

Azure AI Gateway

Configure Azure API Management (APIM) as an AI Gateway for governing AI models, MCP tools, and agents.

To deploy APIM , use the azure-prepare skill. See APIM deployment guide.

When to Use This Skill

Category	Triggers
Model Governance	"semantic caching", "token limits", "load balance AI", "track token usage"
Tool Governance	"rate limit MCP", "protect my tools", "configure my tool", "convert API to MCP"
Agent Governance	"content safety", "jailbreak detection", "filter harmful content"
Configuration	"add Azure OpenAI backend", "configure my model", "add AI Foundry model"
Testing	"test AI gateway", "call OpenAI through gateway"

Quick Reference

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

暂无相关 Skills

# 获取网关 URL
az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv

# 列出后端（AI 模型）
az apim backend list --service-name <apim-name> --resource-group <rg> \
  --query "[].{id:name, url:url}" -o table

# 获取订阅密钥
az apim subscription keys list \
  --service-name <apim-name> --resource-group <rg> --subscription-id <sub-id>

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}'

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

# 发现 AI 资源
az cognitiveservices account list --query "[?kind=='OpenAI']" -o table

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

# 授予访问权限（托管标识）
az role assignment create --assignee <apim-principal-id> \
  --role "Cognitive Services User" --scope <aoai-resource-id>

应用 AI 治理策略

<inbound> 中推荐的策略顺序：

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

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

问题	解决方案
令牌限制 429	增加 `tokens-per-minute` 或添加负载均衡
无缓存命中	将 `score-threshold` 降低至 0.7
内容误报	增加类别阈值 (5-6)
后端身份验证 401	授予 APIM "Cognitive Services User" 角色

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

内容安全 : Python | TypeScript
API 管理 : Python | .NET

Policy	Purpose	Details
`azure-openai-token-limit`	Cost control	Model Policies
`azure-openai-semantic-cache-lookup/store`	60-80% cost savings	Model Policies
`azure-openai-emit-token-metric`	Observability	Model Policies
`llm-content-safety`	Safety & compliance	Agent Policies
`rate-limit-by-key`	MCP/tool protection	Tool Policies

# 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>

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}'

See references/patterns.md for full steps.

# 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>

Apply AI Governance Policy

Recommended policy order in <inbound>:

Authentication - Managed identity to backend
Semantic Cache Lookup - Check cache before calling AI
Token Limits - Cost control
Content Safety - Filter harmful content
Backend Selection - Load balancing
Metrics - Token usage tracking

See references/policies.md for complete example.

Issue	Solution
Token limit 429	Increase `tokens-per-minute` or add load balancing
No cache hits	Lower `score-threshold` to 0.7
Content false positives	Increase category thresholds (5-6)
Backend auth 401	Grant APIM "Cognitive Services User" role

Detailed Policies - Full policy examples
Configuration Patterns - Step-by-step patterns
Troubleshooting - Common issues
AI-Gateway Samples
GenAI Gateway Docs

SDK Quick References

Content Safety : Python | TypeScript
API Management : Python | .NET

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

Azure AI 网关配置指南：使用 APIM 治理 AI 模型、MCP 工具与智能体

🇨🇳中文介绍

Azure AI 网关

何时使用此技能

快速参考

🇺🇸English

Azure AI Gateway

When to Use This Skill

Quick Reference

相关 Skills

获取网关详情

测试 AI 端点

常见任务

添加 AI 后端

应用 AI 治理策略

故障排除

参考

SDK 快速参考

Get Gateway Details

Test AI Endpoint

Common Tasks

Add AI Backend

Apply AI Governance Policy

Troubleshooting

References

SDK Quick References