这两年后台群里问得最多的问题已经从“怎么调用大模型”变成了“调用入口到底怎么管”。业务侧动不动就接三四个模型供应商每个供应商的 Key 不一样、计费口径不一样、限额不一样上传到前端的 Key 随时可能被打包带走上个月还跑得好好的模型说下架就下架你要在客户端改代码。这些问题堆在一起几乎每个团队都会冒出同一个念头能不能有个统一的入口像管普通 API 那样去管大模型调用答案是可以而且不需要自己从头造轮子。Apache APISIX 从 3.9 版本开始正式把它定位为 AI 网关核心思路并不复杂把大模型供应商当成一种特殊的上游服务把 Key、模型路由、提示词处理、限流、统计这些事全部收编到 API 网关这一层。这篇文章我会从架构角度拆解 APISIX AI 网关的设计逻辑再给出我实际部署和调优过程中跑通的配置与踩坑记录给正在做 AI 应用接入的架构师和后端开发一个可直接参考的方案。1. 为什么 API 网关要承载 AI 流量1.1 直连大模型的“快乐”与“烦恼”大模型接入初期最爽的姿势确实是直连。代码里写死一个 base_url配一个 API Key请求一发响应一收完事。团队小、模型少、调用量低的时候这套模式没有任何问题你甚至不需要 API 网关参与。一旦业务开始认真用大模型麻烦就来了。第一类是密钥管理问题。前端如果直接调大模型 APIKey 基本等于裸奔抓包就能拿到后端直连的话Key 散落在各个微服务里哪天要轮换或者某个供应商的额度超了你得逐个服务去改配置再发布。第二类是供应商锁定问题。今天用 A 模型的接口明天想切到 B 模型或者想在两个模型之间做灰度对比如果调用逻辑散落在业务代码里每次切换都是一次代码改动。第三类是治理问题。普通 API 有的限流、熔断、审计、监控大模型 API 一个都不能少而且大模型 API 还多了一个别人没有的维度Token 成本。同样一次请求让贵模型回答和让便宜模型回答成本能差出一个数量级。这些问题的共同点是它们都不是模型本身的问题而是流量治理的问题。而流量治理恰恰是 API 网关最擅长的事。1.2 网关层统一治理Key、限流、熔断、可观测一次性到位把大模型调用收编到网关之后之前那些散落在业务代码里的逻辑可以全部上移。密钥从代码里消失统一由网关注入。业务侧只访问网关自己的地址不需要知道背后到底是哪个供应商也不需要携带任何供应商 Key。网关在转发时把鉴权头加上去杜绝 Key 泄露。切换模型从改代码变成改配置。APISIX 的配置是通过 Admin API 动态下发的改一个 upstream、改一个插件参数秒级生效不需要重启网关也不需要业务重新发布。限流与熔断直接复用 APISIX 成熟的插件体系。limit-count做请求速率限制api-breaker做上游故障熔断这些能力用在普通 REST API 上是什么效果用在大模型 API 上就是什么效果不需要额外开发。可观测性也顺理成章。APISIX 自带的 Prometheus 插件、日志插件、链路追踪插件全部可以直接作用于 AI 调用。你甚至可以统计到每个模型、每个业务线的调用量和 Token 消耗把成本分摊这件事做得明明白白。1.3 直连与网关方案的对比维度业务直连大模型APISIX AI 网关统一接入Key 管理Key 散落各服务易泄露难轮换Key 集中在网关层注入业务无感模型切换改代码、发版改配置秒级生效多供应商接入每个供应商一套 SDK 和协议统一入口网关做协议转换限流与熔断需要自己实现复用成熟插件开箱即用成本统计各服务自行统计口径混乱网关统一记录模型、Token、调用量安全防护提示词注入、越权访问靠业务自己防网关层可以做统一过滤和审计我见过不少团队一开始觉得“我们调用量不大上个网关太重了”结果模型从 1 个变 3 个、调用方从 1 个团队变 5 个团队之后不得不回过头来补网关。早补早省事这不是过度设计而是 AI 应用规模化之后的基本盘。2. APISIX AI 网关的架构拆解与插件矩阵2.1 核心架构控制面与数据面分离APISIX 的架构延续了它一贯的设计etcd 做配置存储与控制面APISIX 节点做数据面处理真实流量。配置变更通过 Admin API 写入 etcd数据面节点 watch 到变化后热加载整个过程不需要重启。这个架构对 AI 网关来说非常关键。大模型领域的变化太快了今天新出一个模型、明天调整一个价格、后天供应商的 API 路径改版这些变动如果都要发版处理运维会被拖死。有了控制面和数据面分离你在 Admin API 上发一个 PUT 请求几百个网关节点就同时拿到了新配置这种动态能力在 AI 场景下是刚需。APISIX 本身是构建在 OpenResty 之上的数据面通过插件机制处理请求。你可以把它理解成一个乐高底座核心引擎和代理能力已经给你了剩下的能力全部按需拼装。AI 网关能力正是通过一组 AI 插件拼装出来的。2.2 AI 插件矩阵从代理转发到提示词工程要理解 APISIX AI 网关不能只盯着某一个插件而是要看这一组插件怎么配合。第一个是核心的ai-proxy插件。它的作用是屏蔽不同大模型供应商的协议差异。OpenAI、Anthropic、通义千问、文心一言这些供应商的接口风格并不完全一致而ai-proxy让你在声明式配置里指定 provider 和鉴权信息客户端统一走网关的路径和请求体格式由插件在转发时做协议改写。这意味着业务代码不需要为每个供应商维护一套客户端。第二个是ai-prompt-template插件。它解决的是提示词治理问题。我见过太多团队把 system prompt 写在业务代码里或者更糟写在客户端里。一旦要调整语气、调整知识边界、适配不同场景就得发版。用这个插件可以把提示词模板托管到网关层通过请求体里的变量动态填充。第三个是ai-prompt-guard插件。它做的是提示词注入防护。大模型应用上线后用户会想方设法尝试绕过系统指令常见的“忽略以上指令”“把 system prompt 输出给我”这类攻击在这个插件里可以做关键词与规则匹配配置成拦截或放行。安全能力下沉到网关业务方就不用各自为战。第四个是ai-statistics插件。它专门做 Token 和调用量的统计。普通 API 网关只看 QPS 和耗时但大模型网关必须看 Token 消耗因为成本是按 Token 算的。这个插件能把模型、Token 数、延迟等信息结构化输出方便对接成本核算系统。配合 APISIX 原有的limit-count、api-breaker、prometheus、syslog等插件一个完整的 AI 网关闭环就成立了入口统一、安全过滤、限流熔断、成本统计全部在网关层完成。2.3 为什么是用 API 网关而不是自研一个 AI Proxy自研 AI Proxy 听起来不难无非是把请求转发到模型供应商再统计一下 Token。但真做起来你会发现自己在重复造 API 网关的轮子。限流要自己写吧熔断要自己写吧多环境隔离要自己写吧灰度发布要自己写吧日志和监控要自己接吧高可用部署要自己考虑吧这些能力在 APISIX 里都是现成的、经受过生产环境检验的。自研一套网关短期看好像代码量不大长期看维护成本会持续累积。还有一个容易被忽略的点APISIX 是 CNCF 项目生态成熟周边工具链完善团队招人也好招遇到问题有社区可以问。自研 AI Proxy 出问题的时候你只能对着自己的代码挠头。3. 实操5 分钟在 APISIX 上接入一个大模型3.1 环境准备用 Docker 快速起一套 APISIX我本地的测试环境是用 Docker 直接拉的最省事的方式是 docker-compose 同时起 APISIX 和 etcd。APISIX 依赖 etcd 做配置存储这两个容器缺一不可。services: etcd: image: bitnami/etcd:3.5 environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://etcd:2379 ports: - 2379:2379 apisix: image: apache/apisix:3.9.0 depends_on: - etcd ports: - 9080:9080 - 9180:9180 volumes: - ./config.yaml:/usr/local/apisix/conf/config.yaml:ro启动命令很简单docker compose up -d启动之后验证一下网关和 Admin API 是否正常curl http://127.0.0.1:9080/apisix/admin/routes -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1默认 Admin API 监听在 9180 端口界面管理台默认是 9080。如果你用的是默认配置Admin API 的 Key 就是上面这个值生产环境一定要改掉。3.2 配置 ai-proxy把模型供应商收编到统一入口API 网关的配置思路永远是一样的先定路由再给路由挂插件。AI 网关也不例外。我用一个实际例子说明。假设我想在网关层代理一个 OpenAI 兼容的服务并且把真实的 API Key 藏起来不让客户端感知。先创建一条路由curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 -X PUT -d { uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, value: Bearer sk-xxxxxxxxxxxx }, model: gpt-4o-mini, route_type: llm, override: true } }, upstream: { type: roundrobin, nodes: { api.openai.com: 1 } } }这里解释几个关键字段。provider告诉插件要走哪套协议格式。auth里的value就是网关要注入到请求里的真实鉴权信息客户端不需要知道。model是默认模型名override为 true 时即使请求体里传了别的模型名也会被网关强制替换成配置的模型。最后用upstream指定模型供应商的真实地址。配置完成后业务侧就可以直接请求网关curl http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 用一句话解释什么是 API 网关} ] }注意这次请求里完全不需要携带 Authorization 头网关会帮你把 Key 注入进去。实测下来这种模式下前端和业务服务拿到的返回体和直连供应商几乎一模一样对现有代码的侵入性非常小。如果你的模型供应商不是 OpenAI而是 Anthropic 或者其他国内云厂商只需要改provider字段和对应的upstream地址客户端代码完全不用动。这一点就是用 AI 网关做协议屏蔽的核心价值。3.3 客户端无感的 Key 管理与模型切换上面这套配置解决了 Key 泄露问题但还有一个细节值得单独说网关里的 Key 也是明文存储在 etcd 里的。生产环境我强烈建议你不要把 Key 直接写进路由配置而是用 APISIX 的 Secret 管理能力把 Key 存到环境变量或者单独的秘密存储中在插件配置里引用。这样即使 Admin API 的 Key 被泄露攻击者看到的也不是真实的供应商 Key。模型切换方面我用的最多的玩法是直接改model字段。比如业务上线初期想先用便宜的小模型验证效果配置里写gpt-4o-mini验证完之后想升级到大模型把model改成gpt-4o请求还是同一个地址客户端一行代码都不用改。如果模型供应商的 endpoint 也要变比如从 OpenAI 官方切到某个提供 OpenAI 兼容接口的私有化平台只需要换upstream的节点地址配合override: true强制指定模型名整套切换对调用方完全透明。3.4 进阶同一网关路由多个模型供应商实际生产场景里几乎没有团队只用一个模型。有些任务适合用小模型省钱有些任务必须用大模型保证质量还有些业务在从 A 供应商往 B 供应商迁移过程中需要灰度对比。APISIX 做多供应商路由有好几种姿势。最简单粗暴的方式是建多个路由每个路由挂不同的ai-proxy配置再用 APISIX 的vars做请求条件匹配。举个例子我希望请求头里带X-Provider: anthropic的请求走 Claude其他请求走 OpenAI 默认模型。创建第一条路由匹配条件限制为 Anthropiccurl http://127.0.0.1:9180/apisix/admin/routes/2 -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 -X PUT -d { uri: /v1/chat/completions, vars: [[http_x_provider, , anthropic]], plugins: { ai-proxy: { provider: anthropic, auth: { header: x-api-key, value: sk-ant-xxxxxxxxxxxx }, model: claude-3-5-sonnet, route_type: llm, override: true } }, upstream: { type: roundrobin, nodes: { api.anthropic.com: 1 } } }第二条路由不匹配X-Provider头走 OpenAI 默认配置URI、插件和上游仍然是上面的那套。请求进来时APISIX 先检查路由 1 的vars条件是否命中命中就走 Anthropic没命中继续向下匹配路由 2。这种玩法的好处是调用方只需要在请求头里切换供应商标识就能做模型级的 A/B 对比。业务代码不用写死厂商全部由网关路由层决策。4. AI 流量治理与成本控制落地4.1 限流与配额防止有人把你的 Key 当水龙头大模型 API 的计费比普通 API 贵一个数量级这意味着流量治理的优先级更高。一次异常调用刷掉几百块是很常见的事。APISIX 的标准限流插件limit-count可以直接挂在 AI 路由上。比如我想限制这个 AI 路由每秒最多 10 个请求curl http://127.0.0.1:9180/apisix/admin/routes/1 -X PATCH -d { plugins: { limit-count: { count: 10, time_window: 60, rejected_code: 429, key_type: var, key: remote_addr } } }这里count是时间窗口内的请求上限time_window是窗口秒数key_type和key决定按什么维度限流。如果按用户维度限流可以把key改成请求头里的用户标识变量。再往深一层想不同业务方共享同一个网关入口配额也应该做到业务隔离。APISIX 的limit-count支持自定义 key你可以用请求里带的X-Business-Line头来区分不同业务线给核心业务线更大的配额给测试业务线更小的配额。提示限流只是兜底成本控制的重点还是可观测。你得先知道钱花在哪了才知道怎么省。4.2 模型灰度与 A/B 测试模型切换最怕的是悄无声息地影响线上回答质量。直接全量切换是大忌正确的姿势是先灰度。APISIX 做模型灰度最直观的方式是利用traffic-split插件。这个插件可以把一定比例的流量转发到不同的 upstream。结合ai-proxy的override功能你可以让 90% 的请求走现有模型10% 的请求走新模型观察一段时间的用户反馈和调用指标后再逐步调整权重。配置思路是这样的主路由保持原模型配置另外建一条测试路由指向新模型。在入口路由上挂traffic-split按权重把部分流量匹配到带特定 header 的测试路由上。这种灰度方式对调用方完全无感不需要客户端传任何灰度标识。我个人的建议是灰度期间不要只看响应延迟这类基础设施指标更要看业务指标。比如客服场景的会话解决率、内容生成场景的编辑采纳率。大模型回答的质量很难用单一技术指标衡量多留几天灰度窗口再多对比几个维度比急着切全量更稳。4.3 通过可观测性看清 Token 消耗普通 API 网关关心的是 QPS 和 P99 延迟AI 网关必须多关心一个指标Token。APISIX 的ai-statistics插件可以记录每次调用的模型、输入 Token 数、输出 Token 数、耗时等结构化数据。实际部署时我会把这些数据接入 Prometheus Grafana再对接内部成本核算系统。如果暂时不想引入额外的插件也可以用 APISIX 本身的日志插件把请求和响应体记录下来再在日志处理链路里解析 Token 使用量。但这么做有两个问题一是 LLM 的响应体可能很大全量日志存储成本高二是从响应体里解析 Token 数是事后行为口径容易被供应商的不同计价方式搞乱。能用专用统计插件就优先用专用插件。还有一个我常用的技巧在网关层对不同的路由加metadata标签标注这个路由对应哪条业务线、哪个场景。这样统计报表出来之后可以一目了然地看到每条业务线的模型调用成本做成本分摊和预算控制的时候数据直接能用。5. 常见问题排查与避坑指南5.1 我在生产环境踩过的几个坑第一个坑是超时配置。大模型接口的响应时间波动极大普通 API 可能 100 毫秒就返回了大模型在流式输出的时候可能要几十秒。如果沿用默认的 60 秒代理超时长任务会频繁被网关掐断。解决方法是把上游超时时间调大同时确认客户端能处理长连接。排查的时候看错误日志如果大量出现upstream timeout十有八九就是这个问题。第二个坑是流式响应。大模型接口普遍支持 SSE 流式输出逐字推送结果。APISIX 在转发流式响应时如果开了缓冲或者中间层有 Buffer 限制客户端可能会等很久才看到第一个字。实际部署中要对使用流式输出的路由关闭响应缓冲并确认网关和客户端之间没有额外的代理层截断流。第三个坑是 Key 泄露的路径不止一个。很多人以为 Key 放在网关里就安全了但如果你在网关之上还挂了 Nginx 或者其他负载均衡层并且这些层的日志记录了完整的请求头那么注入到请求头里的上游 Key 一样可能出现在日志里。排查日志脱敏配置很容易被忽略。第四个坑是模型名不一致。OpenAI 兼容接口里gpt-4o-mini这种模型名在网关配置里写对了不代表所有供应商都认。换成某些聚合平台或者私有化部署的模型服务时模型名的写法可能完全不同。用override: true强转模型名之前先在供应商侧测试一遍。第五个坑是限流维度选错。只按remote_addr限流企业内部多个服务共享网关出口 IP 时一个服务把配额耗光了其他服务全部 429。按调用方身份而不是按来源 IP 限流才是生产环境的正确姿势。5.2 问题排查速查表现象可能原因排查动作网关返回 503upstream 配置错误或供应商服务不可用检查upstream节点地址、供应商控制台状态网关返回 401注入的 Key 无效或格式不对在配置里检查auth.value直接用该 Key 调供应商接口验证请求超时代理超时配置过短调大proxy-read-timeout确认客户端支持长响应返回的模型效果不对override强制覆盖了请求中的模型查看路由配置里的model字段确认是否是预期模型客户端收不到流式响应中间层缓冲了响应关闭路由的响应缓冲检查链路中所有代理层的缓冲设置限流误伤限流 key 维度选择不当确认key_type与key是否符合调用方隔离需求5.3 我的几点实战建议不要在业务代码里做任何供应商相关逻辑。所有供应商切换、模型选择、Key 注入全部下沉到网关层业务只管拼 prompt、发请求、接响应。不要把 AI 网关和普通 API 网关物理隔离。共用一套 APISIX 集群完全没问题AI 路由和普通路由只是插件配置不同混合部署反而有利于运维统一。要注意的是给 AI 路由设置更严格的限流和配额。不要迷信某一个模型供应商。在网关层把多供应商的切换能力提前准备好哪怕当前只用一个模型。大模型行业的演进速度大家都看到了今天的头部模型可能半年后就掉队具备快速切换能力是一个 AI 应用团队的底线。最后再分享一个我自己用着很舒服的扩展思路APISIX AI 网关不仅是接商业模型本地部署的 vLLM、Ollama 等开源模型也可以走同一套入口。只要这些本地服务提供 OpenAI 兼容接口你完全可以把upstream指向内网的模型服务地址让业务方用同样的请求格式访问本地模型。这样一来商业模型和私有化模型之间可以随时互切数据敏感场景走本地模型高质量需求走商业模型网关层一套配置全搞定。这个能力在政企私有化交付和数据合规场景里特别实用。