企业官网建设流程全解析

1. 从流量入口到模型入口：API 网关的角色正在被重写

过去几年里，API 网关在大多数团队里的定位非常清晰：它是南北向流量的统一入口，负责路由转发、鉴权、限流、熔断、可观测性这些"守门人"的活。我们选 APISIX、Kong、Envoy 这类网关，核心诉求就是性能、插件生态和动态配置能力。但最近一年，我明显感觉到一个变化——越来越多的请求不再是"人调用服务"，而是"服务调用模型"，或者"人通过应用调用模型"。请求的形态从结构化的 REST 变成了带 prompt、带上下文、带流式响应的 LLM 调用，网关要处理的东西一下子复杂了一个量级。

这就是"AI 网关"这个概念冒出来的背景。Apache APISIX 作为国内用得最广的开源网关之一，在 3.x 版本之后陆续补齐了面向大模型场景的能力，官方把它统称为 AI 网关能力。它想解决的问题不是"再做一个模型服务平台"，而是把大模型调用这件事，重新纳入到网关这一层来统一治理。换句话说，以前你调 OpenAI、调通义、调本地部署的模型，是在业务代码里硬编码 SDK、硬编码 key、硬编码重试逻辑；现在这些可以下沉到网关层，由网关来做协议适配、密钥托管、负载均衡、限流计费和可观测。

我写这篇东西的出发点很实际：团队里已经有好几个业务线在调大模型，key 散落在各个服务的环境变量里，谁用了多少 token 没人说得清，某家厂商接口抖动的时候只能靠业务自己重试。这种状态下，把 LLM 流量收拢到 APISIX 这一层，是一个性价比很高的选择。下面我会把 APISIX AI 网关的核心机制、落地步骤、以及我自己踩过的坑，尽量讲透。适合已经在用 APISIX 的运维和平台同学，也适合正在评估"要不要上 AI 网关"的架构同学。

2. APISIX AI 网关到底在网关层做了什么

2.1 它解决的不是"能不能调通"，而是"调得可控"

很多人第一次听到 AI 网关，第一反应是"我业务代码里直接调模型 API 不就行了，为什么要多一层"。这个疑问很合理，因为单看"调通"这件事，网关确实不产生价值。AI 网关的价值全部在"调通之后"：当你有 10 个业务、3 家模型厂商、每天几百万次调用的时候，问题就变成了——密钥怎么统一管理、额度怎么分摊、某家厂商挂了怎么自动切换、prompt 和响应怎么审计、token 消耗怎么计费。这些问题在业务代码里各写一遍，就是重复造轮子且必然造歪。

APISIX 的做法是把这些能力做成插件，挂在路由上。核心的几个能力方向是：多厂商协议适配（把不同厂商的请求/响应格式统一）、密钥与凭证托管（key 不落到业务代码）、负载均衡与故障转移（多上游、多 key 轮询）、限流与配额（按 token 或按请求数）、可观测性（记录 prompt、completion、token 用量）。这些能力组合起来，才构成一个"网关"意义上的 AI 治理层。

2.2 协议适配层：把"方言"翻译成"普通话"

大模型厂商的 API 虽然大多号称兼容 OpenAI 的/v1/chat/completions格式，但细节差异非常多。比如流式响应的 SSE 事件格式、finish_reason的取值、错误码的结构、function calling 的字段命名，各家都有自己的"方言"。如果业务直接对接，每换一家就要改代码。

APISIX 在网关层做了一层协议转换。业务侧统一按一种格式（通常是 OpenAI 兼容格式）发请求，网关根据路由配置的上游类型，把请求转成目标厂商的格式，再把响应转回来。这样做的好处是业务代码只认一种协议，换模型厂商对业务透明。我在实际项目里最直观的收益就是：从某家云厂商切到自建推理服务，业务侧一行代码没改，只改了网关的路由上游配置。

