企业官网建设流程全解析

去年我给一个内部知识库工具接 AI 能力时，最折磨我的不是模型效果，而是模型厂商 SDK 之间的差异。项目里同时用到几家主流模型的 API，每个模型一套 SDK，参数风格、流式输出方式、错误码结构全都对不上。改一处调用逻辑就要连带改好几个文件，后来我把 LiteLLM 塞进了项目，用一个 OpenAI 兼容接口统一了所有模型调用，整个代码库才彻底干净下来。

LiteLLM 说到底就干一件事：把不同厂商的大模型 API 包装成同一种格式。你只需要学会一种调用方式，就能对接市面上绝大多数模型服务，还能顺手拿到重试、限速、预算管理这类企业级能力。这篇文章我想从实际使用角度，把我踩过的坑、验证过的用法、以及"什么场景真的该用它"讲清楚，适合正在做多模型接入、想降低长期维护成本的技术小伙伴参考。

1. 大模型调用碎片化：为什么一个项目里会出现三套SDK

1.1 不同厂商SDK的差异到底有多大

很多人觉得"调用大模型不就是 POST 一个 HTTP 请求嘛，能差到哪去"，真做过的人就知道这话有多天真。拿最常见的几个差异点来说：有的厂商用functions参数声明函数调用，有的改成了tools；流式输出时，一个返回delta.content，另一个返回choices[0].delta.text；错误处理更离谱，一个超时抛TimeoutError，另一个直接返回 200 但 body 里写着错误信息。

我当时的项目是给客服系统做智能摘要，需要同时接入两家闭源模型和一家开源模型的 API。最初我的想法很朴素：写一个model_client.py，把三家 SDK 封装一下，谁需要谁调。结果封装类越写越臃肿，今天 A 模型升级了接口，明天 B 模型改了参数名，后天 C 模型报错格式变了，我每天都在跟厂商 changelog 搏斗。

1.2 LiteLLM 的统一思路：一个客户端，一个响应结构

LiteLLM 的思路跟我那个越写越乱的封装类完全不同。它不是让你适配每一个厂商，而是把所有厂商的请求参数转换成各自需要的格式，再把所有响应统一成 OpenAI 的响应结构。你写业务代码时永远只面对一套对象：response.choices[0].message.content，至于底层是哪个厂商、走什么协议，LiteLLM 全替你处理了。

这里有个很重要的设计取舍：LiteLLM 选择了 OpenAI 格式作为"通用语言"。原因很简单，OpenAI 的接口生态最成熟，社区工具链最全，绝大多数开发者都熟悉这套用法。用一套大家都懂的规范做统一层，学习成本最低。你如果熟悉 OpenAI SDK，那基本就熟悉了 LiteLLM 的用法。

1.3 调用时加前缀就能切换模型

LiteLLM 在调用时用厂商名/模型名这种前缀方式指定目标，比如openai/gpt-4o、anthropic/claude-3-5-sonnet、together_ai/meta-llama/Llama-3-70b-hf。同一个messages列表，复制粘贴改个字符串就能切换模型。

这带来的最大好处是：业务逻辑彻底和模型厂商解耦了。测试阶段用便宜的开源模型跑通流程，上线前换成效果更好的商用模型，只改一个字符串，不用改代码逻辑。我在某次演示项目里就是这么干的——先用开源模型把功能跑完整，客户确认效果后再切到商用模型，整个过程我只动了model参数。

2. 用LiteLLM统一调用：安装、环境变量与最小的可运行链路

2.1 安装与全局环境变量配置

LiteLLM 是纯 Python 包，安装很简单：

pip install litellm

如果你要用代理服务器模式和数据库功能，还需要额外装一些依赖，但只做统一调用的话，这个包就够了。安装完后，建议把 API Key 统一放环境变量里，LiteLLM 会自动读取对应前缀的变量名：

export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." export TOGETHERAI_API_KEY="tgp-..."

这里有个容易忽略的点：LiteLLM 读取环境变量的规则是"厂商前缀 + API_KEY"。比如调用anthropic/claude-3-5-sonnet时，它默认找ANTHROPIC_API_KEY，找OPENAI_API_KEY是链不到的。如果你某个厂商的 key 变量名比较特殊，可以在调用时显式传api_key参数覆盖。

2.2 三种主流模型的统一调用代码

先看最基础的调用写法：

from litellm import completion messages = [ {"role": "system", "content": "你是一个简洁的助手"}, {"role": "user", "content": "用一句话解释什么是缓存"}, ] # 调用 OpenAI 模型 response = completion( model="openai/gpt-4o", messages=messages, temperature=0.7 ) print(response.choices[0].message.content) # 换 Anthropic 模型，仅改 model 字符串 response = completion( model="anthropic/claude-3-5-sonnet", messages=messages, temperature=0.7 ) print(response.choices[0].message.content)

