企业官网建设流程全解析

做 AI 应用最烦的不是写提示词，而是接 API。场景稍微一多，你手上就可能同时对着三四个模型平台：有的接口参数风格完全不一样，有的限流阈值说改就改，有的重试逻辑要靠自己手写重试。我这两年搭过好几个类似的系统，最后基本都围着litellm转。它不是什么花哨的炫技项目，就是一层“包在模型平台前面”的网关层，把各家模型 API 收归到同一套格式下面。无论你是只想在脚本里快速调几个模型看效果，还是要给团队搭一套带密钥管理、限额、负载均衡的模型网关，它都能顶上去。这篇内容偏实操，我会从项目原理讲起，把安装、SDK 调用、网关部署、预算控制、缓存配置、以及我踩过的坑一次说完。

1. 项目概览：litellm 到底是干嘛的

1.1 从一次“接口崩溃”说起

先讲个场景。早先我在做某个业务系统的时候，需要同时接三路模型能力：一路做内容总结，一路做意图识别，还有一路做向量化之外的文本后处理。一开始很顺利，每路模型各自调各自的 SDK，代码写得很爽。但上线之后问题开始冒头：某一路模型动不动限流，SDK 内部的重试参数藏得特别深；另一路模型升级了接口版本，原先的请求体字段直接被废弃，导致线上服务必须发版才能修。那次之后我意识到，直接把业务代码和各模型平台的 API 绑死，后期一定被拖死。

后来我把所有模型调用全部改到litellm这层统一封装上，业务侧只需要认识一种请求格式。各家模型在litellm里被映射成统一的model: provider/model_name样式，我切换模型时不用再动业务代码，只要改配置或改参数。这个“多一层”的设计，看起来是绕远路，实际是给后续扩展留了命。

1.2 核心痛点：API 差异与配置分散

为什么这类工具会被反复需要？核心原因是模型平台之间的差异太大，不只是请求格式不同，还有几个维度：

• 请求体格式：消息结构、角色字段、参数命名各不相同，有的要求messages数组，有的要求prompt字符串。
• 鉴权方式：有的用请求头带密钥，有的需要签名参数，有的还要在特定域名下才能访问。
• 流式输出：有的支持标准 SSE 流，有的流式格式里事件命名不一样。
• 错误语义：限流、超时、无效请求的返回体千奇百怪，统一解析很难。
• 模型部署形态：有云端托管，有自建私有化，有网关转发，地址和密钥管理方式完全不同。

litellm解决的就是这一整摊事。它把“模型平台适配层”集中到一个地方维护，让使用方始终面向同一套 API 规范。业务系统的代码不用再关心模型部署在哪里、是不是换了供应商，甚至同一个请求可以自动在不同模型间切换。

1.3 核心能力一览

我用一张表列出它在实际项目中用得最多的能力：

单看列表可能觉得平平无奇，但把这么多能力集中在一个开源项目里，并且通过同一套配置描述模型资源，这在实际工程里的收益非常大。后面我会逐个讲怎么用。

2. 核心原理：为什么“包一层”就够用

2.1 SDK 模式与代理网关模式的双轨设计

litellm有两条完全不同的使用路径，很多人一开始没分清：一条是直接当 Python 库用，另一条是启动一个后台代理服务。

SDK 模式下，你在自己进程里直接调litellm.completion()或litellm.acompletion()，它内部根据model参数里的提供商前缀，把请求转换成对应平台的格式再发给远端模型。这种模式的优点是集成非常轻，适合脚本、微服务、内部小工具。缺点是它的转换发生在你的应用进程里，如果多个业务都要用，就得每个业务都部署一份配置。

代理网关模式下，litellm是个独立服务，所有业务请求先打到这个网关，由网关负责协议转换、密钥管理、负载均衡、预算控制。业务侧只需要配置一个类似http://your-gateway/chat/completions的地址，把网关当统一的模型平台使用。这种模式的工程价值更高，也是我在团队场景里推荐的方式。

理解双轨设计很关键。很多人把它当成普通的“SDK 封装库”，忽略了它其实是个可独立部署的中间件。实际选型时，单机脚本用 SDK 模式方便；多人协作、多服务共享模型资源，代理网关模式几乎是必须的。

2.2 统一请求格式的设计逻辑

litellm对外统一采用当前业界事实标准的chat/completions风格请求体，大体结构如下：

