企业官网建设流程全解析

做AI应用开发这半年，让我最头疼的往往不是模型效果本身，而是接各家大模型API这件事。今天接厂商A的接口，SDK一套写法；明天换厂商B的服务，鉴权逻辑变了；再过一阵想比较几个模型的成本和效果，代码又得改一遍。后来在项目里引入了一个开源网关LiteLLM，情况才彻底好转：所有模型统一走一个入口，业务侧只管发请求，底层是哪个厂商、哪种协议，全部由网关处理。

这篇文章会从我的实际项目出发，讲清楚LiteLLM解决了什么问题、核心能力有哪些、怎么部署配置、生产环境压测和踩坑记录，以及用了一段时间后的调整建议。不管你是刚准备接大模型API的个人开发者，还是在团队里维护AI中台的人，这篇文章都能给你一份可以直接照抄的作业。

1. 模型API一多，代码就开始变味

与其直接讲LiteLLM怎么用，不如先讲清楚我是在什么场景下被逼得必须引入它。这决定了后面的所有配置思路。

1.1 从“单模型试用”进入“多模型并行”后的问题

我最初的项目只对接了一个模型服务，代码写好之后基本不用动。但后来需求变了：要对比多个模型的回答质量，要做成本控制，要支持不同业务线用不同模型，还要在某个模型报错时自动切换到备用模型。

麻烦就从这里开始。每个模型服务商的API风格几乎都不一样，有的用路径参数，有的把所有字段塞在请求体里；有的限流策略是每分钟多少次，有的按token计价并动态限流；返回结果里字段名不同，错误码含义也不同。SDK虽然封装了一层，但换一家厂商就要重装一套SDK，代码里到处是分支判断：

# 糟糕的写法：代码里写满了厂商判断 if provider == "provider_a": result = use_sdk_a(prompt) elif provider == "provider_b": result = use_sdk_b_with_extra_param(prompt) elif provider == "provider_c": result = call_c_api(prompt, version="v2")

这只是最简单的情况。等真正上线，你会发现还要处理密钥管理、失败重试、并发控制、成本记录。一个本来只想做“模型调用”的功能，最后变成了一个需要长期维护的中间层。

1.2 我自己写胶水代码的三个月教训

最开始我也没想上LiteLLM，觉得自己封装一个“统一调用层”就行。我写了统一的请求函数、统一的返回结构、统一的错误处理。头一个月挺顺利，第二个月开始出问题：

厂商A把SDK升级了，废弃了旧参数，我的封装层跟着改；厂商B偶尔返回5xx错误，我的重试逻辑在单测里没问题，但高并发下出现过请求风暴；更烦的是密分散落在多个环境变量和配置文件里，有同事不小心把密钥打到代码仓库，我半夜爬起来处理泄漏问题。

三个月后我算了一笔账：这个封装层大概写了2000多行代码，但真正跟“业务逻辑”有关的不到200行，其余全是在处理各家API的差异、鉴权、重试、限制。关键是它并没有把事情做好，只是把事情“变复杂了”。

1.3 网关方案带来的架构变化

后来我改用LiteLLM，架构变成了这样：

业务方不再关心上游是哪家服务，只认一个域名、一套密钥、一套请求格式。LiteLLM在中间做了协议转换、路由转发、负载均衡、密钥管理和日志记录。业务代码里只剩下：

response = completion( model="llm-liberty", messages=[{"role": "user", "content": "你好"}], api_base="http://llm-gateway.internal:4000", )

这时候业务侧对“上游是哪家模型”这件事完全无感。加一个新模型，不需要发版，只需要在LiteLLM的配置文件里加一段记录，然后重载配置。这个变化看着不大，但对团队效率影响很大。

2. LiteLLM核心能力拆解：一次调用背后的链路

LiteLLM不是简单的“请求转发器”，它在一次调用里做了好几层事情。拆开看，每一层都能对应到实际痛点。

2.1 统一格式层的设计逻辑

