多模型AI网关架构设计:从路由到计量的落地要点

作者:半吊子全栈工匠2026.11.17 03:22浏览量:0

简介:本文面向同时接入多家大模型的后端团队,讲解AI网关的模块划分、按权重与健康度的路由降级策略、SSE流式透传的正确实现、Token计量与配额的对账方法,以及分阶段落地的顺序,帮助读者少走弯路、控制成本。

如果团队同时接入两家以上大模型,直接在业务代码里分别调用各家 SDK,很快会遇到四类问题。接口字段各不相同,密钥散落在各处,单个供应商限流或故障会拖垮整条业务链路,Token 消耗也无法归因到具体租户或业务线。AI 网关把这些问题收敛到一个统一入口,对外提供一套 API,对内负责多供应商接入、调度、鉴权、配额和审计。

一、适用范围与前置条件

适用场景:同时调用两家以上模型,或需要按租户、业务线核算 Token 成本;多个业务共用模型额度,需要限流和降级;上游偶尔限流或超时,希望业务侧无感知。

不适用场景:只调用单一模型且调用量很小,直接在 SDK 外加重试即可;没有任何可用于评测的真实业务样本,此时无法判断路由权重是否合理。

前置条件:已有反向代理或 API 网关;团队能维护 Go 或同类语言的服务;能接入至少一套内容安全服务和一套日志指标系统。

二、整体架构:数据面与控制面分离

AI 网关的骨架与传统 API 网关相同,仍分为数据面和控制面。数据面处理每一次请求,包括鉴权、协议转换、路由、转发和计量。控制面负责配置下发、密钥管理和观测数据汇总。多数团队不会从零重写,而是在现有 API 网关上增加面向模型接口的能力。

需要补充的能力主要有三点。

  1. 无缓冲的请求代理。传统网关常先读完整个响应体再转发,SSE 流式输出一旦被缓冲,首 Token 延迟会从几百毫秒变成整段生成完成的时间。数据面必须边收边发,同时关闭 Nginx 等前置代理的缓冲,例如设置 proxy_buffering off。
  2. 混合上游发现。上游可能是 K8s 中自建的推理服务,可能是公网 SaaS 模型 API,也可能是私有化部署的模型服务。网关需要统一的 endpoint 抽象,屏蔽这些差异。
  3. 优雅排空。一次生成可能超过 60 秒,发布、扩缩容或客户端断连都会中断流。发布时应先摘除实例的新流量,等待存量流结束或超过上限时间后再退出进程。

模块拆分

层次 关键模块 职责
数据面 协议适配层 请求与响应字段归一,各家协议之间相互转换
数据面 流式代理 SSE 透传、断连回收、首包超时判断
数据面 路由调度 按模型名、租户、权重、健康度和剩余配额选择上游
数据面 计量与配额 Token 预占与结算、限流、超额拒绝
数据面 内容安全 输入与输出双向审核,拦截结果写入审计日志
控制面 密钥管理 API Key 池、轮转、熔断摘除
控制面 配置中心 模型注册、路由规则、降级链下发
控制面 可观测 日志、指标、链路追踪、成本归因

生成式内容的合规审核是独立且专业度较高的问题。网关应负责调用时机和结果处理,审核能力本身对接成熟的内容安全服务,不建议自研规则引擎。

三、协议适配

网关内部使用一套规范的请求和响应结构。入站请求先转换为规范格式,出站时再转换为上游格式。这样新增一家供应商时,只需要实现一个适配器,不必改动路由和计量模块。

下表列出 OpenAI 兼容格式与 Anthropic Claude 格式的主要差异。

项目 OpenAI 兼容格式 Anthropic Claude 格式
系统指令 messages 中 role 为 system 的一条消息 顶层 system 字段
最大输出长度 max_tokens 可选 max_tokens 必填
用量字段 usage.prompt_tokens、usage.completion_tokens usage.input_tokens、usage.output_tokens
流式事件 以 data: 开头的行,以 [DONE] 结束 带 event: 类型的事件序列,用量分散在多个事件中

文心等其他供应商的参数名和用量字段以各家官方文档为准。接入前应逐项核对,不要直接套用上表。

