1. 从一个真实困境说起为什么传统网关接不住大模型流量去年帮一个团队做技术咨询他们的情况很有代表性。后端有七八个微服务前面挂着一套传统的 API 网关做鉴权、限流、路由转发跑了一年多一直挺稳。后来产品要加 AI 能力接入了大模型做智能问答和文档摘要问题就来了——原本那套网关在大模型面前几乎成了摆设。具体表现是什么传统网关的限流是按请求数算的比如每秒 100 个请求。但大模型的一次调用和一次普通接口调用完全不是一个量级普通接口可能 50 毫秒返回 2KB 数据大模型一次流式输出可能持续 30 秒、吐出几千个 token。按请求数限流10 个并发的大模型请求就能把后端推理服务打满而网关还觉得“才 10 个请求远没到 100 的阈值”。这就是典型的计量单位错配。更麻烦的是流式响应。大模型普遍采用 SSEServer-Sent Events做流式输出让用户看到文字一个个蹦出来。传统网关很多是按“请求-响应”完整周期设计的遇到长连接流式响应要么缓冲住整个响应再转发用户等半天没反应要么超时断开回答到一半断了。再加上 token 计费、多模型路由、提示词安全过滤这些新需求传统网关的插件体系根本无从下手。Apache APISIX 的 AI 网关能力就是冲着这些痛点来的。它没有另起炉灶搞一套新东西而是在原有 APISIX 网关的基础上通过一系列 AI 相关插件把大模型流量的特殊性吃透了。这篇文章我会从实际落地角度把 APISIX AI 网关的核心机制、关键插件、配置细节和踩坑经验完整拆一遍。不管你是正在选型 AI 网关还是已经在用 APISIX 想接入大模型都能拿到可以直接参考的东西。2. APISIX 做 AI 网关的底层逻辑它凭什么能接住大模型2.1 不是新网关而是插件层的定向增强很多人一听“AI 网关”以为是独立产品其实 APISIX 的思路很务实网关该干的活路由、鉴权、限流、可观测一样不变只是针对大模型流量的特性在插件层做定向增强。这个定位很关键因为它意味着你不需要为了接大模型把现有网关架构推倒重来。APISIX 本身基于 NGINX 和 OpenResty底层用 Lua 做插件扩展天然支持高并发和长连接。它的插件机制是热加载的加一个 AI 插件不需要重启网关。这一点在 AI 场景下特别重要——大模型相关的需求变化极快今天要加个新模型供应商明天要改提示词过滤规则如果每次都要重启网关线上根本受不了。从架构上看APISIX 处理 AI 流量的链路是这样的客户端请求进来先过常规的路由匹配和鉴权插件然后进入 AI 专属插件链包括请求改写比如统一不同厂商的请求格式、模型路由按策略选后端、流式代理处理 SSE、token 计量、响应过滤等最后转发到实际的大模型服务。整条链路对客户端是透明的客户端只管按标准格式发请求。2.2 大模型流量和普通 API 流量的四个本质差异要理解 APISIX 为什么这么设计得先搞清楚大模型流量到底特殊在哪。我总结了四个核心差异这也是选型和配置时最容易踩坑的地方。第一响应是流式的、长时的。普通 API 是“请求-响应”瞬时完成大模型是持续几十秒的流式输出。这要求网关必须支持流式代理不能缓冲整个响应体。APISIX 通过ai-proxy系列插件配合底层的流式转发能力能做到边收边转用户端能实时看到 token 逐个出现。第二计量单位是 token 不是请求数。一次请求可能消耗几十个 token也可能消耗几千个。按请求数限流完全失真。APISIX 的 AI 插件支持在响应流中解析 usage 字段统计 prompt tokens 和 completion tokens据此做限流和配额。第三请求和响应的格式因厂商而异。OpenAI、Anthropic、国内各家大模型的 API 格式都不一样字段名、鉴权方式、流式协议细节都有差异。如果每个业务都自己适配重复劳动巨大。APISIX 的ai-proxy插件做的就是协议归一化——客户端统一按一种格式发插件负责翻译成目标厂商的格式。第四安全边界扩大了。传统 API 的安全主要是鉴权和防注入大模型还多了提示词注入、敏感信息泄露、模型滥用等风险。这需要在网关层做请求内容检查和响应内容过滤。2.3 插件协同的工作流一次 AI 请求在 APISIX 里经历了什么我把一次典型的大模型请求在 APISIX 里的完整旅程拆一下这样你能清楚每个插件在哪个环节起作用。请求进来后首先是常规的路由匹配根据 URI 或 Header 找到对应的 Route。然后进入 AI 插件链ai-proxy或ai-proxy-multi负责把客户端请求转换成目标大模型的格式同时处理鉴权头把网关持有的 API Key 注入进去客户端不需要知道真实 Key。如果是多模型场景ai-proxy-multi还会根据负载均衡策略或故障转移规则选一个健康的模型实例。请求转发出去后大模型开始流式返回。这时候ai-proxy的流式处理逻辑接管逐块解析 SSE 数据一边转发给客户端一边提取 usage 信息。如果配置了ai-rate-limiting它会根据累计的 token 消耗判断是否超限。响应结束后如果有内容过滤插件会对完整响应做一次检查。整个过程中ai-proxy是核心其他插件围绕它做增强。这种设计的好处是职责清晰你可以按需组合不需要的插件不启用不增加额外开销。3. 核心插件逐个拆ai-proxy 系列到底怎么配3.1 ai-proxy单模型接入的最小可用配置ai-proxy是接入单个大模型的基础插件。它的核心作用是请求格式转换 鉴权注入 流式代理。我拿接入一个 OpenAI 兼容接口的模型举例配置大概长这样plugins: ai-proxy: provider: openai auth: header: Authorization: Bearer sk-xxxxxxxx options: model: gpt-4o-mini override: endpoint: https://api.example.com/v1/chat/completions这里有几个点值得展开说。provider字段决定了请求和响应的转换规则APISIX 内置了 openai、anthropic、azure-openai 等常见 provider 的适配。auth.header是网关侧持有的真实密钥客户端请求里不需要带这样密钥不会暴露到前端。override.endpoint允许你指向任意兼容 OpenAI 协议的端点国内很多模型服务都提供 OpenAI 兼容接口改这个字段就能接。实测下来最容易出问题的是model字段的传递。有些客户端会在请求体里自带 model 参数如果和插件配置的冲突行为取决于 provider 的实现。我的建议是统一在插件侧配置 model客户端请求体里不要带避免歧义。3.2 ai-proxy-multi多模型路由与故障转移的实战配置单模型接入简单但生产环境很少只用一个模型。可能是为了成本简单问题走便宜模型复杂问题走贵模型可能是为了可用性主模型挂了自动切备用也可能是为了合规不同地区走不同模型。ai-proxy-multi就是干这个的。它的配置核心是instances列表每个实例是一个独立的模型端点配合balancer做负载策略plugins: ai-proxy-multi: balancer: type: chash hash_on: header key: x-model-tier instances: - name: primary provider: openai weight: 1 auth: header: Authorization: Bearer sk-primary options: model: gpt-4o - name: fallback provider: openai weight: 1 auth: header: Authorization: Bearer sk-fallback options: model: gpt-4o-minibalancer.type支持roundrobin、chash、least_conn等。上面这个例子用chash按请求头x-model-tier做一致性哈希客户端可以通过这个头指定走哪个档位的模型。如果不指定就按权重轮询。故障转移这块要注意ai-proxy-multi的重试逻辑和普通 upstream 重试不一样。大模型请求重试成本很高可能已经消耗了 token所以默认的重试策略要谨慎。我一般会把重试次数设得很低并且只对连接失败这类明确错误重试不对超时重试——因为超时可能意味着模型正在生成重试会导致重复计费。3.3 流式响应处理SSE 转发里那些文档没写的细节流式响应是 AI 网关的命门。APISIX 处理 SSE 的关键在于不缓冲、逐块转发。但实际配置中有几个细节文档里不会重点讲。首先是proxy_buffering必须关掉。APISIX 底层是 NGINX如果 buffering 开着NGINX 会攒够一定大小才转发用户端就会看到“卡一下蹦一大段”而不是流畅输出。在 Route 或上游配置里要确保proxy_buffering: false。其次是超时设置。大模型生成慢的时候单个 chunk 之间可能间隔好几秒。如果proxy_read_timeout设得太短默认 60 秒长回答会被中途掐断。我一般会把它设到 300 秒以上具体看业务的最长回答时长。还有一个坑是chunk 边界处理。SSE 数据是按\n\n分隔的事件块但 TCP 传输不保证边界对齐一个事件块可能被拆到两个 TCP 包里。APISIX 的流式解析器会做缓冲重组但如果你的自定义插件也要解析流必须自己处理这种边界情况不能假设每次收到的都是完整事件。3.4 token 计量与限流怎么算准每一次调用的成本token 计量是 AI 网关区别于普通网关的核心能力之一。APISIX 的做法是在流式响应中解析每个 chunk从最后一个包含 usage 的 chunk 里提取 token 数。OpenAI 的流式响应默认不在每个 chunk 里带 usage需要请求时加stream_options: {include_usage: true}APISIX 的 ai-proxy 插件会自动处理这个参数。拿到 token 数之后ai-rate-limiting插件可以按 token 维度做限流。配置大概是plugins: ai-rate-limiting: limit_strategy: total_tokens limit: 100000 time_window: 3600 rejected_code: 429这表示每小时最多消耗 10 万 token。超过就返回 429。相比按请求数限流这个粒度准确得多。但这里有个实测中的坑如果流式响应中途断开客户端主动取消或网络问题usage 可能拿不到这次调用的 token 就统计不到。APISIX 对这种情况有兜底估算但估算值和实际值可能有偏差。如果你的计费非常敏感建议在业务层也做一次对账。4. 把 AI 网关跑起来从环境准备到验证的完整链路4.1 环境准备版本选择和依赖确认APISIX 的 AI 插件能力是在较新版本里逐步完善的我建议至少用 3.9 以上的版本AI 插件生态比较完整。安装方式看你的习惯Docker 最快docker run -d --name apisix \ -p 9080:9080 -p 9180:9180 \ -v $(pwd)/config.yaml:/usr/local/apisix/conf/config.yaml \ apache/apisix:3.9.0-debian9180是 Admin API 端口用来动态配置路由和插件9080是数据面端口业务流量走这里。生产环境记得把 Admin API 的访问控制做好默认的 admin key 一定要改。依赖方面AI 插件本身不需要额外装什么但如果要用到一些高级的请求改写能力可能需要确认lua-resty-*相关库的版本。Docker 镜像里这些都是打包好的自己编译安装的话要留意。4.2 配置一个可用的 AI 路由分步骤操作第一步创建一个 Upstream 指向大模型服务。如果你用的是外部 API其实可以跳过 Upstream直接在插件里用override.endpoint指定。但如果要做健康检查或负载均衡还是建一个 Upstream 更规范。第二步创建 Route 并挂载 AI 插件。通过 Admin API 操作curl http://127.0.0.1:9180/apisix/admin/routes/ai-chat \ -H X-API-KEY: your-admin-key \ -X PUT -d { uri: /v1/chat/completions, methods: [POST], plugins: { ai-proxy: { provider: openai, auth: { header: { Authorization: Bearer sk-your-real-key } }, options: { model: gpt-4o-mini } } } }第三步验证。用 curl 发一个流式请求curl http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 用一句话解释什么是API网关}], stream: true }如果配置正确你会看到 SSE 格式的流式输出每个 chunk 是一段 JSON。注意请求体里不需要带 model 和 Authorization这些都由网关侧处理了。4.3 验证清单怎么确认流式、计量、路由都正常配完之后别急着上生产按这个清单逐项验证验证项方法预期结果流式转发curl 加stream:true观察输出逐块实时输出无长时间卡顿鉴权注入请求不带 Authorization正常返回说明网关侧密钥生效模型路由请求带x-model-tier头按配置路由到对应模型token 计量查看 APISIX 日志或监控有 usage 统计输出限流生效短时间内大量请求超过阈值返回 429故障转移故意配错主模型密钥自动切到备用实例这个清单我每次上线前都会过一遍尤其是故障转移一定要主动制造故障验证不能假设它一定生效。5. 生产环境才会暴露的问题我踩过的坑和排查思路5.1 流式响应被缓冲一个排查了两小时的配置问题有次上线后用户反馈“AI 回答要等十几秒才一次性出现”完全不是流式效果。第一反应是插件配置问题检查了ai-proxy的配置没发现异常。然后怀疑是客户端问题换了个 curl 测试还是缓冲。排查链路是这样的先确认 APISIX 到上游的请求是不是流式的——抓包看上游确实在逐块返回。那问题就在 APISIX 到客户端这一段。检查 NGINX 层面的配置发现 Route 继承的全局配置里proxy_buffering是默认的on。虽然 AI 插件内部有处理但 NGINX 的 buffering 在更底层生效把流式数据攒起来了。修复很简单在 Route 级别显式关掉{ proxy_buffering: false }这个坑的教训是AI 插件的流式能力依赖底层 NGINX 配置配合不能只看插件文档。上线前一定要用真实的长回答测试流式效果。5.2 token 统计对不上流式中断和并发场景的边界另一个坑是 token 统计。运营那边对账发现网关统计的 token 消耗和模型厂商账单对不上差了大概 5%。排查后发现两个原因。一是流式中断。用户点了“停止生成”或者网络抖动导致连接断开这时候最后一个带 usage 的 chunk 可能没收到这次调用的 token 就漏统计了。APISIX 有估算兜底但估算基于已收到的内容和实际生成的可能有差异。二是并发下的统计聚合。高并发时多个请求的 token 统计如果写同一个计数器可能有竞争。APISIX 用的是共享内存字典原子性有保障但如果你的监控系统拉取频率太高可能读到中间状态。应对办法对计费敏感的场景在业务层做二次对账以模型厂商的账单为准网关统计作为实时参考。不要完全依赖网关的 token 数做最终计费。5.3 多模型路由的故障转移为什么备用模型没被触发配置了主备两个模型主模型挂了但流量没切到备用这是很常见的问题。原因通常有几个。最常见的是健康检查没配。ai-proxy-multi的故障转移依赖上游健康状态如果你没配主动健康检查它不知道主模型已经挂了还会继续往那边发。要配上health_check配置定期探测。第二个原因是错误类型判断。有些错误比如 429 限流不应该触发故障转移因为备用模型可能也限流。APISIX 默认的转移策略对错误码有区分但如果你自定义了重试逻辑可能覆盖了默认行为。第三个原因是超时设置。主模型如果只是慢而不是完全不可用在超时之前不会触发转移。这时候用户会一直等。我的做法是给主模型设一个合理的超时超过就快速失败切备用宁可切换也不要让用户干等。5.4 提示词注入防护网关层能做什么、不能做什么安全方面网关层能做的是基于规则的初步过滤比如检测请求里有没有明显的注入模式、敏感词。APISIX 可以通过自定义插件或请求改写插件实现。但要说清楚网关层做不了深度的语义级防护那需要专门的模型或服务。我的实践是在网关层做两道一是长度和格式校验挡住明显异常的请求二是关键词黑名单挡住已知的注入模式。真正的深度防护放在业务层用专门的提示词安全模型做二次检查。网关层的定位是“快速挡住低级攻击减轻后端压力”不要指望它解决所有安全问题。6. 从能用到好用性能调优和可观测性建设6.1 高并发下的连接池和超时调优大模型请求是长连接、长耗时连接池配置和普通 API 完全不同。普通 API 可能几百毫秒就释放连接了大模型一个连接要占几十秒。如果连接池太小高并发时请求会排队等连接。关键参数是keepalive_pool的size和idle_timeout。size 要根据你的并发量估经验值是峰值并发的 1.5 倍左右。idle_timeout 要大于模型的最长响应时间否则连接还没用完就被回收了。超时方面connect_timeout可以短几秒但read_timeout和send_timeout要长几分钟。这三个要分开设不能一刀切。6.2 日志和指标怎么知道每个模型花了多少钱可观测性是 AI 网关容易被忽视但极其重要的一环。你至少要知道每个模型被调用了多少次、消耗了多少 token、平均响应时间多少、错误率多少。APISIX 的日志插件可以把这些信息打到访问日志里。关键是在日志格式里包含 token 和模型信息。ai-proxy插件会把 usage 信息放到请求上下文里日志插件可以引用。配合 Prometheus 插件还能把这些做成指标接 Grafana 看板。我一般会建几个核心看板按模型的 token 消耗趋势、按用户的调用分布、错误率和延迟的 P99。这几个指标能覆盖大部分运营和排障需求。6.3 成本控制的几个实用手段最后聊聊成本。大模型调用是真金白银网关层能做不少成本控制的事。一是按用户或租户做 token 配额防止单个用户刷爆。二是模型分级路由简单请求走便宜模型复杂请求走贵模型通过请求特征自动判断。三是缓存相同或相似的请求直接返回缓存结果APISIX 有缓存插件可以配合。四是请求合并把多个小请求合并成一次大请求减少调用次数。这些手段组合起来实测能省下不少成本。但要注意缓存对 AI 场景的适用性——大模型输出有随机性缓存要谨慎一般只对确定性强的场景比如固定问题的标准回答用。7. 我对 APISIX AI 网关的真实评价和选型建议用下来这段时间我的整体判断是APISIX 做 AI 网关的思路是对的它没有为了 AI 把网关搞成一个四不像而是在成熟的网关能力上做定向增强。插件化的设计让接入成本很低流式处理和 token 计量这两个核心能力也做得比较扎实。但它也不是银弹。如果你的场景非常简单就接一个模型、并发也不高那直接用官方 SDK 可能更省事没必要上网关。网关的价值在多模型管理、统一鉴权、集中限流、可观测性这些规模化场景下才体现得明显。选型时我建议重点看三件事一是流式处理是否真的无缓冲这个一定要实测二是 token 计量的准确性尤其是异常场景下的兜底三是多模型路由的故障转移是否可靠。这三点是 AI 网关的核心竞争力其他都是锦上添花。最后分享一个我自己的习惯每次接入新模型先不配任何高级插件就用最简配置跑通流式对话确认基础链路没问题再逐步加限流、路由、过滤。这样出问题时排查范围小不会一上来就被一堆插件配置绕晕。AI 网关的配置项比普通网关多不少循序渐进比一步到位靠谱得多。
