企业官网建设流程全解析

过去一年，被问到最多的问题不是“哪个大模型更好用”，而是“公司要接大模型了，流量入口到底应该怎么设计”。我见过不少团队直接把前端连到模型服务商，也见过专门写一个 Python 代理层来转发请求，结果几乎都会绕回到同一个结论：需要一个真正的 AI 网关。Apache APISIX 的 AI 网关，就是把 API 网关 在微服务时代沉淀下来的路由、限流、鉴权、可观测能力，原样搬到了大模型 调用场景中，并且针对流式输出、多模型接入、Prompt 管理这些新问题做了专门处理。这篇文章不聊虚概念，只聊我怎么理解它、怎么把它部署起来，以及生产环境里那些容易被忽略的细节。

如果你正在做 LLM 应用的接入层设计，或者团队正准备把大模型从“临时调接口”升级成“正式基础设施”，这篇内容应该能帮你少走不少弯路。下文基于 Apache APISIX 3.x 版本，具体插件名和配置字段以你所用版本的官方文档为准。

1. 为什么应用都接好大模型了，还要再塞一个网关进去

很多人的第一反应是：我的服务已经能调 OpenAI、能调本地模型了，再加一个 APISIX 不是多此一举吗？这个疑问很合理，但只有在流量小、业务单一、密钥只有一个人管的时候成立。一旦大模型能力开始被多个业务方共用，问题立刻暴露。

1.1 客户端直连模型 API 的三宗罪

第一宗罪是密钥泄露。前端直接调大模型接口，Key 必然会被抓包抓走；后端直连虽然好一点，但多个项目共用一个 Provider 账号时，你根本分不清某个 Key 是从哪个业务流出去的。密钥不是“看起来能用就行”，它直接对应账单。

第二宗罪是费用失控。大模型接口的计费逻辑和普通 REST API 完全不同——同一个接口，输入 100 个 token 和输入 10000 个 token，成本差两个数量级。普通后端代理只转发请求，不做配额管理，一旦某个业务方出现死循环调用或者被人刷接口，月底账单会非常好看。

第三宗罪是供应商绑定。今天用的是 A 厂商的模型，明天评测发现 B 厂商效果更好，或者老板决定换成私有化部署的模型，这时候你会发现业务代码里到处都是模型厂商 SDK 的痕迹，改起来很痛苦。没有一层中间抽象，换模型等于重写接入层。

1.2 API 网关在 AI 时代的新职责

传统 API 网关的核心能力是路由、负载均衡、限流、熔断、鉴权、日志和监控。到了大模型时代，这些能力依然有效，但不够了。AI 场景对网关提出了几个此前不太会遇到的新要求：

• 统一模型入口：无论上游是 OpenAI、Azure、AWS Bedrock，还是本地私有化部署的 vLLM 和 Ollama，业务方都只看到一个标准接口。
• 流式响应转发：大模型生成长文本时普遍使用 SSE 流式返回，网关不能在中间把流截断或者缓冲成一个大包，否则前端体验会非常差。
• Token 级成本控制：按请求数限流远远不够，还要能识别模型、上下文长度、输出长度，从成本角度做配额。
• Prompt 生命周期管理：把提示词模板从业务代码里抽出来，放到网关层统一维护，改 Prompt 不需要重新发版。
• 多模型灰度与容灾：新模型上线后先切 10% 流量观察效果，出问题自动回滚，这在直连架构里很难优雅实现。

本质上，AI 网关是“懂大模型协议的 API 网关”。普通网关只看到 HTTP 请求和响应，AI 网关还要理解什么是 messages、什么是 completion、什么是 SSE 里的 data 帧。

1.3 APISIX 为什么适合当 AI 网关

选型时可以比较很多产品，但 APISIX 有几个天然优势让我愿意把它用在 AI 场景。

首先是APISIX 本身就是 Apache 顶级开源项目，基于 OpenResty/Nginx 实现，单机性能很强，又不需要像传统 Nginx 那样改完配置还要 reload；它用 etcd 保存配置，路由、插件、上游都可以热更新。这意味着 AI 网关的接入、模型切换、限流策略调整，都可以在运行时完成，不需要重启服务。

