企业官网建设流程全解析

1. 项目概述：Litellm 到底是什么

做 AI 应用开发的朋友，尤其是接过大模型接口的，应该都有过这种体会：今天用 A 厂商的接口调通了一个功能，明天老板说要换成 B 厂商的模型对比效果，结果发现不仅 API 地址不一样、鉴权方式不一样，连请求参数的字段名都对不上。明明都是干同一件事，不同厂商的 SDK 却各自为政，改一次需求就要重新写一遍对接代码，相当折腾。

Litellm 就是来解决这个问题的。它是一个开源的 Python 库（也附带代理服务器能力），核心目标只有一个——用一套统一的接口格式，去调用市面上几乎所有主流的大模型服务。OpenAI、Anthropic、Google Gemini、Azure OpenAI、各类开源模型托管的推理服务，以及国内常见厂商的模型服务，它都能帮你转成统一的请求格式。你只需要按照它定义的格式写一份请求，litellm 会在底层帮你完成协议转换、鉴权适配、参数映射这些脏活累活。

这个项目解决的最核心痛点就是“多模型适配成本”。在实际业务里，我们的需求往往不只是“能调用一个模型”，而是要能够：

• 在多个模型之间做对比测试，选出效果最好的那个
• 在某个模型服务出现故障或限流时，自动切换备用模型
• 不同业务线用不同模型，但统一走同一套代码入口
• 汇总所有模型调用的成本消耗，做统一核算

如果没有一个中间适配层，这些事情做起来会非常痛苦，基本上每个模型就要维护一套独立代码。Litellm 的价值就在于——它把“模型调用”这件事抽象成了一个标准动作，无论底层用的是什么模型，对业务代码来说都是同一个入口。

如果你属于下面这几类人群，litellm 会很适合你：

• 应用开发者：需要在产品里集成大模型能力，但又不想被某一个特定厂商绑定
• AI 平台/中间件开发者：需要为团队或公司搭建统一的模型接入层
• 测试/算法工程师：需要频繁对比不同模型的效果，不想为每个模型都写一套测试脚本
• 独立开发者：想快速做出一个支持多模型切换的 Demo 或 MVP

简单总结就是：如果你觉得“对接模型服务”这件事很烦人，值得花点时间看看 litellm，它能把这部分工作大幅简化。

2. 核心思路拆解：它凭什么能做到“一套代码调所有模型”

litellm 的设计思路其实不复杂，概括起来就是“标准化 + 适配器”两层结构。理解了这个设计，你就能明白它的能力和边界在哪里。

2.1 核心设计逻辑：统一标准 + 各类适配器

litellm 为所有支持的模型服务定义了一套标准请求格式（基于 OpenAI 的 API 风格），上层业务代码只需要按照这套标准格式发请求。在底层，litellm 针对每个不同的模型服务都实现了对应的“适配器”组件，负责把标准格式的请求转换为目标服务要求的格式。

打个比方，这就像我们日常使用的充电接口标准。手机厂商都在 Type-C 接口上做统一，但针对老式设备，你还是需要一个转接头。litellm 就是那个万能转接头集线器，你只带一根线，就能给各种设备充电。

这样做的好处非常明显：

• 业务代码与具体模型解耦，换模型时业务代码完全不用改
• 新增模型服务时，只需要增加适配器实现，不影响已有功能
• 可以在适配层统一实现重试、限流、成本统计、日志记录等横切功能

那为什么标准格式要“基于 OpenAI 风格”呢？这里有一个现实原因——OpenAI 的接口格式实际上是当前大模型 API 领域的事实标准。早期很多模型服务厂商在设计自己的 API 时都参考了 OpenAI 的格式，有的甚至直接兼容。litellm 采用了这套风格，意味着学习成本很低，大部分开发者对接过 OpenAI SDK 后就能直接上手。

2.2 支持的模型范围：不只是“多家”，而是“非常多”

