1. 为什么非要自己搭一套网关：被200个接口逼出来的现实选择1.1 从第30个模型开始，痛点开始失控去年年初我们团队负责公司内部的AI能力平台，一开始只接了几个模型，业务方直接调用倒也相安无事。但等到模型数量超过30个之后，问题就压不住了——不是某一个环节难受，而是每个环节都在恶心你。首先是接入成本。每个模型厂商或开源项目的API格式都不一样：有的用JSON-RPC，有的走RESTful，有的参数叫max_tokens，有的叫max_new_tokens，有的还分prompt和messages。认证方式也五花八门，有Static Token、有签名、甚至还有每隔一段时间轮换的动态密钥。业务团队每接一个新模型，就要写一遍适配层、调试一遍鉴权、研究一遍错误码。最离谱的是同一个模型，A同学接了一遍对话接口，B同学又接了一遍向量化接口，两个人各写各的，代码还风格迥异。其次是变动频率。模型版本升级、服务端参数调整、接口废弃，这些消息层层传递到业务方手里时往往已经滞后一两天。我们统计过，模型方发一次不兼容更新，波及的调用方平均有7个。每次都要拉个群、对个表、发个公告，然后等各团队排期改代码。最让我决定动工的是度量问题。老板问"这个月各家模型的调用量、成本、各业务线消耗分别是多少"，我们发现根本答不上来。没有统一收口，每个团队自己记账、自己报关，口径还不一样，人工汇总一次要一整天，出来的数字也经不起审计。1.2 为什么没直接买现成的API管理平台我们也讨论过采购方案。市面上成熟的API网关产品不少，但细看下来都不满足我们的核心诉求。一是模型动态上下架的诉求。我们要接的是快速迭代中的AI模型，可能这周新上一个开源模型、下周某个商用模型调整了定价，网关必须支持灵活的模型注册与下线，而不是像传统API管理那样需要走复杂的发布流程。二是多级成本分摊。我们不是简单做个转发，而是要精确计算每个租户、每个业务线、每个模型下的token消耗与费用。这个粒度很多现成平台做不到，做得到的又贵得离谱。三是私有化部署要求。模型数据涉及业务敏感信息，网关必须部署在内网环境，还要支持与公司已有的统一身份认证、监控告警系统打通。核算了一下：自研核心网关两个后端加一个前端，大概3个人力投入，开发周期两个半月，后续每周大约10%的运维精力。比起采购产品的授权费、定制开发和长期依赖，这笔账是划算的。而且架构掌握在自己手里，后面想怎么扩展都不受制于人。2. 顶层架构设计：数据面、控制面、管理面三面分离2.1 三个平面的职责划分整个网关的架构核心理念是"三面分离"。这个思路借鉴了服务网格的分层思想，但要简单得多，因为我们的可观测性和配置管理需求远没有服务网格那么复杂。平面核心职责关键组件性能/管理要求数据面请求接收、路由、协议转换、限流、转发网关节点集群低延迟，纯转发逻辑，无业务状态控制面模型注册、配置下发、路由表同步、开关管理配置中心、模型注册服务最终一致性即可，不参与流量路径管理面租户管理、配额设置、账单生成、审计日志管理后台、报表服务面向运营人员，延迟不敏感为什么这么分？因为流量路径上的组件最怕的就是"变更"和"重逻辑"。数据面如果承担了太多管理功能，一次配置刷写就可能拖垮转发性能。我们的原则是：数据面只做最纯粹的转发决策，所有需要计算和存储的逻辑一律上抛到控制面和管理面。2.2 网关节点内部的处理流水线单个网关节点内部，请求处理是一条清晰的流水线，顺序是固定的：TLS终止与身份识别API Key校验与租户定位请求级限流检查模型路由匹配协议转换与参数映射后端模型调用响应转换与流式转发这里有个细节值得展开：限流检查放在路由之前。原因很简单，限流失败时我们可以直接返回一个短错误码，不必再走一遍模型路由逻辑，省掉一次不必要的链路计算。这在高并发场景下能省不少CPU。网关节点本身是无状态的，路由表和模型配置全从控制面拉取并缓存到本地内存。节点之间不互相通信，也没有会话粘滞的需求。好处是水平扩容极其简单，前面挂个负载均衡器，后面加节点就行。2.3 关键选型与思考过程网关节点我们用了异步IO模型为主的语言框架，纯粹为了在高并发下用更少的线程资源扛住更多连接。实际上手后确实省心，8核心16G的容器，单节点稳定扛住每秒8000以上的请求，CPU余量还很充足。配置中心选型时，一开始用了关系型数据库加轮询更新的方案。模型少的时候问题不大，但模型数量超过100个后，配置更新到所有节点需要10秒左右。后来换成了配置发布订阅模式，控制面写入配置后立即推送，网关节点监听变更并热加载。实测配置生效时间从10秒降到1秒以内。模型注册和路由表存储在关系型数据库中，但数据面节点只缓存不直查。所以数据库的压力极小，瓶颈完全不在存储层。3. 模型路由层：把"该调谁"从业务代码里彻底剥离3.1 模型注册表：给每个模型打上语义标签路由层是整个网关的灵魂。说白了，我们要解决的核心问题是：调用方发来一个请求，网关如何决定把这个请求转发给哪个模型？最粗暴的做法是用一个映射表，model_name对应到具体后端地址。但这是不够的，因为场景下还要考虑能力类型、上下文窗口、价格、可用性等多个维度。所以我们的模型注册表是一个带能力标签的结构化条目：{ "model_id": "text-gen-llm-a", "display_name": "大规模文本生成模型A", "capabilities": ["chat", "completion", "stream"], "context_window": 32768, "max_output_tokens": 4096, "pricing": { "input_per_million_tokens": 0.8, "output_per_million_tokens": 2.4 }, "backend": { "type": "openai_compatible", "base_url": "http://internal-model-a.example.local/v1", "auth_mode": "static_token", "timeout_ms": 60000 }, "status": "active", "tags": ["general", "high_quality", "chinese_support"] }这里的关键不是字段本身，而是这些字段会被路由策略引用。比如capabilities决定了哪些类型的请求可能路由到这个模型；pricing在做成本感知路由时使用；status控制了模型是否参与流量分配。3.2 三层路由策略我们实现了三层路由，按优先级从高到低排列：**第一层：显式路由。**调用方在请求里明确指定model_id，网关完全尊重调用方的选择，不做任何干预。这适合业务方已经做了充分调研、明确知道自己要用哪个模型的情况。显式路由下我们只做权限校验——检查该租户是否被授权使用这个模型。**第二层：语义路由。**调用方不指定具体模型，而是声明任务意图，比如"我想做一个中文摘要任务"。网关根据tags和capabilities匹配出候选模型列表，再按租户的默认模型配置选出一个。这一层是为了降低业务方的接入认知负担，把"选模型"这个事从业务代码里剥离。**第三层：动态路由。**在候选模型列表里，实时考虑每个模型的健康状态、当前延迟、价格系数，按综合得分选择最优目标。比如两个模型都支持文本生成，一个P99延迟40ms但价格贵，另一个P99延迟80ms但价格便宜一半，动态路由会根据租户配置的成本敏感度来做取舍。三层路由的优先级设计是有意的：显式路由满足强需求，语义路由降低使用门槛，动态路由实现最优调度。实际运行下来，大概40%的流量走显式路由，50%走语义路由，剩下10%走动态路由。语义路由占比这么高，说明业务方其实是愿意把选择权交出来的，前提是网关足够可靠。3.3 模型版本管理与灰度切流模型厂商更新版本是家常便饭，但直接全量替换很容易出事故。我们做了一个简单的版本生命周期：preview（预览）、active（正式）、deprecated（弃用）。新版本模型先以preview状态注册，只允许显式路由的调用方通过特殊参数访问。验证没问题后，管理员在控制面把它切到active，并配置灰度流量比例——比如先给5%的语义路由流量，观察错误率和延迟指标，逐步提升到20%、50%、100%。灰度切流是整个系统里最受欢迎的功能之一。以前模型升级，业务方的对接群要折腾一整天；现在只要配置一条规则，几分钟内完成流量切换，出了问题一键回滚到旧版本。这个能力让网关团队成了"最受欢迎的基础设施组"。4. 协议转换层：200个模型的差异全在这一层消化4.1 内部统一协议：选对标准省一半工作量协议转换层要解决的核心矛盾是：200多个模型的API千奇百怪，但网关向上提供给业务方的接口必须是一致的、稳定的。我们选定的内部统一协议是业界目前最通用的对话接口格式——就是那个messages数组、model字段、temperature、max_tokens那套结构。为什么选它？因为它已经是事实标准，几乎所有开源模型都能通过适配层转换成这套格式，而且公司内部的技术同学对它最熟悉，业务方拿到接口文档几乎不需要额外学习成本。所有模型接入时，都要写一个适配器，把外部API格式转换到内部统一协议。这个适配器的粒度是"每一个模型一条"，但很多模型复用了同一个协议类型，所以实际的适配器数量远小于模型数量。4.2 参数映射：一个容易被低估的细节参数映射远没有表面上那么简单。拿temperature来说，不同模型的默认值范围不一样：有的取值范围是0到1，有的允许0到2，还有的模型根本不支持这个参数，而是用top_p控制生成随机性。如果网关不做处理，直接把调用方传的0.7原样透传，结果可能完全不符合预期。我们维护了一张参数映射表，对每个模型声明哪些参数支持、支持的取值范围、默认值是多少，以及参数不存在时如何处理。映射表在模型注册时配置，运行时由适配器解释执行。这里踩过一个很深的坑：有一个模型的max_tokens语义是"本次生成的最大tokens数"，而另一个模型的同名参数语义是"输入加输出的总tokens上限"，两个语义差了接近一倍。如果网关不做语义转换，调用方用同样的配置调两个模型，输出的长度会差很大，用户以为是模型质量问题，其实是参数语义不同导致的。后来我们在协议转换层把这个参数做了一次口径归一化，统一为"生成的最大tokens数"，避免业务方感知到底层差异。4.3 流式输出：SSE的统一封装流式输出是AI模型调用里最让人头疼的协议转换场景。流式接口的格式各不相同，常见的有纯文本增量、JSON增量、甚至二进制帧。我们的做法是：内部统一协议对业务方承诺标准SSE格式，事件类型固定为delta事件，内容统一为增量文本。适配器负责把后端的各种流式格式转换成这个规范。对于不支持流式的模型，网关做了"伪流式"兜底——等完整结果返回后，按字符分批推给调用方，让体验上像是流式输出。伪流式方案在多数场景下够用，但它有个隐藏缺陷：首字延迟会比真流式慢一个完整生成周期。对于对实时性要求极高的场景（比如客服对话），我们专门在路由层做了标记，优先选择支持真流式的模型，避免业务体验到这种延迟。4.4 错误码归一化：从各说各话到统一口径不同模型的错误码千差万别：有的返回HTTP 400，有的返回200但错误码在业务字段里，还有的干脆直接断连。调用方如果直接消费这些错误信息，写出来的catch逻辑根本没法看。我们定义了一套内部标准错误码，只包含十来个错误类型：内部错误码含义常见触发原因网关是否重试RATE_LIMITED触发限流租户配额耗尽否MODEL_TIMEOUT模型响应超时后端生成时间过长是，最多1次MODEL_OVERLOADED模型服务过载模型端正在处理大量请求是，最多2次INVALID_PARAMETER参数不合法请求超出上下文窗口否AUTH_FAILED鉴权失败API Key无效否MODEL_NOT_FOUND模型不存在model_id拼写错误否MODEL_DEPRECATED模型已下线调用了弃用模型否REMOTE_SERVER_ERROR远端内部错误模型端服务异常是，最多1次GATEWAY_INTERNAL网关内部错误路由表缺失等否适配器负责把所有外部错误映射到这套标准码，同时把原始错误信息记录到审计日志。业务方只需要处理这十来个错误码，不用再关心底层模型方那些天书一样的错误字段。5. 多租户治理：认证、限流、配额、计量一条链5.1 从单Key到四级配额体系网关要服务多个业务线、多个应用，每个调用方都是独立租户。我们建立了四级配额体系，从粗到细层层收敛：全局配额：整个网关的兜底水位，防止单租户异常流量拖垮全局。租户配额：每个租户的总调用额度，按模型类型分别计量。模型配额：租户在某个具体模型上的调用上限，防止某个业务线独占热门模型。单请求限流：针对单位时间的请求速率限制，防止突发冲击。每一级配额的实现是独立的，取交集生效。也就是说，一个请求要同时通过四级检查才能继续往下走。任何一级触发限流，直接返回标准的RATE_LIMITED错误，并携带建议等待时间。5.2 限流算法的取舍限流算法我们混合使用了令牌桶和滑动窗口。整体思路是：请求速率用滑动窗口，突发控制用令牌桶。滑动窗口适合统计"过去一分钟内这个租户调了多少次"，做配额校验；令牌桶适合平滑突发流量，让租户在配额充足时可以短暂加速但不能无限突刺。两层叠加后，既不会因为突发把下游模型打死，也不会浪费配额。具体参数上，我们为每个租户配置基础速率和突发桶容量。比如某内部应用的基础速率是每分钟600次请求，突发桶容量是200。这意味着它可以短时间冲到800次/分钟，但持续超过600就会被反向压制。这些参数一开始是手工配置，后来发现经验值大概在"基础速率=历史峰值×1.2，突发容量=基础速率÷3"附近，就做了个自动建议功能。5.3 计量计费：token级别的成本核算AI网关和其他API网关最大的差别在于：成本不只取决于调用次数，还取决于token消耗量。同样的一个对话请求，上下文长和短的成本差距可能有几十倍。所以我们必须做token级别的计量。网关在协议转换层记录每个请求的输入token数和输出token数，结合模型单价计算成本。计数方式有两个选择：一是从模型返回的用量字段里拿，二是网关自己用分词器估算。大多数模型会返回准确的用量数据，首选方案是用返回值；遇到不返回用量的模型，我们会内置分词器近似估算，精度通常在95%以上。成本数据进入管理面后，按月生成各租户的账单报表。报表维度包括：模型、调用次数、输入token总量、输出token总量、估算成本、按业务线的二级分摊。这个功能上线后，老板再问成本时，我们只需要打开报表页面，而不是人工拼数据。5.4 审计日志：每一个请求都可追溯审计日志最初不受重视，后来在一次线上故障排查中发挥了关键作用，从此成为标配。每条日志包含：请求ID、租户ID、调用方应用、请求的模型ID、输入token数、输出token数、响应耗时、错误码、时间戳。日志量非常可观，峰值时每天数亿条。我们采用异步批量写入，网关节点只把结构化日志放到内存缓冲队列，由后台线程批量刷到日志存储。存储层按天分表，保留90天，过期自动清理。查询侧按照租户和模型做了二级索引，大多数审计查询都能在秒级返回。6. 高可用与故障转移：模型挂了，业务不能跟着挂6.1 主动健康检查与被动熔断模型服务不可能永远稳定，宕机、限流、版本回退都是家常便饭。网关必须有能力感知并规避故障。我们采用了主动加被动双层检测机制。主动健康检查：每个网关节点周期性向后端模型服务发送探活请求，频率默认每30秒一次。探活采用轻量级接口，比如/health或/models，开销很小。连续三次探活失败，模型自动标记为unhealthy，从路由候选列表中摘除。被动熔断：仅靠主动检查不够，因为探活成功不代表实际请求就顺利。我们为每个模型维护一个滑动窗口错误率统计，窗口期默认1分钟。当窗口内错误率超过50%且失败请求数超过10个，触发熔断，模型在短时间内（默认30秒）不会参与新流量路由。这期间网关节点会持续放少量探测请求，如果连续成功，逐步恢复模型权重。双机制配合的效果很显著：某次模型厂商推送了一个坏版本，服务端开始大面积返回500，主动探活还没发现问题，被动熔断已经在60秒内把流量切走了。业务方几乎没有感知到异常。6.2 自动重试怎么设计才安全重试是一把双刃剑。重试太多，故障模型会被打得更惨；重试太少，偶发失败又会让调用方感受到抖动。我们的重试策略严格绑定错误码：MODEL_TIMEOUT：可以重试，但最多1次，且必须换后端实例。MODEL_OVERLOADED：可以重试，最多2次，第二次重试前等待500毫秒，给模型端喘息时间。REMOTE_SERVER_ERROR：可以重试，最多1次，因为服务端内部错误可能是偶发状态。其他错误码一律不重试。重试时还有一个重要细节：重试的请求必须换节点。同一个网关节点到同一个后端实例的连接可能已经处于异常状态，继续重试大概率还是失败。我们让路由层记录上次失败的实例ID，重试时排除它。这个小改动把重试成功率从60%提升到了85%。6.3 降级方案：没有备胎时怎么办不是所有模型都能找到备胎。有些模型是独占的、不可替代的，比如公司内部微调的业务专用模型。这种情况下故障转移机制不适用，只能降级。降级分三个等级：缓存降级、简化降级、明确失败。缓存降级适合那些"结果可缓存"的场景，比如固定问题的问答、分类结果。网关在模型正常时把响应缓存起来，设置过期时间（一般5分钟）。模型故障时，如果请求能命中缓存，直接返回缓存结果，代价是时效性稍差。简化降级适合"不需要最强模型"的场景。比如某租户默认用的是效果最好的大模型，但它挂了，网关自动切到候选的轻量级模型。这对那种"效果可以略降但不能完全不可用"的业务非常实用。明确失败是最后的兜底。直接返回MODEL_TIMEOUT或MODEL_OVERLOADED，附带清晰的错误说明，引导调用方自行处理。有时候诚实比硬撑更有价值。这三个降级等级在管理面按模型配置，每个模型可以声明自己的降级策略和降级目标。配置好后，故障时网关自动按策略执行，不需要人工介入。7. 性能压测与调优实录7.1 网关引入后到底增加了多少延迟引入网关最大的担忧就是性能损耗。网关作为中间层，每一个请求都要多一跳，如果处理效率不高，业务方会直接感受到变慢。我们定的性能目标是：网关自身处理延迟P99小于15毫秒。不包含模型端生成时间，只看网关从收到请求到转发给后端、再收到响应返回给调用方的这一跳。压测环境：8核16G的容器节点，接入的模拟后端延迟固定为20毫秒，压测工具模拟真实流量场景，混合了对话请求和流式请求。场景QPS网关附加延迟P50网关附加延迟P99非流式请求50002.3ms7.8ms非流式请求100003.1ms11.2ms流式请求30003.8ms12.5ms混合场景80003.5ms13.9ms实测结果在目标范围内。这个成绩是在开启全部功能（限流、审计日志、协议转换）的情况下测得的，没有为了跑分关闭组件。7.2 调优过程中印象最深的三个优化点第一个是连接池复用。网关到后端的HTTP连接如果每次都新建，TCP握手开销会让P99飙升。我们为每个后端模型维护一个连接池，默认每个池保留200个空闲连接，复用率上去了，P99降了30%左右。但连接池也不是越大越好，太大会占用大量文件描述符，反而在节点重启时出现端口耗尽。后来把空闲连接设了一个闲置60秒自动回收的策略，稳定很多。第二个是零拷贝日志缓冲。审计日志最初是每条请求同步写一次，压测时发现这个操作占用了约15%的CPU。改成批量异步写入后，CPU占用降到3%以下。但这个优化有一个代价：崩溃时可能丢失最后几秒的日志。经过评估可以接受，因为日志丢失概率极低，而查日志的频率远低于线上故障的严重性。第三个是路由表本地缓存。最初每次请求都从配置中心拉取路由信息，虽然配置中心本身性能不差，但网络开销叠加后延迟明显。改成节点启动时全量加载到本地内存、运行中监听配置变更增量更新后，路由查找从一次远程调用变成一次内存哈希查找，延迟从毫秒级降到微秒级。7.3 容量规划经验容量规划的核心不是算峰值，而是算峰值时的余量。我们的经验公式是：节点数 = 预估峰值QPS ÷ 单节点安全QPS ÷ 冗余系数。其中单节点安全QPS取压测结果的70%（留出CPU余量应对突发和GC抖动），冗余系数取1.5（保证单节点故障时其他节点能扛住流量）。按这个公式，承载12万峰值QPS我们需要约25个节点，实际部署30个，留了一点buffer。容量规划还需要考虑流式请求的特殊性。流式请求虽然QPS不高，但连接时间长，同时占用的内存更大。我们统计过，一个持续30秒的流式请求消耗的内存约等于4个普通请求。所以在容量评估里，我们引入了"等效QPS"的概念：普通请求权重1，流式请求权重4。这个方法让容量估算的准确度提高了不少。8. 踩过的坑与落地建议8.1 五个印象最深的坑坑表面原因根因解法配置下发后路由不一致节点热加载有延迟各节点拉取配置的时间不同步发布流程增加"等待所有节点确认"步骤模型响应超时误判超时时间设置统一为30秒不同模型生成长文本耗时可差5倍超时时间改为模型注册表可配置错误码映射出错适配器里映射表少了一行新模型接入时漏填错误码映射接入流程增加映射完整性校验限流误伤正常流量令牌桶参数过紧突发桶容量设得太小调大突发桶，同时增加滑动窗口兜底流式连接泄漏调用方中途断开连接网关未及时取消后端请求监听调用方断开事件，主动取消后端调用第一个坑最有代表性。上线初期，某个模型的配置更新后，部分节点的路由还是旧版本，导致请求打到已下线的实例上。排查时发现是配置下发后各节点拉取时间差导致的不一致。后来我们在发布流程里加了一步"同步确认"：控制面下发配置后，等待所有在线节点确认收到，才标记配置生效。这个机制保障了所有节点在同一版本上运行。8.2 如果只让我给三条建议第一条：**先定协议标准，再谈模型接入。**内部统一协议是整个网关的中枢神经，必须在接入第5个模型之前就定下来。没有统一协议，后面每接入一个模型就多一分混乱。第二条：**限流和计量一开始就必须设计。**很多网关项目先跑通转发，再补限流和计量，结果后面发现限流做不进去了、计量数据对不上账。这两块涉及数据埋点，中途加会非常痛苦，一定要从第一天就设计好。第三条：**给模型接入留一个"适配器模式"。**不要为每个模型写一套独立的接入代码，而是抽象出"协议类型"这个维度，每个协议类型写一个适配器，同类模型自动复用。我们的200多个模型只写了20多个适配器，就是因为这个模式省了大量重复工作。8.3 网关上线半年后的真实体会网关上线三个月后，我们已经把内部的AI能力调用完全收敛到平台之上，新的模型接入不再需要业务方配合改造，平均接入时间从之前的3到5天压缩到4小时左右，其中大部分时间还花在等待模型方提供访问凭证上。我最深的体会是：统一网关的价值不是"少写几个适配器"这个层面，而是让业务方把注意力从"怎么调用模型"转移到"怎么用好模型"上。以前每次模型变更，业务方要跟着改代码、做测试；现在模型变更被网关消化掉了，业务方完全无感知。这种稳定感带来的信任，比任何技术指标都值钱。最后分享一个实测的小技巧：如果你也要做类似网关，强烈建议在管理面加一个"路由可视化"页面，把每个请求的路由路径、耗时、模型命中情况实时画出来。排查问题的时候，能直接在界面上看到流量走向，比翻日志高效太多。这个功能的开发工作量不大，但回报率极高。
1. 为什么非要自己搭一套网关：被200个接口逼出来的现实选择1.1 从第30个模型开始，痛点开始失控去年年初我们团队负责公司内部的AI能力平台，一开始只接了几个模型，业务方直接调用倒也相安无事。但等到模型数量超过30个之后，问题就压不住了——不是某一个环节难受，而是每个环节都在恶心你。首先是接入成本。每个模型厂商或开源项目的API格式都不一样：有的用JSON-RPC，有的走RESTful，有的参数叫max_tokens，有的叫max_new_tokens，有的还分prompt和messages。认证方式也五花八门，有Static Token、有签名、甚至还有每隔一段时间轮换的动态密钥。业务团队每接一个新模型，就要写一遍适配层、调试一遍鉴权、研究一遍错误码。最离谱的是同一个模型，A同学接了一遍对话接口，B同学又接了一遍向量化接口，两个人各写各的，代码还风格迥异。其次是变动频率。模型版本升级、服务端参数调整、接口废弃，这些消息层层传递到业务方手里时往往已经滞后一两天。我们统计过，模型方发一次不兼容更新，波及的调用方平均有7个。每次都要拉个群、对个表、发个公告，然后等各团队排期改代码。最让我决定动工的是度量问题。老板问"这个月各家模型的调用量、成本、各业务线消耗分别是多少"，我们发现根本答不上来。没有统一收口，每个团队自己记账、自己报关，口径还不一样，人工汇总一次要一整天，出来的数字也经不起审计。1.2 为什么没直接买现成的API管理平台我们也讨论过采购方案。市面上成熟的API网关产品不少，但细看下来都不满足我们的核心诉求。一是模型动态上下架的诉求。我们要接的是快速迭代中的AI模型，可能这周新上一个开源模型、下周某个商用模型调整了定价，网关必须支持灵活的模型注册与下线，而不是像传统API管理那样需要走复杂的发布流程。二是多级成本分摊。我们不是简单做个转发，而是要精确计算每个租户、每个业务线、每个模型下的token消耗与费用。这个粒度很多现成平台做不到，做得到的又贵得离谱。三是私有化部署要求。模型数据涉及业务敏感信息，网关必须部署在内网环境，还要支持与公司已有的统一身份认证、监控告警系统打通。核算了一下：自研核心网关两个后端加一个前端，大概3个人力投入，开发周期两个半月，后续每周大约10%的运维精力。比起采购产品的授权费、定制开发和长期依赖，这笔账是划算的。而且架构掌握在自己手里，后面想怎么扩展都不受制于人。2. 顶层架构设计：数据面、控制面、管理面三面分离2.1 三个平面的职责划分整个网关的架构核心理念是"三面分离"。这个思路借鉴了服务网格的分层思想，但要简单得多，因为我们的可观测性和配置管理需求远没有服务网格那么复杂。平面核心职责关键组件性能/管理要求数据面请求接收、路由、协议转换、限流、转发网关节点集群低延迟，纯转发逻辑，无业务状态控制面模型注册、配置下发、路由表同步、开关管理配置中心、模型注册服务最终一致性即可，不参与流量路径管理面租户管理、配额设置、账单生成、审计日志管理后台、报表服务面向运营人员，延迟不敏感为什么这么分？因为流量路径上的组件最怕的就是"变更"和"重逻辑"。数据面如果承担了太多管理功能，一次配置刷写就可能拖垮转发性能。我们的原则是：数据面只做最纯粹的转发决策，所有需要计算和存储的逻辑一律上抛到控制面和管理面。2.2 网关节点内部的处理流水线单个网关节点内部，请求处理是一条清晰的流水线，顺序是固定的：TLS终止与身份识别API Key校验与租户定位请求级限流检查模型路由匹配协议转换与参数映射后端模型调用响应转换与流式转发这里有个细节值得展开：限流检查放在路由之前。原因很简单，限流失败时我们可以直接返回一个短错误码，不必再走一遍模型路由逻辑，省掉一次不必要的链路计算。这在高并发场景下能省不少CPU。网关节点本身是无状态的，路由表和模型配置全从控制面拉取并缓存到本地内存。节点之间不互相通信，也没有会话粘滞的需求。好处是水平扩容极其简单，前面挂个负载均衡器，后面加节点就行。2.3 关键选型与思考过程网关节点我们用了异步IO模型为主的语言框架，纯粹为了在高并发下用更少的线程资源扛住更多连接。实际上手后确实省心，8核心16G的容器，单节点稳定扛住每秒8000以上的请求，CPU余量还很充足。配置中心选型时，一开始用了关系型数据库加轮询更新的方案。模型少的时候问题不大，但模型数量超过100个后，配置更新到所有节点需要10秒左右。后来换成了配置发布订阅模式，控制面写入配置后立即推送，网关节点监听变更并热加载。实测配置生效时间从10秒降到1秒以内。模型注册和路由表存储在关系型数据库中，但数据面节点只缓存不直查。所以数据库的压力极小，瓶颈完全不在存储层。3. 模型路由层：把"该调谁"从业务代码里彻底剥离3.1 模型注册表：给每个模型打上语义标签路由层是整个网关的灵魂。说白了，我们要解决的核心问题是：调用方发来一个请求，网关如何决定把这个请求转发给哪个模型？最粗暴的做法是用一个映射表，model_name对应到具体后端地址。但这是不够的，因为场景下还要考虑能力类型、上下文窗口、价格、可用性等多个维度。所以我们的模型注册表是一个带能力标签的结构化条目：{ "model_id": "text-gen-llm-a", "display_name": "大规模文本生成模型A", "capabilities": ["chat", "completion", "stream"], "context_window": 32768, "max_output_tokens": 4096, "pricing": { "input_per_million_tokens": 0.8, "output_per_million_tokens": 2.4 }, "backend": { "type": "openai_compatible", "base_url": "http://internal-model-a.example.local/v1", "auth_mode": "static_token", "timeout_ms": 60000 }, "status": "active", "tags": ["general", "high_quality", "chinese_support"] }这里的关键不是字段本身，而是这些字段会被路由策略引用。比如capabilities决定了哪些类型的请求可能路由到这个模型；pricing在做成本感知路由时使用；status控制了模型是否参与流量分配。3.2 三层路由策略我们实现了三层路由，按优先级从高到低排列：**第一层：显式路由。**调用方在请求里明确指定model_id，网关完全尊重调用方的选择，不做任何干预。这适合业务方已经做了充分调研、明确知道自己要用哪个模型的情况。显式路由下我们只做权限校验——检查该租户是否被授权使用这个模型。**第二层：语义路由。**调用方不指定具体模型，而是声明任务意图，比如"我想做一个中文摘要任务"。网关根据tags和capabilities匹配出候选模型列表，再按租户的默认模型配置选出一个。这一层是为了降低业务方的接入认知负担，把"选模型"这个事从业务代码里剥离。**第三层：动态路由。**在候选模型列表里，实时考虑每个模型的健康状态、当前延迟、价格系数，按综合得分选择最优目标。比如两个模型都支持文本生成，一个P99延迟40ms但价格贵，另一个P99延迟80ms但价格便宜一半，动态路由会根据租户配置的成本敏感度来做取舍。三层路由的优先级设计是有意的：显式路由满足强需求，语义路由降低使用门槛，动态路由实现最优调度。实际运行下来，大概40%的流量走显式路由，50%走语义路由，剩下10%走动态路由。语义路由占比这么高，说明业务方其实是愿意把选择权交出来的，前提是网关足够可靠。3.3 模型版本管理与灰度切流模型厂商更新版本是家常便饭，但直接全量替换很容易出事故。我们做了一个简单的版本生命周期：preview（预览）、active（正式）、deprecated（弃用）。新版本模型先以preview状态注册，只允许显式路由的调用方通过特殊参数访问。验证没问题后，管理员在控制面把它切到active，并配置灰度流量比例——比如先给5%的语义路由流量，观察错误率和延迟指标，逐步提升到20%、50%、100%。灰度切流是整个系统里最受欢迎的功能之一。以前模型升级，业务方的对接群要折腾一整天；现在只要配置一条规则，几分钟内完成流量切换，出了问题一键回滚到旧版本。这个能力让网关团队成了"最受欢迎的基础设施组"。4. 协议转换层：200个模型的差异全在这一层消化4.1 内部统一协议：选对标准省一半工作量协议转换层要解决的核心矛盾是：200多个模型的API千奇百怪，但网关向上提供给业务方的接口必须是一致的、稳定的。我们选定的内部统一协议是业界目前最通用的对话接口格式——就是那个messages数组、model字段、temperature、max_tokens那套结构。为什么选它？因为它已经是事实标准，几乎所有开源模型都能通过适配层转换成这套格式，而且公司内部的技术同学对它最熟悉，业务方拿到接口文档几乎不需要额外学习成本。所有模型接入时，都要写一个适配器，把外部API格式转换到内部统一协议。这个适配器的粒度是"每一个模型一条"，但很多模型复用了同一个协议类型，所以实际的适配器数量远小于模型数量。4.2 参数映射：一个容易被低估的细节参数映射远没有表面上那么简单。拿temperature来说，不同模型的默认值范围不一样：有的取值范围是0到1，有的允许0到2，还有的模型根本不支持这个参数，而是用top_p控制生成随机性。如果网关不做处理，直接把调用方传的0.7原样透传，结果可能完全不符合预期。我们维护了一张参数映射表，对每个模型声明哪些参数支持、支持的取值范围、默认值是多少，以及参数不存在时如何处理。映射表在模型注册时配置，运行时由适配器解释执行。这里踩过一个很深的坑：有一个模型的max_tokens语义是"本次生成的最大tokens数"，而另一个模型的同名参数语义是"输入加输出的总tokens上限"，两个语义差了接近一倍。如果网关不做语义转换，调用方用同样的配置调两个模型，输出的长度会差很大，用户以为是模型质量问题，其实是参数语义不同导致的。后来我们在协议转换层把这个参数做了一次口径归一化，统一为"生成的最大tokens数"，避免业务方感知到底层差异。4.3 流式输出：SSE的统一封装流式输出是AI模型调用里最让人头疼的协议转换场景。流式接口的格式各不相同，常见的有纯文本增量、JSON增量、甚至二进制帧。我们的做法是：内部统一协议对业务方承诺标准SSE格式，事件类型固定为delta事件，内容统一为增量文本。适配器负责把后端的各种流式格式转换成这个规范。对于不支持流式的模型，网关做了"伪流式"兜底——等完整结果返回后，按字符分批推给调用方，让体验上像是流式输出。伪流式方案在多数场景下够用，但它有个隐藏缺陷：首字延迟会比真流式慢一个完整生成周期。对于对实时性要求极高的场景（比如客服对话），我们专门在路由层做了标记，优先选择支持真流式的模型，避免业务体验到这种延迟。4.4 错误码归一化：从各说各话到统一口径不同模型的错误码千差万别：有的返回HTTP 400，有的返回200但错误码在业务字段里，还有的干脆直接断连。调用方如果直接消费这些错误信息，写出来的catch逻辑根本没法看。我们定义了一套内部标准错误码，只包含十来个错误类型：内部错误码含义常见触发原因网关是否重试RATE_LIMITED触发限流租户配额耗尽否MODEL_TIMEOUT模型响应超时后端生成时间过长是，最多1次MODEL_OVERLOADED模型服务过载模型端正在处理大量请求是，最多2次INVALID_PARAMETER参数不合法请求超出上下文窗口否AUTH_FAILED鉴权失败API Key无效否MODEL_NOT_FOUND模型不存在model_id拼写错误否MODEL_DEPRECATED模型已下线调用了弃用模型否REMOTE_SERVER_ERROR远端内部错误模型端服务异常是，最多1次GATEWAY_INTERNAL网关内部错误路由表缺失等否适配器负责把所有外部错误映射到这套标准码，同时把原始错误信息记录到审计日志。业务方只需要处理这十来个错误码，不用再关心底层模型方那些天书一样的错误字段。5. 多租户治理：认证、限流、配额、计量一条链5.1 从单Key到四级配额体系网关要服务多个业务线、多个应用，每个调用方都是独立租户。我们建立了四级配额体系，从粗到细层层收敛：全局配额：整个网关的兜底水位，防止单租户异常流量拖垮全局。租户配额：每个租户的总调用额度，按模型类型分别计量。模型配额：租户在某个具体模型上的调用上限，防止某个业务线独占热门模型。单请求限流：针对单位时间的请求速率限制，防止突发冲击。每一级配额的实现是独立的，取交集生效。也就是说，一个请求要同时通过四级检查才能继续往下走。任何一级触发限流，直接返回标准的RATE_LIMITED错误，并携带建议等待时间。5.2 限流算法的取舍限流算法我们混合使用了令牌桶和滑动窗口。整体思路是：请求速率用滑动窗口，突发控制用令牌桶。滑动窗口适合统计"过去一分钟内这个租户调了多少次"，做配额校验；令牌桶适合平滑突发流量，让租户在配额充足时可以短暂加速但不能无限突刺。两层叠加后，既不会因为突发把下游模型打死，也不会浪费配额。具体参数上，我们为每个租户配置基础速率和突发桶容量。比如某内部应用的基础速率是每分钟600次请求，突发桶容量是200。这意味着它可以短时间冲到800次/分钟，但持续超过600就会被反向压制。这些参数一开始是手工配置，后来发现经验值大概在"基础速率=历史峰值×1.2，突发容量=基础速率÷3"附近，就做了个自动建议功能。5.3 计量计费：token级别的成本核算AI网关和其他API网关最大的差别在于：成本不只取决于调用次数，还取决于token消耗量。同样的一个对话请求，上下文长和短的成本差距可能有几十倍。所以我们必须做token级别的计量。网关在协议转换层记录每个请求的输入token数和输出token数，结合模型单价计算成本。计数方式有两个选择：一是从模型返回的用量字段里拿，二是网关自己用分词器估算。大多数模型会返回准确的用量数据，首选方案是用返回值；遇到不返回用量的模型，我们会内置分词器近似估算，精度通常在95%以上。成本数据进入管理面后，按月生成各租户的账单报表。报表维度包括：模型、调用次数、输入token总量、输出token总量、估算成本、按业务线的二级分摊。这个功能上线后，老板再问成本时，我们只需要打开报表页面，而不是人工拼数据。5.4 审计日志：每一个请求都可追溯审计日志最初不受重视，后来在一次线上故障排查中发挥了关键作用，从此成为标配。每条日志包含：请求ID、租户ID、调用方应用、请求的模型ID、输入token数、输出token数、响应耗时、错误码、时间戳。日志量非常可观，峰值时每天数亿条。我们采用异步批量写入，网关节点只把结构化日志放到内存缓冲队列，由后台线程批量刷到日志存储。存储层按天分表，保留90天，过期自动清理。查询侧按照租户和模型做了二级索引，大多数审计查询都能在秒级返回。6. 高可用与故障转移：模型挂了，业务不能跟着挂6.1 主动健康检查与被动熔断模型服务不可能永远稳定，宕机、限流、版本回退都是家常便饭。网关必须有能力感知并规避故障。我们采用了主动加被动双层检测机制。主动健康检查：每个网关节点周期性向后端模型服务发送探活请求，频率默认每30秒一次。探活采用轻量级接口，比如/health或/models，开销很小。连续三次探活失败，模型自动标记为unhealthy，从路由候选列表中摘除。被动熔断：仅靠主动检查不够，因为探活成功不代表实际请求就顺利。我们为每个模型维护一个滑动窗口错误率统计，窗口期默认1分钟。当窗口内错误率超过50%且失败请求数超过10个，触发熔断，模型在短时间内（默认30秒）不会参与新流量路由。这期间网关节点会持续放少量探测请求，如果连续成功，逐步恢复模型权重。双机制配合的效果很显著：某次模型厂商推送了一个坏版本，服务端开始大面积返回500，主动探活还没发现问题，被动熔断已经在60秒内把流量切走了。业务方几乎没有感知到异常。6.2 自动重试怎么设计才安全重试是一把双刃剑。重试太多，故障模型会被打得更惨；重试太少，偶发失败又会让调用方感受到抖动。我们的重试策略严格绑定错误码：MODEL_TIMEOUT：可以重试，但最多1次，且必须换后端实例。MODEL_OVERLOADED：可以重试，最多2次，第二次重试前等待500毫秒，给模型端喘息时间。REMOTE_SERVER_ERROR：可以重试，最多1次，因为服务端内部错误可能是偶发状态。其他错误码一律不重试。重试时还有一个重要细节：重试的请求必须换节点。同一个网关节点到同一个后端实例的连接可能已经处于异常状态，继续重试大概率还是失败。我们让路由层记录上次失败的实例ID，重试时排除它。这个小改动把重试成功率从60%提升到了85%。6.3 降级方案：没有备胎时怎么办不是所有模型都能找到备胎。有些模型是独占的、不可替代的，比如公司内部微调的业务专用模型。这种情况下故障转移机制不适用，只能降级。降级分三个等级：缓存降级、简化降级、明确失败。缓存降级适合那些"结果可缓存"的场景，比如固定问题的问答、分类结果。网关在模型正常时把响应缓存起来，设置过期时间（一般5分钟）。模型故障时，如果请求能命中缓存，直接返回缓存结果，代价是时效性稍差。简化降级适合"不需要最强模型"的场景。比如某租户默认用的是效果最好的大模型，但它挂了，网关自动切到候选的轻量级模型。这对那种"效果可以略降但不能完全不可用"的业务非常实用。明确失败是最后的兜底。直接返回MODEL_TIMEOUT或MODEL_OVERLOADED，附带清晰的错误说明，引导调用方自行处理。有时候诚实比硬撑更有价值。这三个降级等级在管理面按模型配置，每个模型可以声明自己的降级策略和降级目标。配置好后，故障时网关自动按策略执行，不需要人工介入。7. 性能压测与调优实录7.1 网关引入后到底增加了多少延迟引入网关最大的担忧就是性能损耗。网关作为中间层，每一个请求都要多一跳，如果处理效率不高，业务方会直接感受到变慢。我们定的性能目标是：网关自身处理延迟P99小于15毫秒。不包含模型端生成时间，只看网关从收到请求到转发给后端、再收到响应返回给调用方的这一跳。压测环境：8核16G的容器节点，接入的模拟后端延迟固定为20毫秒，压测工具模拟真实流量场景，混合了对话请求和流式请求。场景QPS网关附加延迟P50网关附加延迟P99非流式请求50002.3ms7.8ms非流式请求100003.1ms11.2ms流式请求30003.8ms12.5ms混合场景80003.5ms13.9ms实测结果在目标范围内。这个成绩是在开启全部功能（限流、审计日志、协议转换）的情况下测得的，没有为了跑分关闭组件。7.2 调优过程中印象最深的三个优化点第一个是连接池复用。网关到后端的HTTP连接如果每次都新建，TCP握手开销会让P99飙升。我们为每个后端模型维护一个连接池，默认每个池保留200个空闲连接，复用率上去了，P99降了30%左右。但连接池也不是越大越好，太大会占用大量文件描述符，反而在节点重启时出现端口耗尽。后来把空闲连接设了一个闲置60秒自动回收的策略，稳定很多。第二个是零拷贝日志缓冲。审计日志最初是每条请求同步写一次，压测时发现这个操作占用了约15%的CPU。改成批量异步写入后，CPU占用降到3%以下。但这个优化有一个代价：崩溃时可能丢失最后几秒的日志。经过评估可以接受，因为日志丢失概率极低，而查日志的频率远低于线上故障的严重性。第三个是路由表本地缓存。最初每次请求都从配置中心拉取路由信息，虽然配置中心本身性能不差，但网络开销叠加后延迟明显。改成节点启动时全量加载到本地内存、运行中监听配置变更增量更新后，路由查找从一次远程调用变成一次内存哈希查找，延迟从毫秒级降到微秒级。7.3 容量规划经验容量规划的核心不是算峰值，而是算峰值时的余量。我们的经验公式是：节点数 = 预估峰值QPS ÷ 单节点安全QPS ÷ 冗余系数。其中单节点安全QPS取压测结果的70%（留出CPU余量应对突发和GC抖动），冗余系数取1.5（保证单节点故障时其他节点能扛住流量）。按这个公式，承载12万峰值QPS我们需要约25个节点，实际部署30个，留了一点buffer。容量规划还需要考虑流式请求的特殊性。流式请求虽然QPS不高，但连接时间长，同时占用的内存更大。我们统计过，一个持续30秒的流式请求消耗的内存约等于4个普通请求。所以在容量评估里，我们引入了"等效QPS"的概念：普通请求权重1，流式请求权重4。这个方法让容量估算的准确度提高了不少。8. 踩过的坑与落地建议8.1 五个印象最深的坑坑表面原因根因解法配置下发后路由不一致节点热加载有延迟各节点拉取配置的时间不同步发布流程增加"等待所有节点确认"步骤模型响应超时误判超时时间设置统一为30秒不同模型生成长文本耗时可差5倍超时时间改为模型注册表可配置错误码映射出错适配器里映射表少了一行新模型接入时漏填错误码映射接入流程增加映射完整性校验限流误伤正常流量令牌桶参数过紧突发桶容量设得太小调大突发桶，同时增加滑动窗口兜底流式连接泄漏调用方中途断开连接网关未及时取消后端请求监听调用方断开事件，主动取消后端调用第一个坑最有代表性。上线初期，某个模型的配置更新后，部分节点的路由还是旧版本，导致请求打到已下线的实例上。排查时发现是配置下发后各节点拉取时间差导致的不一致。后来我们在发布流程里加了一步"同步确认"：控制面下发配置后，等待所有在线节点确认收到，才标记配置生效。这个机制保障了所有节点在同一版本上运行。8.2 如果只让我给三条建议第一条：**先定协议标准，再谈模型接入。**内部统一协议是整个网关的中枢神经，必须在接入第5个模型之前就定下来。没有统一协议，后面每接入一个模型就多一分混乱。第二条：**限流和计量一开始就必须设计。**很多网关项目先跑通转发，再补限流和计量，结果后面发现限流做不进去了、计量数据对不上账。这两块涉及数据埋点，中途加会非常痛苦，一定要从第一天就设计好。第三条：**给模型接入留一个"适配器模式"。**不要为每个模型写一套独立的接入代码，而是抽象出"协议类型"这个维度，每个协议类型写一个适配器，同类模型自动复用。我们的200多个模型只写了20多个适配器，就是因为这个模式省了大量重复工作。8.3 网关上线半年后的真实体会网关上线三个月后，我们已经把内部的AI能力调用完全收敛到平台之上，新的模型接入不再需要业务方配合改造，平均接入时间从之前的3到5天压缩到4小时左右，其中大部分时间还花在等待模型方提供访问凭证上。我最深的体会是：统一网关的价值不是"少写几个适配器"这个层面，而是让业务方把注意力从"怎么调用模型"转移到"怎么用好模型"上。以前每次模型变更，业务方要跟着改代码、做测试；现在模型变更被网关消化掉了，业务方完全无感知。这种稳定感带来的信任，比任何技术指标都值钱。最后分享一个实测的小技巧：如果你也要做类似网关，强烈建议在管理面加一个"路由可视化"页面，把每个请求的路由路径、耗时、模型命中情况实时画出来。排查问题的时候，能直接在界面上看到流量走向，比翻日志高效太多。这个功能的开发工作量不大，但回报率极高。