Azure网关CLI专业版

付费版专享能力

核心能力

多端点路由与负载均衡

• 支持配置多个Azure端点，按权重分配流量
• 基于响应延迟的动态权重调整，优先选择更快的端点
• 支持按模型维度路由，不同模型指向不同部署

输入: 用户提供多端点路由与负载均衡所需的指令和必要参数. 处理: 解析多端点路由与负载均衡的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回多端点路由与负载均衡的处理结果,包含执行状态码、结果数据和执行日志。### 故障切换与熔断

• 端点异常时自动切换到备用端点，切换时间小于1秒
• 熔断器机制：连续失败达阈值后暂停该端点，定时探测恢复
• 故障事件记录，便于事后复盘

输入: 用户提供故障切换与熔断所需的指令和必要参数. 处理: 解析故障切换与熔断的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回故障切换与熔断的处理结果,包含执行状态码、结果数据和执行日志。### 请求缓存与成本治理

• 相同请求内容的响应缓存，可配置TTL与缓存大小
• 缓存命中率统计，量化节省的调用量
• 按租户、模型、时间维度的成本统计报表
• 预算告警：消耗达阈值时通知或限流

多租户与Key管理

• 多租户配置隔离，每个租户独立Key与配额
• API Key轮换：支持双Key平滑切换，避免单Key失效导致中断
• Key健康度检查：定期探测Key有效性，异常时告警

输入: 用户提供多租户与Key管理所需的指令和必要参数. 输出: 返回多租户与Key管理的处理结果,包含执行状态码、结果数据和执行日志。### 服务化部署

• 内置systemd服务模板，一键注册为系统服务
• 开机自启与崩溃自动重启
• 优雅关闭：收到终止信号时等待进行中请求完成

处理: 解析服务化部署的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回服务化部署的处理结果,包含执行状态码、结果数据和执行日志.

适用场景

场景一：团队共享Azure额度与成本核算

团队多人共用企业Azure订阅，需按项目或成员核算各自用量。专业版的多租户配置让每个成员使用独立Key与配额，月度报表清晰展示各方成本.

场景二：高可用生产代理

生产环境要求99.9%可用性，单端点故障不可接受。配置主备两个Azure端点，故障时自动切换，熔断器保护避免雪崩.

场景三：成本敏感型批量调用

批量处理任务中存在大量重复请求（如相同提示词的温度采样）。启用请求缓存后，相同内容的请求直接返回缓存结果，成本降低40%以上.

场景四：多模型统一网关

团队同时使用GPT-4o、GPT-4o-mini、o3等多个部署，通过专业版的模型路由能力，客户端只需指向单一网关端口，网关按模型名自动分发到对应部署.

使用流程

预计上手时间：约120秒.

优秀步：编写多端点配置

创建config.yaml：

endpoints:
  - name: primary
    host: your-resource-primary.openai.azure.com
    deployment: gpt-4o
    apiVersion: "2025-01-01-preview"
    weight: 70
  - name: backup
    host: your-resource-backup.openai.azure.com
    deployment: gpt-4o
    apiVersion: "2025-01-01-preview"
    weight: 30
# ...
cache:
  enabled: true
  ttlMs: 600000
  maxSize: 1000
# ...
circuitBreaker:
  failureThreshold: 5
  cooldownMs: 30000
# ...
tenants:
  - id: team-a
    apiKey: ${TEAM_A_AZURE_KEY}
    budgetMonthly: 500
  - id: team-b
    apiKey: ${TEAM_B_AZURE_KEY}
    budgetMonthly: 300

第二步：启动网关

node （请参考skill目录中的脚本文件） --config config.yaml

第三步：注册为系统服务（可选）

mkdir -p ~/.config/systemd/user
cp （请参考skill目录中的脚本文件） ~/.config/systemd/user/
nano ~/.config/systemd/user/azure-gateway.service
# ...
systemctl --user daemon-reload
systemctl --user enable azure-gateway
systemctl --user start azure-gateway

