企业官网建设流程全解析

1. 企业大模型网关到底解决什么问题

1.1 从一个真实的翻车现场说起

去年帮一家做 SaaS 的团队做架构评审，他们内部有 7 个业务线，每个业务线都在自己调 OpenAI 的接口。听起来没什么，直到我让他们把各自的 API Key 拿出来数一数——23 个。散落在 23 个不同的配置文件、环境变量、甚至某个同事的本地.env里。有人离职了 Key 还在跑，有人把 Key 硬编码进了前端构建产物，还有人为了省钱偷偷换了个便宜的中转服务，结果那家中转把请求日志全存下来了。

这就是没有网关的典型状态：Key 失控、成本失控、合规失控、可观测性为零。

企业大模型网关（LLM Gateway）本质上就是所有模型调用的统一入口。它站在业务代码和各家模型 API 之间，把鉴权、路由、限流、计费、日志、缓存、降级这些脏活累活全部收拢到一层。业务方只需要对着网关发一个标准的 OpenAI 兼容请求，至于这个请求最终打到哪家模型、走哪条链路、花了多少钱，网关说了算。

1.2 网关不是反向代理那么简单

很多人第一反应是"这不就是个 Nginx 吗"。差得远。Nginx 做的是七层转发，它不理解你请求体里那个model字段是什么意思，也不知道prompt_tokens和completion_tokens的区别。而大模型网关必须理解语义层的东西：

• 协议转换：把 OpenAI 的/v1/chat/completions格式翻译成 Anthropic 的 Messages API、通义千问的 DashScope 格式、或者本地 vLLM 的接口。业务方永远只写一种格式。
• Token 计量：不同模型的 tokenizer 不一样，同一个中文句子在 GPT 和 Claude 下算出来的 token 数能差 30%。网关要按各自的分词器精确计量，才能算准成本。
• 流式透传：SSE（Server-Sent Events）流式响应必须原样透传，中间不能缓冲，否则用户会看到打字机效果变成"憋一大段再吐出来"。
• 语义缓存：两个用户问"北京今天天气怎么样"和"今天北京天气如何"，字面不同但语义相同，网关可以命中同一个缓存结果，直接省掉一次模型调用。

这四件事，任何一件都不是 Nginx 配置能搞定的。

1.3 什么样的团队真的需要网关

不是所有团队都得上网关。我的判断标准很粗暴：

我见过最极端的案例是一家公司有 40 多个内部工具在调模型，财务月底对账时发现账单比预期高了 6 倍，查了三天才定位到是某个测试脚本忘了关，一直在跑批量任务。有网关的话，一个限流规则就能拦住。

2. 网关的核心架构与关键选型

2.1 分层设计：别把网关做成大泥球

一个能扛住生产流量的网关，我一般会拆成四层，每层职责单一：

接入层负责 TLS 终止、连接复用、请求体大小限制。这一层用 Nginx 或者云厂商的 LB 就行，不要在这里写业务逻辑。

鉴权与配额层做虚拟 Key 的校验、租户识别、RPM/TPM 限流。这里的关键设计是：业务方拿到的是虚拟 Key，不是真实的上游 Key。虚拟 Key 可以随时吊销、可以绑定配额、可以追溯归属。真实 Key 只存在网关的密钥管理服务里，业务方永远看不到。

路由与编排层是网关的大脑。它根据请求里的model字段、租户配置、当前各上游的健康状态，决定这个请求打到哪。高级一点的还会做 fallback：主模型超时了自动切备用模型，备用也挂了就返回降级响应。

可观测层记录每一次调用的完整链路：谁调的、调的什么模型、输入输出 token 数、耗时、是否命中缓存、花了多少钱。这些数据是成本分摊和容量规划的基础。

2.2 自研还是用开源：一笔算清楚的账

这是被问得最多的问题。我的建议是先看开源方案能不能满足 80% 的需求，剩下 20% 再自己扩展。

主流的开源网关方案里，LiteLLM Proxy 的生态最成熟，支持 100 多个模型提供商，OpenAI 兼容做得最彻底，配置用 YAML 就能搞定。One-API 在国内团队里用得多，中文文档全，管理后台开箱即用。Higress 的 AI 网关插件适合已经在用 K8s 和 Istio 的团队，能复用现有的服务网格能力。

自研的诱惑在于"完全可控"，但你要想清楚自研意味着什么：协议转换要跟着各家 API 的版本更新走，OpenAI 一年改好几次接口细节；限流要做分布式，单机限流在多个网关实例下会失效；密钥管理要做加密存储和轮换。这些工作量加起来，两个资深后端至少三个月才能到生产可用。

我的实际经验是：用开源做底座，把企业特有的逻辑（比如内部计费规则、特殊的租户隔离策略）做成插件挂上去。这样既省了 80% 的重复劳动，又保留了定制空间。