{ "model": "provider_name/model_name", "messages": [ {"role": "system", "content": "你是一位助手"}, {"role": "user", "content": "帮我总结这段文字"} ], "temperature": 0.7, "max_tokens": 512 }

它为什么能统一各家？因为这种请求结构足够通用：messages数组承载多轮对话，role区分系统、用户、助手身份，temperature控制随机性，max_tokens控制长度上限。绝大多数模型都具备类似语义的能力，只是字段名和包装方式不同。litellm内部做的事情就是“把标准输入翻译成各家方言”，再把各家的返回体翻译成统一结构。

这种设计让业务层完全感知不到模型差异。我遇到过的情况是，某个模型返回内容里带了一段评审意见文本，格式和另一个模型的差异很大，但通过统一结构处理后，业务侧拿到的始终是choices[0].message.content这种固定路径，后处理逻辑就特别好写。

2.3 参数透传与转换细节

需要留意的是，并非所有参数都能在不同模型间直接等价转换。temperature、max_tokens、top_p这些通用参数一般没问题，但长上下文模型里的上下文窗口、以及一些模型特有的采样参数，就需要具体匹配。

litellm的策略是尽量兼容：能转换的自动转换，不能转换的透传，实在不支持的模型会自动忽略或报错。比如某模型的 max tokens 命名是max_tokens_to_sample，litellm内部会把它映射过去。这个过程中最需要注意的是“你以为你在设置 A 模型的参数，实际模型 B 可能对参数语义解释得不同”。比如有的开源模型把temperature和top_p的关系处理得很敏感，直接用默认值反而更稳。

所以我的一个习惯是，模型切换后不要只跑一条“能通”的用例，还要对采样效果做一次回归。这不是litellm的限制，而是模型风格差异本身导致的。

3. 上手实操：Python 直连调用

3.1 安装与环境准备

先安装依赖：

pip install litellm

它依赖比较少，基本就是 Python 3.8 以上就能跑，安装后不需要额外初始化数据库或配置文件，非常适合快速体验。

然后准备模型平台密钥。在 SDK 模式下，最直接的方式是设置环境变量：

export MY_PROVIDER_API_KEY="你的密钥"

这里的MY_PROVIDER_API_KEY是我写的代称。实际项目里，litellm支持几十种模型平台，每个平台的环境变量命名都有对应约定，一般在项目文档里能查到。你也可以在代码里直接传api_key参数，但生产环境还是建议用环境变量或后面要讲的密钥管理服务。

3.2 第一个调用：调通一个文本生成模型

先看最基础的非流式调用：

import litellm response = litellm.completion( model="your_provider/your_model", messages=[ {"role": "system", "content": "你是一个简洁的助手，回答不超过50字。"}, {"role": "user", "content": "介绍一下什么是模型网关。"} ], temperature=0.3, ) print(response.choices[0].message.content)

第一次跑通这个示例，基本就能理解它和直接调 SDK 的差别：除了model前缀不同，你的调用方式和单一平台 SDK 几乎一样。litellm会根据model字符串里的前缀定位到对应平台，再调用底层适配逻辑。

这里有个很实用的细节：litellm内置了模型名称提示。如果你把your_provider/your_model写成了不存在的模型标识，它会报ModelNotRegisteredError或者给出可用模型前缀的提示。第一次使用某个平台时，建议先打印一下它支持的模型列表。

3.3 多轮对话与消息扩展

多轮对话就是往messages里继续追加：

messages = [ {"role": "system", "content": "你是一名数据分析师。"}, {"role": "user", "content": "我有一段销售数据要处理。"}, {"role": "assistant", "content": "好的，请提供数据说明。"}, {"role": "user", "content": "帮我生成一个分析思路。"} ] response = litellm.completion( model="your_provider/your_model", messages=messages, )

大部分模型平台的消息格式即使不完全一样，litellm也会做转换。但有一个用户常踩的坑：某些开源模型对assistant消息有额外要求，例如要求消息文本为字符串，或者要求消息前必须有一段用户消息。遇到这种问题，建议先查看原始模型平台的文档，确认是不是格式限制导致的，再决定是否需要调整消息构造逻辑。

3.4 流式输出的实现方式

流式输出在很多场景下是刚需，比如问答产品里需要打字机效果。用法如下：

response = litellm.completion( model="your_provider/your_model", messages=[{"role": "user", "content": "写一个300字的故事"}], stream=True ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)