所有模型服务商的API差异，LiteLLM在“格式层”帮你抹平了。对外它提供一套统一的接口协议：统一的请求结构、统一的鉴权方式、统一的返回格式。对内的“翻译”逻辑，LiteLLM通过各个provider适配器实现。请求进来后，网关根据模型名找到对应的上游配置，把统一格式翻译成上游API需要的参数结构；拿到上游响应后，再把字段解析成统一返回格式。

这里有个容易被忽略的点：响应也要翻译。不同厂商返回的token统计字段、错误信息结构、usage信息位置都不一样。如果业务侧直接解析原始响应，一旦换厂商，前端展示token消耗的地方就可能出问题。用LiteLLM之后，这些字段被标准化了，业务侧只需要处理一种结构。

2.2 模型路由与负载均衡的工作方式

当同一个对外模型名对应了多个上游模型实例时，LiteLLM会做路由决策。支持的策略包括最简单的轮询、基于最少并发数的路由、基于加权权重的分配等。我实际用得最多的是“最少并发数优先”：配置里有多个上游实例，网关会把请求分给当前并发数最低的那个。

这个功能在应对上游限流时非常有用。比如某个厂商的模型在高峰期容易返回429或5xx，LiteLLM可以在连续失败N次之后把这个上游实例暂时摘除，冷却一段时间再放回来，同时对其他可用实例继续转发请求。我常用的一个配置思路是这样：

router_settings: routing_strategy: "least-busy" num_retries: 2 request_timeout: 60 allowed_fails: 2 cooldown_time: 30

含义是：优先选当前不忙的实例；请求失败最多自动重试2次；单次请求60秒超时；某个上游连续失败2次后就进入30秒冷却，不再分配新请求。这些参数看着简单，但实际踩坑后发现，allowed_fails和cooldown_time必须配合业务容忍度调，太小容易频繁摘除实例，太大又起不到熔断效果。

2.3 虚拟密钥与团队权限管理

这是我最喜欢的部分。LiteLLM支持在网关层生成“虚拟密钥”。团队里每个人、每个业务线都可以有自己的key，但这个key不是任何上游厂商的真实密钥，而是网关自己签发的。管理员可以给不同密钥设置不同的限流频率、总额度，甚至指定这个key只能访问哪些模型。

举个例子：A组在做客服问答，只允许用低成本模型，每月预算设死；B组在做复杂推理实验，允许访问高性能模型，限制并发数。原来这种需求要在各自代码里写逻辑，现在全部沉淀在网关配置里。密钥随时可以作废，不用去上游厂商重新生成。

这对安全也有帮助。上游厂商的真实密钥只存在网关环境变量里，研发环境、测试环境拿到的都是虚拟key。某个key泄漏了，直接废弃重建即可，不会影响真实密钥。

2.4 可观测性：日志、指标与审计

做AI应用最容易被忽视的就是观测。调用大模型API不是免费的，出了问题没有日志简直无从排查。LiteLLM默认记录每一次请求的：调用模型、消耗token数量、耗时、请求来源、成功或失败原因。

我把这些日志接到监控系统之后，能很直观地看到：哪个模型的P95延迟在升高、哪个业务线的token消耗异常增长、哪段时间失败率突增。月底对成本时也方便，直接按业务线维度聚合token消耗，不用再去各家厂商后台导数据。

3. 从零部署：配置、验证、接入

下面这部分讲实际操作。我假设你已经有一个Linux服务器或者容器环境，Python版本在3.9以上。

3.1 安装LiteLLM并准备上游密钥

安装很简单：

pip install 'litellm[proxy]'

安装完之后，把上游各家模型服务的真实密钥放到环境变量里。我习惯放在一个独立的.env文件里：

FACTORY_A_KEY=sk-real-key-here FACTORY_B_KEY=sk-another-key-here

注意不要把这个文件提交到git仓库。即使是在团队内部，密钥也应该走密钥管理系统分发，而不是放在代码仓库里靠.gitignore兜底。

3.2 配置文件config.yaml的写法

LiteLLM的核心是config.yaml。我理解的配置逻辑分两层：一层是“对外模型名”，也就是业务方请求时用的名字；另一层是“真实上游模型”，也就是对应哪个厂商的哪个模型。中间通过model_list关联起来：