2.3 部署形态：Sidecar 还是中心化

两种形态各有场景。中心化部署就是一个独立的网关集群，所有业务方通过网络调用它。优点是管理简单、配额统一、升级一次全生效。缺点是网关本身成了单点，得多副本加健康检查。

Sidecar 形态是把网关作为边车容器跟业务服务部署在一起。优点是网络延迟低、故障隔离好。缺点是配置分发复杂，几十个 Sidecar 的版本一致性很难保证。

我的建议是：中小团队直接中心化，别折腾 Sidecar。等你的业务方超过 50 个、跨多个机房了，再考虑混合形态。

3. 从零搭一个可用的网关：实操步骤

3.1 环境准备与依赖安装

假设我们用 LiteLLM Proxy 做底座，跑在一台 4C8G 的机器上。先装 Python 环境和依赖：

python3 -m venv venv source venv/bin/activate pip install 'litellm[proxy]' prisma

这里有个坑：LiteLLM 依赖 Prisma 做数据库 ORM，第一次运行会自动下载 Prisma 的二进制文件。如果网络环境不好，这一步会卡很久。可以提前设置镜像源，或者手动下载二进制放到缓存目录。

数据库我建议用 PostgreSQL，别用 SQLite。SQLite 在并发写入时锁表严重，网关这种高频写日志的场景下会拖垮性能。

docker run -d --name gateway-db \ -e POSTGRES_PASSWORD=yourpassword \ -e POSTGRES_DB=litellm \ -p 5432:5432 postgres:16

3.2 配置文件：把模型和 Key 管起来

网关的核心配置文件长这样，我加了详细注释：

model_list: - model_name: gpt-4o # 业务方请求时用的名字 litellm_params: model: openai/gpt-4o # 实际的上游模型标识 api_key: os.environ/OPENAI_KEY_1 # 从环境变量读，不写死在配置里 rpm: 500 # 这个 Key 每分钟最多 500 次 - model_name: gpt-4o # 同名模型可以配多个，做负载均衡 litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_KEY_2 rpm: 500 - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-20250514 api_key: os.environ/ANTHROPIC_KEY router_settings: routing_strategy: usage-based-routing-v2 # 按实际用量做负载均衡 num_retries: 2 # 失败重试 2 次 timeout: 30 # 单次请求 30 秒超时 fallbacks: [{"gpt-4o": ["claude-sonnet"]}] # gpt-4o 全挂了切 claude general_settings: master_key: sk-your-master-key # 管理接口的密钥 database_url: os.environ/DATABASE_URL

为什么同名模型要配多个 Key：这是最实用的负载均衡手段。单个 OpenAI Key 有 RPM 和 TPM 限制，配多个 Key 轮询能把有效配额翻倍。usage-based-routing-v2策略会优先选当前用量最低的那个，比简单的轮询更聪明。

fallback 的坑：不是所有模型都能互相 fallback。gpt-4o 切 claude-sonnet 时，如果请求里带了 OpenAI 特有的response_format: {type: "json_schema"}，Claude 可能不支持这个参数，会直接报错。所以 fallback 链上的模型，能力要尽量对齐。

3.3 虚拟 Key 的签发与配额管理

启动网关后，用 master key 调管理接口签发虚拟 Key：

curl -X POST http://localhost:4000/key/generate \ -H "Authorization: Bearer sk-your-master-key" \ -H "Content-Type: application/json" \ -d '{ "models": ["gpt-4o", "claude-sonnet"], "max_budget": 100, "budget_duration": "30d", "rpm_limit": 100, "tpm_limit": 50000, "metadata": {"team": "search", "owner": "zhangsan"} }'

返回的key字段就是给业务方的虚拟 Key。注意几个参数的含义：

• max_budget: 100表示这个 Key 在 30 天内最多花 100 美元，超了直接拒绝。
• rpm_limit和tpm_limit是双保险，防止某个业务方突发流量打爆上游。
• metadata里的团队信息是成本分摊的依据，月底按这个字段聚合就能出账单。

提示：虚拟 Key 一定要设置过期时间。我见过太多团队签发的 Key 从来不回收，离职员工的 Key 还在跑。建议默认 90 天过期，续期走审批流程。

3.4 业务方怎么接入

业务方的代码改动量极小，只需要把 base_url 和 api_key 换掉：