很多类似的库可能只支持三五家主流服务，但 litellm 覆盖的范围要广得多。它能同时支持：

• OpenAI 系列（包括 GPT 系列全模型）
• Anthropic 系列（Claude 系列）
• Google 系列（Gemini 系列等）
• Azure OpenAI（企业级部署形态）
• AWS Bedrock 上的各类模型
• 各类开源模型的托管推理服务（通过兼容接口接入）
• 国内多家厂商的大模型服务（通过兼容适配接入）
• 本地部署的推理服务（比如通过 Ollama 等工具启动的本地模型）

这意味着，无论你是在做一个聚合类 AI 产品，还是在企业内部做多模型调度平台，基本都能在 litellm 中找到对应的适配实现。

2.3 不只是 API 转换：代理模式是真正的杀手锏

如果你以为 litellm 只是一个“调用 SDK 封装库”，那就忽略了这个项目最重要的价值。除了在 Python 代码里作为库使用，litellm 还提供了一个代理服务器模式（Proxy Server），这一点在企业应用场景中价值很大。

代理模式是什么意思呢？你不需要在业务代码里引入 litellm SDK，只需要部署一个 litellm 代理服务，它对外暴露一个统一的 API 入口（兼容 OpenAI 接口格式），你仍然用你熟悉的 OpenAI SDK 去访问这个代理，但代理会把请求转发到你配置好的任意一个真实模型服务上。

这个设计在企业环境中很实用：

• 团队内不同项目不需要都学习 litellm 的 SDK 用法，直接用 OpenAI SDK 就能访问
• API 密钥可以统一在代理层管理，不散落在各个业务代码里
• 可以在代理层统一配置重试策略、熔断机制、速率限制、成本告警
• 上层业务完全无感知地切换底层模型服务

用一句话概括：litellm 既能当作库来用，也能当作服务来部署。前者适合单体应用快速接入，后者适合团队级统一管控。两者结合，不管是个人项目还是企业级应用，都能找到合适的落点。

3. 实操过程全解：从安装到跑通第一个多模型调用

这块我直接分享非常具体的实操过程，按照我实际跑通的步骤来写，包含坑和注意事项。

3.1 安装与基础环境准备

首先，litellm 是基于 Python 的，所以你需要一个 Python 环境，3.8 以上版本就行（新版本建议 3.10+，有些新模型特性会依赖更新的 Python 特性）。安装方式非常简单：

pip install litellm

或者你打算使用代理服务器模式，一并安装 proxy 相关依赖：

pip install 'litellm[proxy]'

安装完成后，在 Python 环境中验证一下能不能正常导入：

import litellm print(litellm.__version__)

正常打印版本号就说明安装成功了。

这里有一个很多人第一次用时会犯的错：litellm 安装后不会自动包含所有模型服务商的 SDK 依赖，它会在实际调用某个服务时按需加载。所以如果你只安装了最基础的 litellm 包，调用 OpenAI 没问题，但调用 Anthropic 时可能会提示缺少某些依赖。遇到这种情况不用慌，根据错误提示补装对应依赖包，或者直接用pip install 'litellm[all]'把常用项都装齐。

3.2 快速上手：用代码直接调用多个模型

litellm 的库模式使用体验很顺，核心的方法就是litellm.completion()，我们直接看一个多模型调用的例子。

假设我们想在三个不同的模型之间做一次效果对比，分别是 OpenAI 的 GPT 4.0 系列模型、Anthropic 的 Claude 系列模型，以及一个通过 Ollama 拉起的本地模型。你只需要这样写：

import litellm # 调用 OpenAI 系列模型 response_openai = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "讲一个程序员加班的笑话"}], api_key="你的OpenAI_API_Key" ) # 调用 Anthropic 系列模型 response_claude = litellm.completion( model="claude-3-5-sonnet-20241022", messages=[{"role": "user", "content": "讲一个程序员加班的笑话"}], api_key="你的Anthropic_API_Key" ) # 调用本地 Ollama 模型 response_local = litellm.completion( model="ollama/llama3", messages=[{"role": "user", "content": "讲一个程序员加班的笑话"}] ) print(response_openai.choices[0].message.content) print(response_claude.choices[0].message.content) print(response_local.choices[0].message.content)