注意：协议适配不是万能的。如果业务用到了某家厂商独有的高级能力（比如特定的多模态字段、特有的工具调用格式），适配层可能覆盖不到，这时候要么在网关侧扩展，要么这部分流量单独走。别指望网关能抹平所有差异。

2.3 密钥托管与多 key 负载：把 key 从代码里赶出去

这是我认为 AI 网关最刚需的能力。以前的做法是每个服务的环境变量里塞一个 API key，出了问题要全量重启才能换 key，key 泄露了要挨个服务排查。APISIX 的做法是把 key 存在网关的配置里（或者对接密钥管理服务），业务请求里不带 key，网关在转发时注入。

更进一步的是多 key 负载均衡。同一家厂商你可以配多个 key，网关按轮询或权重分发，单个 key 触发限流时自动切到下一个。这个能力在免费额度或者按 key 限速的场景下特别有用。我实测下来，配置多个 key 之后，单 key 的 429 错误基本被网关消化掉了，业务侧几乎感知不到。

2.4 流式响应的处理：SSE 是绕不开的坎

大模型对话体验的核心是流式输出，也就是 SSE（Server-Sent Events）。网关要处理流式响应，比处理普通 JSON 响应难得多，因为响应是分块到达的，网关不能等整个响应收完再转发，必须边收边转。同时，如果网关要在流式响应里做 token 计数、内容审计，就得解析每一个 chunk，这对性能是有影响的。

APISIX 基于 OpenResty/Nginx 的事件驱动模型，处理流式转发本身是擅长的。但要注意的是，一旦你在流式链路上挂了会缓冲的插件（比如某些日志插件默认会攒批），流式体验就会被破坏，表现为"回答卡住半天然后一次性吐出来"。这个坑我在第一次配置的时候踩得很实，排查了半天才发现是日志插件的缓冲策略问题。

3. 把 LLM 流量接进 APISIX 的完整落地路径

3.1 环境准备：版本和依赖别选错

APISIX 的 AI 相关插件是在较新版本里逐步完善的，如果你用的是很老的 2.x，很多能力是没有的。我的建议是直接用 3.x 的较新版本，并且确认你需要的 AI 插件在当前版本里已经内置。安装方式上，生产环境我倾向于用官方推荐的包管理或容器方式，避免自己编译带来的依赖问题。

依赖方面，AI 网关插件通常需要额外的 Lua 依赖（比如处理 JSON、处理 SSE 的库）。如果你是从源码构建，记得把这些依赖装全，否则插件加载会报错。容器镜像的话，官方镜像一般已经打包好了，省心很多。

# 以容器方式快速起一个用于验证的实例（示例，具体版本按官方最新文档） docker run -d --name apisix-ai \ -p 9080:9080 -p 9180:9180 \ apache/apisix:latest

启动之后先确认 Admin API 能通，这是后面所有配置的前提。

curl http://127.0.0.1:9180/apisix/admin/routes -H 'X-API-KEY: your-admin-key'

3.2 配置一条指向大模型的上游和路由

核心思路是：把大模型服务当成一个上游（upstream），然后建一条路由，在路由上挂 AI 相关插件。下面是一个概念性的配置示例，实际字段名请以你所用版本的官方文档为准。

# 创建上游，指向模型服务地址 curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \ -H 'X-API-KEY: your-admin-key' \ -X PUT -d ' { "type": "roundrobin", "nodes": { "api.model-provider.com:443": 1 }, "scheme": "https" }'

# 创建路由，挂上 AI 代理类插件 curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H 'X-API-KEY: your-admin-key' \ -X PUT -d ' { "uri": "/ai/chat/*", "upstream_id": "1", "plugins": { "ai-proxy": { "provider": "openai", "auth": { "header": { "Authorization": "Bearer sk-your-key" } }, "options": { "model": "gpt-4o-mini" } } } }'