流式返回的每个chunk结构和非流式很接近，区别是内容放在delta里。如果你同时对接多个不同模型，大概率会遇到流式事件格式不一致的问题，litellm会把这些差异抹平，但你仍然需要在业务层处理首包延迟、中断恢复等问题。

异步场景则使用：

import asyncio import litellm async def main(): response = await litellm.acompletion( model="your_provider/your_model", messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content) asyncio.run(main())

异步接口和同步接口的参数完全一致，这在并发调用时特别重要，不用为异步单独写一套适配代码。

4. 进阶部署：本地网关做业务隔离

4.1 用一条命令启动服务

SDK 模式适合跑在单个进程里，一旦业务变多，我还是建议把litellm网关独立部署出去。它的启动方式非常简单：

litellm --model your_provider/your_model --port 4000

启动后，本地会暴露一个兼容统一接口的服务，监听在 4000 端口。你可以直接用标准客户端去请求：

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

这种用法最大的好处是业务服务和模型平台解耦。业务侧只认localhost:4000这个地址，无论后面模型换成哪家的、配置怎么变，业务服务都不需要重新发版。

4.2 通过配置文件管理多个模型

生产环境不建议把模型都写在启动命令里，我更推荐用config.yaml来管理：

model_list: - model_name: chat-main litellm_params: model: provider_name/model_name_1 api_key: os.environ/MY_PROVIDER_KEY_1 - model_name: chat-backup litellm_params: model: provider_name/model_name_2 api_key: os.environ/MY_PROVIDER_KEY_2 - model_name: embed-service litellm_params: model: provider_name/embedding_model

然后启动：

litellm --config config.yaml --port 4000

这里有几个设计点值得注意：

• model_name是网关对外开放的模型别名，业务侧只认这个名字。
• litellm_params.model是真实平台模型标识，真正的协议转换在这里发生。
• api_key可以通过os.environ引用，避免把密钥写在配置文件里。
• 一个别名可以对应多个真实模型，网关自动做负载均衡。

这种“别名 + 真实模型”的映射方式，是litellm作为网关最好用的特性之一。我经常做的一件事就是在配置里把某个内部服务的模型从“厂商A的模型”直接切成“自建模型”，只需要改一行配置。

4.3 虚拟密钥与调用方隔离

如果多个团队共用一个网关，密钥管理就得讲点规矩。litellm网关支持虚拟密钥，也就是调用方持有的密钥和真实模型平台密钥是两回事。

第一次启动网关时，需要设置主密钥：

export LITELLM_MASTER_KEY="sk-gateway-master-key" litellm --config config.yaml --port 4000

随后你可以用主密钥去创建一个虚拟密钥：

curl http://localhost:4000/key/generate \ -H "Authorization: Bearer sk-gateway-master-key" \ -H "Content-Type: application/json" \ -d '{"models": ["chat-main"], "max_budget": 10}'

返回的虚拟密钥就是给调用方用的。这样做有几个实际收益：你可以随时吊销某个虚拟密钥而不影响真实平台密钥；可以给每个团队设置独立预算；可以按密钥维度审计调用量和消耗金额。即便你的团队只有两三个人，我也建议用虚拟密钥，因为人一旦变多，“这个 token 到底是谁在跑”就成了真问题。

5. 生产级特性：重试、预算、限流与缓存

5.1 自动重试与负载均衡

线上模型调用最大的敌人是限流。litellm在网关模式下对限流有一套比较成熟的应对策略：自动重试 + 多模型轮询。

比如配置里同一个逻辑别名挂了三路模型：

model_list: - model_name: chat-service litellm_params: model: provider_a/model_large api_key: os.environ/PROVIDER_A_KEY - model_name: chat-service litellm_params: model: provider_b/model_large api_key: os.environ/PROVIDER_B_KEY

当provider_a限流时，网关会自动把请求转到provider_b，整个过程对业务层透明。这种多副本设计，在某个模型离线或故障时简直就是救命稻草。不过要做好随机性的心理预期：不同模型能力风格不同，故障转移后的输出质量不完全一致。如果业务对这个差异敏感，建议把故障转移模型限制在同规格模型上。

5.2 预算控制与限流配置

预算控制是我觉得最值钱但最容易被忽略的功能。模型 API 是按 token 计费的，一旦没有控制，一次线上 bug 或者恶意刷接口都能造成不小的成本损失。