注意看model参数，litellm 对不同模型服务有约定的格式，通常是“服务前缀/模型名”的格式。比如 OpenAI 模型直接写模型名，Anthropic 也是直接写模型名，但本地 Ollama 模型就是ollama/模型名。这种约定在 litellm 文档中都有清晰说明。

这样一段代码，就完成了三个不同服务商的模型调用。如果将来要换模型或者换服务商，你只需要改model字段和对应的api_key，其他业务逻辑完全不用动。

在上面的例子里我把api_key直接写在代码里了，但真实项目中千万别这么做——密钥管理很关键，建议通过环境变量设置。litellm 也支持通过环境变量读取密钥：

export OPENAI_API_KEY="你的OpenAI密钥" export ANTHROPIC_API_KEY="你的Anthropic密钥"

设置好环境变量之后，代码里就不需要传api_key参数了，litellm 会自动去环境变量中匹配对应的密钥。

3.3 服务商返回格式统一：这件事比表面看起来重要

有时候我们在 Python 里打印 litellm 的返回值，会看到它返回的对象结构和 OpenAI SDK 的返回结构几乎一样，都包含choices、usage这些字段，这就是它做的“返回结果标准化”。

为什么说这件事重要？因为我们做业务对接时，需要处理各种逻辑——比如从返回结果中抽取文本内容、统计 token 消耗、获取对应的结束原因等。如果每家模型返回的字段结构都不一样，那你的业务代码就要写大量的if provider == "openai"这种类型判断。litellm 帮你把这些差异都抹平了，拿到手的就是一个统一的响应对象，写代码时心智负担小很多。

我来展示一个更贴近真实业务的使用方式：一个封装好的函数，内部用它来调用任意模型，并提取文本内容：

def ask_llm(model: str, user_query: str) -> str: try: response = litellm.completion( model=model, messages=[ {"role": "system", "content": "你是一个乐于助人的中文助手。"}, {"role": "user", "content": user_query} ], temperature=0.7 ) return response.choices[0].message.content except Exception as e: # 统一异常处理，记录日志 print(f"模型 {model} 调用失败：{e}") return ""

然后当你需要对比多个模型时，只需要一个循环：

models = ["gpt-4o", "claude-3-5-sonnet-20241022", "ollama/llama3"] question = "用一句话解释什么是HTTP协议" for m in models: answer = ask_llm(m, question) print(f"模型 {m} 的回答：\n{answer}\n" + "—"*40)

实测下来，这种方式写对比测试脚本效率很高。以前要做类似的事情，我需要打开三个不同的 SDK 文档，分别处理不同的鉴权逻辑，现在全部统一在几行代码里搞定。

3.4 代理服务器模式：部署一个“模型网关”

如果你是一个团队的技术负责人，想给团队提供一个统一的模型访问入口，那就需要部署 proxy 模式了。安装好litellm[proxy]后，可以用命令行启动一个服务。

先准备一个配置文件config.yaml，内容大致是这样：

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

然后启动代理服务：

litellm --config config.yaml --port 4000

启动后，本地会监听 4000 端口，外部通过 OpenAI SDK 兼容的方式访问http://localhost:4000就行。比如用 Python 的 openai SDK 访问：

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000", api_key="任意值，代理层可能会校验，但默认情况下可以配置跳过或统一校验" ) response = client.chat.completions.create( model="gpt-openai", # 这里用的是配置里设置的 model_name messages=[{"role": "user", "content": "你好，介绍一下自己"}] ) print(response.choices[0].message.content)

