团队把大模型接进系统这事我最近一年经手了不止一个。最初大家都很兴奋觉得把 OpenAI 的 SDK 一装调用几个接口就能上线了。可真到生产环境才发现大模型接入和传统 API 接入完全是两码事模型供应商五花八门每个团队各接各的API Key 散落在一堆代码仓库里账单月底一拉出来谁用了多少 token 根本说不清。后来我把 Apache APISIX 重新翻出来折腾了一圈才意识到当年做流量入口的 API 网关如今已经长出了另一套完整的 AI 网关能力。这篇文章就围绕“API 网关 大模型”这个组合聊聊 APISIX AI 网关到底解决了什么问题、怎么配置、以及实际跑起来都有哪些值得留神的坑。适合看这篇的人很明确已经在公司内部做大模型应用接入、正在物色统一入口方案或者单纯在用 APISIX 但不知道 AI 插件该怎么用的后端开发者。如果你以为网关只是转发请求那这篇文章可能会改变你对网关的认知。1. 为什么说 API 网关站在大模型接入的必经之路上1.1 大模型请求和普通 API 请求根本不是一回事传统的 API 网关不管是 Kong、APISIX 还是别的什么干的事情其实很固定路由转发、鉴权、限流、熔断、日志、灰度。这套模型针对的是普通 HTTP 接口请求体积小、响应时间可控、每次调用成本几乎可以忽略不计。按 QPS 去限流按 URL 去做灰度这些做法放到大模型场景下立刻就显得不对味了。大模型请求有几个非常反常规的特点。第一个是成本结构完全不同按 token 计费一个复杂点的生成请求可能抵得上几千次普通接口调用如果还是按请求数去限流实际上是限了个寂寞。第二个是响应模式变了大模型普遍支持 SSE 流式返回客户端期望拿到的是一个持续推送的增量数据流而不是等全部内容生成完再一起返回。第三个是请求和响应的体积都很大多轮对话场景里请求体可能塞进几万 token 的历史上下文普通网关的日志记录和超时配置如果不做调整很容易在长对话中直接超时断开。还有个更麻烦的点模型供应商不是一个。OpenAI、Azure OpenAI、AWS Bedrock、Google Gemini再加上公司内部私有化部署的 Llama 或 Qwen每个的协议细节都有一点差异。有的返回结构不同有的认证方式不同有的模型名称叫法都不同。如果业务团队各自对接这些供应商网关层就完全失控了你会看到同一个公司里出现三套互不兼容的调用封装各自维护各自的密钥。所以大模型接入这件事本质上不是一个“选哪个模型”的问题而是一个“怎么把模型调用管起来”的问题。API 网关天然站在这个治理入口的位置上前提是它得有 AI 相关的感知能力。1.2 自研转发服务的三个坑重复造轮子、SDK 绑定、治理缺失我知道很多人第一反应是自研。毕竟转发一个 HTTP 请求有什么难的用 Node 或者 Go 写个中间层把客户端请求转给 OpenAI再把结果转回来半天就能搞定。我见过太多团队这么做半年之后基本都后悔了。第一个坑是重复造轮子。每个业务团队都有自己的接入需求A 团队写了一个转发服务B 团队看不上它的代码风格又自己写了一个C 团队觉得直接用供应商 SDK 更省事。最后结果是同一家公司里存在多个模型调用入口密钥分散鉴权逻辑各写各的出了安全问题都不知道从哪个口子漏的。第二个坑是 SDK 绑定。自研转发服务通常直接用模型供应商的官方 SDKSDK 一旦升级或者供应商改了 API 参数所有接入方都得跟着改。而且官方 SDK 的设计通常面向单机调用没有把“多租户配额”“细粒度计量”“流式转发兼容”这些网关层问题纳入考虑。你在自研转发服务里做这些实际上是重新造一个不完整的网关。第三个坑是治理缺失。没有统一入口就没有办法回答几个核心问题全公司每天到底消耗多少 token哪个业务线花得最多有没有某个密钥被刷爆导致巨额账单模型供应商限流的时候应该优先保哪个业务这些问题在自研方案里通常只能通过事后拉日志统计来回答费时费力。我自己并不反对自研在并发量很小、只有一个模型供应商、只有两三个业务方的情况下自研转发服务完全够用。但一旦规模上来统一网关的价值就会迅速超过自研。1.3 AI 网关应该长成什么样说了这么多问题AI 网关到底是什么我的理解是它仍然是传统 API 网关的进化形态但多了一层“感知大模型请求”的能力。传统网关把上游当作一个普通 HTTP 服务它不知道上游是按 token 计费的不知道上游返回的是流式 SSE也不知道上游有幻觉和提示注入这回事。AI 网关则不同它知道每个请求背后是模型调用知道怎么把请求转发给不同供应商知道怎么解析模型返回的 usage 信息也知道怎么在流式响应中间做计量和转发。从承载的职责来看AI 网关至少要覆盖这几件事统一对外暴露 OpenAI 兼容接口让业务方不用关心后端到底是哪家供应商在网关层做密钥托管API Key 不落到客户端按 token 维度做配额和计量支持流式响应透传和协议转换还能做一些普通网关做不到的优化比如语义缓存和多模型路由。Apache APISIX 做的事情就是把这些能力以插件的形式集成进网关。它其实没有改变 APISIX 本身的架构而是让插件体系延伸到 AI 这个新领域你之前熟悉的 route、service、consumer、plugin 这些概念全部继续生效只是插件从限流、鉴权换成了 ai-proxy、ai-rag 这些新面孔。2. APISIX AI 网关的核心能力拆解2.1 从 ai-proxy 插件看统一接入层APISIX 里最核心的 AI 插件是ai-proxy它要解决的就是我刚才说的统一接入问题。这个插件的定位很简单让 APISIX 对外暴露一个 OpenAI 兼容的接口然后内部把请求转发给任意配置好的模型供应商。这么设计有一个很大的好处业务方不需要更换自己的调用代码。一个团队如果已经用 OpenAI 的 SDK 写好了应用那它在 APISIX AI 网关模式下几乎不用改动只需要把 base_url 指到网关地址把 API Key 换成网关分发的 Key 就行。网关在后端把这些请求映射到实际配置的模型供应商可能是 Azure OpenAI可能是本地 Ollama也可能是 Bedrock 上的某个模型。ai-proxy在配置上分成几块provider 指定要对接的模型供应商比如 openai、azure-openai、bedrock、gemini 等auth 配置模型供应商的密钥model 配置模型名称和生成参数比如 temperature、max_tokensprotocol 处理流式和非流式的传输细节。举个例子一条最简单的路由可以这样创建curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: admin \ -X PUT -d { uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, key: Bearer sk-你的模型密钥 }, model: { name: gpt-4o, temperature: 0.7, max_tokens: 2048 } } } }创建完之后客户端访问/v1/chat/completions请求体会按 OpenAI 的 chat/completions 协议发给网关网关负责转发给真正的模型供应商然后把响应原样返回。密钥被好好关在网关里客户端永远接触不到。这里需要注意一个版本差异APISIX 的 AI 插件演进速度很快3.9 到 3.11 的字段定义就有不少变化。上面的示例是常见写法但建议在实际部署时先apisix version确认版本再对照官方文档的插件字段描述确认一遍。2.2 多 Provider 适配与模型路由统一接入是第一步多样化的供应商适配才是 APISIX AI 网关真正让人省心的地方。APISIX 在 ai-proxy 之外还维护了一组按供应商拆分的插件比如ai-aws-proxy、ai-azure-openai-proxy、ai-google-proxy名称里带供应商的插件通常针对该供应商的特殊协议做了适配。为什么需要单独的插件因为不同供应商的 API 差异并不只在密钥和 URL 上。Azure OpenAI 的端点路径里带部署名称AWS Bedrock 的请求需要拿 IAM 签名Google Gemini 的请求体和 OpenAI 不是同一套 schema这些差异靠一个通用插件硬吃下来会非常痛苦。拆分插件之后每个插件只需要专心处理该供应商的协议细节而对外输出的接口仍然保持 OpenAI 兼容这样业务方的代码就不用跟着变了。模型路由这块APISIX 的做法也比较灵活。你可以针对不同的 route 配置不同的 ai-proxy比如/v1/chat/small路由用gpt-4o-mini或者qwen2.5:7b/v1/chat/large路由用gpt-4o。业务方根据任务复杂度选择不同入口网关自动把请求转到对应的模型供应商。这样的路由策略天然支持了成本优化简单任务用小模型复杂任务用大模型。实际跑起来之后你会发现这一条简单的分流规则对账单的影响可能比任何缓存都来得明显。我见过不少团队把所有的请求都打到 gpt-4o月度成本高得离谱后来在网关层按业务线划分模型入口成本直接降了一半以上。2.3 网关层独有的 AI 治理能力计量、限流、缓存、防护传统网关和 AI 网关的分水岭就在治理能力上。APISIX 在 AI 场景下提供了几项传统插件体系完全覆盖不到的能力。第一项是 token 计量。ai-proxy 在转发请求之后会解析模型返回的 usage 信息把 prompt_tokens 和 completion_tokens 记录到日志和指标里。有了这个数据你就能精确回答“每个业务方消耗了多少 token”这个问题而不是对着模型供应商的账单猜。在流式响应场景下网关还需要边转发边累积增量计算 token 消耗这对插件的实现要求比普通转发高得多。第二项是 token 维度的配额控制。普通限流按请求次数来在大模型场景下不够用。APISIX 的 AI 相关插件里可以按消费者维度配置 token 配额比如“这个业务方每天最多用 100 万 token”超过之后直接拒绝请求。这个能力对控制成本非常关键尤其是当业务方的代码里有循环调用大模型的逻辑时一个 bug 可能导致一次运行烧掉几万 token。第三项是语义缓存。大模型场景里很多请求其实是重复的比如企业的智能客服系统里用户问“怎么重置密码”这类问题每天会被问几百次。如果每次都由真实模型生成成本高、响应慢。语义缓存会在网关层把用户请求向量化跟已有缓存做相似度匹配超过阈值的直接返回缓存结果。这个能力在传统 HTTP 缓存里根本做不到因为用户请求的措辞可能不同含义却相同。第四项是安全防护。大模型引入了一个新型安全风险叫提示注入攻击者通过精心构造的输入诱导模型输出敏感内容或者绕过系统限制。APISIX 也提供相关的 AI 安全插件做输入检测虽然不能替代完整的应用层防护但放在网关层作为统一防线至少能做到所有流量都过一遍检查。3. 实操5 分钟跑起一个 APISIX AI 网关3.1 环境准备Docker 部署 APISIX 和 etcdAPISIX 依赖 etcd 做配置存储最简单的跑法是用 docker-compose 把两个服务一起拉起来。我直接给出一个能用的最小配置version: 3.8 services: etcd: image: bitnami/etcd:3.5 environment: ETCD_ENABLE_V2: true ALLOW_NONE_AUTHENTICATION: yes ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379 ports: - 2379:2379 apisix: image: apache/apisix:3.9.0 ports: - 9180:9180 - 9080:9080 volumes: - ./config.yaml:/usr/local/apisix/conf/config.yaml:ro depends_on: - etcd9180是 Admin API 端口用来配置路由和插件只允许内网访问。9080是数据面端口客户端实际请求的流量都走这里。启动之前需要准备一个 config.yaml告诉 APISIX 如何连接 etcd最简配置只要设置 etcd 的地址即可。启动命令就一行docker compose up -d等两个容器都进入运行状态后先确认 Admin API 可用curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: admin返回routes的 JSON 数组就说明环境正常。如果你的 APISIX 版本里默认改了 Admin API 的密钥记得换成 config.yaml 里的admin_key。3.2 创建第一条 AI 路由参数解释与验证环境起来之后创建一条 AI 路由。这里我用一个支持 OpenAI 协议的本地模型服务做演示这种情况在生产里也很常见公司内部部署了 Qwen 或者 Llama用 vLLM 或者 Ollama 对外提供服务。按照前面给过的示例创建/v1/chat/completions路由把上游指向本地模型服务端口curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: admin \ -X PUT -d { uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, key: Bearer EMPTY }, model: { name: qwen2.5, temperature: 0.7, max_tokens: 1024 }, protocol: { stream: true } } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:8000: 1 } } }这里 upstream 指向本机的 vLLM 服务地址。有的 AI 插件版本里不需要配置 upstream因为请求由插件直接处理但配置一个占位 upstream 能保证路由通过校验也不会影响插件逻辑。配置完成后用 curl 模拟一次客户端请求curl http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5, messages: [ {role: user, content: 用一句话介绍网关的作用} ], stream: true }如果一切正常你会看到 SSE 格式的增量数据流不断输出最后以data: [DONE]结束。这意味着 APISIX 已经成功充当了大模型请求的代理入口。这个配置里有一个关键点值得展开stream: true是放在客户端请求体里的。ai-proxy 会根据这个参数决定是否以流式模式转发上游。如果客户端没有声明流式网关就按普通 JSON 响应处理如果声明了流式网关需要保证从上游读取的 SSE 数据能够实时地以 chunked transfer 方式返回给客户端。3.3 把 API Key 藏好消费者鉴权与 token 配额统一入口搭好之后下一步就是鉴权。APISIX 的传统插件体系在这里直接复用最常用的是key-auth。首先要创建一个消费者消费者代表一个业务方或者一个应用curl http://127.0.0.1:9180/apisix/admin/consumers \ -H X-API-KEY: admin \ -X PUT -d { username: crm-service, plugins: { key-auth: { key: crm-key-2024 } } }然后在路由上启用 key-authcurl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: admin \ -X PATCH -d { plugins: { key-auth: {} } }配置完之后客户端请求必须带apikey: crm-key-2024才能访问网关。上游模型的真实密钥仍然由 ai-proxy 在网关侧管理业务方完全看不到。如果要把 key-auth 和 ai-proxy 接起来做 token 配额可以在消费者或者路由上配置 AI 相关的配额插件不同版本字段差异比较大。一个比较通用的思路是在路由上先做 key-auth 得到消费者 ID再结合 ai-proxy 解析出的 usage 信息把 token 消耗累计到消费者维度。APISIX 的日志和指标会为这个提供数据基础Prometheus 插件可以直接暴露 token 消耗指标。3.4 用日志和指标看清每一次模型调用网关的另一个价值是可观测性。APISIX 的日志插件可以把每次模型调用的关键信息落盘包括消费者信息、请求模型、token 消耗、响应码、耗时。在 AI 网关场景下我建议至少记录这些字段消费者名称、调用时间、目标模型、prompt_tokens、completion_tokens、总延迟、首字延迟。首字延迟这个指标在传统 API 里很少见但对大模型体验至关重要——用户在客户端等第一个字返回的时间直接决定了他觉得快还是慢。APISIX 接入日志可以通过file-logger或者http-logger插件实现。如果公司有现成的日志平台直接把日志推到 Kafka 或者 Elasticsearch然后用看板聚合展示。我自己的经验是先做一张简单的表每个业务方每日 token 消耗、每次请求平均 token 数、按模型的成本分布。这三张表跑起来之后成本问题基本上就透明了。4. 踩坑实录AI 网关落地中的典型问题4.1 高频问题速查表我把实际跑 AI 网关过程中最常遇到的问题整理成了一张速查表方便你对照排查。现象可能原因排查方向流式响应积攒一段时间才吐出代理缓冲未关闭检查 route 的 proxy-buffering 配置客户端收到data: [DONE]后连接不关闭SSE 结束处理不干净查看网关 read_timeout 和上游关闭行为返回 401网关侧模型密钥配置错误检查 ai-proxy 的 auth 字段返回 429触发了供应商限流或配额查看模型供应商限额配置检查消费者 token 配额token 统计和账单对不上流式模式 usage 解析不完整对比网关日志 usage 与供应商账单缓存命中率极低语义缓存阈值过高或向量化不一致检查相似度阈值和缓存键策略长对话请求超时上游响应时间超过 read_timeout调大 read_timeout确认流式模式生效日志里 token 字段为空AI 插件未解析 usage确认上游响应真实包含 usage非流式模式优先验证4.2 流式响应“卡住”和连接断开的真相流式响应卡住是最常见的现象现象描述通常是客户端的 UI 上文字生成到一半突然停了过几秒又一口气蹦出来一大段或者干脆一直停留在半截。大多数情况下这个锅都得甩给代理缓冲。nginx 默认开启 proxy_bufferingAPISIX 底层基于 OpenResty也可能继承了这个行为。如果代理缓冲开启上游传回的 SSE 流会被 nginx 缓冲攒够一定大小或者等待一定时间之后才一次性发给客户端表现就是“一段一段地跳”。解决方法是关闭该路由的缓冲功能APISIX 里可以设置 route 的proxy-buffering为 false或者通过nginx_proxy_buffering相关配置控制。流式连接断开的另一个常见原因是超时配置。普通 HTTP 请求的 read_timeout 设置成 60 秒是合理的但一个复杂的生成请求跑两分钟也很正常。如果网关在 60 秒就断开上游连接客户端感知就会是“生成到一半报错了”。我实际遇到过一个更隐蔽的问题上游模型服务在流式结束后没有正确返回data: [DONE]客户端代码按照 OpenAI 协议去解析等不到结束标记就一直等待直到自己超时。这通常不是网关的问题而是模型服务实现不规范排查时要注意把网关日志和上游服务日志拿到一起对比。4.3 账单和 token 统计对不上怎么办网关记录的 token 消耗和模型供应商账单对不上这是我最常被问到的问题。首先要理解差距从哪来。不同模型供应商对 token 的计数口径不完全一致有的算上系统提示词有的不算有的按字符估算有的用 tokenizer 精确计算。网关只能转述模型 API 返回的 usage 字段如果上游本身返回的就是估算值那网关记录自然也是估算值。在流式模式下部分模型 API 的 usage 信息可能并不在每个增量里都携带需要网关自己根据增量文本估算误差就会更大。那网关的计量还有意义吗有但定位需要明确网关计量作用是为成本分配和配额控制提供依据而不是替代供应商账单做精确计费。实际操作中我会按月把网关记录的 token 总和和供应商账单做一次对比如果偏差在 10% 以内说明网关解析基本正常。如果偏差长期超过 20%就要检查是不是漏掉了某个模型供应商的 usage 字段或者流式模式下有大量请求没被完整统计。一个我踩过的细节部分模型 API 返回的 usage 里prompt_tokens 和 completion_tokens 的字段名不是标准命名比如有些模型把total_tokens返回在顶层有些放在usage内部插件的解析逻辑对新模型支持不完整。遇到这种情况升级网关版本或者查插件更新日志是最直接的解法。4.4 供应商限流与超时如何做退避和容灾模型供应商的限流策略比普通 API 要复杂。OpenAI 的限流维度包括 RPM 和 TPMAzure 更细到部署级别。当请求量上来之后网关很容易触发供应商的 429。普通 API 的 429 处理逻辑是退避重试但大模型请求要小心一个生成请求在供应商侧可能已经在消耗算力了盲目重试会导致成本翻倍。遇到 429先确认供应商返回的Retry-After头按这个时间退避如果供应商没给用指数退避初始等待 1 秒乘数 2上限 30 秒。APISIX 原生不一定自带这个逻辑可以用自定义插件实现也可以结合 APISIX 的limit-*插件在网关侧做限速思想是“与其让供应商限流不如自己先限住”。容灾方面多模型供应商的价值这时候就体现出来了。如果主模型供应商大面积限流甚至故障网关应该能自动把流量切换到备选供应商。具体做法可以是配置多条路由入口一致但上游和 ai-proxy 配置不同然后在网关侧根据上游健康状态做切换。手工切换可控但响应慢自动切换需要完整的健康检查逻辑别让备选供应商也一起崩掉。5. 把 AI 网关用好进阶玩法与落地建议5.1 多模型路由与成本优化网关一旦立住接下来的优化空间就打开了。我建议从成本优化开始因为它最直接影响预算容易让老板看到价值。成本优化的第一层是模型分流。把最简单的请求路由到最便宜的模型复杂推理才用高配模型。比如客服场景下的常见问题匹配用一个小模型就足够代码生成、长文总结这类任务才需要上大模型。利用 APISIX 的路由能力可以轻松实现不同 URL 走不同模型或者同一个 URL 根据请求体里的model字段做二次分发。第二层是语义缓存。用户没变但是问题重复率极高。在智能客服、知识库问答这类场景里语义缓存的命中率往往能到 30% 以上直接节省了大量 token 消耗。缓存的实现思路前面说过关键点是相似度阈值要调准阈值太高缓存命中率低太低会出现答非所问的误命中需要根据具体场景反复试。第三层是闲时任务调度。一些非实时的任务比如批量文档分类、周报生成可以引导到成本更低的时段或者批量接口网关在这个场景里主要充当调度入口和计量通道。5.2 提示注入与敏感信息防护大模型安全的特殊性在于攻击面不仅仅在传统 Web 层面还多了一个提示注入。攻击者可以在任何用户输入里隐藏指令试图让模型忽略系统提示、输出系统提示词或者泄露其他用户的信息。网关层的防护思路是在请求到达模型之前做检查在响应返回客户端之前再做一次检查。APISIX 的相关安全插件或者自定义插件可以在这些节点上做规则匹配。规则可以是关键词黑名单也可以接一个专门的安全模型更复杂的方案是接一个独立的 guard model对输入输出做分类判断。必须说清楚网关层的安全防护是兜底不是全部。真正可靠的做法是应用层自己做隔离和权限控制模型层用系统提示词限制行为范围网关层再做统一过滤。三层叠加之后风险才能可控。只靠网关过滤、应用层完全不设防遇到高级攻击者还是会被绕过去。5.3 结合 RAG 让网关更懂业务APISIX 的 AI 能力不止是转发RAG 场景也有插件支撑。RAG 的本质是给模型补充业务知识让它在回答问题时先检索公司内部的文档或数据库把检索结果作为上下文交给模型生成。在没有网关参与的时候RAG 通常是应用层自己做的应用调向量数据库再调模型逻辑耦合在业务代码里。有了 ai-rag 这类插件网关可以在请求链路里自动完成检索增强把检索结果注入到发给模型的请求里。这个玩法的好处是统一。任何业务方接入网关就自动获得了知识库增强能力不需要每个团队各自搭一套向量检索和 prompt 拼接逻辑。知识库的更新集中在网关侧维护。不过我要提醒一点RAG 插件的成熟度和业务适配之间还有不小差距如果你的业务有强定制化的检索逻辑先在测试环境仔细验证检索质量再决定要不要在网关层统一处理。5.4 落地顺序的建议先治理再优化最后聊聊落地节奏。见过一些人一开始就追求大而全语义缓存、多模型路由、安全防护、RAG 全部上线结果配置复杂到根本维护不住一个环节出问题都很难排查。我的建议是四步走。第一步统一入口。不管后续做什么先把所有模型调用的流量全部经过 APISIX这一步成本最低、最不容易出错但价值最大因为从这一刻起你能看到全部流量的样子。第二步加鉴权计量。用 key-auth 管理调用方用 ai-proxy 的计量能力统计各业务方的 token 消耗让成本透明化。第三步做限流和配额。按消费者设置 token 配额避免单业务方失控烧穿预算。第四步再考虑缓存、路由、安全这些优化项。每一步都要先灰度验证。AI 插件的演进速度很快生产环境一定要先备份路由配置升级前在测试环境把新版本完整跑一遍。我在实际使用中的体会是AI 网关的价值不在“转发”这两个字上而在“可控”这两个字上。模型能力是别人的但闸门和控制权需要掌握在自己手里。如果你正好在给团队搭大模型接入层我建议从最小可用开始——先让所有模型请求都经过一个网关后面的事都会顺畅很多。最后分享一个小技巧网关配置的 curl 命令不要随手乱存用 APISIX 的配置导出功能把全部路由、消费者和插件配置定期备份到 GitAI 插件配置字段随时在变留一份版本记录能让你在出了问题的时候少掉很多头发。