实测下来，这套代码在两个模型之间切换，除了 model 参数字符串不同，其他代码完全不用动。响应对象都是 OpenAI 结构，response.choices[0].message.content直接拿文本，response.usage拿 token 统计，连response.model字段都会自动填上实际调用的模型名。

2.3 流式输出和函数调用也能统一

非流式调用只是第一步，真实项目里流式输出基本是刚需。LiteLLM 对流式的处理同样统一：

response = completion( model="anthropic/claude-3-5-sonnet", messages=messages, stream=True ) for chunk in response: # 同样是 OpenAI 风格的 delta delta = chunk.choices[0].delta if delta.content: print(delta.content, end="")

这里你可能会问：Anthropic 的流式格式和 OpenAI 明明不一样，LiteLLM 怎么统一的？答案是它把底层差异全部消化在包内部了。你看到的chunk.choices[0].delta是经过转换后的统一结构，不用关心底层是content_block_delta还是choices。

函数调用也是同类逻辑。OpenAI 传tools，Anthropic 传tools但内部结构有差异，LiteLLM 做了一层映射，你只管写一套函数调用代码，切换厂商后行为保持一致。

3. 代理服务器模式：从个人脚本变成团队的模型网关

3.1 什么是代理模式，它解决了什么问题

单机脚本用completion函数很舒服，但团队协作时问题来了：每个人的电脑上都要配环境变量，key 散落在各台机器上，换成新同事还要手把手教他配置。更麻烦的是，你没法统一管控——谁调了多少 token、哪个接口在报错、需不需要限流，完全没有抓手。

LiteLLM 的代理模式解决的就是这个问题。你在一台服务器上启动一个代理服务，所有团队成员把请求发到这个代理地址，代理统一处理鉴权、转发、重试、限流、日志。团队成员不需要任何厂商 key，只需要知道代理地址和一个团队共享的 key。

启动代理：

litellm --config config.yaml --port 4000

然后写一个config.yaml，定义允许哪些模型进入代理：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY

注意model_name是外部暴露的名字，litellm_params.model是真正转发时使用的模型标识。你可以随便给模型起别名，比如把团队常用的模型统一叫main-model，背后指向不同厂商，业务方完全无感知。

3.2 预算、限速和负载均衡的配置思路

代理模式真正的价值在于管控。你可以在配置里给每个模型加上速限：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 60 # 每分钟最多 60 个请求 tpm: 100000 # 每分钟最多 10 万 token

同一个模型也可以定义多个供应商来源做负载分担：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o litellm_params: model: azure/openai/gpt-4o api_base: https://your-resource.openai.azure.com/ api_key: os.environ/AZURE_API_KEY

当代理收到model=gpt-4o的请求时，会自动在两个 provider 之间做负载均衡。这个能力在对接多个独立供应商时非常实用——哪家服务不稳定，流量自动往另一家走，业务代码完全不用改。

3.3 对接现有 OpenAI SDK：只需改一行 base_url

代理模式最爽的地方在于：客户端不用装 LiteLLM，直接用官方 OpenAI SDK 就能对接。原因前面说过，LiteLLM 输出的是 OpenAI 兼容格式，所以任何支持 OpenAI 协议的工具都能无缝接进来。

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000", # 指向 LiteLLM 代理 api_key="sk-any-key" # 代理会校验这个 key ) response = client.chat.completions.create( model="claude-3-5-sonnet", # 代理配置里暴露的模型名 messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content)

我在某团队合作项目里就是这么干的：前端有个语言工具已经在用 OpenAI SDK，切换到 LiteLLM 代理只改了一行base_url，其他代码原封不动。团队的新人上手成本几乎为零，因为他们学的还是 OpenAI 那套 API。

3.4 重试与观测同样集中在代理层

代理模式另外一个好处是：重试策略可以在代理层面统一设置，而不是在每个客户端代码里各写各的。

router_settings: routing_strategy: simple-shuffle num_retries: 2 request_timeout: 30

这样客户端那边可以完全关掉自己的重试逻辑，把可靠性交给代理层。日志和监控也是同理，所有请求都经过代理，天然留痕，/health端点检查存活状态，/spend/logs查看调用记录，排查问题再也不用挨台机器看日志了。

4. 踩坑实录：环境变量串线、幽灵超时与对不上的token账单

4.1 环境变量优先级导致的模型串线问题

有一段时间我同时跑两个项目，一个接 OpenAI 模型，一个接另一个厂商的模型。为了省事，两个进程都用了同一个 shell 环境变量，结果其中一个项目频繁报错，明明配置写得没问题，请求却总是跑到另一家厂商那边。