这个模式的关键点在于：业务团队完全不用修改代码，只要把base_url指到代理服务，把model换成配置里自定义的model_name，就能访问代理背后配置的任何模型。哪天你想把某个业务从 OpenAI 模型切换到 Claude 模型，只需要修改代理的配置文件，重启服务即可，业务代码一行都不用动。

我在实际部署中体会最深的点是：代理模式是模型切换的“开关”，业务代码是“灯泡”。你不需要去改灯泡的接线，只需要在开关处控制电流走向就行。

3.5 成本与 Token 统计：做 AI 应用的人迟早都要面对的事

不管是大模型 API 的账单，还是内部多个业务线的成本核算，Token 用量统计都绕不开。litellm 在返回结果中会带上usage信息，包含prompt_tokens（输入 Token 数）、completion_tokens（输出 Token 数）和total_tokens（总 Token 数）。

更实用的是，litellm 还提供了成本估算能力。当你配置了模型对应的价格信息后（部分默认支持，需要你确认定价周期），你可以通过litellm.completion_cost()直接算出一调用的费用：

import litellm response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "写一段100字的产品介绍"}] ) cost = litellm.completion_cost(completion_response=response) print(f"本次调用花费：${cost}")

在企业里，这个功能可以直接用于：

• 按业务线汇总模型消耗，分摊成本
• 设置成本阈值告警，避免某个业务线费用失控
• 在多个模型之间做性价比对比（效果差不多但价格低 30% 的模型优先选）

做一个粗略的估算公式：如果单次请求处理 2000 个输入 token 并生成 1000 个输出 token，用某个 0.03 美元/千输入 token、0.06 美元/千输出 token 的模型计算，一次调用大约是 0.03 × 2 + 0.06 × 1 = 0.12 美元。如果每天调用一万次，那就是 1200 美元。通过成本估算提前做预算规划，对公司决策很有帮助。

4. 进阶玩法与实战细节

litellm 不止能“调用模型”，它还有很多实用的高级能力。这一部分分享几个我实际使用过并且觉得价值很高的功能。

4.1 模型重试、超时和兜底降级策略

在生产环境里，模型服务商可能会不稳定，也偶尔会遇到限流（429 状态码）或者服务不可用（5xx）。如果我们只在代码里写一次调用，出错了就抛异常，会让用户体验很不好。litellm 提供了一些内建的机制，你可以通过参数来控制重试行为：

import litellm # 设置全局重试次数 litellm.num_retries = 3 # 设置超时时间（单位秒） litellm.request_timeout = 30 # 自定义重试退避策略（默认是1秒起步，支持设置） litellm.max_retries = 5

除此之外，比较进阶的操作是“模型兜底降级”。举个例子：你的应用默认使用 GPT-4o，但它出现了限流或故障，你希望在这种情况下自动用一个备用的模型（比如本地 Ollama 的 Llama）继续服务，而不是直接报错。litellm 的代理服务器配置里可以定义 fallback：

model_list: - model_name: main-model litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: fallback-model litellm_params: model: ollama/llama3 litellm_settings: fallbacks: [{"main-model": ["fallback-model"]}]

这样配置之后，当主模型调用失败时，请求会自动尝试备用模型。对于实时在线业务来说，这种降级策略能显著提升可用性。

4.2 多模型路由与负载均衡

当你的业务请求量很大，或者想让不同请求尽量均匀地分配到多个模型实例上时，代理模式中的路由能力就派上用场了。你可以在配置里把一个逻辑模型名对应到多个目标模型上：

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

然后业务请求时指定model: my-chat-model，代理会根据配置的策略（支持轮询、随机、最少请求优先等）分发到一个实际模型上。

对于内部平台来说，这种方式非常实用：你可以用同一个 API 入口，把不同用户的请求分发到不同模型上，再配合权重设置，实现按流量分配。比如 80% 流量走性价比模型，20% 流量走最强模型做对比或验证。

4.3 流式输出