model_list: - model_name: "llm-liberty" litellm_params: model: "factory-a/text-sonic" api_key: os.environ["FACTORY_A_KEY"] api_base: "https://api.factory-a.example.com/v1" - model_name: "llm-liberty" litellm_params: model: "factory-b/llm-pioneer" api_key: os.environ["FACTORY_B_KEY"] api_base: "https://api.factory-b.example.com/v2"

这里两个上游都映射到同一个对外名llm-liberty，于是网关会认为这个模型有两个可用实例，自动做负载均衡和故障转移。这个设计很有意思：业务方完全不知道哪个实例在处理请求。

对于单个上游服务商，还可以设置权重。比如低成本实例权重高一点，高性能实例权重低一点，让大部分流量走便宜方案，少量走高质量方案。权重字段不同版本写法略有差异，但思路都是为每个条目加一个routing_params或者权重配置，建议以版本文档为准。

3.3 启动服务并验证调用

用下面的命令启动：

litellm --config ./config.yaml --port 4000

启动日志里会打印出当前加载的模型列表。确认无误后，用curl测试：

curl http://localhost:4000/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-your-virtual-key" \ -d '{"model":"llm-liberty","messages":[{"role":"user","content":"你好"}]}'

如果配置正确，你会收到正常的结构化响应。这里有个细节：整个请求里并没有告诉网关“你要走厂商A还是厂商B”，网关靠着内部路由逻辑自己做的决定。

3.4 SDK接入方式

对于Python项目，LiteLLM本身提供了Python SDK，可以直接用completion方法，把网关地址传进去：

from litellm import completion response = completion( model="llm-liberty", messages=[{"role": "user", "content": "介绍一下你自己"}], api_base="http://localhost:4000", ) print(response.choices[0].message.content)

因为LiteLLM对外提供的是兼容主流格式的接口，所以Node.js、Java等语言也能直接通过HTTP请求调用。团队里不同语言、不同业务线，最终都收敛到同一个网关入口。

3.5 生产环境建议用容器部署

开发环境直接跑进程没问题，但生产环境我建议打包成容器服务。原因很简单：进程崩溃后可以自动重启，滚动更新时新老实例无缝切换。容器内配置一个健康检查指向网关的健康检查端点，配合编排系统的启动探针和就绪探针，能避免流量打到还没准备好的实例上。

我踩过的一个小坑是：健康检查路径写错了，导致探针一直失败，网关实例被反复重启，而我还以为是自己配置有问题。排查了半天才发现是探针路径的问题。这个问题在本文第4章会进一步展开。

4. 生产环境压测与真实踩坑记录

配置写完、接口能通，这只是万里长征第一步。真正上线前我做了压测，上线后又踩了几个坑，记录在这里。

4.1 我做的压测思路和结果

我选择了一个典型场景：模拟用户问答，平均请求体约800个token。压测工具用简单的并发脚本，分别以20、80、150并发跑1000个请求，统计成功率、P95延迟和错误类型。

结果大致如下：

这里要说明：具体数字跟上游模型本身的速度、你的网络环境、服务器配置都有关系，不能直接套用。但趋势值得关注：并发一高，瓶颈主要在上游，而不是LiteLLM本身。网关只是中间搬运工，上游慢，响应就慢。

4.2 坑一：网关超时设置比上游更早触发

第一次压测时，网关的request_timeout设成了30秒。按理说这个值不短了，但上游在高峰期处理一个长任务可能超过45秒。结果就是：上游其实还在正常处理，网关已经等不及返回超时错误了，业务侧看到的就是“请求失败”。

这个问题的本质是：超时一定要分层设置。业务侧的超时 > 网关超时 > 上游超时，否则总有某一层提前掐断请求。我最后把网关超时改成比上游超时再多20秒，才解决误报超时的问题。

4.3 坑二：模型名映射不统一，统计数据全乱了

