简介:本文面向同时接入多家大模型的后端团队,讲解AI网关的模块划分、按权重与健康度的路由降级策略、SSE流式透传的正确实现、Token计量与配额的对账方法,以及分阶段落地的顺序,帮助读者少走弯路、控制成本。
如果团队同时接入两家以上大模型,直接在业务代码里分别调用各家 SDK,很快会遇到四类问题。接口字段各不相同,密钥散落在各处,单个供应商限流或故障会拖垮整条业务链路,Token 消耗也无法归因到具体租户或业务线。AI 网关把这些问题收敛到一个统一入口,对外提供一套 API,对内负责多供应商接入、调度、鉴权、配额和审计。
适用场景:同时调用两家以上模型,或需要按租户、业务线核算 Token 成本;多个业务共用模型额度,需要限流和降级;上游偶尔限流或超时,希望业务侧无感知。
不适用场景:只调用单一模型且调用量很小,直接在 SDK 外加重试即可;没有任何可用于评测的真实业务样本,此时无法判断路由权重是否合理。
前置条件:已有反向代理或 API 网关;团队能维护 Go 或同类语言的服务;能接入至少一套内容安全服务和一套日志指标系统。
AI 网关的骨架与传统 API 网关相同,仍分为数据面和控制面。数据面处理每一次请求,包括鉴权、协议转换、路由、转发和计量。控制面负责配置下发、密钥管理和观测数据汇总。多数团队不会从零重写,而是在现有 API 网关上增加面向模型接口的能力。
需要补充的能力主要有三点。
proxy_buffering off。| 层次 | 关键模块 | 职责 |
|---|---|---|
| 数据面 | 协议适配层 | 请求与响应字段归一,各家协议之间相互转换 |
| 数据面 | 流式代理 | 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: 类型的事件序列,用量分散在多个事件中 |
文心等其他供应商的参数名和用量字段以各家官方文档为准。接入前应逐项核对,不要直接套用上表。
纯轮询无法应对上游波动。建议对每个候选上游计算综合得分,选择得分最高的上游。
routes:- model: "ernie-4.0-turbo"upstreams:- name: qianfan-primarykeys: ["${KEY_POOL_A}"]weight: 60max_qps: 50timeout:ttft_ms: 10000total_ms: 60000- name: self-hosted-vllmdiscovery: k8s://llm-ns/svc:8000weight: 40timeout:ttft_ms: 5000total_ms: 60000health:window_s: 60min_samples: 20error_rate_eject: 0.2eject_s: 30- model: "long-context-128k"upstreams:- name: qianfan-128kkeys: ["${KEY_POOL_B}"]weight: 100max_input_tokens: 131072fallback_chain:- model: "ernie-3.5"when: ["429", "5xx", "ttft_timeout", "connect_error"]- model: "cached:last_good_response"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。
降级规则按错误类型区分处理。
降级模型的上下文窗口不能小于原请求。例如原请求长度超过 131072 个 Token 时,降级到窗口较短的模型会直接失败,正确做法是返回 400 并说明原因。
cached:last_good_response 是最后的兜底手段,但它有明确的风险。第一,返回的内容可能已经过期。第二,缓存的回答可能来自另一个模型,格式和风格不一致。第三,如果缓存跨用户共享,可能泄露他人对话内容。因此它只适用于无个性化、非实时的 FAQ 类请求。缓存键必须包含租户标识和 prompt 哈希,TTL 建议设为 10 分钟以内,并在响应头中标记 X-Degraded: true,让业务方知道这是降级结果。
无缓冲代理的核心是逐块转发,并在每一块到达后立即 flush。下面的示例省略了 newUpstreamRequest、handleUpstreamError 等辅助函数,重点展示 SSE 的处理方式。
func (p *Proxy) streamSSE(w http.ResponseWriter, r *http.Request, up *url.URL) {// 使用 r.Context() 构造上游请求,客户端断开时上游连接随之取消,不再白烧 Tokenreq, err := p.newUpstreamRequest(r.Context(), r, up)if err != nil {p.fallback(w, r)return}// 要求上游返回未压缩内容,避免处理 gzip 等编码req.Header.Set("Accept-Encoding", "identity")resp, err := p.client.Do(req)if err != nil {p.fallback(w, r) // 尚未向客户端写入任何字节,可以安全降级return}defer resp.Body.Close()// 非 2xx 状态码先按错误规则分流,不进入流式输出if resp.StatusCode >= 400 {p.handleUpstreamError(w, r, resp)return}// 上游不遵守协商结果时,不透传压缩字节if enc := resp.Header.Get("Content-Encoding"); enc != "" && enc != "identity" {p.metrics.incUpstreamError("unexpected_encoding")p.fallback(w, r)return}flusher, ok := w.(http.Flusher)if !ok {p.emitLog(r.Context(), nil)return}h := w.Header()h.Set("Content-Type", "text/event-stream")h.Set("Cache-Control", "no-cache")h.Set("X-Accel-Buffering", "no") // 通知 Nginx 关闭缓冲w.WriteHeader(http.StatusOK)var usage *Usagereader := bufio.NewReaderSize(resp.Body, 4096)for {line, readErr := reader.ReadBytes('\n')if len(line) > 0 {if _, writeErr := w.Write(line); writeErr != nil {break // 客户端已断开}flusher.Flush()if payload, ok := parseDataLine(line); ok {if u := extractUsage(payload); u != nil {usage = u}}}if readErr != nil {break // io.EOF 或上游异常}}p.metrics.recordUsage(r, usage)p.emitLog(r.Context(), usage)}func parseDataLine(line []byte) ([]byte, bool) {s := bytes.TrimSpace(line)if !bytes.HasPrefix(s, []byte("data:")) {return nil, false}payload := bytes.TrimSpace(s[len("data:"):])if len(payload) == 0 || bytes.Equal(payload, []byte("[DONE]")) {return nil, false}return payload, true}type streamEnvelope struct {Usage *Usage `json:"usage"`}func extractUsage(payload []byte) *Usage {var env streamEnvelopeif err := json.Unmarshal(payload, &env); err != nil {return nil}return env.Usage}
代码有几处需要注意。
data: 行只用于提取 usage,解析失败不影响转发。WriteHeader。之后再修改响应头无效。X-Accel-Buffering: no,还要确认 proxy_buffering off 已生效,否则代理层仍会缓冲。计量不能靠字符数除以二这类估算。可靠做法分为两层。优先使用上游返回的 usage 字段。上游不返回时,再用分词器在本地估算。
流式场景的 usage 有前置条件。对于 OpenAI 兼容接口,需要在请求体中加入 "stream_options": {"include_usage": true},usage 会出现在最后一个带内容的 chunk 中,有时 choices 为空。并非所有上游都支持该参数,接入前应在每家供应商的测试环境中验证。如果上游不返回 usage,网关会记录 usage_source=estimated,并使用本地估算值。
配额采用预占和结算两步。
max_tokens,从租户配额中扣除预占额度。额度不足时直接拒绝。本地分词器的误差取决于模型和分词器版本,通常在百分之几的范围内,无法与上游账单完全一致。因此本地估算只用于预占和告警,最终计费以上游返回的 usage 为准。月底应按模型对比网关统计值与供应商账单,差异超过 2% 时排查 usage_source=estimated 的记录占比、重试产生的重复计量以及漏记的失败请求。
成本归因建议按 tenant_id + app_id + model + api_key 四维打标。这样出账时能直接定位到具体业务线的消耗,也便于为每个业务线设置预算告警。
语义缓存在命中时直接省掉整次调用的费用,对 FAQ 类高重复场景收益明显。它的设计要点包括以下几项。
temperature 为 0 或业务允许复用结果的请求。涉及个人信息、实时数据或强依赖上下文的请求不进入缓存。传统网关的指标是 QPS、P99 延迟和错误率。AI 网关还需要以下指标。
告警阈值可以作为起点,结合实际流量调整。
链路追踪应把 request_id 透传到上游,并在日志中记录完整 prompt 的哈希值,不记录明文,兼顾排障与隐私。
排错时可以按以下顺序检查。
request_id 在网关日志和上游日志中查找同一条请求,确认两侧记录一致。usage_source。如果是 estimated,说明上游未返回 usage,需要核对该上游的流式参数。max_input_tokens,以及降级模型是否满足窗口要求。不要一次性实现全部能力。建议按以下顺序推进,每一步都能单独验证。
路由权重不应只依据榜单确定。建议先用一批真实业务 prompt,在候选模型上做小规模评测,同时记录成本、延迟和输出质量,再确定初始权重。这样做比上线后反复调参更省成本。
如果团队暂时不想自建全部能力,可以把模型接入层交给云平台托管,网关只负责路由、鉴权、计量和降级等业务策略。这种组合在实践中较为常见:网关管业务规则,平台管模型供给与运维。