其次是插件体系成熟。AI 网关不是从零发明的新物种，而是把传统网关能力和 AI 专用逻辑组合在一起。APISIX 社区已经有了 key-auth、limit-count、prometheus、opentelemetry 这些经过生产验证的插件，再叠加 AI 插件，就能快速拼出一个完整的 AI 接入层。

最后是部署形态灵活。APISIX 可以部署在 Kubernetes 里做 Ingress，也可以以传统网关方式跑在虚拟机或容器中，还能跟 Apache SkyWalking、Prometheus 等生态无缝对接。不管你的基础设施是云原生还是传统架构，都能把它塞进去。

2. 先看懂 APISIX 的 AI 网关方案长什么样

APISIX 做 AI 网关的思路非常直白：不推翻原有架构，而是增加一组能听懂“模型语言”的插件。你依然用 API 网关的方式去创建路由、配置上游、挂插件，只是插件从“限流”“鉴权”扩展到了“代理大模型”“管理 Prompt”“改写模型请求”。

2.1 从“流量转发”到“模型协议感知”

传统反向代理拿到请求后，基本只关心 Host、Path、Header，然后把流量转发给后端。APISIX 的 AI 相关插件打破了这层“不关注报文内容”的默契，它会解析请求体里的模型参数、messages 结构，然后按目标模型厂商的要求重新组织请求。这样带来的直接好处是：业务方不需要关心上游到底是哪家模型，只需要按标准格式发请求，剩下的协议转换由网关完成。

举一个最简单的例子：同一个业务请求，要发给 OpenAI 时路径是/v1/chat/completions，要发给 Azure OpenAI 时路径却变成了/openai/deployments/{deployment}/chat/completions?api-version=xxx，还要额外加两个请求头。如果业务服务直接对接，这些差异就会散落在代码的各个角落；接到 APISIX 之后，差异被收敛在网关路由和插件配置里。

2.2 插件全家桶：ai-proxy 与它的邻居们

APISIX 在 3.x 版本里陆续引入了一系列 AI 插件，大致可以分为代理类、Prompt 类和适配类。先看一张简表，后面逐个解释：

ai-proxy是整个 AI 网关的核心。它的工作方式是在路由上开启，然后指定 provider（模型厂商）、auth（密钥注入方式）、options（模型名、temperature、max_tokens 等参数）。开启之后，业务方发来的请求会被统一接管，网关替你拼好鉴权头、填好模型参数，再转发到上游。流式请求时它也能正确透传 SSE 数据帧。

ai-prompt-template解决的是 Prompt 散落在业务代码里的问题。很多团队用大模型时，system prompt 是在后端 Java/Python 代码里拼字符串，改一次 Prompt 就要发一次版。用这个插件可以把 Prompt 模板放到网关配置里，运行时从请求参数或者请求头里取变量填充模板。

ai-api-rewrite更像一个“翻译层”。比如你的老系统本来有一个查询天气的接口，现在想用大模型生成天气描述，业务方不希望改接口格式，那就由这个插件把旧接口的请求体改写成/v1/chat/completions需要的 messages 结构。

ai-aws-llm / ai-azure-llm这类专用插件解决的问题是：有些云厂商的模型服务并不是标准的 OpenAI 协议。AWS Bedrock 的请求结构、签名算法和流式格式都跟 OpenAI 不一样；Azure OpenAI 则有自己的一套路径和 API 版本管理。专用插件把这些差异封装起来，业务侧依然可以用相对统一的方式对接。

注意：AI 插件在 APISIX 里迭代很快，插件名和配置字段在不同版本间可能有调整。我在 3.10 上验证过上述插件的存在，如果你用的是更早或更新的版本，先通过 Admin API 查看/apisix/admin/schema/ai-proxy这类接口确认当前 schema，再写配置。

2.3 一个聊天请求的完整旅程

为了把 APISIX 的 AI 网关逻辑讲清楚，我画一个文字版的请求链路，不涉及具体配置，先建立整体印象：