很多大模型应用都需要打字机效果，也就是流式输出。litellm 对流的支持也比较到位。在代码模式下，只需要传入stream=True：

import litellm response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "写一个800字的旅游攻略"}], stream=True ) for chunk in response: if chunk.choices[0].get("delta", {}).get("content"): print(chunk.choices[0].delta.content, end="", flush=True)

我在本地测试过流式输出，整体延迟表现不错，各个模型在 litellm 层被统一成了相同结构的流式对象。如果你用 OpenAI SDK 兼容模式访问代理，流式输出也能正常工作，因为代理把底层的流式返回格式转为了 OpenAI 风格的流式格式，上层代码拿到的是标准 SSE 流。

需要注意的是：流式输出对代理服务的并发连接数有一定要求。如果业务里流式请求特别多，建议在代理服务前面加负载均衡，避免单实例连接数过高导致新请求排队。

4.4 嵌入模型支持

litellm 不止做文本生成，它还支持调用各种嵌入模型，这在做语义搜索、向量数据库、知识库召回的场景中很有用。用法同样很简洁：

import litellm response = litellm.embedding( model="text-embedding-3-large", input=["什么是大语言模型", "自然语言处理的常见任务"], api_key="你的OpenAI_API_Key" ) embeddings = response.data print(len(embeddings[0].embedding)) # 输出向量维度

如果业务里需要同时使用文本生成和向量化两类能力，统一用 litellm 也意味着你只需要维护一套工具链，不用给不同的服务商分别准备 SDK。

4.5 本地大模型的一碗水端平

为什么我在多个示例里都提到 Ollama 和本地模型？因为在做模型效果对比、隐私敏感数据处理、离线环境开发时，本地模型往往是很好的补充方案。litellm 对 Ollama 的支持很好，你在本地用 Ollama 启动模型后，litellm 可以直接通过ollama/模型名来调用，不需要额外的 API Key。

此外，litellm 还支持通过 OpenAI 兼容接口接入本地推理服务，比如某些开源项目通过 vLLM 等框架启动的本地推理服务。这就让本地模型和云端模型在代码层面完全对等，你可以放心地在不同环境（本地开发、测试、生产）中切换，而不需要重写调用逻辑。

5. 常见问题与排查经验实录

说实话，用 litellm 对接这么多家服务，踩坑是难免的。这里我整理了一些高频问题的实测经验，方便你遇到类似情况时快速定位。

5.1 报错提示找不到对应的模型服务

典型报错：litellm.exceptions.BadRequestError或者Model not found之类。

常见原因：model参数里的服务前缀写错，或者模型名称和实际服务商提供的名称不一致。litellm 识别模型服务是通过provider/模型名的规则，如果你不写前缀，它会默认当成 OpenAI 去解析，自然找不到其他服务上的模型。

排查与解决：先在 litellm 文档的模型列表中确认“服务前缀”和“模型全名”的写法，再对照一次代码中的参数。也可以直接在 Python 中打印出实际请求发送的目标地址，方便确认是否按预期路由：

import litellm # 查看一个模型实际会请求的地址 url = litellm.get_llm_provider("claude-3-5-sonnet-20241022") print(url)

5.2 鉴权失败，返回 401

典型报错：AuthenticationError: api_key not found或者Invalid API key provided。

常见原因：环境变量没有设置对应的密钥；或者设置的环境变量名不是 litellm 约定的那个（比如 OpenAI 密钥必须是OPENAI_API_KEY，Anthropic 密钥必须是ANTHROPIC_API_KEY）。

排查与解决：优先检查环境变量是否在当前进程可见。可以用echo $OPENAI_API_KEY这种方式确认。如果业务代码是在某个容器或服务器上跑的，还要检查环境变量是否在部署配置中正确注入。

5.3 返回内容被截断，或者输出不完整

常见原因：max_tokens设置太小。有些模型服务在 litellm 中的参数会被转换成目标服务对应设置；如果底层模型服务默认限制了最大输出长度，而你传入的最大长度不匹配，就会出现输出中断。