四、路由、负载均衡与降级

纯轮询无法应对上游波动。建议对每个候选上游计算综合得分,选择得分最高的上游。

  1. routes:
  2. - model: "ernie-4.0-turbo"
  3. upstreams:
  4. - name: qianfan-primary
  5. keys: ["${KEY_POOL_A}"]
  6. weight: 60
  7. max_qps: 50
  8. timeout:
  9. ttft_ms: 10000
  10. total_ms: 60000
  11. - name: self-hosted-vllm
  12. discovery: k8s://llm-ns/svc:8000
  13. weight: 40
  14. timeout:
  15. ttft_ms: 5000
  16. total_ms: 60000
  17. health:
  18. window_s: 60
  19. min_samples: 20
  20. error_rate_eject: 0.2
  21. eject_s: 30
  22. - model: "long-context-128k"
  23. upstreams:
  24. - name: qianfan-128k
  25. keys: ["${KEY_POOL_B}"]
  26. weight: 100
  27. max_input_tokens: 131072
  28. fallback_chain:
  29. - model: "ernie-3.5"
  30. when: ["429", "5xx", "ttft_timeout", "connect_error"]
  31. - model: "cached:last_good_response"
  32. when: ["all_upstreams_failed"]

综合得分的计算方式如下。

  • 健康度:health = success_rate_60s × min(1, ttft_target / ttft_p95),其中 success_rate_60s 是最近 60 秒的成功率,ttft_target 是配置的首包超时,ttft_p95 是最近窗口的首包延迟 P95。
  • 配额比例:quota_ratio = 剩余 QPS 或剩余 Token 额度 / 上限,取两者中较小的值。
  • 权重:weight_norm = weight / 同路由权重之和。
  • 综合得分:score = 0.5 × health + 0.3 × quota_ratio + 0.2 × weight_norm。

样本数不足 min_samples 时,健康度按 1 计算,避免新上游因为样本少而被误判。错误率超过 error_rate_eject 的上游会被摘除 eject_s 秒,期间得分记为 0。

降级规则按错误类型区分处理。

  • 连接失败、首包超时、5xx:计入错误,先尝试同一路由的其他上游,全部失败后再按降级链切换模型。
  • 429:先切换同一上游的其他密钥。所有密钥都被限流后,才进入降级流程。
  • 其他 4xx(例如参数错误):不降级,直接返回给用户。换模型也不会成功,降级只会浪费配额。
  • 降级只能发生在向客户端写入第一个字节之前。流已经开始后,上游中断只能以错误事件结束当前流,无法切换模型继续输出。

降级模型的上下文窗口不能小于原请求。例如原请求长度超过 131072 个 Token 时,降级到窗口较短的模型会直接失败,正确做法是返回 400 并说明原因。

cached:last_good_response 是最后的兜底手段,但它有明确的风险。第一,返回的内容可能已经过期。第二,缓存的回答可能来自另一个模型,格式和风格不一致。第三,如果缓存跨用户共享,可能泄露他人对话内容。因此它只适用于无个性化、非实时的 FAQ 类请求。缓存键必须包含租户标识和 prompt 哈希,TTL 建议设为 10 分钟以内,并在响应头中标记 X-Degraded: true,让业务方知道这是降级结果。

五、流式透传代理