1. 客户端把请求发到 APISIX 数据面，比如POST /v1/chat/completions。
2. 请求先经过路由匹配，APISIX 找到对应的 Route，以及 Route 上挂载的插件链。
3. 插件链按顺序执行：key-auth先做身份认证，limit-count做请求次数的限流，ai-prompt-template把业务变量填充进 Prompt 模板，最后轮到ai-proxy。
4. ai-proxy根据配置的 provider 重构请求：补充 Authorization 头、填充模型名和采样参数、必要时改写请求路径。
5. 上游连接把请求发送给真实的模型服务。如果配置了本地模型，就转发到本地推理服务；如果配置了云端模型，就转发到云厂商。
6. 模型服务返回响应，如果是流式输出，ai-proxy会逐帧透传 SSE 数据，不缓存、不攒包。
7. 响应回程时，prometheus 插件记录指标，http-logger 插件输出审计日志，然后返回客户端。

这个链路和传统微服务网关最大的区别在第 4 步和第 6 步。传统网关不会修改你的请求体，AI 网关则会按模型协议“重新组织”你的请求；传统网关倾向于缓冲响应以减少上游压力，AI 网关则必须尊重流式语义。

2.4 和传统微服务网关的共存关系

很多人担心引入 AI 网关之后，团队是不是要再维护一套独立基础设施。APISIX 的答案是不用。它本身就是一套通用网关，AI 能力只是新增的插件和路由策略。

你在同一个 APISIX 集群里，完全可以让/api/order走订单微服务，让/ai/chat走大模型服务，两者共用同一套 Admin API、同一个 etcd 集群、同一套监控体系。甚至可以在同一个路由上同时挂载传统插件和 AI 插件。这意味着团队不需要额外引入一个“AI BFF”服务，也不需要维护两台不同的网关，运维成本没有显著增加。

这个设计对中小团队尤其友好。大模型接入初期流量不大，可以先在现有 APISIX 集群里加一两个 AI 路由试水；等业务量上来了，再把 AI 路由拆到独立的数据面节点上做资源隔离。演进路径非常平滑。

3. 从零跑通：把 OpenAI 兼容接口接入 APISIX

理论说再多，不如亲手跑通一条路由。我用一个最小化的 Docker 部署来演示，目标是让 APISIX 成为一个大模型流量的统一入口。

3.1 先跑一个最小 APISIX 实例

APISIX 依赖 etcd 做配置存储，所以我先用 Docker 拉起一个 etcd，再启动 APISIX。这里为了演示方便，把两个容器放在同一个自定义网络里：

docker network create apisix-demo docker run -d --name apisix-etcd --network apisix-demo \ -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \ -e ETCD_ADVERTISE_CLIENT_URLS=http://apisix-etcd:2379 \ quay.io/coreos/etcd:v3.5.7 docker run -d --name apisix-gateway --network apisix-demo \ -p 9080:9080 -p 9180:9180 \ -e APISIX_ETCD_HOST=apisix-etcd:2379 \ apache/apisix:3.10.0-debian

容器起来后，9080 是数据面 HTTP 端口，9180 是 Admin API 端口。先确认 APISIX 是否正常：

curl http://127.0.0.1:9180/apisix/admin/routes \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

能返回一个空列表就说明 Admin API 可用。上面那个 X-API-KEY 是 APISIX 默认配置里的管理密钥，只适合本地实验，生产环境必须改掉。

3.2 创建第一条 AI 路由

我用最常规的 OpenAI 兼容接口做例子。这里的关键点是：ai-proxy插件负责在网关层注入鉴权头和模型参数，upstream指向真实的模型服务地址。

curl http://127.0.0.1:9180/apisix/admin/routes/llm -X PUT \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \ -d '{ "name": "openai-chat", "uri": "/v1/chat/completions", "plugins": { "ai-proxy": { "provider": "openai", "auth": { "header": { "name": "Authorization", "value": "Bearer sk-your-openai-key" } }, "options": { "model": "gpt-4o-mini", "max_tokens": 800, "temperature": 0.3 } } }, "upstream": { "type": "roundrobin", "scheme": "https", "nodes": { "api.openai.com:443": 1 } } }'