from openai import OpenAI client = OpenAI( base_url="http://gateway.internal:4000/v1", # 指向网关 api_key="sk-virtual-key-xxx" # 虚拟 Key ) resp = client.chat.completions.create( model="gpt-4o", # 用网关定义的模型名 messages=[{"role": "user", "content": "你好"}], stream=True )

原来的 OpenAI SDK 代码一行都不用改，因为网关完全兼容 OpenAI 协议。这是网关设计里最重要的一条原则：不要让业务方感知到网关的存在。任何需要业务方改代码的网关方案，推广阻力都会大十倍。

4. 自动化编程 Agent 与 CLI 的落地实践

4.1 Agent 和普通脚本的本质区别

热词里 agent 出现频率极高，但很多人对它的理解还停留在"会调工具的脚本"。这两者的区别在于决策循环。

普通脚本是线性的：读输入 → 处理 → 输出。Agent 是一个循环：观察当前状态 → 决定下一步动作 → 执行动作 → 观察结果 → 再决定。这个循环会一直跑到任务完成或者达到终止条件。

用生活类比：普通脚本是自动售货机，投币出货，流程固定。Agent 是刚入职的实习生，你给他一个目标，他自己决定先查资料还是先问人，遇到问题会调整策略。

这个区别决定了 Agent 的工程复杂度远高于脚本。你需要处理：循环终止条件（防止无限循环烧钱）、工具调用的错误恢复、上下文窗口管理（对话太长要压缩）、以及最关键的——权限边界。

4.2 CLI 形态的 Agent 为什么突然火了

命令行 Agent 工具（比如各类 codex 风格的 CLI）最近很火，原因很实际：开发者的工作流本来就在终端里。

传统的 AI 编程助手是 IDE 插件形态，你得在编辑器里选中代码、打开侧边栏、输入问题。而 CLI Agent 直接在终端里跑，可以读你当前目录的文件、执行 git 命令、跑测试、看报错，然后自己决定改哪个文件。整个"发现问题 → 定位 → 修复 → 验证"的闭环都在终端完成，不用切换上下文。

一个典型的 CLI Agent 工作流是这样的：

# 安装（以 npm 分发的 CLI 为例） npm install -g @example/coding-agent # 首次登录，绑定账号 coding-agent login # 在项目目录里直接下任务 cd my-project coding-agent "修复 src/utils/parser.js 里处理空数组时的崩溃，并补一个测试"

Agent 会自己读文件、分析问题、改代码、跑测试，最后给你一个 diff。你要做的是 review 这个 diff，而不是从零写代码。

4.3 把 CLI Agent 接到企业网关上

这里有个关键问题：CLI Agent 默认会直连模型提供商的 API。在企业环境里，这既不合规（数据出域）也不经济（无法统一计费）。

解决办法是让 CLI Agent 支持自定义 base_url。大部分成熟的 CLI 工具都提供了这个配置项，通常通过环境变量或者配置文件设置：

export OPENAI_BASE_URL=http://gateway.internal:4000/v1 export OPENAI_API_KEY=sk-virtual-key-for-cli

这样 CLI Agent 的所有模型调用都会经过企业网关，享受统一的鉴权、限流、日志和计费。同时网关侧可以针对 CLI 场景做特殊配置：比如给代码补全类请求设置更低的超时（用户等不了 30 秒），给代码审查类请求设置更高的 token 上限。

注意：CLI Agent 会读取项目文件内容发给模型，如果项目里有敏感配置（数据库密码、私钥），要确保 Agent 的忽略规则配置正确。大部分工具支持.agentignore或类似机制，把敏感文件排除掉。

4.4 Agent 的安全边界怎么划

Agent 能执行命令、能改文件，这既是能力也是风险。我踩过的坑里，最惊险的一次是 Agent 在执行清理任务时，把rm -rf的目标路径算错了，差点删掉整个构建目录。幸好当时是在容器里跑的。

几条硬性建议：

第一，Agent 永远在沙箱里跑。用容器或者虚拟机隔离，给它一个独立的工作目录，不要让它碰宿主机的重要路径。

第二，危险操作要二次确认。删除文件、执行数据库变更、推送代码到远程仓库，这些操作应该要求人工确认。可以在 Agent 框架里配置一个"需要审批的工具列表"。

第三，给 Agent 的 API Key 设置严格的配额。Agent 的循环特性意味着它可能在一个任务上烧掉大量 token。我一般给 Agent 用的虚拟 Key 设置比普通业务更低的日预算，比如 5 美元，超了就停。

第四，完整的审计日志。Agent 的每一步决策、每一次工具调用都要记录。出了问题能回溯，这是底线。

5. 常见问题与排查实录

5.1 网关侧的高频故障

问题一：流式响应中断，用户看到半截就没了。

排查思路：先看网关日志里这次请求的耗时，如果刚好卡在某个整数秒（比如 30 秒、60 秒），大概率是超时配置。检查三个地方：网关到上游的超时、负载均衡器的空闲连接超时、以及客户端自己的超时。这三个超时值要满足"客户端 > 网关 > 上游"的关系，否则会出现网关还在等上游、客户端已经断开的情况。

问题二：Token 计量和上游账单对不上。

这是最常见的对账问题。原因通常有三个：一是网关用的 tokenizer 和上游不一致，中文场景下差异尤其明显；二是重试的请求被计了两次费（上游只算一次，但网关记了两次）；三是缓存命中的请求网关记了 0 成本，但上游其实也计了费（如果缓存是在上游做的）。

解决办法：网关的计量数据只作为内部成本分摊的参考，真正的账单以上游为准。两者差异控制在 5% 以内就算正常。

问题三：某个 Key 突然大量 429。

429 是限流错误。先确认是网关自己的限流还是上游返回的。如果是网关限流，调高对应虚拟 Key 的 rpm_limit。如果是上游返回的，说明这个上游 Key 的配额用完了，需要加 Key 或者切到备用模型。

5.2 CLI Agent 的典型报错

5.3 几个我踩过的坑

坑一：网关的健康检查太激进。早期我配的健康检查是每 5 秒探一次上游，结果上游偶尔抖动一下就被标记为不健康，流量全切走了。后来改成连续 3 次失败才标记，恢复也要连续 3 次成功，稳定多了。

坑二：日志把 prompt 全文存下来了。这在小规模时无所谓，规模大了之后存储成本惊人，而且有隐私风险。正确做法是只存 token 数和元数据，prompt 内容按需采样或者脱敏后存储。

坑三：Agent 的循环没有硬性上限。有一次 Agent 陷入了一个"改代码 → 测试失败 → 再改 → 还是失败"的死循环，跑了 40 多轮才被预算限制拦住，烧了小 10 美元。后来我给所有 Agent 加了最大轮次限制，默认 15 轮，超了直接停并报告。

坑四：虚拟 Key 的权限给太宽。图省事给某个业务方开了所有模型的权限，结果他们误用了一个贵 20 倍的模型跑批量任务。现在我的原则是最小权限，用哪个开哪个。

6. 成本控制与容量规划

6.1 算清楚每一分钱花在哪

网关最大的价值之一就是让成本可见。我一般会按三个维度做成本报表：

按团队：每个虚拟 Key 绑定了团队信息，月底聚合就能出各团队的花费。这个数据直接用于内部结算。

按模型：不同模型的单价差异巨大，搞清楚哪些场景在用贵模型、能不能换成便宜模型，往往能省 30% 以上。

按调用类型：区分交互式调用（用户在等）和批处理调用（后台跑）。批处理完全可以用更便宜的模型，或者错峰到低峰期跑。

6.2 省钱的几个实操手段

语义缓存是最直接的。客服场景里，用户问的问题重复率极高，缓存命中率能到 40%。一次缓存命中省下的就是一次完整的模型调用费用。

Prompt 压缩也很有效。很多团队的 system prompt 写得又臭又长，塞了几千 token 的背景信息。实际上大部分信息可以精简，或者用 RAG 按需检索。把 system prompt 从 3000 token 压到 800 token，每次调用省 70% 的输入成本。

模型分级是长期策略。把任务按难度分级，简单任务用小模型，复杂任务才用大模型。网关的路由层可以根据请求的元数据自动分流，业务方甚至不用改代码。

6.3 容量规划的基本方法

网关本身的容量好算：它是 IO 密集型，单核能扛几百 QPS，瓶颈通常在数据库写入。日志异步写、批量写，能大幅提升吞吐。

真正难算的是上游配额。你需要知道：峰值时段的 RPM 是多少、平均每次请求多少 token、上游 Key 的配额是多少。三个数一除，就知道需要几个 Key。

我的经验值是留 50% 的余量。因为流量有突发性，而且上游偶尔会限流，余量不够时用户体验会明显下降。

7. 后续可以怎么扩展

网关跑起来之后，往上叠能力就很自然了。我见过做得比较深的团队，在网关层加了这些：

Prompt 模板管理。把常用 prompt 做成模板存在网关侧，业务方传参数就行。好处是 prompt 可以统一迭代，改一次全生效，不用每个业务方各自维护。

A/B 测试。同一个请求按比例分流到不同模型或不同 prompt，对比效果。网关天然适合做这个，因为所有流量都经过它。

内容安全过滤。在请求进和响应出两个方向做敏感内容检测，不合规的直接拦截。这个在企业场景里是刚需。

多模态统一入口。现在很多网关已经不只处理文本了，图片生成、语音识别、向量嵌入都能走同一个入口。协议统一之后，业务方的接入成本极低。

我个人在实际操作中的体会是：网关这东西，早上比晚上好，简单上比复杂上好。不要一上来就追求大而全，先把 Key 管起来、把日志记下来、把成本算清楚，这三件事做到位，价值就已经出来了。剩下的能力，等业务真的需要了再叠。