这里有几个关键点值得展开。provider决定了协议适配的目标格式；auth是网关注入凭证的地方，业务请求里不需要带 key；options.model可以强制覆盖业务传来的模型名，也可以做成映射。业务侧只需要往/ai/chat/completions发标准的 OpenAI 格式请求，剩下的交给网关。

3.3 多 key 与故障转移的配置思路

单 key 的配置只能算跑通，真正上生产要考虑多 key 和多上游。多 key 一般通过在上游节点里配置多个带不同凭证的节点，或者用插件层面的 key 池来实现。多上游则是配置多个 upstream，用优先级或健康检查来做故障转移。

我自己的经验是，把"同一厂商的多个 key"和"不同厂商的备用上游"分成两层来做。第一层是同厂商多 key 轮询，解决限流问题；第二层是跨厂商故障转移，解决厂商级故障。第二层的难点在于不同厂商的模型能力不一样，切过去之后回答质量可能变化，所以更适合做"降级"而不是"等价替换"。这一点在配置前一定要和业务方对齐预期。

3.4 验证：别只看 200，要看流式和用量

配置完之后，验证不能只发一个请求看返回 200 就完事。至少要验证三件事：流式响应是否正常（用curl -N看是否逐块返回）、token 用量是否被正确记录、key 是否真的没暴露给业务。

# 验证流式输出，-N 关闭缓冲 curl -N http://127.0.0.1:9080/ai/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-4o-mini", "stream": true, "messages": [{"role": "user", "content": "用一句话解释什么是网关"}] }'

如果这个命令能一行一行地吐出内容，说明流式链路是通的。如果卡很久然后一次性出来，八成是中间有缓冲，回去查插件配置。

4. 那些文档里不会写、但一定会踩的坑

4.1 流式被缓冲：最常见的"体验杀手"

前面提过一次，这里展开讲。流式响应被缓冲的典型表现是：客户端发起请求后长时间没有输出，然后突然一大段内容一次性出现。原因通常是链路上某个环节开启了缓冲，可能是 Nginx 的proxy_buffering，可能是某个日志或审计插件在攒批，也可能是客户端自己的缓冲。

排查顺序我建议从外到内：先确认客户端（curl 加-N）没问题，再查网关的插件配置，最后查 Nginx 层的缓冲开关。定位方法很简单，把可疑插件一个个摘掉，看流式是否恢复。我当时的元凶是一个默认开启缓冲的日志插件，关掉缓冲或者改成异步上报之后就正常了。

提示：任何要在流式链路上做"内容处理"的插件，都要先确认它是否支持流式透传。不支持流式的插件挂在流式路由上，轻则体验变差，重则直接报错。

4.2 token 计数的误差：别把它当账单

网关侧统计 token 用量，通常是基于响应内容做估算或者调用厂商返回的 usage 字段。这两种方式都有误差。基于内容估算的，不同分词器结果不一样；依赖厂商 usage 的，流式响应里 usage 往往在最后一个 chunk 才返回，如果连接提前断开就拿不到。

所以我的建议是：网关侧的 token 统计用来做趋势监控和配额粗控是够的，但不要直接拿它当计费账单。真要精确计费，得结合厂商侧的账单数据做对账。这个认知很重要，我见过有团队直接拿网关统计的数字去跟业务方结算，结果对不上账，很尴尬。

4.3 超时设置：大模型比普通接口慢得多

普通 API 的超时可能设个 3 秒、5 秒，但大模型生成一段长文本，几十秒是常态。如果网关的超时沿用了默认值，会出现"模型还在生成，网关已经把连接断了"的情况。需要调整的超时包括：网关到上游的读超时、连接超时，以及如果前面还有一层负载均衡，那一层也要同步调大。

流式场景下还要注意，超时应该是"两个 chunk 之间的间隔超时"，而不是"整个响应的总超时"。如果配成了总超时，长回答必然被截断。这个细节在配置项里往往体现为不同的超时参数，要仔细看文档。

4.4 错误码的透传与统一