这段配置里要做几件事：路由路径是/v1/chat/completions；ai-proxy的 provider 是 openai，意味着插件会按 OpenAI 协议处理请求；auth.header表示插件在转发时会把Authorization: Bearer sk-xxx加到请求头里，业务方不用再关心模型厂商密钥；options里的模型参数会被统一注入。

这里有一个设计细节值得注意：业务方发请求时，其实不需要自己在请求体里写 model 和 temperature。网关侧的 options 会统一补上。这样做的意义是，后续换模型只需要改路由配置，业务代码一行不用动。

3.3 普通响应和 SSE 流式响应都验证一遍

先用普通请求验证：

curl http://127.0.0.1:9080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "messages": [ {"role": "user", "content": "用一句话介绍 API 网关"} ] }'

如果一切正常，你会看到类似下面的响应：

{ "id": "chatcmpl-xxx", "object": "chat.completion", "model": "gpt-4o-mini", "choices": [ { "message": { "role": "assistant", "content": "API 网关是微服务架构中统一管理、路由和保护 API 流量的入口层。" } } ], "usage": { "prompt_tokens": 20, "completion_tokens": 30, "total_tokens": 50 } }

注意请求体里我没有写 model 和 temperature，因为网关已经帮我填了。这就是 ai-proxy 的价值：业务调用方只需要关心 messages 内容。

再验证流式输出。大模型场景里流式才是常态，前端需要边生成边渲染，所以要加上"stream": true：

curl -N http://127.0.0.1:9080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "messages": [ {"role": "user", "content": "用三句话介绍 Apache APISIX"} ], "stream": true }'

-N参数告诉 curl 不要缓冲输出，这样你能看到 SSE 数据逐帧到达，格式大致是：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"Apache"}}]} data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":" A"}}]} data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"PISIX"}}]} data: [DONE]

看到这种逐帧返回的效果，说明网关没有把流掐断或者攒成一个大包再返回，SSE 透传是通的。

3.4 把本地部署的大模型也接进来

云端模型适合很多场景，但企业一旦涉及数据隐私、合规或者离线推理需求，往往会在内网部署本地大模型。常见的方案是 Ollama 或者 vLLM，它们都提供 OpenAI 兼容接口。最直观的做法是：绕开云端 provider，直接把上游指向本地模型服务。

以 vLLM 为例，假设它跑在一台内网机器上，监听了 8000 端口，OpenAI 兼容路径是/v1/chat/completions。那么我可以在 APISIX 里加这样一个路由：

{ "name": "local-vllm", "uri": "/local/v1/chat/completions", "plugins": { "ai-proxy": { "provider": "openai", "options": { "model": "qwen2.5-7b-instruct", "max_tokens": 512, "temperature": 0.7 } } }, "upstream": { "type": "roundrobin", "scheme": "http", "nodes": { "10.0.0.8:8000": 1 } } }

这里我把provider设为openai，是因为 vLLM 的接口本身是 OpenAI 兼容的，ai-proxy 仍然可以帮你统一注入模型名和采样参数。如果你用的是 Ollama，默认端口是 11434，OpenAI 兼容路径同样是/v1/chat/completions，配置思路完全一致。

这样业务方就拥有了一个混合接入层：访问/v1/chat/completions走云端模型，访问/local/v1/chat/completions走本地模型。想灰度切换时，只需要调整路由权重，或者把某个 Consumer 的请求导向另一个路由，不需要改业务代码。

提示：如果你是拿 APISIX 容器访问宿主机上的本地模型，容器内不能用 127.0.0.1 访问宿主机，需要把 upstream 节点改成host.docker.internal:8000，并在启动容器时追加--add-host=host.docker.internal:host-gateway。

4. 生产环境必须处理的四件事

演示路由跑通只是第一步。真正要把 AI 网关放上生产，有四个问题必须提前想清楚，否则上线后一定会被账单、安全事件或者故障折腾到怀疑人生。

4.1 密钥管理与租户隔离

模型厂商的密钥一旦配置进ai-proxy，业务方就不应该再接触到它。理想状态下，模型厂商密钥只存在于 APISIX 配置或秘密管理工具里，业务方使用的是 APISIX 自己颁发的访问凭据。