排查与解决：看一下返回结果中的finish_reason字段，如果是length，说明是因为达到长度限制而停止，而非正常结束。可以调大max_tokens参数：

response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "写一篇长文章"}], max_tokens=4096 )

另外要注意，不同模型单次请求的最大输出限制不一样，有的 4K，有的 8K，还有的更少。最好了解目标模型的具体限制，再设置合理的max_tokens。

5.4 传参格式错误

有时候你写代码传了temperature、top_p、presence_penalty等参数，但目标模型服务不支持其中某些参数。litellm 会有两种处理方式：一是忽略不支持的参数并继续调用，二是直接抛出异常。这取决于目标服务商实现的具体行为。

实测心得：对于不支持某些参数的服务，建议在调用前通过 litellm 提供的能力查一下该模型支持的参数列表。如果业务代码里有比较“激进”的参数组合，可以对不同模型做参数差异化处理。比如在函数中把参数按模型类型分组，避免强求一套参数走天下。

5.5 代理模式下访问延迟偏高

现象：在代理模式下，流式响应或者非流式请求整体比直连模型服务晚几百毫秒到数秒。

原因：请求多了一层代理转发，网络耗时增加；且 litellm 代理在处理某些复杂逻辑（比如重试、路由）时，如果配置不够精简，会增大开销。

经验：

• 将代理服务器部署在与模型服务网络距离较近的地方
• 避免在代理层配置过多无关联的 fallback 链，只在必要时启用
• 如果业务并发不高，可以减少不必要的日志和统计插件
• 实测中发现，把代理和业务服务部署在同一地域或同一内网后，额外延迟能控制在 50-100 毫秒左右，基本可以接受

5.6 安装依赖冲突

现象：安装litellm[all]后，与项目其他包发生依赖版本冲突，尤其是openai、pydantic等较常用的包。

经验：实测建议不要一上来就安装[all]。先装基础包，按需补充缺的依赖。出现冲突时优先看错误信息中提示的具体库和版本要求，通过虚拟环境隔离可以降低这类问题的影响。用pip install 'litellm[proxy]'是折中方案，既能用代理模式，又尽可能少引入额外依赖。

6. 个人使用体验和一些拓展想法

最后说点我自己的感受。用过一段时间 litellm 后，我最大的体会是：它解决的不是“能不能调通”的问题，而是“长期维护成本”的问题。AI 模型迭代速度很快，今天好用的模型可能半年后就被更好的替代了。如果没有一个统一适配层，每次模型切换都是一次伤筋动骨的改动。有了 litellm，切换模型变成了一件很轻的事——改配置，跑测试，上生产。

如果你在公司做技术基建，我建议可以以小范围试点的方式推进 litellm。先让一两个项目通过代理模式接入，跑通后把成本统计、模型切换、限流重试这些能力都沉淀下来，再逐步推广到更多业务线。跟引入任何基础组件一样，最好配上文档和内部示例，让团队里的人快速上手。

另外，litellm 的社区版本使用上没什么门槛，但是如果你想把它用到大规模生产环境，建议仔细理解它的路由策略、并发模型、配置管理和监控告警能力。必要时可以对代理服务做压测，确保在峰值流量下稳定运行。

最后分享一个小技巧：如果你在用 litellm 的代理模式，别忘了利用它的health check能力，定时检查配置的模型服务是否健康。配合 prometheus 等监控体系，你可以把每个模型服务的成功率、延迟、耗时都量化出来，后续做模型选型和容量规划时，这些数据会很有说服力。

总之，litellm 不是一个能让你“一键解决所有模型调用问题”的神器，但它所提供的统一接入思路和完善的工具链，确实能大幅降低多模型场景下的维护成本。如果你正在被多模型对接、切换、成本核算这些琐事困扰，花半天时间试试它，大概率会有所收获。