第四步：验证多端点与缓存

# 健康检查
curl http://localhost:18790/health
# ...
# 查看端点状态
curl http://localhost:18790/endpoints
# ...
# 查看缓存统计
curl http://localhost:18790/cache/stats
# ...
# 查看租户成本
curl http://localhost:18790/tenants/team-a/cost

输入格式

输出格式

{
  "success": true,
  "data": {
    "overall_grade": "A",
    "total_score": 92,
    "max_score": 100,
    "summary": "处理完成",
    "details": [
      {
        "item": "代码风格",
        "status": "pass",
        "score": 95,
        "comment": "符合规范"
      },
      {
        "item": "安全合规",
        "status": "warn",
        "score": 80,
        "comment": "符合规范"
      }
    ],
    "improvements": [
      {
        "priority": "high",
        "suggestion": "建议优化",
        "expected_gain": "+5分"
      },
      {
        "priority": "medium",
        "suggestion": "建议优化",
        "expected_gain": "+3分"
      }
    ]
  },
  "error": null
}

异常处理

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Node.js: 18+（推荐LTS版本）
• 网络: 需可访问所有配置的Azure OpenAI端点
• 可选: systemd（用于服务化部署）

依赖说明(补充)

API Key 配置

• Azure API Key: 通过环境变量AZURE_OPENAI_API_KEY或租户级环境变量注入
• 多租户Key: 通过tenants[].apiKey字段引用环境变量，不写入明文
• Key存储: 建议使用d:\skills\.skillhub-credentials\目录（已gitignore）
• 禁止: 在SKILL.md、配置文件或脚本中硬编码API Key

可用性分类

• 分类: MD+EXEC（）
• 说明: 基于Markdown的AI Skill，

案例展示

完整环境变量

租户级路由配置

{
  "tenants": {
    "team-a": {
      "endpoints": ["primary", "backup"],
      "rateLimit": "100/min",
      "budgetMonthly": 500
    },
    "team-b": {
      "endpoints": ["backup"],
      "rateLimit": "50/min",
      "budgetMonthly": 300
    }
  }
}

缓存策略配置

cache:
  enabled: true
  ttlMs: 600000
  maxSize: 1000
  keyStrategy: "hash"  # hash | exact
  excludeModels: ["o3"]  # 不缓存实时性要求高的模型

常见问题

Q1：多端点如何选择主备？

建议主端点选择延迟最低的区域，备用端点选择不同区域的同规格部署。通过curl测量各端点延迟后分配权重.

Q2：熔断器触发后如何恢复？

熔断器进入冷却期（默认30秒）后会自动探测端点，连续2次成功探测后恢复流量。也可通过POST /endpoints/{name}/reset手动重置.

Q3：缓存导致响应不一致怎么办？

对实时性要求高的场景（如代码生成、流式输出），可在请求头中添加Cache-Control: no-cache跳过缓存，或将该模型加入excludeModels列表.

Q4：租户预算超限后会怎样？

默认行为是限流（返回429），可在配置中改为告警放行（budgetAction: warn）或硬阻断（budgetAction: block）.

Q5：Key轮换期间如何保证不中断？

配置双Key模式，新Key与旧Key并存，网关优先使用新Key。旧Key在确认新Key稳定后移除，整个过程零中断.

Q6：如何查看实时成本统计？

访问GET /stats/cost?tenant=team-a&range=today，返回当日该租户的调用次数、Token消耗与费用估算.

Q7：systemd服务启动失败如何排查？

执行journalctl --user -u azure-gateway -f查看实时日志，常见原因包括Node.js路径错误、配置文件路径不存在、端口被占用.

Q8：能否与Nginx反向代理叠加使用？

可以。Nginx负责TLS卸载与外部访问控制，本网关负责协议适配与多端点路由，两者分工互补.

错误处理

已知限制

• 需要API Key，无Key环境无法使用
• 依赖云服务，需要网络连接
• 本地运行，不支持多设备同步