配置方式既可以在虚拟密钥上设置，也可以在配置里设置全局策略：

general_settings: max_budget: 100 budget_duration: 1mo rps_limit: 10 rpm_limit: 100 max_tokens_per_minute: 50000

字段含义分别是：月度总预算、每秒请求数上限、每分钟请求数上限、每分钟 token 消耗上限。这些限制同一时间生效，哪个先到就拦哪个。

我做过的实际处理是：给同一个网关下的不同业务线设置差异明显的 RPS 限制。某条低优先级业务给它每秒 2 个请求，另一条核心业务每秒 20 个。这样即使低优先级业务突发流量，也不会把核心业务的调用额度打满。

5.3 缓存：高频重复请求的降本神器

在很多企业内部工具里，用户经常问相似的问题。litellm提供了缓存层，可以大大降低重复请求的成本和延迟。

最简单的用法是在配置里开启缓存：

litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379

也可以直接用环境变量开启：

export LITELLM_CACHE_TYPE=redis

开启后，相同参数的请求会被直接命中缓存。litellm缓存分完全匹配和语义搜索两种。完全匹配是相同请求直接返回；语义搜索是计算 embedding 后找相似问题，适合“不同问法但同答案”的场景，不过需要额外配置向量存储。

这个功能很有价值，但我建议先保守使用：只在确定业务允许“重复问题返回同一结果”的场景开启。对于那些需要实时性的业务，缓存可能带来副作用。我的经验是，先看日志里的请求重复率，如果重复率高，再开缓存，效果最明显。

6. 踩坑实录：常见问题快速排查

6.1 常见问题速查表

到目前我已经在实际环境里用过很久的litellm，这里整理了一些反复出现的问题和对应解法：

6.2 定位这类问题的通用方法

遇到litellm配置问题，我一般不直接翻源码，而是按三步走：

第一步，确认问题发生在哪一层。先用 SDK 模式直接调模型看能否连通；如果 SDK 模式没问题，说明问题出在网关配置或权限层；如果 SDK 模式就报错，说明写入的模型标识、密钥或网络本身有问题。

第二步，看网关日志。日志里会输出详细请求链路，比如请求转到了哪个平台、走了哪个虚拟密钥、耗时多久、token 消耗多少。做负载均衡时，日志还能告诉我们请求具体分配到了哪一路模型。

第三步，最小化复现。把场景简化成一个已知可用的模型，再逐项把参数加回去。比如先把stream=True去掉，把tools去掉，把cache关掉，一项一项排除。这个方法虽然笨，但比靠猜要快得多。

6.3 我对这套方案的一些实操心得

最后讲几条我自己的使用体会，不算普适真理，但大概率能帮你少走弯路。

第一个心得是：不要让业务服务同时混用 SDK 模式和代理网关模式。团队里一旦有些人直接对着模型平台调用，有些人走网关，成本审计和密钥管理就会失控。统一入口是第一步。

第二个心得是：配置文件的命名规则要定早。我后来维护过一个大网关，里面模型列表越加越多，每个别名对应什么真实模型、属于哪个业务线、预算上限多少，如果没有清晰命名，三个月后连自己都看不懂。建议从一开始就给model_name加上业务标签，比如chat-order-flow、embedding-search，而不是model-a这种。

第三个心得是：别把litellm当万能转换器。它的适配层做得再厚，也顶不住某些模型平台极其特殊的输出结构。遇到某类模型非标准返回时，优先看官方适配列表，确认该模型是否完整支持功能，比如工具调用、JSON 模式。有的模型宣称支持工具调用，但实际返回质量很差，这不一定是litellm的错，而是模型本身的问题。

第四个心得是关于成本治理的：开启虚拟密钥以后，最好把密钥生成接口接入到内部申请系统，让每次创建密钥都带上审批记录、业务负责人、预算额度。模型网关不是装完就完事的东西，它本质上是一个团队共用的基础设施，运维起来需要投入，但投入产出比在业务模型越用越多的阶段会越来越高。

如果你也要做类似的多模型统一接入，我建议先用 SDK 模式把链路跑通，再逐步迁移到代理网关模式。链路通了以后，加模型、加权限、加预算，都只是往配置里加几行的事。这就是litellm最实在的价值：把“接各家模型”这件事从反复造轮子，变成一套可以持续沉淀的工程能力。