无缓冲代理的核心是逐块转发,并在每一块到达后立即 flush。下面的示例省略了 newUpstreamRequest、handleUpstreamError 等辅助函数,重点展示 SSE 的处理方式。

  1. func (p *Proxy) streamSSE(w http.ResponseWriter, r *http.Request, up *url.URL) {
  2. // 使用 r.Context() 构造上游请求,客户端断开时上游连接随之取消,不再白烧 Token
  3. req, err := p.newUpstreamRequest(r.Context(), r, up)
  4. if err != nil {
  5. p.fallback(w, r)
  6. return
  7. }
  8. // 要求上游返回未压缩内容,避免处理 gzip 等编码
  9. req.Header.Set("Accept-Encoding", "identity")
  10. resp, err := p.client.Do(req)
  11. if err != nil {
  12. p.fallback(w, r) // 尚未向客户端写入任何字节,可以安全降级
  13. return
  14. }
  15. defer resp.Body.Close()
  16. // 非 2xx 状态码先按错误规则分流,不进入流式输出
  17. if resp.StatusCode >= 400 {
  18. p.handleUpstreamError(w, r, resp)
  19. return
  20. }
  21. // 上游不遵守协商结果时,不透传压缩字节
  22. if enc := resp.Header.Get("Content-Encoding"); enc != "" && enc != "identity" {
  23. p.metrics.incUpstreamError("unexpected_encoding")
  24. p.fallback(w, r)
  25. return
  26. }
  27. flusher, ok := w.(http.Flusher)
  28. if !ok {
  29. p.emitLog(r.Context(), nil)
  30. return
  31. }
  32. h := w.Header()
  33. h.Set("Content-Type", "text/event-stream")
  34. h.Set("Cache-Control", "no-cache")
  35. h.Set("X-Accel-Buffering", "no") // 通知 Nginx 关闭缓冲
  36. w.WriteHeader(http.StatusOK)
  37. var usage *Usage
  38. reader := bufio.NewReaderSize(resp.Body, 4096)
  39. for {
  40. line, readErr := reader.ReadBytes('\n')
  41. if len(line) > 0 {
  42. if _, writeErr := w.Write(line); writeErr != nil {
  43. break // 客户端已断开
  44. }
  45. flusher.Flush()
  46. if payload, ok := parseDataLine(line); ok {
  47. if u := extractUsage(payload); u != nil {
  48. usage = u
  49. }
  50. }
  51. }
  52. if readErr != nil {
  53. break // io.EOF 或上游异常
  54. }
  55. }
  56. p.metrics.recordUsage(r, usage)
  57. p.emitLog(r.Context(), usage)
  58. }
  59. func parseDataLine(line []byte) ([]byte, bool) {
  60. s := bytes.TrimSpace(line)
  61. if !bytes.HasPrefix(s, []byte("data:")) {
  62. return nil, false
  63. }
  64. payload := bytes.TrimSpace(s[len("data:"):])
  65. if len(payload) == 0 || bytes.Equal(payload, []byte("[DONE]")) {
  66. return nil, false
  67. }
  68. return payload, true
  69. }
  70. type streamEnvelope struct {
  71. Usage *Usage `json:"usage"`
  72. }
  73. func extractUsage(payload []byte) *Usage {
  74. var env streamEnvelope
  75. if err := json.Unmarshal(payload, &env); err != nil {
  76. return nil
  77. }
  78. return env.Usage
  79. }

代码有几处需要注意。

  • SSE 是按行分隔的文本协议,事件之间以空行区分。代理按原样写出每一行,事件边界自然保留,不需要重新编码 JSON。
  • 解析 data: 行只用于提取 usage,解析失败不影响转发。
  • 响应头必须在第一次写入前设置,并调用 WriteHeader。之后再修改响应头无效。
  • 如果部署在 Nginx 之后,除了 X-Accel-Buffering: no,还要确认 proxy_buffering off 已生效,否则代理层仍会缓冲。

六、Token 计量与配额

计量不能靠字符数除以二这类估算。可靠做法分为两层。优先使用上游返回的 usage 字段。上游不返回时,再用分词器在本地估算。

流式场景的 usage 有前置条件。对于 OpenAI 兼容接口,需要在请求体中加入 "stream_options": {"include_usage": true},usage 会出现在最后一个带内容的 chunk 中,有时 choices 为空。并非所有上游都支持该参数,接入前应在每家供应商的测试环境中验证。如果上游不返回 usage,网关会记录 usage_source=estimated,并使用本地估算值。

配额采用预占和结算两步。

  1. 请求前预占:预估输入 Token 数加上 max_tokens,从租户配额中扣除预占额度。额度不足时直接拒绝。
  2. 响应结束后结算:用实际用量与预占值做差,多退少补。客户端断连或上游异常时,也必须执行结算,否则预占额度会永久占用。