APISIX 的 Consumer +key-auth插件可以帮你做到这一点。先创建一个 Consumer：

curl http://127.0.0.1:9180/apisix/admin/consumers -X PUT \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \ -d '{ "username": "business-a", "plugins": { "key-auth": { "key": "business-a-secret-key" } } }'

然后在 AI 路由上挂上key-auth：

{ "plugins": { "key-auth": {}, "ai-proxy": { "provider": "openai", "auth": { "header": { "name": "Authorization", "value": "Bearer sk-your-openai-key" } }, "options": { "model": "gpt-4o-mini" } } } }

这样业务方调用时只需要带 APISIX 颁发的 Key，所有模型厂商密钥都沉淀在网关侧。即使某个业务方 Key 泄露，你也可以只撤销这一个 Consumer，而不用去模型厂商后台重置全局密钥。这就是网关层密钥托管的核心价值。

4.2 限流：别只数 QPS，还要盯 token

传统限流按 QPS 数就够用了，但大模型接口不一样。一次请求可能消耗 100 token，也可能消耗 10000 token，成本差异巨大。APISIX 原生的limit-count插件可以按请求次数限流，这是第一道防线：

{ "plugins": { "limit-count": { "count": 100, "time_window": 60, "rejected_code": 429, "key_type": "var", "key": "consumer_name", "policy": "local" } } }

上面的配置表示每个 Consumer 每分钟最多 100 次请求。对于防止恶意刷量和失控循环调用，这个配置基本够用。但它没有覆盖 token 维度的成本控制，因为网关在拿到响应之前，并不知道这次请求实际消耗了多少 token。

我的建议是组合拳：limit-count控制请求频率，同时在网关层记录响应里的usage字段，异步计算每个 Consumer 的累计 token 消耗。如果预算控制严格，可以在网关里用自定义插件做前置检查，结合请求里 messages 的预估长度做粗粒度拦截。精确的 token 级限流往往需要模型厂商的配额接口配合，目前更多是靠“网关限频 + 账本核算 + 告警”的方式落地。

4.3 成本与审计：谁在什么时候问了多少 token

大模型调用必须留审计日志，原因不用多说：Prompt 有问题要排查、成本异常要定位、合规审计要证据。传统网关日志只需要记录 URL、状态码、耗时；AI 网关日志里还应该记录模型名、prompt 概览、completion 概览、token 用量。

APISIX 的http-logger或kafka-logger插件可以完成这件事。我把请求和响应的关键信息发送到日志服务：

{ "plugins": { "http-logger": { "uri": "http://log-service:8080/receive", "batch_max_size": 100, "include_req_body": true, "include_resp_body": true } } }

include_req_body和include_resp_body开启后，网关会把请求体和响应体一起发到日志服务。但这里有一个非常重要的注意点：不要把完整的 Prompt 明文日志直接接到所有人的终端上。Prompt 里可能包含用户隐私、内部业务数据甚至密钥。更稳妥的做法是，日志系统里做脱敏和权限控制，或者只记录 token 数量和模型名，仅在需要排查时再临时开启完整 body 记录。

4.4 可观测性：把大模型调用纳入监控体系

最后是监控。APISIX 原生支持 Prometheus 指标暴露，开启prometheus插件后，你可以从/apisix/prometheus/metrics拉取网关自身的流量指标。配合 Grafana 可以很快看到 QPS、延迟、上游错误率。

但 AI 场景的监控不能只停留在网关层。我建议额外关注两个维度：

• 模型维度指标：不同模型、不同 Consumer 的调用量、token 消耗、首 token 延迟、平均生成速率。这些指标能告诉你哪个模型在烧钱、哪个模型响应慢。
• 上游模型服务的健康状况：本地大模型在推理负载高时，排队延迟会显著上升。网关要能感知上游超时和 5xx，配合 APISIX 的api-breaker插件做熔断，避免雪崩。

技术实现上，可以在 APISIX 上通过自定义插件埋点，或者用 OpenTelemetry 插件把请求链路送到 SkyWalking、Jaeger 这类平台。核心原则是：模型调用也是调用，必须和其它后端服务一样有完整的指标、日志和链路追踪，不能成为监控盲区。

