1. 从流量入口到模型入口API 网关的角色正在被重写过去几年里API 网关在大多数团队里的定位非常清晰它是南北向流量的统一入口负责路由转发、鉴权、限流、熔断、可观测性这些守门人的活。我们选 APISIX、Kong、Envoy 这类网关核心诉求就是性能、插件生态和动态配置能力。但最近一年我明显感觉到一个变化——越来越多的请求不再是人调用服务而是服务调用模型或者人通过应用调用模型。请求的形态从结构化的 REST 变成了带 prompt、带上下文、带流式响应的 LLM 调用网关要处理的东西一下子复杂了一个量级。这就是AI 网关这个概念冒出来的背景。Apache APISIX 作为国内用得最广的开源网关之一在 3.x 版本之后陆续补齐了面向大模型场景的能力官方把它统称为 AI 网关能力。它想解决的问题不是再做一个模型服务平台而是把大模型调用这件事重新纳入到网关这一层来统一治理。换句话说以前你调 OpenAI、调通义、调本地部署的模型是在业务代码里硬编码 SDK、硬编码 key、硬编码重试逻辑现在这些可以下沉到网关层由网关来做协议适配、密钥托管、负载均衡、限流计费和可观测。我写这篇东西的出发点很实际团队里已经有好几个业务线在调大模型key 散落在各个服务的环境变量里谁用了多少 token 没人说得清某家厂商接口抖动的时候只能靠业务自己重试。这种状态下把 LLM 流量收拢到 APISIX 这一层是一个性价比很高的选择。下面我会把 APISIX AI 网关的核心机制、落地步骤、以及我自己踩过的坑尽量讲透。适合已经在用 APISIX 的运维和平台同学也适合正在评估要不要上 AI 网关的架构同学。2. APISIX AI 网关到底在网关层做了什么2.1 它解决的不是能不能调通而是调得可控很多人第一次听到 AI 网关第一反应是我业务代码里直接调模型 API 不就行了为什么要多一层。这个疑问很合理因为单看调通这件事网关确实不产生价值。AI 网关的价值全部在调通之后当你有 10 个业务、3 家模型厂商、每天几百万次调用的时候问题就变成了——密钥怎么统一管理、额度怎么分摊、某家厂商挂了怎么自动切换、prompt 和响应怎么审计、token 消耗怎么计费。这些问题在业务代码里各写一遍就是重复造轮子且必然造歪。APISIX 的做法是把这些能力做成插件挂在路由上。核心的几个能力方向是多厂商协议适配把不同厂商的请求/响应格式统一、密钥与凭证托管key 不落到业务代码、负载均衡与故障转移多上游、多 key 轮询、限流与配额按 token 或按请求数、可观测性记录 prompt、completion、token 用量。这些能力组合起来才构成一个网关意义上的 AI 治理层。2.2 协议适配层把方言翻译成普通话大模型厂商的 API 虽然大多号称兼容 OpenAI 的/v1/chat/completions格式但细节差异非常多。比如流式响应的 SSE 事件格式、finish_reason的取值、错误码的结构、function calling 的字段命名各家都有自己的方言。如果业务直接对接每换一家就要改代码。APISIX 在网关层做了一层协议转换。业务侧统一按一种格式通常是 OpenAI 兼容格式发请求网关根据路由配置的上游类型把请求转成目标厂商的格式再把响应转回来。这样做的好处是业务代码只认一种协议换模型厂商对业务透明。我在实际项目里最直观的收益就是从某家云厂商切到自建推理服务业务侧一行代码没改只改了网关的路由上游配置。注意协议适配不是万能的。如果业务用到了某家厂商独有的高级能力比如特定的多模态字段、特有的工具调用格式适配层可能覆盖不到这时候要么在网关侧扩展要么这部分流量单独走。别指望网关能抹平所有差异。2.3 密钥托管与多 key 负载把 key 从代码里赶出去这是我认为 AI 网关最刚需的能力。以前的做法是每个服务的环境变量里塞一个 API key出了问题要全量重启才能换 keykey 泄露了要挨个服务排查。APISIX 的做法是把 key 存在网关的配置里或者对接密钥管理服务业务请求里不带 key网关在转发时注入。更进一步的是多 key 负载均衡。同一家厂商你可以配多个 key网关按轮询或权重分发单个 key 触发限流时自动切到下一个。这个能力在免费额度或者按 key 限速的场景下特别有用。我实测下来配置多个 key 之后单 key 的 429 错误基本被网关消化掉了业务侧几乎感知不到。2.4 流式响应的处理SSE 是绕不开的坎大模型对话体验的核心是流式输出也就是 SSEServer-Sent Events。网关要处理流式响应比处理普通 JSON 响应难得多因为响应是分块到达的网关不能等整个响应收完再转发必须边收边转。同时如果网关要在流式响应里做 token 计数、内容审计就得解析每一个 chunk这对性能是有影响的。APISIX 基于 OpenResty/Nginx 的事件驱动模型处理流式转发本身是擅长的。但要注意的是一旦你在流式链路上挂了会缓冲的插件比如某些日志插件默认会攒批流式体验就会被破坏表现为回答卡住半天然后一次性吐出来。这个坑我在第一次配置的时候踩得很实排查了半天才发现是日志插件的缓冲策略问题。3. 把 LLM 流量接进 APISIX 的完整落地路径3.1 环境准备版本和依赖别选错APISIX 的 AI 相关插件是在较新版本里逐步完善的如果你用的是很老的 2.x很多能力是没有的。我的建议是直接用 3.x 的较新版本并且确认你需要的 AI 插件在当前版本里已经内置。安装方式上生产环境我倾向于用官方推荐的包管理或容器方式避免自己编译带来的依赖问题。依赖方面AI 网关插件通常需要额外的 Lua 依赖比如处理 JSON、处理 SSE 的库。如果你是从源码构建记得把这些依赖装全否则插件加载会报错。容器镜像的话官方镜像一般已经打包好了省心很多。# 以容器方式快速起一个用于验证的实例示例具体版本按官方最新文档 docker run -d --name apisix-ai \ -p 9080:9080 -p 9180:9180 \ apache/apisix:latest启动之后先确认 Admin API 能通这是后面所有配置的前提。curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: your-admin-key3.2 配置一条指向大模型的上游和路由核心思路是把大模型服务当成一个上游upstream然后建一条路由在路由上挂 AI 相关插件。下面是一个概念性的配置示例实际字段名请以你所用版本的官方文档为准。# 创建上游指向模型服务地址 curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \ -H X-API-KEY: your-admin-key \ -X PUT -d { type: roundrobin, nodes: { api.model-provider.com:443: 1 }, scheme: https }# 创建路由挂上 AI 代理类插件 curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: your-admin-key \ -X PUT -d { uri: /ai/chat/*, upstream_id: 1, plugins: { ai-proxy: { provider: openai, auth: { header: { Authorization: Bearer sk-your-key } }, options: { model: gpt-4o-mini } } } }这里有几个关键点值得展开。provider决定了协议适配的目标格式auth是网关注入凭证的地方业务请求里不需要带 keyoptions.model可以强制覆盖业务传来的模型名也可以做成映射。业务侧只需要往/ai/chat/completions发标准的 OpenAI 格式请求剩下的交给网关。3.3 多 key 与故障转移的配置思路单 key 的配置只能算跑通真正上生产要考虑多 key 和多上游。多 key 一般通过在上游节点里配置多个带不同凭证的节点或者用插件层面的 key 池来实现。多上游则是配置多个 upstream用优先级或健康检查来做故障转移。我自己的经验是把同一厂商的多个 key和不同厂商的备用上游分成两层来做。第一层是同厂商多 key 轮询解决限流问题第二层是跨厂商故障转移解决厂商级故障。第二层的难点在于不同厂商的模型能力不一样切过去之后回答质量可能变化所以更适合做降级而不是等价替换。这一点在配置前一定要和业务方对齐预期。3.4 验证别只看 200要看流式和用量配置完之后验证不能只发一个请求看返回 200 就完事。至少要验证三件事流式响应是否正常用curl -N看是否逐块返回、token 用量是否被正确记录、key 是否真的没暴露给业务。# 验证流式输出-N 关闭缓冲 curl -N http://127.0.0.1:9080/ai/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, stream: true, messages: [{role: user, content: 用一句话解释什么是网关}] }如果这个命令能一行一行地吐出内容说明流式链路是通的。如果卡很久然后一次性出来八成是中间有缓冲回去查插件配置。4. 那些文档里不会写、但一定会踩的坑4.1 流式被缓冲最常见的体验杀手前面提过一次这里展开讲。流式响应被缓冲的典型表现是客户端发起请求后长时间没有输出然后突然一大段内容一次性出现。原因通常是链路上某个环节开启了缓冲可能是 Nginx 的proxy_buffering可能是某个日志或审计插件在攒批也可能是客户端自己的缓冲。排查顺序我建议从外到内先确认客户端curl 加-N没问题再查网关的插件配置最后查 Nginx 层的缓冲开关。定位方法很简单把可疑插件一个个摘掉看流式是否恢复。我当时的元凶是一个默认开启缓冲的日志插件关掉缓冲或者改成异步上报之后就正常了。提示任何要在流式链路上做内容处理的插件都要先确认它是否支持流式透传。不支持流式的插件挂在流式路由上轻则体验变差重则直接报错。4.2 token 计数的误差别把它当账单网关侧统计 token 用量通常是基于响应内容做估算或者调用厂商返回的 usage 字段。这两种方式都有误差。基于内容估算的不同分词器结果不一样依赖厂商 usage 的流式响应里 usage 往往在最后一个 chunk 才返回如果连接提前断开就拿不到。所以我的建议是网关侧的 token 统计用来做趋势监控和配额粗控是够的但不要直接拿它当计费账单。真要精确计费得结合厂商侧的账单数据做对账。这个认知很重要我见过有团队直接拿网关统计的数字去跟业务方结算结果对不上账很尴尬。4.3 超时设置大模型比普通接口慢得多普通 API 的超时可能设个 3 秒、5 秒但大模型生成一段长文本几十秒是常态。如果网关的超时沿用了默认值会出现模型还在生成网关已经把连接断了的情况。需要调整的超时包括网关到上游的读超时、连接超时以及如果前面还有一层负载均衡那一层也要同步调大。流式场景下还要注意超时应该是两个 chunk 之间的间隔超时而不是整个响应的总超时。如果配成了总超时长回答必然被截断。这个细节在配置项里往往体现为不同的超时参数要仔细看文档。4.4 错误码的透传与统一不同厂商的错误码结构不一样有的用 HTTP 状态码有的在 body 里塞业务错误码。网关做协议适配的时候如果不处理错误码业务侧就会收到五花八门的错误格式处理起来很痛苦。理想的做法是网关把上游错误统一成一种格式再返回给业务同时保留原始错误信息用于排查。我在项目里就遇到过某厂商限流返回 200 但 body 里是错误业务侧按 HTTP 状态码判断完全没识别出来导致重试逻辑失效。后来在网关侧加了一层错误归一化才解决。这类问题不看实际返回是发现不了的所以联调阶段一定要把各家的错误场景都造一遍。5. 从能跑到好用AI 网关的进阶玩法5.1 按业务线做配额和限流当多个业务共用一套模型凭证时最怕的是某个业务把额度跑满其他业务跟着遭殃。APISIX 的限流插件可以按路由、按 consumer、按 header 维度做限制。我的做法是给每个业务线分配一个 consumer绑定独立的配额这样既能隔离又能在监控上区分。限流的维度选择上按请求数限流实现简单但不够公平长回答和短回答算一次按 token 限流更公平但实现复杂。折中方案是按请求数做粗限再配合 token 用量的监控告警。具体怎么选取决于你对公平性的要求有多高。5.2 语义缓存省钱又提速的一招大模型调用又贵又慢但很多请求其实是重复或高度相似的。语义缓存的做法是把请求的 prompt 做向量化在缓存里找相似度超过阈值的历史回答命中就直接返回不调模型。APISIX 生态里有相关的缓存插件思路可以借鉴。这个能力的收益在客服、FAQ 这类场景特别明显命中率能到相当可观的水平。但要注意阈值设置设太高命中率低设太低会返回不相关的答案。我建议先用日志把真实请求的相似度分布跑出来再定阈值别拍脑袋。5.3 可观测性prompt 和响应要不要记从排查问题的角度记录完整的 prompt 和响应是最有用的。但从合规和隐私角度这里面可能包含用户敏感信息。我的建议是分级处理默认只记录元数据模型、token 数、耗时、状态码完整内容按需开启并且做脱敏敏感业务线默认不记录内容。这个策略要在上线前就和法务、安全对齐别等出了事再补。5.4 和现有网关体系的融合如果你的团队已经在用 APISIX 做普通 API 网关那 AI 网关不需要另起一套直接在现有集群上加路由和插件即可。好处是复用现有的鉴权、监控、发布流程运维成本低。但要注意资源隔离大模型的流式长连接会占用较多连接数如果和普通 API 混部可能互相影响。有条件的话给 AI 流量单独一组网关节点更稳妥。6. 我在这套方案里的一些真实体会把 LLM 流量收进 APISIX 这一层最大的价值不是技术上的炫技而是把散落在各处的模型调用变成了可治理的基础设施。我自己的项目从最初的业务直连到后来全部收拢到网关最直观的变化是换模型厂商从改一周代码变成了改一条配置key 泄露的风险从全量排查变成了网关侧一处更换成本从月底看账单吓一跳变成了实时能看到每个业务用了多少。但也要说清楚AI 网关不是银弹。它解决的是治理问题不解决模型效果问题它能统一协议但抹不平厂商之间的能力差异它能统计用量但精度不足以直接当账单。把它放在正确的位置上——一个统一入口和治理层——它的价值就非常明确。如果你现在正准备上这套方案我的建议是先从一个非核心业务线试点把流式、超时、错误码这几个最容易出问题的点跑通再逐步扩大范围。别一上来就把核心业务全切过去流式链路的坑比你想象的多。等试点稳定了再考虑多 key、语义缓存这些进阶能力。这套东西的投入产出比在调用量上来之后会越来越明显。