做基础架构这些年我一直觉得网关是那种“平时没人记得、出事全是你的”组件。但这半年情况变了团队里接入大模型LLM的业务越来越多API 网关反而成了最受关注的一层甚至到了“没有网关不敢上线 AI 功能”的地步。原因不复杂。大模型不是一个普通的后端服务它带来了新的协议、新的计费模型、完全不同的延迟特征和新的安全边界。直接把这些问题丢给业务团队等于在每个应用里埋雷。Apache APISIX 从 3.9 版本开始陆续引入 AI 相关插件一步步把传统 API 网关扩展成了真正的 AI 网关。这篇文章我会从架构思路、核心插件、实操配置到踩坑经验把这条路径完整串一遍给正在做选型或者已经被大模型接入折磨过的同行一些参考。1. 为什么大模型时代需要 API 网关1.1 业务接入大模型的三个老大难先说最直观的问题。假设你现在负责公司的基础架构某天产品经理告诉你“我们要在 10 个业务线里用上大模型”接下来的三件事会让你的头发迅速减少。第一是协议碎片化。OpenAI 的协议、Anthropic 的协议、Azure 的协议、AWS Bedrock 的协议再加上国内各家模型厂商各自的原生接口。虽说现在很多厂商都提供了 OpenAI 兼容端点但请求格式、鉴权头、模型命名、流式交互的方式还是存在细节差异。每个业务团队都自己对接一遍等于同一份错误犯了十次。第二是密钥和权限管理失控。业务方直接拿厂商密钥去调模型密钥分散在各处代码仓库里、配置文件里、甚至前端页面里。一旦某个前端把 key 暴露出去别人就能拿着它白嫖你的模型额度账单直接爆炸。第三是成本和稳定性无法度量。大模型是按 token 计费的一个普通聊天请求可能花几分钱一个长上下文总结请求可能花几块钱。没有统一的网关层你根本不知道哪个业务在烧钱也不知道哪个调用慢是因为模型服务本身慢还是因为业务代码写得烂。这三点叠加在一起结论很清楚你需要一个统一入口来做接入、鉴权、流控、计费和观测。这就是 API 网关在大模型时代的价值起点。1.2 网关层统一接管之后把大模型接入收编到网关之后架构会清爽很多。业务方不再需要持有任何厂商密钥他们只要向网关申请一个访问凭证网关在转发请求时自动注入真正的模型密钥。密钥只存在于网关配置和网关所在的环境里攻击面大幅缩小。限流也不再是空话。传统限流看 QPS但大模型的成本更依赖 token 消耗和并发连接数。你可以针对不同业务方配置调用配额比如 A 团队每天最多消耗 500 万 tokenB 应用高峰期最多同时发起 20 个流式请求。网关既能扛住突发流量也能防止内部滥用。再往下是灰度发布。换模型这件事比换数据库还敏感因为模型行为不可精确预期。有了网关新模型可以先切 5% 的流量观察延迟和成本稳定后再逐步放量。就算新模型翻车随时可以一键切回旧模型代价比重新发版小得多。最后是可观测性。网关作为必经之路把每次请求的模型名称、token 消耗、响应延迟、成本全部记录下来按业务线、按模型、按时间段聚合。有了这些数据你才能回答老板那句“我们的 AI 功能到底烧了多少钱”。1.3 一套通用的 AI 网关架构长什么样从我落地的经验看一套通用的 AI 网关架构大概是这样的客户端或者业务后端请求先打到网关网关层负责路由、认证、限流、提示词模板渲染、成本统计和日志然后网关把请求转发到实际的模型服务这个模型服务可能是外部厂商 API也可能是你私有化部署的 vLLM、LocalAI 之类的推理服务。旁边还会挂两个辅助系统一是 RAG 检索服务负责把知识库内容查出来拼进提示词二是日志和监控系统接收网关产生的访问日志和指标数据。整套架构的核心原则是业务代码只面对一个稳定的 OpenAI 风格接口底层接的是哪家模型、怎么计费、怎么限流都由网关解决。这套架构最大的好处是稳定。业务方不需要关心模型供应商的变更你今天用通义明天切 DeepSeek对业务代码来说只是网关配置的一次改动。所以与其说是 API 网关遇见了大模型不如说是大模型这种新型后端服务终于迎来了真正能管住它的基础设施。2. APISIX AI 网关的核心能力拆解2.1 ai-proxy把“接入模型”从开发变成配置APISIX AI 网关的基石插件是 ai-proxy。它的作用可以简单理解为一个懂大模型协议的智能代理。传统的 proxy 插件只负责转发字节流完全不关心你在调什么接口而 ai-proxy 理解 OpenAI、Azure OpenAI、AWS Bedrock、GCP Vertex AI 等主流大模型服务的协议格式也支持智谱 AI 这类国内原生 provider。我在生产环境中最常用的姿势是让网关对外暴露一个固定的 OpenAI 兼容接口/v1/chat/completions内部再由 ai-proxy 转发到不同厂商。配置起来非常直观{ uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, token: sk-你的密钥 }, model: gpt-4o-mini, override_model: true } } }这里有几个关键点。provider决定 ai-proxy 按哪种协议、哪个默认地址去转发。override_model设为 true 后客户端请求里如果自己指定了 model就以客户端的为准设为 false 则强制使用网关配置的模型防止业务方乱选贵模型。我建议在正式环境把 override_model 设为 false成本控制会容易得多。用了 ai-proxy 之后路由上通常不需要再配 upstream因为转发目标由 provider 决定。这一点和传统路由差异很大刚上手的人很容易下意识去配一个 upstream结果发现 ai-proxy 的请求根本没走后端业务服务全被插件接管了。2.2 ai-prompt-template提示词模板在网关层沉淀模型接入稳定之后第二件让人头疼的事情是提示词管理。早期业务代码里到处散落着拼 prompt 的字符串不同的开发者维护各自的版本系统提示词改一个字都要发版上线审计的时候根本说不清线上跑的是哪个版本。ai-prompt-template 插件解决的就是这个问题。它允许你在网关层定义一组提示词模板支持模板变量业务方在请求时传入变量值网关渲染完再交给模型。一个简化的配置长这样{ plugins: { ai-prompt-template: { templates: { code_review: { system_prompt: 你是一名资深代码评审工程师请从正确性、可维护性、安全性三个角度给出评审意见。, user_prompt_pattern: 请评审以下代码{{code}} } } } } }业务方调用时只需要请求体里带上 template 名称和 code 变量网关自动渲染。模板集中管理之后prompt 的修改可以走配置变更流程回滚也简单不用再反复折腾业务服务。不过我要提醒一句prompt 模板化之后对用户的输入变量一定要做长度和内容校验。满屏的“忽略之前的指令”就是靠模板里混入用户输入来攻击模型的网关层加一道清洗和截断能挡掉大多数不怀好意的尝试。2.3 ai-vendors多模型供应商的集中管理ai-proxy 解决了“怎么转发”的问题但如果你有多个模型供应商、多套密钥、多个 base_url每个路由都写一遍认证信息还是很痛苦。ai-vendors 插件就是为此设计的它把模型供应商的配置抽成独立资源统一管理 base_url、认证方式、模型列表等路由只需要引用 vendor 名称。大致的使用方式是先创建一个 vendor 资源{ name: deepseek-main, provider: openai, api: { base_url: https://api.deepseek.com/v1, auth: { type: bearer, token: sk-deepseek密钥 } } }然后在路由里引用它{ plugins: { ai-proxy: { vendor: deepseek-main, model: deepseek-chat } } }这样做的好处是变更集中。比如某个厂商因为备案或者迁移换了域名你只需要改 vendor 里的 base_url所有引用它的路由立刻生效。密钥轮换也是同理一次修改全局生效不用逐条改路由。如果你在管理多个模型供应商ai-vendors 基本是必上插件。2.4 ai-cost 与 ai-latency成本与延迟的精细观测大模型网关不能只看 QPS必须看 token 和成本。APISIX 在 AI 场景下提供了 ai-cost 和 ai-latency 两个观测类插件我用下来觉得它们才是 AI 网关和传统网关最不一样的地方。ai-cost 会从模型响应里解析出 prompt_tokens、completion_tokens 以及模型名称计算每次请求的成本指标并暴露给 Prometheus 或写入访问日志。配合 APISIX 的日志插件你可以把成本数据按业务线、按模型维度汇总每天跑一张报表出来。这样“哪个业务在烧钱”就不需要拍脑袋了。ai-latency 则把一次大模型请求拆成了多个阶段客户端连上网关的耗时、网关转发到模型服务的耗时、等待第一个 token 返回的时间TTFB、流式传输的总时长。TTFB 是衡量模型服务真实性能的关键指标如果 TTFB 很长说明推理服务本身慢跟网关无关如果 TTFB 很短但总时长很长说明是流式生成阶段慢那就要考虑模型输出长度是不是太长了。我实测下来这两个插件对长尾问题非常有用。特别是流式请求业务方很容易觉得是网关吞了响应但 ai-latency 的数据能清楚告诉你时间到底花在哪一段。2.5 进阶场景RAG 与 AI 安全策略在网关落地当 AI 网关承担的角色越来越多它还可以承载一些进阶能力。比如 ai-rag 插件让网关在转发前先从向量数据库里检索相关知识再拼进提示词。这比在业务代码里单独接 RAG 更统一尤其适合多团队共建知识库的场景。另一个方向是安全。大模型请求的审计日志天然应该放在网关层谁在什么时候问过什么问题理应是可追溯的。网关还可以统一接入 WAF 类插件对请求体做关键词匹配、敏感信息识别。虽然网关不能替代专门的大模型安全防护系统但作为第一道闸门已经能拦掉很多低级风险。我个人的建议是不要把太业务化、太定制化的逻辑塞进网关。网关适合放通用能力认证、限流、协议、观测、基础安全。凡是“只有某个业务才需要”的逻辑留在业务侧更好否则网关配置会膨胀成一个没人敢动的怪兽。3. 实操从零搭建一个可用的 APISIX AI 网关3.1 部署docker compose 起一套 APISIX实操部分我们从零开始。最简单的方式是用 docker compose 把 etcd 和 APISIX 跑起来。etcd 是 APISIX 的配置存储相当于它的数据库。services: etcd: image: bitnami/etcd:3.5 restart: always environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://etcd:2379 ports: - 2379:2379 apisix: image: apache/apisix:3.12.1-debian restart: always depends_on: - etcd environment: - ETCD_HOSTetcd ports: - 9080:9080 - 9180:9180 volumes: - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro这里注意9080 是数据面端口所有真实请求走这里9180 是 Admin API 端口用来配置路由和插件。生产环境里 9180 绝对不能直接暴露到公网必须做访问控制。容器起来之后先验证 Admin API 是否正常curl http://127.0.0.1:9180/apisix/admin/routes \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1能返回一个 JSON 数组就说明环境没问题。需要提醒的是AI 插件在 APISIX 3.9 版本后才陆续引入ai-vendors 在更新的版本里才比较完善建议直接用 3.12 或更新的稳定版省得踩版本坑。3.2 第一个 AI 路由对接 OpenAI 兼容协议假设你现在要接一个支持 OpenAI 兼容协议的大模型服务创建一个路由如下curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/ai-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, token: sk-你的密钥 }, model: gpt-4o-mini, override_model: false } } }创建好之后直接往里打请求curl http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好用一句话介绍自己}], stream: false }能收到模型回复说明网关已经成功代理了模型服务。整个过程没有业务代码参与纯粹是配置驱动的接入。这个路由的 URI 是/v1/chat/completions对你下游的所有业务来说它们看到的仍然是 OpenAI 风格的接口将来换成其他供应商业务代码一行都不用改。3.3 对接国内大模型以 DeepSeek 和通义为例国内用户真正高频使用的还是国产模型。好消息是绝大多数国产模型服务都提供了 OpenAI 兼容端点这意味着你不需要等 APISIX 出专属 provider直接复用 openai provider 然后改 base_url 就行。以 DeepSeek 为例先创建一个 vendorcurl -X PUT http://127.0.0.1:9180/apisix/admin/ai_vendors/deepseek-main \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { name: deepseek-main, provider: openai, api: { base_url: https://api.deepseek.com/v1, auth: { header: Authorization, token: sk-deepseek密钥 } } }然后再建路由引用这个 vendorcurl -X PUT http://127.0.0.1:9180/apisix/admin/routes/deepseek-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, plugins: { ai-proxy: { vendor: deepseek-main, model: deepseek-chat } } }通义千问的操作逻辑一样base_url 换成https://dashscope.aliyuncs.com/compatible-mode/v1模型名换成qwen-plus之类的即可。这里有个小技巧如果一个模型服务厂商提供了原生 provider比如智谱 AI那就直接用原生 provider如果只提供 OpenAI 兼容接口就用 openai provider 加自定义 base_url。前者的协议适配更完善后者更通用二者可以并存。3.4 流式输出与超时调优大模型聊天几乎必然用到流式输出。SSEServer-Sent Events协议让模型一段一段地吐文字用户看到的是打字机效果体感远好于等完整响应。网关层对流式请求最怕两件事连接被缓冲、连接被超时杀掉。默认情况下APISIX 的流式转发是 OK 的但如果你在 APISIX 前面还挂了一层 nginx 或者其他反代那层代理极有可能开启缓冲导致前端迟迟收不到数据。排查手段很简单用 curl 直连网关测试流式请求。curl -N http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: 讲一个三句话的笑话}], stream: true }如果 curl 能逐段输出但业务前端收不到问题大概率在你和客户端之间的网络组件上。如果 curl 也卡住那就要看超时配置。APISIX 默认的 nginx 读超时是 60 秒大模型一次正常的流式回答动辄 30 秒到 90 秒遇到长文本可能更久。我习惯把全局超时调到 300 秒方法是在 config.yaml 里改nginx_config: http: proxy_read_timeout: 300s proxy_send_timeout: 300s改完重启 APISIX 再用 curl 测长对话就不会被莫名其妙掐断了。注意这和使用哪个模型无关纯粹是网关到模型服务这条链路的超时设置建议统一调大反正大模型服务本身就是慢服务没必要按普通 HTTP 接口的标准去卡它。3.5 多模型供应商管理与灰度切换模型供应商多了之后最实用的玩法是做多模型路由和灰度切换。我常用的方案是基于请求头做条件路由默认流量走主力模型测试流量走新模型。比如主力模型用 DeepSeek新模型准备切到通义。先创建通义的 vendor然后创建第二条路由URI 同样是/v1/chat/completions但加了一个条件只有请求头里带着X-Model-Backend: qwen的请求才命中这条路由。curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/qwen-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, vars: [ [http_x_model_backend, , qwen] ], plugins: { ai-proxy: { vendor: qwen-main, model: qwen-plus } } }默认请求仍然落在 DeepSeek 那条路由上只有内测业务方带特殊 header 才会走到通义。观察一段时间后如果新模型在延迟和成本上都符合预期就让网关团队把默认路由的 vendor 改成通义灰度完成。这个流程不需要业务方配合也不需要重新发版操作起来非常顺滑。4. 踩坑实录与排查清单4.1 流式响应白屏或断流这是 AI 网关上线后最常被业务方骂的问题。表象是Stream 模式下前端偶尔收到一半就断了界面卡在白屏。我一开始以为是 APISIX 的 bug后来定位到是前端和网关之间的网络链路有缓冲代理。Nginx 默认开启 proxy_buffering会让 SSE 数据攒到一定量才转发流式效果直接报废。排查时先在网关这一层用curl -N测试确认网关本身没问题再逐层检查前面的代理。另外如果每个 token 之间的生成间隔超过读超时时间连接也会被断开。长对话场景模型思考时间较长一定记得把超时调大。4.2 请求超时导致 504大模型生成慢不是 bug但默认超时设置会把它变成 bug。如果你的请求在模型生成到一半时返回 504十有八九是网关到模型服务的读超时不够长。记住大模型接口不能用普通 API 的 30 秒标准来设计直接把 read_timeout 和 send_timeout 拉到 300 秒是更稳的选择。另外要注意超时不止存在于网关这一层客户端到网关的超时也要设置。如果客户端设置了 30 秒超时网关就算等 300 秒也没有意义前端早就放弃等待了。全链路超时参数要一起调整。4.3 密钥泄漏风险我见过最惊险的一次事故是有人把模型密钥写在了前端配置里被爬虫抓走后刷了几万块。AI 网关落地后业务方就不应该再接触厂商密钥了所有密钥统一收口到网关配置。密钥的读取和存储也要做好隔离Admin API 的 X-API-KEY 不要用默认值9180 端口禁止公网访问etcd 的数据目录做好权限控制。如果团队有专门的密钥管理服务比如 Vault可以把 vendor 里的 token 用环境变量或者进程注入的方式引用而不是硬编码在配置文件中。这个细节越早做越省心。4.4 成本统计对不上账ai-cost 插件能统计 token 消耗但和厂商账单对不上是常态。厂商账单通常按实际生成量计费包括缓存命中、中途失败的 token而网关侧的统计会漏掉一些异常中断的请求或者因为流式输出在客户端断开后终止统计到的 completion_tokens 少于实际生成量。我的做法是把网关日志里的 ai-cost 数据落库按模型、按业务方、按天做聚合和厂商账单的差异控制在 5% 以内就算可接受。真正要盯的是趋势哪天某个业务线的 token 消耗突然翻倍那大概率是出问题了而不是纠结那百分之几的统计误差。4.5 常见问题速查表现象可能原因解决办法401/403vendor 里 token 错误或已过期检查并轮换密钥确认鉴权头格式404 Not Found路由 URI 与请求路径不匹配统一走 /v1/chat/completions400 Bad Request模型名错误或请求体不符合协议核对 vendor 支持的模型名504 Gateway Timeout网关到模型服务超时调大 nginx 超时和 AI 转发超时流式响应中断缓冲代理或单次生成超时curl -N 逐层排查、关缓冲、调超时跨域报错前端直接调用网关配置 cors 插件并限制来源最后聊几句实在的这套 AI 网关方案我在团队内部用了大半年最大的感受是大模型接入终于从“开发任务”变成了“配置任务”。新业务要接 AI不再需要到处找密钥、写协议适配、担心被刷爆账单只需要提交一条路由配置剩下的认证、流控、成本统计都是网关自动兜底。如果后续要在这个方案上继续扩展我建议优先考虑三件事一是把私有化部署的推理服务比如 vLLM接进来让网关同时管理外部 API 和内部算力二是把多租户配额体系做起来每个业务方在网关层能清晰地看到自己的额度和消耗三是把请求审计日志接入公司内部的审计系统做到每一次 AI 调用都有据可查。网关这东西不性感但它是大模型真正进入企业架构的最短路径。当你被问“AI 能力怎么接入”的时候别再让它变成一场混乱的踩坑大战把网关卡在最前面一切都会顺很多。
APISIX AI网关实战：从大模型接入到成本监控的完整指南
做基础架构这些年我一直觉得网关是那种“平时没人记得、出事全是你的”组件。但这半年情况变了团队里接入大模型LLM的业务越来越多API 网关反而成了最受关注的一层甚至到了“没有网关不敢上线 AI 功能”的地步。原因不复杂。大模型不是一个普通的后端服务它带来了新的协议、新的计费模型、完全不同的延迟特征和新的安全边界。直接把这些问题丢给业务团队等于在每个应用里埋雷。Apache APISIX 从 3.9 版本开始陆续引入 AI 相关插件一步步把传统 API 网关扩展成了真正的 AI 网关。这篇文章我会从架构思路、核心插件、实操配置到踩坑经验把这条路径完整串一遍给正在做选型或者已经被大模型接入折磨过的同行一些参考。1. 为什么大模型时代需要 API 网关1.1 业务接入大模型的三个老大难先说最直观的问题。假设你现在负责公司的基础架构某天产品经理告诉你“我们要在 10 个业务线里用上大模型”接下来的三件事会让你的头发迅速减少。第一是协议碎片化。OpenAI 的协议、Anthropic 的协议、Azure 的协议、AWS Bedrock 的协议再加上国内各家模型厂商各自的原生接口。虽说现在很多厂商都提供了 OpenAI 兼容端点但请求格式、鉴权头、模型命名、流式交互的方式还是存在细节差异。每个业务团队都自己对接一遍等于同一份错误犯了十次。第二是密钥和权限管理失控。业务方直接拿厂商密钥去调模型密钥分散在各处代码仓库里、配置文件里、甚至前端页面里。一旦某个前端把 key 暴露出去别人就能拿着它白嫖你的模型额度账单直接爆炸。第三是成本和稳定性无法度量。大模型是按 token 计费的一个普通聊天请求可能花几分钱一个长上下文总结请求可能花几块钱。没有统一的网关层你根本不知道哪个业务在烧钱也不知道哪个调用慢是因为模型服务本身慢还是因为业务代码写得烂。这三点叠加在一起结论很清楚你需要一个统一入口来做接入、鉴权、流控、计费和观测。这就是 API 网关在大模型时代的价值起点。1.2 网关层统一接管之后把大模型接入收编到网关之后架构会清爽很多。业务方不再需要持有任何厂商密钥他们只要向网关申请一个访问凭证网关在转发请求时自动注入真正的模型密钥。密钥只存在于网关配置和网关所在的环境里攻击面大幅缩小。限流也不再是空话。传统限流看 QPS但大模型的成本更依赖 token 消耗和并发连接数。你可以针对不同业务方配置调用配额比如 A 团队每天最多消耗 500 万 tokenB 应用高峰期最多同时发起 20 个流式请求。网关既能扛住突发流量也能防止内部滥用。再往下是灰度发布。换模型这件事比换数据库还敏感因为模型行为不可精确预期。有了网关新模型可以先切 5% 的流量观察延迟和成本稳定后再逐步放量。就算新模型翻车随时可以一键切回旧模型代价比重新发版小得多。最后是可观测性。网关作为必经之路把每次请求的模型名称、token 消耗、响应延迟、成本全部记录下来按业务线、按模型、按时间段聚合。有了这些数据你才能回答老板那句“我们的 AI 功能到底烧了多少钱”。1.3 一套通用的 AI 网关架构长什么样从我落地的经验看一套通用的 AI 网关架构大概是这样的客户端或者业务后端请求先打到网关网关层负责路由、认证、限流、提示词模板渲染、成本统计和日志然后网关把请求转发到实际的模型服务这个模型服务可能是外部厂商 API也可能是你私有化部署的 vLLM、LocalAI 之类的推理服务。旁边还会挂两个辅助系统一是 RAG 检索服务负责把知识库内容查出来拼进提示词二是日志和监控系统接收网关产生的访问日志和指标数据。整套架构的核心原则是业务代码只面对一个稳定的 OpenAI 风格接口底层接的是哪家模型、怎么计费、怎么限流都由网关解决。这套架构最大的好处是稳定。业务方不需要关心模型供应商的变更你今天用通义明天切 DeepSeek对业务代码来说只是网关配置的一次改动。所以与其说是 API 网关遇见了大模型不如说是大模型这种新型后端服务终于迎来了真正能管住它的基础设施。2. APISIX AI 网关的核心能力拆解2.1 ai-proxy把“接入模型”从开发变成配置APISIX AI 网关的基石插件是 ai-proxy。它的作用可以简单理解为一个懂大模型协议的智能代理。传统的 proxy 插件只负责转发字节流完全不关心你在调什么接口而 ai-proxy 理解 OpenAI、Azure OpenAI、AWS Bedrock、GCP Vertex AI 等主流大模型服务的协议格式也支持智谱 AI 这类国内原生 provider。我在生产环境中最常用的姿势是让网关对外暴露一个固定的 OpenAI 兼容接口/v1/chat/completions内部再由 ai-proxy 转发到不同厂商。配置起来非常直观{ uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, token: sk-你的密钥 }, model: gpt-4o-mini, override_model: true } } }这里有几个关键点。provider决定 ai-proxy 按哪种协议、哪个默认地址去转发。override_model设为 true 后客户端请求里如果自己指定了 model就以客户端的为准设为 false 则强制使用网关配置的模型防止业务方乱选贵模型。我建议在正式环境把 override_model 设为 false成本控制会容易得多。用了 ai-proxy 之后路由上通常不需要再配 upstream因为转发目标由 provider 决定。这一点和传统路由差异很大刚上手的人很容易下意识去配一个 upstream结果发现 ai-proxy 的请求根本没走后端业务服务全被插件接管了。2.2 ai-prompt-template提示词模板在网关层沉淀模型接入稳定之后第二件让人头疼的事情是提示词管理。早期业务代码里到处散落着拼 prompt 的字符串不同的开发者维护各自的版本系统提示词改一个字都要发版上线审计的时候根本说不清线上跑的是哪个版本。ai-prompt-template 插件解决的就是这个问题。它允许你在网关层定义一组提示词模板支持模板变量业务方在请求时传入变量值网关渲染完再交给模型。一个简化的配置长这样{ plugins: { ai-prompt-template: { templates: { code_review: { system_prompt: 你是一名资深代码评审工程师请从正确性、可维护性、安全性三个角度给出评审意见。, user_prompt_pattern: 请评审以下代码{{code}} } } } } }业务方调用时只需要请求体里带上 template 名称和 code 变量网关自动渲染。模板集中管理之后prompt 的修改可以走配置变更流程回滚也简单不用再反复折腾业务服务。不过我要提醒一句prompt 模板化之后对用户的输入变量一定要做长度和内容校验。满屏的“忽略之前的指令”就是靠模板里混入用户输入来攻击模型的网关层加一道清洗和截断能挡掉大多数不怀好意的尝试。2.3 ai-vendors多模型供应商的集中管理ai-proxy 解决了“怎么转发”的问题但如果你有多个模型供应商、多套密钥、多个 base_url每个路由都写一遍认证信息还是很痛苦。ai-vendors 插件就是为此设计的它把模型供应商的配置抽成独立资源统一管理 base_url、认证方式、模型列表等路由只需要引用 vendor 名称。大致的使用方式是先创建一个 vendor 资源{ name: deepseek-main, provider: openai, api: { base_url: https://api.deepseek.com/v1, auth: { type: bearer, token: sk-deepseek密钥 } } }然后在路由里引用它{ plugins: { ai-proxy: { vendor: deepseek-main, model: deepseek-chat } } }这样做的好处是变更集中。比如某个厂商因为备案或者迁移换了域名你只需要改 vendor 里的 base_url所有引用它的路由立刻生效。密钥轮换也是同理一次修改全局生效不用逐条改路由。如果你在管理多个模型供应商ai-vendors 基本是必上插件。2.4 ai-cost 与 ai-latency成本与延迟的精细观测大模型网关不能只看 QPS必须看 token 和成本。APISIX 在 AI 场景下提供了 ai-cost 和 ai-latency 两个观测类插件我用下来觉得它们才是 AI 网关和传统网关最不一样的地方。ai-cost 会从模型响应里解析出 prompt_tokens、completion_tokens 以及模型名称计算每次请求的成本指标并暴露给 Prometheus 或写入访问日志。配合 APISIX 的日志插件你可以把成本数据按业务线、按模型维度汇总每天跑一张报表出来。这样“哪个业务在烧钱”就不需要拍脑袋了。ai-latency 则把一次大模型请求拆成了多个阶段客户端连上网关的耗时、网关转发到模型服务的耗时、等待第一个 token 返回的时间TTFB、流式传输的总时长。TTFB 是衡量模型服务真实性能的关键指标如果 TTFB 很长说明推理服务本身慢跟网关无关如果 TTFB 很短但总时长很长说明是流式生成阶段慢那就要考虑模型输出长度是不是太长了。我实测下来这两个插件对长尾问题非常有用。特别是流式请求业务方很容易觉得是网关吞了响应但 ai-latency 的数据能清楚告诉你时间到底花在哪一段。2.5 进阶场景RAG 与 AI 安全策略在网关落地当 AI 网关承担的角色越来越多它还可以承载一些进阶能力。比如 ai-rag 插件让网关在转发前先从向量数据库里检索相关知识再拼进提示词。这比在业务代码里单独接 RAG 更统一尤其适合多团队共建知识库的场景。另一个方向是安全。大模型请求的审计日志天然应该放在网关层谁在什么时候问过什么问题理应是可追溯的。网关还可以统一接入 WAF 类插件对请求体做关键词匹配、敏感信息识别。虽然网关不能替代专门的大模型安全防护系统但作为第一道闸门已经能拦掉很多低级风险。我个人的建议是不要把太业务化、太定制化的逻辑塞进网关。网关适合放通用能力认证、限流、协议、观测、基础安全。凡是“只有某个业务才需要”的逻辑留在业务侧更好否则网关配置会膨胀成一个没人敢动的怪兽。3. 实操从零搭建一个可用的 APISIX AI 网关3.1 部署docker compose 起一套 APISIX实操部分我们从零开始。最简单的方式是用 docker compose 把 etcd 和 APISIX 跑起来。etcd 是 APISIX 的配置存储相当于它的数据库。services: etcd: image: bitnami/etcd:3.5 restart: always environment: - ALLOW_NONE_AUTHENTICATIONyes - ETCD_ADVERTISE_CLIENT_URLShttp://etcd:2379 ports: - 2379:2379 apisix: image: apache/apisix:3.12.1-debian restart: always depends_on: - etcd environment: - ETCD_HOSTetcd ports: - 9080:9080 - 9180:9180 volumes: - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro这里注意9080 是数据面端口所有真实请求走这里9180 是 Admin API 端口用来配置路由和插件。生产环境里 9180 绝对不能直接暴露到公网必须做访问控制。容器起来之后先验证 Admin API 是否正常curl http://127.0.0.1:9180/apisix/admin/routes \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1能返回一个 JSON 数组就说明环境没问题。需要提醒的是AI 插件在 APISIX 3.9 版本后才陆续引入ai-vendors 在更新的版本里才比较完善建议直接用 3.12 或更新的稳定版省得踩版本坑。3.2 第一个 AI 路由对接 OpenAI 兼容协议假设你现在要接一个支持 OpenAI 兼容协议的大模型服务创建一个路由如下curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/ai-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, plugins: { ai-proxy: { provider: openai, auth: { header: Authorization, token: sk-你的密钥 }, model: gpt-4o-mini, override_model: false } } }创建好之后直接往里打请求curl http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好用一句话介绍自己}], stream: false }能收到模型回复说明网关已经成功代理了模型服务。整个过程没有业务代码参与纯粹是配置驱动的接入。这个路由的 URI 是/v1/chat/completions对你下游的所有业务来说它们看到的仍然是 OpenAI 风格的接口将来换成其他供应商业务代码一行都不用改。3.3 对接国内大模型以 DeepSeek 和通义为例国内用户真正高频使用的还是国产模型。好消息是绝大多数国产模型服务都提供了 OpenAI 兼容端点这意味着你不需要等 APISIX 出专属 provider直接复用 openai provider 然后改 base_url 就行。以 DeepSeek 为例先创建一个 vendorcurl -X PUT http://127.0.0.1:9180/apisix/admin/ai_vendors/deepseek-main \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { name: deepseek-main, provider: openai, api: { base_url: https://api.deepseek.com/v1, auth: { header: Authorization, token: sk-deepseek密钥 } } }然后再建路由引用这个 vendorcurl -X PUT http://127.0.0.1:9180/apisix/admin/routes/deepseek-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, plugins: { ai-proxy: { vendor: deepseek-main, model: deepseek-chat } } }通义千问的操作逻辑一样base_url 换成https://dashscope.aliyuncs.com/compatible-mode/v1模型名换成qwen-plus之类的即可。这里有个小技巧如果一个模型服务厂商提供了原生 provider比如智谱 AI那就直接用原生 provider如果只提供 OpenAI 兼容接口就用 openai provider 加自定义 base_url。前者的协议适配更完善后者更通用二者可以并存。3.4 流式输出与超时调优大模型聊天几乎必然用到流式输出。SSEServer-Sent Events协议让模型一段一段地吐文字用户看到的是打字机效果体感远好于等完整响应。网关层对流式请求最怕两件事连接被缓冲、连接被超时杀掉。默认情况下APISIX 的流式转发是 OK 的但如果你在 APISIX 前面还挂了一层 nginx 或者其他反代那层代理极有可能开启缓冲导致前端迟迟收不到数据。排查手段很简单用 curl 直连网关测试流式请求。curl -N http://127.0.0.1:9080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: 讲一个三句话的笑话}], stream: true }如果 curl 能逐段输出但业务前端收不到问题大概率在你和客户端之间的网络组件上。如果 curl 也卡住那就要看超时配置。APISIX 默认的 nginx 读超时是 60 秒大模型一次正常的流式回答动辄 30 秒到 90 秒遇到长文本可能更久。我习惯把全局超时调到 300 秒方法是在 config.yaml 里改nginx_config: http: proxy_read_timeout: 300s proxy_send_timeout: 300s改完重启 APISIX 再用 curl 测长对话就不会被莫名其妙掐断了。注意这和使用哪个模型无关纯粹是网关到模型服务这条链路的超时设置建议统一调大反正大模型服务本身就是慢服务没必要按普通 HTTP 接口的标准去卡它。3.5 多模型供应商管理与灰度切换模型供应商多了之后最实用的玩法是做多模型路由和灰度切换。我常用的方案是基于请求头做条件路由默认流量走主力模型测试流量走新模型。比如主力模型用 DeepSeek新模型准备切到通义。先创建通义的 vendor然后创建第二条路由URI 同样是/v1/chat/completions但加了一个条件只有请求头里带着X-Model-Backend: qwen的请求才命中这条路由。curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/qwen-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c2f1 \ -H Content-Type: application/json \ -d { uri: /v1/chat/completions, vars: [ [http_x_model_backend, , qwen] ], plugins: { ai-proxy: { vendor: qwen-main, model: qwen-plus } } }默认请求仍然落在 DeepSeek 那条路由上只有内测业务方带特殊 header 才会走到通义。观察一段时间后如果新模型在延迟和成本上都符合预期就让网关团队把默认路由的 vendor 改成通义灰度完成。这个流程不需要业务方配合也不需要重新发版操作起来非常顺滑。4. 踩坑实录与排查清单4.1 流式响应白屏或断流这是 AI 网关上线后最常被业务方骂的问题。表象是Stream 模式下前端偶尔收到一半就断了界面卡在白屏。我一开始以为是 APISIX 的 bug后来定位到是前端和网关之间的网络链路有缓冲代理。Nginx 默认开启 proxy_buffering会让 SSE 数据攒到一定量才转发流式效果直接报废。排查时先在网关这一层用curl -N测试确认网关本身没问题再逐层检查前面的代理。另外如果每个 token 之间的生成间隔超过读超时时间连接也会被断开。长对话场景模型思考时间较长一定记得把超时调大。4.2 请求超时导致 504大模型生成慢不是 bug但默认超时设置会把它变成 bug。如果你的请求在模型生成到一半时返回 504十有八九是网关到模型服务的读超时不够长。记住大模型接口不能用普通 API 的 30 秒标准来设计直接把 read_timeout 和 send_timeout 拉到 300 秒是更稳的选择。另外要注意超时不止存在于网关这一层客户端到网关的超时也要设置。如果客户端设置了 30 秒超时网关就算等 300 秒也没有意义前端早就放弃等待了。全链路超时参数要一起调整。4.3 密钥泄漏风险我见过最惊险的一次事故是有人把模型密钥写在了前端配置里被爬虫抓走后刷了几万块。AI 网关落地后业务方就不应该再接触厂商密钥了所有密钥统一收口到网关配置。密钥的读取和存储也要做好隔离Admin API 的 X-API-KEY 不要用默认值9180 端口禁止公网访问etcd 的数据目录做好权限控制。如果团队有专门的密钥管理服务比如 Vault可以把 vendor 里的 token 用环境变量或者进程注入的方式引用而不是硬编码在配置文件中。这个细节越早做越省心。4.4 成本统计对不上账ai-cost 插件能统计 token 消耗但和厂商账单对不上是常态。厂商账单通常按实际生成量计费包括缓存命中、中途失败的 token而网关侧的统计会漏掉一些异常中断的请求或者因为流式输出在客户端断开后终止统计到的 completion_tokens 少于实际生成量。我的做法是把网关日志里的 ai-cost 数据落库按模型、按业务方、按天做聚合和厂商账单的差异控制在 5% 以内就算可接受。真正要盯的是趋势哪天某个业务线的 token 消耗突然翻倍那大概率是出问题了而不是纠结那百分之几的统计误差。4.5 常见问题速查表现象可能原因解决办法401/403vendor 里 token 错误或已过期检查并轮换密钥确认鉴权头格式404 Not Found路由 URI 与请求路径不匹配统一走 /v1/chat/completions400 Bad Request模型名错误或请求体不符合协议核对 vendor 支持的模型名504 Gateway Timeout网关到模型服务超时调大 nginx 超时和 AI 转发超时流式响应中断缓冲代理或单次生成超时curl -N 逐层排查、关缓冲、调超时跨域报错前端直接调用网关配置 cors 插件并限制来源最后聊几句实在的这套 AI 网关方案我在团队内部用了大半年最大的感受是大模型接入终于从“开发任务”变成了“配置任务”。新业务要接 AI不再需要到处找密钥、写协议适配、担心被刷爆账单只需要提交一条路由配置剩下的认证、流控、成本统计都是网关自动兜底。如果后续要在这个方案上继续扩展我建议优先考虑三件事一是把私有化部署的推理服务比如 vLLM接进来让网关同时管理外部 API 和内部算力二是把多租户配额体系做起来每个业务方在网关层能清晰地看到自己的额度和消耗三是把请求审计日志接入公司内部的审计系统做到每一次 AI 调用都有据可查。网关这东西不性感但它是大模型真正进入企业架构的最短路径。当你被问“AI 能力怎么接入”的时候别再让它变成一场混乱的踩坑大战把网关卡在最前面一切都会顺很多。