5. 这些坑我帮你踩过了

最后这部分内容，是几个真实项目里遇到并踩过的问题。每个问题最初看起来都像“模型厂商的错”，最后排查下来，多多少少都有接入层的责任。

5.1 SSE 流式回包被网关截断或缓冲

有一次前端反馈：回答不是逐字出来的，而是等了好一会儿才一次性出现一整段。第一反应是模型生成慢，后来抓包才发现，请求到达模型很快，响应其实早就开始流式返回了，但网关侧把流缓冲住了。

排查思路是先分清“上游没有流”还是“网关没有转流”。用 curl 直接访问模型服务，如果 SSE 正常，问题就出在中间链路。APISIX 本身对流式转发是支持的，但你需要注意响应缓冲相关的配置。若发现响应被缓冲，可以检查数据面 Nginx 的proxy_buffering配置，或者让上游在响应头里显式返回X-Accel-Buffering: no，告诉中间层不要缓冲这个响应。

这类问题最坑的地方在于：普通请求一切正常，只有 SSE 请求会踩，而且只在长回答场景下暴露，第一轮简短回答根本发现不了。我的建议是在接入阶段就专门写一个长文本流式测试用例，别嫌麻烦。

5.2 各家“OpenAI 兼容”其实并不完全兼容

很多本地推理框架都宣称“兼容 OpenAI 接口”，但真的切换起来，细节差异不少。有的框架支持max_tokens，有的只支持max_new_tokens；有的在流式响应里带usage字段，有的不带；还有的在finish_reason的处理上跟 OpenAI 官方不一致。

更麻烦的是 Azure OpenAI。它虽然整体上也是 OpenAI 协议，但路径里必须带 deployment 名称和api-version参数，鉴权方式也不一定是 Bearer Token。如果不做适配，业务代码会被这些差异填满。

APISIX 的价值在这里体现得很充分：差异收敛在网关层，业务侧保持标准 OpenAI 格式。用对应的 provider 插件处理云端厂商的特殊协议；对于本地模型，宁可在网关里加一层轻量请求改写，也不要把兼容逻辑散落在多个业务服务里。

5.3 提示词注入和数据隐私不是模型厂商单方面的事

网关接管了大模型流量之后，它会变成一个非常敏感的数据咽喉：所有发给模型的 Prompt、所有模型返回的内容，都会经过这里。这意味着你必须考虑两类风险：

一类是提示词注入。攻击者可能在用户输入里塞入“忽略之前的指令”这类内容，诱导模型输出异常内容。网关层可以做简单的规则过滤，也可以在转发前调用专门的安全模型做内容审核。APISIX 的serverless-pre-function插件允许你在转发前执行自定义脚本，适合做这块的轻量拦截。但说实话，提示词注入目前没有银弹，规则过滤只能挡常见攻击，真正的语义级防护还需要模型侧加固。

另一类是数据隐私。日志里记录了 Prompt，监控平台上有完整请求体，如果这些数据被不该看到的人接触到，就是合规事故。生产环境里，尽量做到日志脱敏、访问控制、传输加密。不要因为网关“只是转发”就忽略数据安全责任。

5.4 版本迭代太快，插件 schema 会变

这一点我必须强调：APISIX 的 AI 插件还处在快速演进期。我从早期版本接触这些插件时，名字和配置就跟现在不一样，升级版本时确实遇到过后向兼容问题。所以不要默认“同一个配置在下一个版本还能直接跑”。

我的实践是：固定版本，升级前先看 changelog，重点检查 AI 插件相关的 breaking change；上线前先在非生产环境把旧路由导出、重新导入、跑一遍回归测试，尤其是流式响应场景。APISIX 本身支持通过 Admin API 导出导入路由配置，这个能力在升级验证时很好用。

如果你打算上 APISIX AI 网关，我的建议是先小流量接一个非核心场景跑一两周。看看流式透传是否稳定，看看日志和监控数据能不能支撑你后续做成本治理，再逐步把核心业务迁过来。网关本身不会让你的模型变聪明，但它能让你在大模型这条路上走得稳一点。