最近帮一个客户团队搭模型路由层聊的时候发现一个很有意思的现象他们不缺好用的模型团队里各种大模型 API 的调用代码写了一大堆卡点反而非常统一——几十个应用都要用模型谁来统一管这些接口供应商的 API key 怎么管预算谁盯某个模型供应商出问题怎么办在回答这些问题之前业务代码里已经到处都是硬编码的密钥换一个模型等于把所有线上服务都改一遍。Apache APISIX 的 AI 网关就是把“API 网关”这个老角色放到大模型场景下重新做了一遍统一接入多家大模型、做负载均衡和故障转移、限流降级、记录每一个 token 的流向。这篇文章我会结合自己实际部署和调优 APISIX AI 网关的经验把它能干什么、怎么配、生产环境会踩什么坑一次讲清楚。适合正在搭模型底座、做平台化 API 管理的后端开发和架构师参考。1. 大模型时代API网关为什么需要“重刷一次”1.1 从“服务间路由”到“模型间路由”网关的职责变了先聊一个很多人没想透的问题。传统 API 网关解决的是“服务 A 请求服务 B”这种微服务之间的调用问题路由按路径转发、鉴权校验、灰度发布、限流熔断目标是把后端服务的拓扑关系藏起来对外暴露一组稳定接口。大模型接入之后拓扑关系变了。过去你调用的是自己公司的服务现在调用的可能是 OpenAI、Anthropic、国内好几个云厂家的模型甚至还有公司私有化部署在 GPU 节点上的开源模型。这些供应商的 API 风格不一样模型版本经常变计费规则不同可用性还参差不齐。如果每个业务都直接连供应商本质上是把“基础设施决策”下放到了业务团队业务要自己管理 API key自己处理 429 限流自己搞退避重试自己盯着账单。这里面最大的问题不是技术而是治理。多团队多应用同时在用模型平台方根本说不清楚谁在调用哪个模型、花了多少钱、有没有异常调用。这种混乱场景其实就是网关最擅长解决的只不过它路由的对象从一个“后端服务”变成了一个“模型供应商”。APISIX 的做法是在保留传统路由、鉴权、限流这些能力的基础上加了一套面向模型调用的代理与治理机制让模型网关成为一个独立的基础设施层。1.2 大模型API的三个“怪脾气”长连接、高延迟、token计费为什么不能拿传统网关代理普通 HTTP API 的思路直接套 AI因为 LLM 接口有三个特点会把传统网关的默认参数打穿。第一个是响应时间跨度极大。普通接口一般几百毫秒就返回网关超时设置个 3 秒、5 秒都没问题。大模型生成几千字可能要几十秒甚至几分钟尤其流式输出情况下连接会保持很长时间。如果按传统参数配置读超时或者空闲超时请求很容易被中间层“掐断”。APISIX 在 AI 网关里对长生命周期请求做了针对性处理包括 proxy 层的 read timeout、send timeout 调大以及流式响应场景下配合 chunked 转发避免响应体被缓冲。第二个是流式返回。SSE 是 LLM 场景里最常见的通信方式数据不是一次性返回而是按 token 分片推给客户端。网关不能按照普通 JSON 响应那样拿完整 body 再做后处理必须保证流能一路透传客户端才能产生“打字机”效果。如果网关开了响应缓冲或者带了某些会缓存 body 的插件回复就会卡顿甚至超时。第三个是成本模型从“带宽/请求数”变成了“token 计费”。普通 API 网关限流基本只看 QPS大模型场景下两块钱一千次请求的接口和两块钱一千个 token 的接口完全不是一回事。限流必须能看懂用户的请求里面大概会消耗多少 token并且把配额、成本、预算绑定起来。这也是 AI 网关和传统网关最重要的差异之一。1.3 AI网关解决的是统一接入、降级、成本、审计这四件事把需求收敛一下AI 网关其实就是四类能力。统一接入客户端不管用 OpenAI 协议还是 Anthropic 协议到网关这里都变成公司内部统一的一套 HTTP 接口。后端模型升级、切换、新增供应商业务代码不用改。降级容错一个模型供应商故障网关自动把流量切给另一个能力相近的模型或者直接返回降级结果避免用户的页面长时间转圈。成本治理按应用、按部门、按 API key 维度做配额管理与限流控制住大模型账单的增长速度。审计追溯每一次模型调用来自哪个应用、发了什么、返回了多久、消耗了多少 token全部落日志后续做对账、做安全审查都有据可依。这四件事不是 AI 时代的全新发明API 网关早就做类似的事只是治理对象的复杂度变高了。我自己的体会是如果公司里有超过两三个团队在用大模型 API或者已经接入了两家以上供应商那就应该尽快把网关层建起来越晚接入清理硬编码 API key 的成本越高。2. Apache APISIX AI网关核心能力拆解2.1 插件化架构APISIX为什么能快速长出AI能力对没用过 APISIX 的朋友先交代下背景。APISIX 是基于 OpenResty/Nginx 和 etcd 构建的云原生 API 网关Apache 顶级项目。它的一个核心设计是“插件 热加载”路由匹配到之后会按优先级依次执行一串插件限流、鉴权、日志、改写、转发都可以用插件组合出来。新增能力不需要改 Nginx 代码改配置就能动态下发而且插件可以针对某个路由单独打开或关闭。这个架构对 AI 场景非常有利。因为 AI 网关不是一套全新的系统而是传统网关能力的“叠加应用”路由还是那套路由upstream 还是那套 upstream代理转发还是 Nginx 那一套高性能转发逻辑。APISIX 只需要在插件层补齐与模型供应商的协议适配、prompt 处理这些增量逻辑就能够在已有高性能底座上长出 AI 能力。这也是为什么它能推出 ai-proxy、ai-prompt-template、ai-rag 等系列插件底层复用成熟机制上层做场景适配。另外 APISIX 的数据中心用 etcd配置更新是全量分发的毫秒级别生效。生产环境切流、上线新模型、改限流阈值都不需要重启网关进程。这个特性在大模型快速迭代的场景是很值钱的因为模型切换往往很频繁今天新模型上线明天某个供应商又发新版接口。相比那些改配置还要 reload 的老牌网关APISIX 的这种动态能力在实际运维中的体验要好太多。2.2 多模型统一接入一个入口对接OpenAI、Anthropic与本地模型APISIX AI 网关最核心的插件是 ai-proxy。它解决的问题是客户端按照一套协议通常可以按 OpenAI 兼容协议来设计发请求网关负责把请求转换成目标供应商的协议并转发。在配置层面ai-proxy 允许你声明一个或者多个 provider每个 provider 对应一个模型供应商可以配置它的请求域名、认证方式、默认模型名称、协议类型。支持的协议类型覆盖主流厂商比如 OpenAI、Anthropic、Azure OpenAI、Google Gemini、AWS Bedrock 等也支持通过 OpenAI 兼容协议接入私有化部署的模型服务比如本地用 Ollama 或 vLLM 启动的模型。我拿自己团队的做法举个例子。我们没有让业务端直接面对各家供应商的格式差异而是在网关层暴露了一个/v1/chat/completions的统一入口格式与 OpenAI 保持一致。前端和后端只认这一套接口底层究竟是接了 OpenAI 的 GPT还是接的 Azure 的部署或者切到了公司内部的微调模型调用方完全无感。这种“内部协议统一、底层供应商可替换”的模式我认为是大模型平台化交付的关键。如果你不想让网关做太重的协议转换也可以退一步用 APISIX 传统的 proxy-rewrite upstream 做一个纯路径转发把/v1/chat/completions映射到真实供应商的地址。这种做法胜在简单适合各家模型接口风格比较接近的场景。但一旦供应商之间协议差异大比如一个用 OpenAI 格式一个用 Anthropic 格式还是得靠 ai-proxy 这类插件来做适配。2.3 负载均衡与故障转移模型挂了自动切换接入多家模型之后第二个问题就是“能不能别让业务感知到供应商故障”。APISIX 在这方面提供了两层机制。第一层是传统的 upstream 多节点负载均衡。同一个供应商的 API 也可以有多个接入点比如不同区域的 endpoint把它们配置到同一个 upstream 下用 roundrobin 或者 least_conn 算法做负载均衡配合主动健康检查和被动健康检查节点挂了自动摘除。第二层是模型供应商级别的故障转移。如果你配置了多个 provider一个是首选模型另几个是备用模型网关可以在首选 provider 出现连续错误或者超时的时候把请求转移到备用 provider 上。这里一个很实际的经验是备用模型最好是“能力等价但供应商不同”的模型比如主模型和备模型都具备相近的对话能力这样切换之后用户体验不会断崖下降。我见过有的团队把 GPT-4o 的备用模型配成自己微调的小模型结果正常流量体验差异极大等于是把故障转移做成了故障放大。配置故障转移之前一定要先明确切换的触发条件和最大重试次数。不能遇上偶发超时就把用户请求全都切到备用模型否则成本会在一瞬间翻好几倍。合理的做法是上游连续失败达到阈值才切换并且切换之后要有恢复机制主模型恢复健康后流量再逐步切回来。2.4 限流与配额治理防止一个应用刷爆预算成本控制是 AI 网关区别于传统网关的一个硬需求。APISIX 本身就有一组成熟的限流插件limit-req、limit-count、limit-conn分别对应令牌桶算法、固定窗口计数器、并发连接数限制。在 AI 场景下这些插件依然有效但需要结合模型特点做调整。可以参考的做法是“二维限流”第一维按请求维度限流比如每个 API key 每秒最多多少个请求第二维按并发维度限流控制同时进行的模型调用数量防止几十个流式请求把上游打爆。这个组合能挡住大部分“用量失控”问题。更细一点如果能做到 token 维度的配额管理那成本账就更清晰了。APISIX 的 AI 可观测相关能力会记录流式响应过程中的 token 消耗平台可以把这些数据汇总成一个配额池每个应用用完了额度就返回 429。这块逻辑我们在落地时是配合一个内部计费服务做的网关负责把每次调用的模型、输入 token、输出 token 打到消息队列计费服务异步记账然后定期把用量同步给 APISIX 的限流配置。整体不复杂但把“预算超标”的事故从“事后看账单”变成了“事中自动拦截”。需要注意限流阈值设得太死的后果是模型服务的并发吞吐突然被打折生产环境容易出现“明明量不大但一直报 429”的诡异现象。这个问题在后面排查章节我会专门展开。2.5 缓存与性能优化让重复请求少花冤枉钱大模型调用单价高而且同样的问题被反复问是一种很常见的浪费。做过客服机器人的都懂每天用户问题里可能有三成是历史问题的高频变体。对这些请求直接透传给模型等于每一块钱都花得很冤枉。APISIX 的 proxy-cache 插件可以在 AI 场景下做一层精准缓存。它的前提只能是“请求的 prompt 完全一致”才能直接复用之前响应。对于完全一致的简单问答比如系统提示词固定的客服场景缓存命中率确实能省不少钱。值得留意的是大模型响应会带流式和非流式两种形态。如果客户端用的是流式 SSE网关做缓存会比较别扭——你不知道响应什么时候算结束缓存下来的数据也可能被截断。目前我们的经验是非流式、请求体较小、prompt 稳定的场景下开缓存收益明显流式场景不开或者搭配 prompt template 做了归一化之后再考虑。更聪明的语义缓存需要对 prompt 做 embedding 后再计算相似度这个就不是 APISIX 内置能力了需要结合向量数据库单独做。APISIX 生态里 ai-rag 插件已经开始覆盖检索增强生成的场景但语义缓存更多属于业务层方案不建议在网关层硬塞。网关层守住“精确缓存 并发控制”这两件事已经能帮团队省下一笔很可观的费用。2.6 可观测与安全审计每个token都要有据可查模型调用的可观测性重要程度不亚于网关本身。传统网关看 QPS、错误率、P99 延迟就差不多了。AI 网关还要多出几个关键维度按模型看调用分布、按应用看 token 消耗、按 prompt 长度看成本趋势。APISIX 原生支持 Prometheus 指标暴露可以直接把每个 route 的请求量、错误量、延迟分布接入 Grafana。AI 相关插件和日志插件则可以记录更细的信息比如消费了多少 token、用的哪个模型、哪个 provider 返回的。这些数据是后续做成本分摊、做容量规划的基础。安全和审计方面APISIX 支持 key-auth、jwt-auth、openid-connect 等常见鉴权方式可以给不同内部应用签发不同的 key再配合 consumer 维度做限流和配额。相比把密钥直接写在业务环境变量里API key 集中在网关侧管理泄露风险和控制粒度都会好很多。日志审计也要注意一个分寸请求体里可能包含用户的隐私问题落日志之前最好做脱敏处理尤其是对话类场景不能为了排查问题把用户聊天内容完整记下来。3. 手把手实操用APISIX搭出一个能上生产的AI网关3.1 环境准备Docker Compose 快速拉起 APISIX 集群实操部分我直接给一套可复现的方案。官方推荐用 etcd 做配置中心一个标准的开发环境部署包含两个容器APISIX 和 etcd。下面是我常用的 docker-compose 配置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.10.0 ports: - 9080:9080 - 9180:9180 volumes: - ./apisix/config.yml:/usr/local/apisix/conf/config.yaml:ro depends_on: - etcd启动之后9080 是对外流量入口9180 是 Admin API 管理端口。Admin API 默认有一个 key通常是edd1c9f034335f136f87ad84b625c8f1测试环境可以先这么用生产一定要换。配置好之后用下面命令验证网关是否正常curl -i http://127.0.0.1:9080/ curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1能正常返回说明环境就绪。几点提醒Docker 部署时记得把 etcd 的数据目录做持久化否则配置重启就没了APISIX 新版本对 etcd 版本也有要求别在旧 etcd 上强行跑新 APISIX。3.2 第一步配置一个 OpenAI 兼容模型代理假设团队内部已经约定好统一走 OpenAI 兼容协议现在要把请求转发到本地用 vLLM 部署的开源模型。这个场景很适合演示因为本地上游没有授权问题方便你验证全链路。先创建一个 upstream指向本地的 vLLM 服务curl -X PUT http://127.0.0.1:9180/apisix/admin/upstreams/llm-local \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 \ -d { type: roundrobin, nodes: { 10.0.0.12:8000: 1 }, scheme: http, timeout: { connect: 5, send: 60, read: 300 } }再创建一条路由开放一个内部接口curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/llm-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 \ -d { uri: /v1/chat/completions, upstream_id: llm-local }这时客户端请求/v1/chat/completionsAPISIX 会把它转发到本地模型的同名路径上。对于 OpenAI 兼容的模型服务这个配置已经可以正常工作。如果目标供应商的路径和客户端不一致比如某家模型的补全接口实际路径是/api/generate可以在路由插件里加一个 proxy-rewrite把 uri 改写成目标路径。我要特别提醒 read timeout 的取值。本地模型如果配置不高生成速度慢几十秒出结果很正常。把 read timeout 设成 3 秒、5 秒这种常规值会让网关在模型还在正常生成时就把连接断开用户在客户端看到的却是“我明明等了半分钟结果报错了”。3.3 第二步多模型聚合与自动故障转移配置如果要接入真正的云端供应商建议直接使用 ai-proxy 插件来做协议适配和多 provider 编排。下面这个配置是官方文档风格的示意具体字段名要以你部署版本的文档为准curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/llm-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 \ -d { uri: /v1/chat/completions, plugins: { ai-proxy: { providers: [ { name: main-provider, type: openai, model: gpt-4o, auth: { header: Authorization, value: Bearer sk-example }, upstream: { scheme: https, nodes: { api.openai.com:443: 1 } } }, { name: local-fallback, type: openai, model: meta-llama-3.1-8b, auth: { header: Authorization, value: Bearer local-no-key }, upstream: { scheme: http, nodes: { 10.0.0.12:8000: 1 } } } ] } } }这个配置的核心逻辑是让 ai-proxy 在首选 provider 不可用的情况下把请求转向备用 provider。APISIX 会自动把统一的 OpenAI 格式请求转换成对应 provider 需要的协议并处理认证信息。配置时最容易出错的两个地方。一个是 provider 里的 model 字段不要写错写错会导致模型名称直接被透传给上游上游返回 model not found。另一个是本地备用模型的协议一定要兼容 OpenAI私有化部署 Ollama、vLLM 时都要打开它们兼容 OpenAI 的接口模式否则切换后请求会直接失败。3.4 第三步限流、配额与成本控制组合拳网关层做成本控制我推荐用“并发限流 请求限流 key 级配额”三层。并发限流用 limit-conncurl -X PUT http://127.0.0.1:9180/apisix/admin/routes/llm-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 \ -d { uri: /v1/chat/completions, plugins: { limit-conn: { conn: 10, burst: 5, default_conn_delay: 0.1, key: remote_addr }, limit-count: { count: 600, time_window: 60, key: remote_addr, rejected_code: 429 } } }limit-conn 限制同一时刻最多 10 个并发请求突发多给 5 个名额limit-count 限制每分钟 600 个请求。对绝大多数内部应用来说这两组值已经能挡住失控流量。要是想按应用甚至按用户做配额前提是网关知道调用方是谁。通常会在 AI 网关前面再挂一层认证比如 key-auth给不同应用签发不同 key然后限流 key 不取 remote_addr改成取 consumer_name。这才能真正做到“应用 A 超额了应用 B 不受影响”。另外我强烈建议把 429 之后的响应体写成对调用方友好的格式别让客户端只拿到一个裸的 429 状态码。可以在网关里配一个自定义响应告诉调用方是哪个维度触发了限流、大概多久之后可以重试这样客户端能做正确的退避而不是无脑疯狂重试导致限流更严重。3.5 第四步接入 Prometheus 查看调用大盘可观测性直接复用 APISIX 的 prometheus 插件。给路由开启插件后管理接口/apisix/prometheus/metrics就会暴露指标数据接入 Prometheus 采集即可。这个插件也可以在全局配置里开启让所有路由都自动上报指标。开启插件curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/llm-chat \ -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 \ -d { uri: /v1/chat/completions, plugins: { prometheus: {} } }采集配置里让 Prometheus 的 job 指向 APISIX 节点的/apisix/prometheus/metrics即可。在 Grafana 里我一般会建两个核心视图。第一个是“接入层总览”看总请求量、错误率、P50/P95 延迟。第二个是“模型路由视图”按路由或者按 provider 拆分看调用分布。AI 场景下的可观测性有一个传统网关不太会出现的问题请求总量少了不代表系统正常因为很多请求是长连接上的多轮对话。真正的关键指标是“完成了多少次成功响应、生成了多少个 token、平均每个请求花了多少时间在等待首 token 上”。首 token 延迟比整体延迟更能反映模型服务的真实健康度这个指标在 AI 网关大盘里值得做成独立面板。4. 生产中常见问题与排查实录4.1 配置不生效、路由 503先按这三个方向查配置完经常遇到的第一类故障是明明 PUT 了路由请求还是 404 或者 503。我会按这个顺序排查。第一看 Admin API 有没有真正返回成功。APISIX 的 Admin API 是强 schema 校验的字段写错会直接返回 400并提示具体是哪个字段不合法。所以先确认创建资源时的 Response而不是默认“PUT 200 就成功”。如果配置内容偏大建议先保存在 JSON 文件里再提交方便回滚和对比。第二看路由的匹配优先级。APISIX 支持按 uri 前缀、正则等方式匹配如果之前已经存在一个更高优先级的全路径路由新路由可能一直没被走到。用curl /apisix/admin/routes拉全量路由列表检查或者临时建一条精确匹配的测试路由验证是否被覆盖。第三看 upstream 的健康检查。upstream 配了 passive 健康检查之后如果上游连续失败达到阈值节点会被标记为不可用之后请求直接 503但此时业务服务本身已经恢复了。这种情况在压测时特别常见压测把上游打挂了网关把节点摘了压测结束后流量依然进不来。4.2 流式输出被缓冲或截断模型回复像“卡住”了SSE 流式输出的排查在网关层有一个经典坑响应被缓冲。现象是客户端在浏览器里看到内容半天不刷新或者等流结束后一次性出现完全失去打字机效果更严重的情况是连接超时、直接报错。原因是 APISIX 或者它后面的 LB/CDN 对响应做了缓冲。SSE 是边生成边推送的协议一分块数据如果被缓冲层攒住客户端就要等攒满或连接结束才能拿到。在 APISIX 侧确保代理配置没有开启会缓冲响应的逻辑。像 proxy-cache 这类插件在流式路由上要关掉如果有 gzip 插件对 SSE 场景也要小心压缩和流式推送混在一起容易出问题。另外检查上游返回的响应头是否带了Content-Type: text/event-stream以及Cache-Control: no-cacheAPISIX 转发时通常会保留但如果中间有 proxy-rewrite 的 header 改写插件有可能把关键头覆盖掉。我自己的经验是网关层配置一定要预留一个“直连测试”手段。排查流式问题时先用 curl 直连上游确认上游 SSE 正常再经网关请求逐段对比。通过二分法找出是上游的问题、网关的问题还是客户端的问题。如果直连上游没有问题那九成就是某一层代理或多层代理之间的缓冲。4.3 Authorization 头冲突与 API Key 泄露隐患调用大模型 API 的鉴权头各家并不一样。OpenAI 系用Authorization: Bearer形式Anthropic 用x-api-keyAWS Bedrock 则用签名机制。ai-proxy 插件会帮你构造目标供应商的鉴权所以配置 provider 时就不要把外部上游的 key 暴露给业务端。这里有个很容易犯的错业务端调用网关时自己也在 header 里带了一个Authorization网关转发时如果直接把 header 原样透传给上游就可能把客户端伪造的 key 发给真实模型供应商或者把网关侧配置好的 key 覆盖掉。这种问题排查起来很难一眼看出因为错误信息往往出现在上游返回的 401 响应里。安全上还要注意一点不要用 ai-proxy 或者 proxy-rewrite 把 API key 拼到 URL 查询参数里。URL 参数会进网关日志、访问日志、浏览器历史甚至 CDN 缓存泄露面大得多。所有密钥都应该从 header 注入并在出口时把业务端的认证头去掉。这条原则在国内外的云服务安全规范里都是明确红线网关场景同样适用。4.4 插件执行顺序错误导致鉴权失效APISIX 插件按优先级顺序执行。AI 网关场景里限流、鉴权、AI 代理这几个插件的顺序直接影响行为。比如把 key-auth 放在 ai-proxy 后面就会出现“未经认证的请求先被转发到模型供应商”这种严重安全问题。常见的正确顺序是认证类插件key-auth/jwt-auth最先执行接着是限流类limit-*、日志/观测类最后是代理类ai-proxy/proxy-rewrite。APISIX 官方对每个插件有默认 priority最好不要自己乱改全局优先级而是在路由配置里只放需要的插件并理解它们的执行顺序。我踩过的另一个坑是某些版本里 ai-proxy 插件与日志类插件有特殊的交互逻辑。比如又要记录 token 又要做 LLM 代理日志插件拿不到真实的上游状态。遇到这种问题最快的定位方式是在调试环境给 route 开 debug 日志把插件执行链打出来看每个插件处理前后请求的状态码和 header 变化。4.5 本地模型与云端模型协议差异踩坑最后聊一个很多人都遇到过的差异化问题你以为本地模型兼容 OpenAI但实际细节槽点很多。vLLM、Ollama 都提供了 OpenAI 兼容接口但兼容程度和默认行为有差异。比如参数名OpenAI 的max_tokens在有的实现里接受但某些版本更严格地要求max_completion_tokensstream_options字段在部分本地推理引擎里会被忽略。再比如模型名本地模型注册名是部署时指定的如果客户端传的模型名与 vLLM 服务里的模型名不一致返回的 404 文案还特别有误导性。遇到这类差异建议在网关层补一层“请求归一化”由网关统一填充默认值、过滤掉各个模型不支持的参数。这样业务端始终按 OpenAI 规范传参兼容性问题都在网关层消化。这块逻辑虽然不复杂但却是把“多云多模型”真正落地成“一套接口”的关键收尾动作值得投入人力做到位。下面把 AI 网关场景的典型故障整理成一个速查表方便大家直接对照问题现象可能原因排查方向路由 404配置好像没生效路由优先级被更高匹配规则覆盖拉全量路由列表检查 uri 匹配优先级请求 503服务本身正常upstream 被动健康检查把节点摘除查看健康检查配置确认节点是否被标记不可用SSE 流式输出一次性返回中间代理层缓冲了响应关掉 proxy-cache检查响应头是否保留 event-stream上游返回 401业务端 Authorization 头透传覆盖了网关配置检查 header 改写规则出口处剥离业务端认证头模型切换后请求失败provider 的 model 名称与上游不一致核对 model 字段与模型服务注册名调用量不高但频繁 429限流阈值设置过低或 key 维度不对查看 limit-conn 并发限制确认限流 key 取值5. 复盘与几个真心话5.1 不是所有流量都适合走AI网关把全公司的模型调用都压到网关之前建议先分清楚流量类型。离线批处理任务、模型训练脚本、内部数据回流这类流量并发模型简单通常有自己的一套弹性扩缩容策略硬塞进网关里反而会增加排队和限流干预。真正适合走 AI 网关的是面向在线业务、需要统一治理、需要做成本分摊的那部分流量。这也意味着网关选型时就要考虑“旁路流量”怎么处理。比较合理的边界是在线推理流量走网关批处理流量走独立通道两边在成本账上分开记。不要把网关当成万能代理一旦它成为所有模型流量的唯一入口但本身没有足够的性能和容量设计反而会成为新的单点。我在一个客户那里就见过这种情况为了省事把所有脚本调模型也放进网关结果某个离线任务高峰期直接占满了限流并发额度在线业务跟着遭殃。5.2 故障转移策略一定要在业务层有兜底网关的故障转移能解决的问题是“模型供应商不可用”但它解决不了“所有备用供应商同时不可用”和“模型能力不匹配”这类问题。所以故障转移只能作为第一道防线业务层仍然要设计自己的降级策略可以降级成固定话术、降级成较早版本的模型或者降级到缓存中最接近的答案。我见过一个典型案例团队把主模型、备用模型都配置在不同的供应商自认为高可用。结果这两家在同一个时间段都出现了网络波动流量切来切去全部失败。后来他们在业务层加了一个“回答不了就返回结构化错误码并提示稍后重试”的兜底逻辑用户体验反而稳定了很多。AI 网关把故障转移往前推进了一层但业务的最终兜底永远是自己的。5.3 版本升级别冲动AI插件还在快速迭代最后提醒一句AI 网关相关的插件迭代速度非常快今天看的配置示例到你安装的版本可能已经有新字段旧的字段也可能标记废弃。不要为了赶新功能在生产环境直接大版本升级先看 release notes重点检查插件配置 schema 的变化在一个隔离环境把全量路由配置重放一遍再切换。我在实际部署中的一个习惯是把所有 AI 网关的路由配置、插件配置、upstream 配置都放进 Git用 CI 或者脚本统一发布。这样每次升级版本后可以直接比对生成出的配置和线上配置第一时间发现被废弃的字段。不要完全信任文档里的示例能直接复制到线上以你自己版本里 Admin API 返回的 schema 为准那才是最靠谱的说明书。把模型供应商统一收敛到网关之后整个平台的“模型调用”这件事终于可以被管理了。我自己的体会是AI 网关的价值不完全在于它能转发多少种模型协议而在于它把以前散落在各个业务代码里的“模型调用细节”收拢成了一个基础设施层。上个月帮一个团队搭完这套网关他们最感慨的不是接入了多少家模型而是删掉了近 30 个硬编码在服务里的密钥。如果你们团队也正处于“模型越多反而越乱”的阶段不妨先用 APISIX 搭一个小规模的 AI 网关把一两条核心链路管起来跑通之后再去铺全量。等真的跑起来你会发现后面真正的工作并不是连模型而是把模型使用的治理规则一步步沉淀到网关层。