AI Gateway

明确 Gateway 做与不做

Gateway 位于 Agent Runtime 与模型 Provider 之间，统一完成调用方认证、模型授权、协议适配、路由、配额、预算、Telemetry 和费用归因。对所有模型都必须执行的数据分类、内容检查或区域政策也适合在此落地，因为这里能看到调用身份、目标模型和请求元数据。

Azure API Management 的 GenAI Gateway 文档列出的 Token 限制、语义缓存、负载均衡和熔断证明这些横切能力可以被网关集中执行。但这是产品能力事实，不代表所有企业都应采用同一实现。Gateway 的组织价值仍要由统一覆盖率、尾延迟、事故隔离和单位成本证明。

不要把所有 Provider 字段压成最低公分母。通用契约负责稳定语义，Provider Options 显式承载 Reasoning、Prompt Cache、内置 Tool 或批处理等差异；上层声明可接受的能力与降级，而不是依赖网关静默删除参数。

请求路径上的关键阶段

请求先从经过验证的会话或工作负载凭据解析租户、应用、用户、用途和 Trace，不接受 Prompt 中声称的身份。随后完成目标模型授权、Schema 与大小检查、数据分类和区域约束，再进行配额预留与路由。Provider 返回流事件后，网关逐帧透传并记录首 Token、完成、取消和 Usage；最后结算预算并把 Provider 回执与上游 Trace 关联。

Token 预算在调用前只能估算，完成后必须以 Provider Usage 或可验证计量结算。预留过少会超卖容量，预留过多会降低利用率；可用“最大输出上限 + 输入估算”保守预留，再在结束、取消或超时后释放差额。流连接断开时要向 Runtime 返回明确的“可能已消费、输出不完整”状态，不能统一归一成可安全重试的 500。

公共契约与特性逃生舱

公共契约至少稳定消息与多模态片段、Tool Definition、流事件、停止原因、Usage、错误类别、取消和 Deadline。Adapter 负责把 Provider 原始协议映射到这些语义，同时保留原始请求 ID、模型版本和未识别字段，便于排障与渐进升级。

能力探测由控制面定期执行并生成版本化元数据，数据面按请求绑定版本。发布新 Adapter 时，用录制的无敏感契约样本、Provider Sandbox 和影子流量比较事件序列、完成原因与 Usage；先按租户或应用灰度，再扩大流量。

工程建议：对 Provider 特性采用 namespaced options，并要求调用方声明 fallback 行为。例如目标端点不支持缓存控制时，明确拒绝、移除该可选能力或切换等价端点，不能静默改变成本与隐私语义。

路由同时考虑质量和实时健康

路由先做硬约束过滤：任务所需模态与 Tool 能力、风险等级、数据地域、租户准入、模型版本和最大上下文。剩余候选再按离线评测质量、在线成功率、容量、尾延迟和预算排序。质量不是一个全局分数，同一模型在代码修复、抽取与高风险决策上可能有不同门槛。

熔断按 Provider、区域、模型和错误类别分桶，避免一个模型的容量错误拖走整家 Provider。半开请求使用小流量探测，不把所有积压同时释放。Fallback 必须重新检查数据政策与质量门槛，并在 Trace 中记录路由理由与原始失败。

透明重试只适用于确认 Provider 未接收、尚未向客户端输出、没有 Tool 或外部副作用且 Deadline 仍足够的请求。首 Token 已流出后，另一个模型续写会造成语义拼接；Tool Call 已被 Runtime 执行后重放更可能重复副作用。此时 Gateway 报告部分结果，由 Runtime 根据任务状态决定恢复。

多层配额保护平台与租户

请求数不足以表达模型负载。Gateway 同时管理请求速率、输入与输出 Token、并发流、费用和特定 Provider 容量，并按组织、租户、应用、用户、模型与业务优先级组合计数。短窗口 Token Bucket 吸收正常突发，长窗口预算约束持续消费；交互、批处理和关键任务使用不同队列与预留。

Microsoft 官方文档明确指出 Provider 的 Token/分钟配额需要在多个应用间分配；多区域文档同时提醒部分网关的计数器按 Gateway 或区域独立，不能假定天然全局一致。实现时要明确计数一致性：强一致全局额度会增加延迟与故障耦合，本地额度加中央预算更可用，但必须保留安全余量和对账。

拒绝本身也是 API 契约。返回限制维度、当前消耗、可重试时间和申请扩容路径，客户端才能退避或降级。容量压测需要覆盖长流、超长 Prompt、取消风暴和 Provider 延迟抖动，不能只测短响应 QPS。

缓存只有在语义与隐私允许时使用

Provider Prompt Cache 通常复用已处理前缀，减少延迟或计费，但仍由 Provider 定义匹配、生命周期与隔离；Gateway 应记录缓存命中 Usage，不能把它宣传为本地数据不会离开系统。语义结果缓存则直接复用旧答案，只有请求等价、事实允许过期、身份与权限一致并且随机性不是产品目标时才安全。

缓存命中也要重新执行当下授权和输出政策，不能把旧授权结果一起缓存。紧急撤销、租户删除、模型或 Tool 版本变化必须触发可验证失效。缓存收益以单位成功任务的成本与延迟衡量，同时监控错误复用率和陈旧答案率；只看命中率会鼓励危险复用。

Gateway 是成本与访问证据源

Gateway 能统一记录输入、输出、缓存与 Reasoning Token，Provider、模型、区域、路由理由、调用方、租户、应用、业务场景和价格版本，因此适合作为访问与用量证据源。它不是最终财务账本：退款、承诺用量、批量折扣和 Provider 账单差异仍需由成本系统对账。

OpenTelemetry Semantic Conventions 1.43.0提供跨语言遥测命名基础，但 GenAI 约定仍存在版本与稳定性变化。生产 Schema 要记录约定版本，使用内部稳定映射，并对迁移执行双写或离线转换，不能把实验属性直接当长期财务合同。

Showback 让团队看到消费与单位成本，Chargeback 则进入真实内部结算，后者需要财务认可的价格版本和对账规则。预算告警应关联业务成功率：成本突然下降可能来自网关拒绝、模型退化或 Trace 丢失，不一定是优化。