排查了很久才发现根因：LiteLLM 在某些版本里对api_base的处理优先级不直观。当你在环境变量里设置了OPENAI_API_BASE，又在一个项目里显式传了api_base时，某些旧版本会优先读环境变量，导致你的请求被转发到错误的地址。

提示：如果你同时用多个模型，强烈建议在litellm_params里显式写出该模型的api_base和api_key，不要完全依赖环境变量。环境变量对于快速 Demo 很方便，但对于长期运行的团队服务，显式配置才是最稳的。

4.2 批量长文本请求的幽灵超时

某次我跑批量摘要任务，两千多条数据依次发到代理，跑到一半总有几条报超时。单看每一条请求，数据量并不大，响应速度也正常，但批量跑的时候就是会出现偶发性超时。

问题出在客户端默认超时设置上。官方 OpenAI SDK 的默认超时比较宽松，但我当时图省事用的是某个封装好的 HTTP 客户端，它内置了一个很短的连接超时。请求经过代理转发到上游，再排队等模型返回，整条链路时间比直连更长，短超时就扛不住了。

解决方法是显式调大客户端超时时间，同时关闭客户端侧的重试，把重试统一交给代理层：

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000", api_key="sk-any-key", timeout=120.0, max_retries=0 )

这里有个重要逻辑：客户端重试和代理重试如果同时开启，会把问题放大。代理重试了一次，客户端又重复了一次，同一个请求可能被送到上游两次，轻则浪费 token，重则造成数据重复写入。

4.3 token 统计对不上账：usage 字段有时是空的

接入代理后另一个让我头疼的问题是对账。月度成本分析会上，我导出的 token 使用量总和，怎么都对不上厂商后台的账单。仔细查下来发现，有些模型服务商根本不回传 token 使用量，LiteLLM 的usage字段只能显示 0 或空值。

具体表现是：response.usage.prompt_tokens有时有值，有时是 0。这取决于上游厂商是否在响应里附带 token 统计。LiteLLM 只是一个透明转发层，上游不给数据，它也没办法凭空造出来。对此我能给的建议是：如果你要基于 token 做成本核算，优先选择那些在 API 响应里稳定回传 usage 的厂商，或者在代码里自行用tiktoken这类工具估算输入 token 量。

4.4 版本升级引发的不兼容：锁定版本比追新更稳

LiteLLM 更新速度很快，几乎每周都有新版本，新特性确实诱人，但也意味着接口变动频繁。某次我把包从旧版本升级到新版本后，原先配置好的某个模型突然报错，排查半天发现是配置格式变了，需要多写一个字段。

从那以后我的做法很明确：生产环境锁定版本号，先在一个临时环境里验证新版本，确认兼容后再升级。安装时直接写死版本：

pip install litellm==1.40.0

这样做的代价是你暂时享受不到新特性，但换来了稳定可控。对于团队用的网关服务来说，稳定永远是第一优先级。

5. 什么场景真的值得用LiteLLM，什么场景不需要

5.1 值得引入的场景

从我自己的体验来看，LiteLLM 最适用的场景有几个共通特征：多家模型供应商同时在线、代码库需要保持简洁、团队协作需要统一管控。

典型的例子是内部工具平台，比如同时接入了闭源模型做对话、开源模型做推理摘要，还要应对不同项目使用不同模型的情况。LiteLLM 的价值在这里不只是省事，而是把"换模型"变成了一次配置修改，而不是一次代码重构。另一类是面向大量外部调用的网关服务，预算管控、限流、日志审计是硬需求，代理模式本身就提供了这些能力。

5.2 不需要引入的场景

如果你只用一个厂商的一个模型，并且确定未来不会换，那确实没必要引入 LiteLLM。官方 SDK 性能更好，依赖更少，文档也更贴切。

还有一种情况是团队没有独立的服务器资源来部署代理，且所有人的调用都发生在本地脚本里，统一管控的需求不强。这种情况下直接在每个脚本里配置环境变量就够了，引入代理反而增加了运维负担。

5.3 关于统一入口，我最看重的东西

在大量项目里用下来，我发现 LiteLLM 最大的红利其实不是"少写几行代码"，而是变更成本。模型这个领域变化太快，今天效果最好的模型，下个月可能就被另一个模型超越了。当你把所有调用统一到一个入口后，做这种切换只需要修改配置，业务逻辑不用动，测试范围也大幅缩小。

最后说一个小建议：如果团队刚开始接触 LiteLLM，不要一上来就把所有模型、所有限流策略都配好。先把一个模型跑通，再把第二个接进来，感受一下统一调用的效果，最后再逐步加负载均衡、预算管理这些高级功能。一步步来，踩坑时更容易定位问题。