不同厂商的错误码结构不一样，有的用 HTTP 状态码，有的在 body 里塞业务错误码。网关做协议适配的时候，如果不处理错误码，业务侧就会收到五花八门的错误格式，处理起来很痛苦。理想的做法是网关把上游错误统一成一种格式再返回给业务，同时保留原始错误信息用于排查。

我在项目里就遇到过：某厂商限流返回 200 但 body 里是错误，业务侧按 HTTP 状态码判断，完全没识别出来，导致重试逻辑失效。后来在网关侧加了一层错误归一化才解决。这类问题不看实际返回是发现不了的，所以联调阶段一定要把各家的错误场景都造一遍。

5. 从"能跑"到"好用"：AI 网关的进阶玩法

5.1 按业务线做配额和限流

当多个业务共用一套模型凭证时，最怕的是某个业务把额度跑满，其他业务跟着遭殃。APISIX 的限流插件可以按路由、按 consumer、按 header 维度做限制。我的做法是给每个业务线分配一个 consumer，绑定独立的配额，这样既能隔离，又能在监控上区分。

限流的维度选择上，按请求数限流实现简单但不够公平（长回答和短回答算一次），按 token 限流更公平但实现复杂。折中方案是按请求数做粗限，再配合 token 用量的监控告警。具体怎么选，取决于你对公平性的要求有多高。

5.2 语义缓存：省钱又提速的一招

大模型调用又贵又慢，但很多请求其实是重复或高度相似的。语义缓存的做法是：把请求的 prompt 做向量化，在缓存里找相似度超过阈值的历史回答，命中就直接返回，不调模型。APISIX 生态里有相关的缓存插件思路可以借鉴。

这个能力的收益在客服、FAQ 这类场景特别明显，命中率能到相当可观的水平。但要注意阈值设置：设太高命中率低，设太低会返回不相关的答案。我建议先用日志把真实请求的相似度分布跑出来，再定阈值，别拍脑袋。

5.3 可观测性：prompt 和响应要不要记

从排查问题的角度，记录完整的 prompt 和响应是最有用的。但从合规和隐私角度，这里面可能包含用户敏感信息。我的建议是分级处理：默认只记录元数据（模型、token 数、耗时、状态码），完整内容按需开启并且做脱敏，敏感业务线默认不记录内容。这个策略要在上线前就和法务、安全对齐，别等出了事再补。

5.4 和现有网关体系的融合

如果你的团队已经在用 APISIX 做普通 API 网关，那 AI 网关不需要另起一套，直接在现有集群上加路由和插件即可。好处是复用现有的鉴权、监控、发布流程，运维成本低。但要注意资源隔离：大模型的流式长连接会占用较多连接数，如果和普通 API 混部，可能互相影响。有条件的话，给 AI 流量单独一组网关节点更稳妥。

6. 我在这套方案里的一些真实体会

把 LLM 流量收进 APISIX 这一层，最大的价值不是技术上的炫技，而是把"散落在各处的模型调用"变成了"可治理的基础设施"。我自己的项目从最初的业务直连，到后来全部收拢到网关，最直观的变化是：换模型厂商从"改一周代码"变成了"改一条配置"，key 泄露的风险从"全量排查"变成了"网关侧一处更换"，成本从"月底看账单吓一跳"变成了"实时能看到每个业务用了多少"。

但也要说清楚，AI 网关不是银弹。它解决的是治理问题，不解决模型效果问题；它能统一协议，但抹不平厂商之间的能力差异；它能统计用量，但精度不足以直接当账单。把它放在正确的位置上——一个统一入口和治理层——它的价值就非常明确。

如果你现在正准备上这套方案，我的建议是先从一个非核心业务线试点，把流式、超时、错误码这几个最容易出问题的点跑通，再逐步扩大范围。别一上来就把核心业务全切过去，流式链路的坑比你想象的多。等试点稳定了，再考虑多 key、语义缓存这些进阶能力。这套东西的投入产出比，在调用量上来之后会越来越明显。