LiteLLM支持在配置里做模型别名映射，但团队里一旦有人不走网关，直接拿上游密钥调原始API，统计就不完整了。还有人在请求时用了上游真实模型名而不是配置里的对外名，网关找不到路由，返回404，排错时又对不上号。

后来我做了两条硬性规定：第一，所有请求必须走网关地址；第二，代码里只能出现配置文件中定义的对外模型名。谁要是直接写了上游模型名进代码，CR阶段就会被打回。别嫌这个规定死板，等你看月度成本报表时，按统一模型名聚合的清晰度，能让你少很多麻烦。

4.4 坑三：上游限流是动态变化的，不能只看文档

每家厂商都会在文档里写“限量值”，但实际限流策略往往包含动态因素：同一个密钥下并发数限制、每分钟请求数限制、每段时间token总量限制，而且这些限制可能随服务端负载动态变化。

我踩过的场景是：单看每个指标都没超，但多个维度叠加之后触发了限流，上游返回429。网关重试几次还是429，然后错误率飙升。解决办法除了配置合理的num_retries，还要给不同的上游设置独立的退避策略。比如第一次失败等0.5秒重试，第二次等1秒，第三次等2秒。这个退避递增机制很重要，很多“重试”导致的雪崩，就是因为所有客户端在失败后同时立即重试。

4.5 坑四：访问日志太多，日志系统直接被冲垮

LiteLLM默认日志很详细，这在调试时是好事，在高流量下就是灾难。我遇到过一次：接入网关后流量涨了十倍，日志系统先扛不住了，磁盘被打满，日志收集端开始丢数据。

后来我在日志层面做了采样和分级处理：普通访问日志只记录关键字段，错误日志完整保留，某些高频健康检查请求不记录。观测系统要的是“能定位问题”而非“把所有信息都存下来”。这个度要自己把握。

5. 用了一段时间之后的体会和调整

服务稳定运行两三个月之后，有些长期价值才慢慢显现，也产生了一些新的使用方向。这章聊点我对架构和团队工作流的看法。

5.1 接入新模型变成一次纯配置变更

最明显的变化是团队节奏变了。以前要接一个新模型，流程是：商务开通权限、前端同学联调SDK、后端改代码、测试验证、发版上线。整套流程跑下来至少一两天。

现在改成：模型服务商开通密钥后，运维在config.yaml里加一段，reload配置，业务侧甚至不用改任何代码，新模型就已经通过原有对外名生效了。如果只想“小流量试一个模型”，直接在路由权重里调低比例即可。这个效率提升是巨大的。

5.2 哪些高级功能我暂时没启用

LiteLLM还有不少高级功能，比如多租户计费、复杂的缓存策略、基于请求内容的路由等。我评估之后选择了暂时不启用。

多租户计费适合做外部产品或者多部门结算，我们内部规模还没到，虚拟密钥已经能满足需求。缓存策略会带来成本收益，但也可能造成响应内容过期，尤其在我做的是对话交互场景时，宁可牺牲一点性能也不希望返回陈旧答案。我的建议是：不要一开始追求功能全面，遇到了明确需求再开，否则配置复杂度反而造成负担。

5.3 把所有路由逻辑收敛到网关层之前，先想清楚这几点

第一，网关一定要保持“薄”。它的职责是路由、转发、鉴权、日志，不要把业务规则塞进去。我在代码审查时反复强调：网关层的配置里不要出现只有业务团队才懂的字段。

第二，密钥轮换流程要提前设计。虚拟密钥可以随时作废，但真实密钥轮换时，网关会短暂不可用，要在低峰期操作并提前通知各业务方。

第三，监控看板比YAML配置更重要。没有看板之前，我根本不知道某个模型的成本占比是多少，也不知道夜间某个模型延迟增长。接入LiteLLM之后，无论看板还是告警，都尽量做到按模型和业务线两个维度切分。

现在我处理新模型接入的顺序基本固定了：先在压测环境用低配虚拟密钥跑通调用，确认延迟和错误率；再放到生产网关的小流量权重上观察半天；最后逐步放大权重并关注看板上的成本曲线。整个过程不再需要写一行业务代码，这大概就是网关层带来的最大价值。