本地分词器的误差取决于模型和分词器版本,通常在百分之几的范围内,无法与上游账单完全一致。因此本地估算只用于预占和告警,最终计费以上游返回的 usage 为准。月底应按模型对比网关统计值与供应商账单,差异超过 2% 时排查 usage_source=estimated 的记录占比、重试产生的重复计量以及漏记的失败请求。

成本归因建议按 tenant_id + app_id + model + api_key 四维打标。这样出账时能直接定位到具体业务线的消耗,也便于为每个业务线设置预算告警。

七、语义缓存

语义缓存在命中时直接省掉整次调用的费用,对 FAQ 类高重复场景收益明显。它的设计要点包括以下几项。

  • 缓存键:由租户、模型、系统提示词版本和归一化后的用户问题组成。系统提示词或知识库版本变化时,旧缓存自动失效。
  • 两级匹配:先做精确哈希匹配,未命中再做向量相似度匹配。相似度阈值建议从 0.95 起步,并依据人工抽检结果调整。
  • 适用请求:只缓存 temperature 为 0 或业务允许复用结果的请求。涉及个人信息、实时数据或强依赖上下文的请求不进入缓存。
  • TTL:通用 FAQ 可设为 24 小时。政策、价格等会变化的内容应绑定知识库版本号,版本更新时整体失效,而不是依赖固定 TTL。
  • 指标:统计命中率和误命中率。误命中率通过每周抽检约 200 条命中记录,由人工判断答案是否仍然正确得出。

八、可观测性与告警

传统网关的指标是 QPS、P99 延迟和错误率。AI 网关还需要以下指标。

  • TTFT(首 Token 延迟)与 TPS(每秒输出 Token 数)分开统计,因为二者受不同因素影响。TTFT 主要受排队和上游首包速度影响,TPS 主要受模型和输出长度影响。
  • 单请求 Token 消耗分布,用于发现异常长的 prompt。
  • 上游限流命中率,作为扩容或增加密钥的依据。
  • 降级触发次数,持续非零说明主模型容量不足。
  • 配额超限率,用于判断租户额度设置是否合理。

告警阈值可以作为起点,结合实际流量调整。

  • TTFT P99 超过 3 秒,持续 5 分钟,发出告警。
  • 降级率超过 5%,持续 10 分钟,发出告警。
  • 上游 429 命中率超过 10%,持续 5 分钟,检查密钥池和限流配额。
  • 配额超限率超过 3%,持续 15 分钟,通知租户负责人。

链路追踪应把 request_id 透传到上游,并在日志中记录完整 prompt 的哈希值,不记录明文,兼顾排障与隐私。

排错时可以按以下顺序检查。

  1. 用 request_id 在网关日志和上游日志中查找同一条请求,确认两侧记录一致。
  2. 查看上游返回的状态码和错误体,判断是限流、超时还是参数问题。
  3. 检查对应密钥是否已被熔断摘除,以及密钥池剩余额度。
  4. 检查该请求的 usage_source。如果是 estimated,说明上游未返回 usage,需要核对该上游的流式参数。
  5. 检查请求长度是否超过路由配置的 max_input_tokens,以及降级模型是否满足窗口要求。

九、落地顺序

不要一次性实现全部能力。建议按以下顺序推进,每一步都能单独验证。

  1. 协议归一与单模型代理。先让一条请求从业务方经过网关到达上游并正确返回,记录基础日志。
  2. 密钥池与限流。解决密钥分散和单密钥限流的问题。
  3. 流式透传与优雅排空。用真实的长文本生成任务验证首包延迟和断连回收。
  4. 路由评分与降级链。先用固定权重上线,再根据健康度数据调整评分参数。
  5. 计量、配额与成本归因。与供应商账单完成一次完整对账后再开放租户配额。
  6. 语义缓存、内容安全与告警。在前面的指标稳定后叠加,并在每一步设置回滚开关。

路由权重不应只依据榜单确定。建议先用一批真实业务 prompt,在候选模型上做小规模评测,同时记录成本、延迟和输出质量,再确定初始权重。这样做比上线后反复调参更省成本。

如果团队暂时不想自建全部能力,可以把模型接入层交给云平台托管,网关只负责路由、鉴权、计量和降级等业务策略。这种组合在实践中较为常见:网关管业务规则,平台管模型供给与运维。