Apache APISIX AI网关：大模型API统一接入与治理实战

最近帮一个客户团队搭模型路由层，聊的时候发现一个很有意思的现象：他们不缺好用的模型，团队里各种大模型 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_AUTHENTICATION=yes - ETCD_ADVERTISE_CLIENT_URLS=http://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/completions，APISIX 会把它转发到本地模型的同名路径上。对于 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-conn：

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": { "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-cache，APISIX 转发时通常会保留，但如果中间有 proxy-rewrite 的 header 改写插件，有可能把关键头覆盖掉。

我自己的经验是：网关层配置一定要预留一个“直连测试”手段。排查流式问题时，先用 curl 直连上游，确认上游 SSE 正常；再经网关请求，逐段对比。通过二分法找出是上游的问题、网关的问题还是客户端的问题。如果直连上游没有问题，那九成就是某一层代理或多层代理之间的缓冲。

4.3 Authorization 头冲突与 API Key 泄露隐患

调用大模型 API 的鉴权头各家并不一样。OpenAI 系用Authorization: Bearer形式，Anthropic 用x-api-key，AWS 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_tokens；stream_options字段在部分本地推理引擎里会被忽略。再比如模型名，本地模型注册名是部署时指定的，如果客户端传的模型名与 vLLM 服务里的模型名不一致，返回的 404 文案还特别有误导性。

遇到这类差异，建议在网关层补一层“请求归一化”：由网关统一填充默认值、过滤掉各个模型不支持的参数。这样业务端始终按 OpenAI 规范传参，兼容性问题都在网关层消化。这块逻辑虽然不复杂，但却是把“多云多模型”真正落地成“一套接口”的关键收尾动作，值得投入人力做到位。

下面把 AI 网关场景的典型故障整理成一个速查表，方便大家直接对照：

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 网关，把一两条核心链路管起来，跑通之后再去铺全量。等真的跑起来你会发现，后面真正的工作并不是连模型，而是把模型使用的治理规则一步步沉淀到网关层。