1. 为什么走到这一步：200+ 模型背后，是没人管得住的混乱
1.1 最真实的痛点：每个团队都在自己对接模型
先交代一下背景。我们团队维护的是一个内部模型服务平台，最开始只是给两三个业务方提供大模型 API，大家各调各的，没什么问题。但随着业务铺开，平台里接进来的模型越来越多，从各家闭源商用模型到开源的本地部署模型，加起来超过 200 个，问题一下子全暴露了。最典型的场景是：某支付团队要在他们的小程序里接入一个对话机器人，产品经理对比了五六个模型的效果后，决定先上 A 模型；结果 A 模型的服务商接口升级，老版本不再续约，他们就得改代码重新联调。这个流程走一遍两三天，而且每个团队都在重复做类似的事情——维护各自的 API Key、各自的超时重试逻辑、各自对响应格式的解析，甚至连"这个模型今天挂没挂"这种信息都要自己盯着。
当时平台这边收到的求助消息几乎每周都有："B 模型现在还能不能用？""C 模型的接口怎么又变了？""D 模型的返回里为什么多了个字段？"实际上问题不在模型本身，而在接入方式太原始。每个团队直接对着模型原始 API 编程，意味着任何一家上游的微小变更都会传导到所有下游，这就是典型的耦合爆炸。我那时候意识到，必须有一个统一的 API 网关把这些模型包起来，把碎片化的接入变成标准化的调用，否则 200 个模型就是 200 个负担。
1.2 我们能统一的只有什么：协议、计量、路由、安全
想清楚"要统一什么"比"怎么实现"更重要。和团队反复讨论后，我们把网关的职责收敛为四件事：
- 协议统一：对外只暴露一套标准接口格式，内部再去适配 200 多个模型的原始差异。
- 计量统一：所有团队通过网关调用模型，网关记录每次请求的模型、Token 消耗、耗时、错误信息，一套账，谁用了多少一目了然。
- 路由统一：同一个模型逻辑名背后可能有多个物理来源（比如多个副本、多区域部署），网关负责选路和故障转移。
- 安全统一：API Key 管理、白名单、限流这些事集中做，而不是每个业务团队各自为政。
至于"性能优化"和"业务逻辑"这种，我们刻意没有放进来。网关就是网关，它只解决接入和治理的问题，不替业务方做 RAG、不做对话状态管理，也不碰向量检索。边界划清楚，后面做架构决策时就不容易纠结。
1.3 统一网关的边界：哪些事必须由网关做，哪些必须放手
这里多说一句边界问题。刚立项的时候，有同事提过"既然都有了网关，不如把提示词工程、模型效果对比、甚至数据集管理都做进去"，我直接泼了冷水。网关一旦背上太多业务包袱，就会变得又重又脆，任何业务逻辑的改动都得重新发布网关，这违背了它作为基础设施的定位。我们最终的策略是：网关只保证"请求能到模型、响应能回得去、过程可观测、结果能计量"，剩下的全部留给上层业务平台。这个原则在后来的演进中帮了大忙，因为模型更新的频率远高于业务平台的更新频率，把变化隔离在网关内部，是保持整体稳定的基石。
2. 网关整体架构与分层设计：热路径上只放"必须做的事"
2.1 三层架构：接入层、编排层、配置存储层
网关的整体架构可以分成三层来看。最外面是接入层，负责处理 HTTP 请求、鉴权、基础的限流和超时控制；中间是编排层，干的是协议转换、路由选择、重试退避、故障转移这些"需要动脑子"的事；最底层是配置存储层，保存模型注册信息、路由规则、密钥、限流配额和计量日志。
接入层我们做得很薄，几乎只是把请求从网络连接上接住，扔给编排层。为什么？因为接入层一旦变厚，比如在接入层解析请求体、做参数校验，高并发下会白白消耗 CPU 和内存。编排层才是核心，所有模型的适配逻辑都在这一层，通过插件化的处理器（Handler）实现。新增一个模型时，通常只需要新写一个适配器，注册到模型配置里，不需要改动网关主流程。配置存储层最开始用了一个简单的配置中心加数据库，后来计量数据量大了以后单独拆了时序存储。三层之间的通信是纯内存调用，避免序列化开销，因为我们知道网关会成为所有模型流量的必经之路，性能必须省着用。
2.2 中间标准格式：一切模型差异的"翻译基准"
协议适配的第一步是定义一套中间标准格式。我们没有直接用任何一家厂商的原始格式作为标准，而是基于主流协议设计了一套内部统一的请求/响应结构，这样谁也绑架不了我们。举个最简单的例子：不同模型对"系统提示词"的支持方式完全不同，有的叫 system，有的叫 instruction，有的只支持 messages 数组里塞特定角色。在标准格式里，我们统一用 messages 数组加一个可选的 system 字段来表达；适配器负责把标准格式翻译成目标模型需要的原始格式，再把模型的响应反翻译成标准格式。
这里有个很关键的设计原则：标准格式必须取各家格式的并集，并且允许未知字段旁路透传。什么意思？如果标准格式只保留各家都支持的公共字段，那一些模型独有的高级参数（比如某个模型支持 JSON Schema 输出限制、另一个支持 logprobs 返回）就无法传递，适配器写起来会非常痛苦。我们的做法是：标准格式里定义公共字段，同时保留一个 extensions 字典，适配器可以把模型特有参数塞进去；这样既保证了主要调用的统一性，又不扼杀模型的差异化能力。
2.3 为什么不用"直接转发": 拦截点在流式场景下才是价值所在
有人可能会问，HTTP 代理不就能做转发吗，为什么要自己写一个网关？关键在于流式响应。大模型接口现在基本都是 SSE（Server-Sent Events）流式返回，客户端边收边用。如果网关只是把上游字节流原封不动转发给下游，那网关确实只是个管道。但我们想要的不仅仅是转发，我们要在转发过程中做三件事：按需修改流内容、统计流式 Token、在流中断时触发重试或降级。
这直接决定了网关不能是"转发模式"，而必须是"缓冲+处理+转发"的模式。当然，缓冲是有代价的，流式体验要求首字延迟尽量低，所以我们在缓冲设计上做了个折中：不把整个响应都攒在内存里，而是边读边处理，每收到一个数据块就立即标准化并转发给下游。唯一需要额外等待的，是某些必须在响应开头插入的前置信息（比如补一个标准的 role 字段），这个处理开销微乎其微。整体实测下来，网关引入的额外首字延迟控制在 20 毫秒以内，对用户来说基本无感。
3. 协议适配层的核心实现：把 200 种脾气拧成一股绳
3.1 请求适配：system prompt、参数归一化与格式重整
协议适配层是工作量最大的地方，也是最容易出暗坑的地方。首先是 system prompt 的处理。我们发现某些模型对 system prompt 有隐式约束：如果 system 里写了不该写的指令，模型会拒绝回答；如果 system 为空，模型又会变得过于"散漫"。因此适配器里设计了 prompt 改写规则，例如把标准格式里 system 段落拆成目标模型允许的 role 组合，或者反过来把原生态的 system 合并进第一条用户消息。这些规则每接一个新模型都要调一轮，没有什么通用规律可循，靠的就是对照测试用例逐条验证。
参数归一化也是个细活。各家模型的 temperature、top_p、max_tokens、stop 这些超参定义差异很大：有的 temperature 范围是 0 到 1，有的是 0 到 2；有的 stop 只支持字符串，有的必须传字符串数组。我们在标准格式里统一按一套"人类直觉合理"的范围定义，比如 temperature 就是 0 到 2 的浮点数，适配器负责映射。遇到目标模型不支持的参数，适配器的策略是忽略并记一条警告日志，而不是报错拒绝请求，因为大多数业务场景下这些参数的缺失是可以容忍的。
还有多模态请求的格式重整。有的模型要求图片以 URL 形式传入，有的则要求 base64 内联；有的模型把图片理解放在 content 数组里，有的放在独立字段里。适配器要做的事情就是把标准格式里的"内容块数组"重新组装成目标模型认识的样子。这个过程比较琐碎，但一旦做好了缓存下来，新模型接入的时候就只是填表式配置。
3.2 流式响应的真实处理：改格式、插内容、断点续传
流式处理的复杂程度远超预期。各家 SSE 的格式差异、分片粒度、结束标记都不一样，有的用data: [DONE]结尾，有的用event: stop，有的干脆不发结束事件，只靠连接关闭来暗示。我们的标准流格式统一为data: {"delta": "...", "usage": null}这种结构，适配器需要把上游各种格式转换成这个结构。转换本身不复杂，真正复杂的是流内容的后处理。
我们有一个实际需求：对模型输出的内容做在线敏感信息过滤和格式矫正，比如把全角括号转成半角、修正成对的引号、把中英文标点统一。这些操作如果放在客户端做，所有调用方都得改代码；放在网关做才是最合理的。但流式场景下，一个词可能被拆成好几个分片，直接在每个分片内做替换会导致结果错乱。我们的办法是设定一个短窗口缓冲：攒够一定字符数或到达句读边界时，再对当前拼接好的文本段落做后处理，然后转发。这个"攒-处理-发"的节奏要调节得很小心，窗口太大会增加延迟，窗口太小又处理不干净，最终在两到三个分片之间找到了一个非常合适的平衡点。
流中断的问题我们也在适配层做了兜底。当上游连接意外断开时，适配器会先拼接已收到的内容，判断是否到达了语义完整点（比如最后一个 delta 后面没有半个词）。如果确实不完整，网关会尝试用同一个配置重试一次；如果重试也失败，就给下游返回一个带有部分内容和错误标记的响应，客户端可以基于这个标记决定是渲染已收到的内容还是提示用户重新生成。
3.3 token 计量：别信上游的 usage 字段
计量是网关的硬需求，但 Token 统计远比想象中坑多。各家返回的 usage 字段统计口径不一样：有的只统计输出 Token，有的把输入输出都算上但把 prompt 缓存部分单列，有的对系统提示词内部重复计费。直接用上游 usage 字段做账，月底对账的时候保证哭出来。我们的方案是：网关内置一套离线 Token 分词器，对每个业务请求独立统计输入和输出 Token，并且只以网关统计为准。这套分词器的精度不一定比得上各家厂商的内部实现，但至少口径一致、可复现、可审计。
同时我们特意把计量数据设计成事件流而不是单纯聚合值。每条计量日志包含 request_id、用户、应用、模型别名、输入 Token、输出 Token、耗时、错误码。后续不管是做账单、成本分析、模型效果热力图还是异常检测，都可以基于这些原始事件重新聚合，而不是依赖某一版本的预聚合结果。这个设计在某个大促期间帮了大忙：业务方想看某几个模型在高峰期的成本分布，我们直接从事件流里重放了一天半的计量数据，半小时就给出了分析。
4. 路由、容灾与灰度：模型从"接进来"到"用得好"的关键一跳
4.1 路由策略设计：可用性优先、成本优先、效果优先
200 多个模型不可能全都是"独一份"的存在，很多模型在功能上是等价的，只是效果、价格、速度方面有差异。所以我们定义了逻辑模型（Logical Model）与物理模型（Physical Model）两层概念：业务方调用"逻辑模型"，网关到路由表里去查这个逻辑模型底下挂了哪些物理模型。路由策略有三档：
- 可用性优先：正常情况下把所有流量都导给主物理模型，一旦主模型故障，自动切换到备选模型。大多数核心业务用这个策略。
- 成本优先：在满足效果阈值的前提下优先选择单价最低的物理模型。适合对响应质量要求不那么苛刻、对成本敏感的场景。
- 效果优先：用线上真实请求做小流量对比，哪个模型的效果评分高就往哪个模型多导流。
这三档策略我们并没有做得很复杂，核心就是路由表加一个评分器。评分器根据健康检查、延迟、错误率、成本、效果评分等维度，给每个物理模型打一个分数，然后按策略选择。比如成本优先并不是永远选最便宜的，而是设定一个"效果分数不得低于 0.85"的硬性条件，再在满足条件的候选里挑最便宜的。
4.2 故障转移的时间窗设计：多少超时才算"挂了"
路由和容灾是一体两面。故障转移做得太激进，上游稍微抖动一下你就切走了，反而制造更多不稳定；做得太保守，用户已经在报错了还在傻等。我们线上跑了一段时间后，把超时和重试的阈值调成了这样：
- 连接超时：2 秒。
- 首字响应超时：15 秒。超过这个时间还没有返回第一个数据块，大概率是模型推理卡死了。
- 流式读取整体超时：不设固定上限，但要求每个分片之间的间隔不超过 60 秒；超过就判定死流。
- 重试次数：最多 1 次，且只在连接超时、首字超时、特定 5xx 错误码时重试。4xx 一律不重试，因为那是请求本身有问题。
这里有个关键决策是：错误响应和超时重试不能一刀切。我们踩过的坑是，早期一律重试 3 次，结果上游服务商的一个限流错误导致所有调用方同时重试，引发了重试风暴，网关和上游一起被打爆。后来把重试次数降到 1 次并且加了随机抖动（退避时间为 200ms 加上 0 到 200ms 的随机区间），线上的重试风暴基本绝迹。
4.3 model 别名与灰度切换：业务代码一刀不改
模型迭代是常态：同一个模型厂商可能隔几周就发布新版本，效果更好、价格也可能变了。如果业务方代码里写死了具体模型名，每次升级都得通知所有调用方改配置，这显然不可接受。所以网关里实现了别名机制：业务方只认stable、preview、legacy这类别名，网关维护别名到具体物理模型版本的映射。
发新版模型的时候，我们的操作流程是这样的：先把新版本模型注册为物理模型，在路由表里加上一条 5% 的灰度配比，让 5% 的线上请求打到新版本；然后观察错误率、延迟、用户反馈，一切正常就逐步提高到 20%、50%、100%。整个过程中，业务方一行代码不用改，因为他们调用的稳定别名始终指向"当前最佳版本"。如果新版本效果明显不如旧版，我们只需要在灰度配置里把比例调回 0，把别名重新指回旧版本，一分钟内完成回滚。这个机制后来成了我们应对模型厂商"突然发布一个惊悚新版本"的保命符。
5. 安全治理与计量：网关不能只会转发
5.1 全局限流与配额：单机令牌桶解决不了的问题
网关部署是多实例集群，所以限流不能用单机令牌桶实现，否则节点扩容的时候限流总量就变了。我们实现的是分布式限流：外层的全局限流用中心化的令牌桶服务，预先为每个 API Key 分配每秒可用配额；同时每个网关实例本地还维护一个实时计数器，用于兜底突发流量。这里的关键是容忍一定的配额偏差，不追求精确到毫秒的严格限流，因为对模型调用这种场景来说，限制的粒度是"秒级、分钟级"，本来就允许一定范围内的超卖。
配额的管理也做了多级拆分：从总配额到应用配额再到模型级配额。比如某部门每天的模型 Token 预算是 1000 万，这个预算会自动分配到这个部门旗下的各个应用上，每个应用还能指定"只能调用某些模型"。这样做的好处是防止个别团队一上线活动就把全部门预算烧光。配额用完了怎么处理？我们默认返回 429 加一个标准错误信息，业务方可以自定义兜底策略，比如自动降级到成本更低的模型。
5.2 密钥管理：上游 Key 分发的零信任原则
还有一个经常被忽略但极其重要的点：业务团队拿到的永远只是网关的 API Key，而不是各家模型上游的密钥。这是零信任原则在网关场景下的具体实践。如果每个业务团队都持有各家模型服务商的原始密钥，一旦某个团队泄露密钥，影响面就是所有模型的全部配额；而只给他们网关的 Key，我们可以做到按应用隔离、随时吊销、按量审计。上游密钥全部加密存放在配置存储层，只在网关进程内存里解密使用，绝不出网关所在的内网环境。
密钥轮换我们也做成自动化了。厂商密钥有个有效期，快到期时网关的密钥管理模块会自动获取新密钥，先以影子密钥的方式写入配置中心，验证连通性之后再切换主密钥。整个轮换过程中，业务方一次都不用重新配置，完全无感知。这个功能上线之后，我们的人力成本省了一大截——以前每隔几个月就要手动换一次上游 Key，还要找业务方确认更新完没有。
5.3 调用溯源与成本分摊：账本的元数据结构
最后是调用溯源。我们设计了一套完整的元数据结构，每条请求要么成功要么失败，但无论哪种情况都必须留下记录。字段包括 request_id、trace_id、调用的 API Key、对应的应用名、用户标识、模型别名、实际命中的物理模型、输入输出 Token、网关处理耗时、上游响应耗时、错误类型。这些数据会同时进入两个管道：一个管道用于实时监控告警，另一个管道落到数据仓库做离线分析。
成本分摊就建立在这个账本之上。每到月底，平台依据这一个月的事件流数据，按"应用 x 模型"维度聚合成成本报表，自动推送给各业务团队。以前没有网关的时候，成本数据分散在各家模型服务商的后台里，拉出来以后还得手工对账，误差率很高。现在每个团队打开报表就能看到自己用了哪些模型、各花了多少钱、有没有异常调用（比如某天 Token 消耗突然暴涨），成本一目了然。这里我特别建议想搭网关的朋友，计量元数据一开始就要设计好扩展字段，否则后期加字段要迁移历史数据，痛苦程度超出想象。
6. 真实踩坑复盘：网关上线前后我们交过的学费
6.1 HTTP 状态码的语义污染与重试风暴
网关承接的请求多了以后，我们发现一个非常隐蔽的问题：上游服务商的 HTTP 状态码语义不统一。比如有的服务商用 429 表示限流，有的用 429 表示账户余额不足，还有的用 503 表示模型正在加载、但其他服务商 503 却意味着服务彻底不可用。如果我们把这些状态码直接透传给业务方，业务方就得针对每一个上游的不同语义写不同的兜底逻辑，七嘴八舌的适配需求会让我们疯掉。
后来我们定了个铁律：网关对外只使用一套标准化错误码，把上游的状态码在适配层归一化。比如统一用rate_limit_exceeded表示限流，model_not_found表示模型不存在，upstream_unavailable表示上游不可用。上游原始状态码和错误信息只放到日志和响应头的扩展字段里，调试时可以看，但业务方不需要知道。这个决策直接终结了"业务方挨个适配上游错误码"的混乱局面。
重试风暴前面提过一嘴，这里展开讲一下经过。早期我们对超时重试没有加随机抖动，且重试次数设置得偏高，在一次模型服务商故障中，成千上万个并发请求在第一次超时后同时进入重试，相当于把故障放大了一倍多。后来我们在重试策略里强制引入"指数退避加抖动"：第一次重试等待 200ms 到 400ms 之间的随机值，第二次重试等待 400ms 到 800ms，超过两次就不再重试。从那次之后，我们再没遇到过重试风暴。
6.2 SSE 断流后，客户端状态失控
这是流式场景下的一个经典坑。客户端通过网关调用模型，网关把上游 SSE 流实时转发给客户端；某次上游连接意外断开，网关已经收到了 70% 的响应内容，但客户端不知道"流已经断了"——因为连接看起来只是关闭了，并没有按约定发送结束标记。客户端一直等到超时，才给用户弹了个"生成失败"。可实际上前面 70% 的内容是可以用的，直接丢弃非常可惜。
我们的修复方案是：网关转发 SSE 流时，在结束位置上做补偿。具体来说，适配器观察到上游流中断后，会先尝试补齐语义不完整的最后一个分片（比如补上半个引号、补上缺失的结束标记），然后发送一个标准格式的finish_reason为interrupted的结束事件，再关闭连接。客户端收到这个事件后就知道"这次生成是被打断的，但已生成内容可用"，可以选择保留已显示内容，而不是整段作废。这个改动的代码量不大，但对流式场景的用户体验提升非常明显。我们内部测试时，那些"答到一半断网"的请求，重新生成的比例从接近 100% 降到不足 20%。
6.3 网关自身的过载：热路径上的"慢性毒药"
网关上线初期的另一个隐形问题，是我们在转发路径上加了太多"看似轻量"的操作。比如每个请求都要打四条日志、更新三次缓存、跑一遍敏感词过滤、再做一次响应体 JSON 校验。单看每一项都微不足道，但在每秒几千请求的规模下，P99 延迟肉眼可见地被拖高。
后来我们做了性能剖析，发现最耗时的不是模型调用本身，而是网关内部多余的 JSON 序列化和反序列化。有些适配器贪图代码简单，把请求体先转成 map 再转成目标格式，来回折腾了好几次。优化的时候我们把热路径上的所有操作列了一个清单，逐个问"这件事必须同步做吗？能不能异步？能不能批量？"。最终砍掉了响应体的二次解析，把埋点日志改成异步批量上报，把不依赖请求内容的配置类查询全部前置缓存。优化完以后网关的 P99 额外延迟从 60 毫秒降到了 20 毫秒以内。这件事给我的教训是：网关代码的第一优先级不是可读性，而是热路径上的资源效率；业务代码可以写得优雅，网关的转发链路每一毫秒都要斤斤计较。
6.4 别把"健康检查"做成"狼来了"
最后一个值得分享的坑是健康检查的设计。网关需要对上游物理模型做健康探测，但我们一开始用的是"定期发一个最小请求"的方式，结果上游对这个探测请求也是真实计费的，而且会污染我们自己的调用统计。更严重的是，有些模型面对这种探测请求会返回"OK"但实际推理能力已经异常（比如被迫降级到一个小模型），导致健康检查显示正常、真实请求却一直在失败。
后来我们改成了"被动健康检查"为主：不主动探测，而是根据真实流量的成功率、平均延迟、错误分布来动态计算健康分。只有当一段窗口内完全没有任何流量且业务上确实需要这个模型可用时，才手动触发一次主动探测。这个机制上线后，误判导致的"以为上游健康、实则已故障"的情况大幅减少。网关的运行状态我每天只看三个指标：整体请求成功率、P99 延迟、限流触发次数，其他数据全部交给告警规则去盯。
7. 写在最后：这套网关给我最大的三个认知
如果只让我说三件事，我会这样总结：第一，协议适配层是整个网关的价值核心，技术含量不在转发，而在"翻译"——翻译做得好，200 个模型就只是一张表格；第二，流式场景下的中间处理能力是自研网关区别于普通反向代理的分水岭，没有这个需求，直接上开源网关可能更省事；第三，计量和观测体系必须和网关同步建设，账目清楚才能让业务方放心把核心链路托付给你。
从 0 到 1 搭起这个网关，我最大的体会是：架构设计里最难的不是选型，而是定义边界。哪些事归网关管、哪些事不归网关管，想清楚这两件事，后面 80% 的决策都会变得简单。现在我们的业务方接入一个新模型，最快的只需要补充一份适配配置，走一遍自动联调用例，基本不用动代码。希望这套思路对你也有参考价值，特别是正在被"模型五花八门、团队各连各的"问题折磨的朋友。
