LiteLLM 入门指南:统一调用 100+ LLM 的 Python 库
背景
2023-2025 年是大模型爆发的几年,市面上涌现了 OpenAI、Anthropic、Google Gemini、Mistral、Groq、Cohere 等数十家模型提供商,每个厂商都有自己的 API 格式、鉴权方式和 SDK。这种碎片化给开发者带来了巨大的集成成本:
- 切换模型需要重写调用代码
- 不同厂商的错误处理机制不同
- 缺乏统一的成本追踪
- 多模型 fallback 需要自己实现重试逻辑
LiteLLM 就是为了解决这些问题而生的。它是一个轻量级的 Python 库(也提供 Proxy Server),把所有 LLM API 统一成 OpenAI 兼容格式,一行代码切换模型提供商。目前支持 100+ 模型提供商,包括主流的 OpenAI、Anthropic、Google、AWS Bedrock、Azure、Groq、Together AI 等。
核心概念
LiteLLM 的核心设计哲学很简单:用 OpenAI 的调用方式,调用所有模型。
1
|
你的代码 → LiteLLM → 任意 LLM API
|
它的架构分为两层:
Python SDK:直接在代码中调用的库,提供 completion()、embedding()、image_generation() 等函数。适合需要在应用代码中直接控制模型调用的场景。
Proxy Server:一个 OpenAI 兼容的 API 网关服务,部署后可以作为一个统一的 API 端点,提供集中式认证、成本追踪、限流、负载均衡等功能。适合团队使用,或者需要将多个模型统一暴露为一个服务端的场景。
安装
就是这么简单,没有额外的依赖安装步骤。如果你需要 Proxy Server:
1
|
pip install 'litellm[proxy]'
|
快速上手
设置 API Key
使用环境变量配置 API 密钥是推荐方式:
1
2
3
4
5
6
7
|
import os
os.environ["OPENAI_API_KEY"] = "sk-xxx" # OpenAI
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-xxx" # Anthropic
os.environ["GEMINI_API_KEY"] = "AIza..." # Google Gemini
os.environ["GROQ_API_KEY"] = "gsk_xxx" # Groq
os.environ["TOGETHERAI_API_KEY"] = "xxx" # Together AI
|
第一次调用
1
2
3
4
5
6
7
8
9
10
|
from litellm import completion
response = completion(
model="gpt-4o",
messages=[
{"role": "user", "content": "用一句话解释什么是 LiteLLM"}
]
)
print(response.choices[0].message.content)
|
返回的 response 对象与 OpenAI SDK 返回的结构完全一致,包含 choices、usage、model 等字段。
多模型调用示例
LiteLLM 最大的价值在于一行代码切换模型:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
from litellm import completion
messages = [{"role": "user", "content": "你好,请介绍一下你自己"}]
# OpenAI
response = completion(model="gpt-4o", messages=messages)
print("GPT-4o:", response.choices[0].message.content)
# Anthropic Claude
response = completion(model="claude-sonnet-4-20250514", messages=messages)
print("Claude:", response.choices[0].message.content)
# Google Gemini
response = completion(model="gemini/gemini-2.5-pro", messages=messages)
print("Gemini:", response.choices[0].message.content)
# Groq (开源模型)
response = completion(model="groq/llama-3.3-70b-versatile", messages=messages)
print("Groq Llama:", response.choices[0].message.content)
# Together AI
response = completion(model="together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo", messages=messages)
print("Together:", response.choices[0].message.content)
|
模型名称的格式为 provider/model-name,如果不加前缀(如直接写 gpt-4o),LiteLLM 会根据模型名自动匹配提供商。
支持的模型前缀
| 提供商 |
模型名格式 |
环境变量 |
| OpenAI |
gpt-4o, gpt-4o-mini |
OPENAI_API_KEY |
| Anthropic |
claude-sonnet-4-20250514, claude-haiku-3-5 |
ANTHROPIC_API_KEY |
| Google |
gemini/gemini-2.5-pro, gemini/gemini-2.5-flash |
GEMINI_API_KEY |
| AWS Bedrock |
bedrock/anthropic.claude-3-5-sonnet |
AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY |
| Azure |
azure/gpt-4o |
AZURE_API_KEY + AZURE_API_BASE |
| Groq |
groq/llama-3.3-70b-versatile |
GROQ_API_KEY |
| Together AI |
together_ai/... |
TOGETHERAI_API_KEY |
| Mistral |
mistral/mistral-large |
MISTRAL_API_KEY |
| Cohere |
command-r-plus |
COHERE_API_KEY |
| HuggingFace |
huggingface/... |
HF_TOKEN |
| Ollama (本地) |
ollama/llama3 |
无需 API Key |
流式输出 (Stream)
流式输出的接口与 OpenAI 完全一致,只需传 stream=True:
1
2
3
4
5
6
7
8
9
10
11
12
|
from litellm import completion
response = completion(
model="gpt-4o",
messages=[{"role": "user", "content": "讲一个简短的笑话"}],
stream=True
)
for chunk in response:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
|
这对 Claude、Gemini、Groq 等所有支持流式输出的模型同样适用。
Model Fallback(模型回退)
生产环境中,某个模型可能会因为限流、服务宕机等原因不可用。LiteLLM 内置了 fallback 机制:
1
2
3
4
5
6
7
8
9
10
|
from litellm import completion
response = completion(
model="gpt-4o",
messages=[{"role": "user", "content": "写一段 Python 代码"}],
fallbacks=[
{"model": "gpt-4o-mini"},
{"model": "claude-sonnet-4-20250514"}
]
)
|
当 gpt-4o 调用失败时,LiteLLM 自动尝试 gpt-4o-mini,如果还失败则尝试 claude-sonnet-4。整个过程对上层透明。
也可以使用 model_list_fallback 指定多个 fallback 的组合:
1
2
3
4
5
|
response = completion(
model="gpt-4",
messages=[{"role": "user", "content": "测试"}],
model_list_fallback=[["gpt-3.5-turbo", "claude-3-haiku"]]
)
|
使用 Router 进行负载均衡
对大规模生产环境,LiteLLM 提供了 Router 类,支持多 deployment 的负载均衡和自动重试:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
from litellm import Router
router = Router(model_list=[
{
"model_name": "gpt-4o-group", # 自定义分组名
"litellm_params": {
"model": "openai/gpt-4o",
"api_key": os.environ["OPENAI_API_KEY"],
"api_base": "https://api.openai.com/v1"
}
},
{
"model_name": "gpt-4o-group",
"litellm_params": {
"model": "openai/gpt-4o",
"api_key": os.environ["OPENAI_API_KEY2"], # 另一个 Key
"api_base": "https://api.openai.com/v1"
}
},
{
"model_name": "claude-group",
"litellm_params": {
"model": "anthropic/claude-sonnet-4-20250514",
"api_key": os.environ["ANTHROPIC_API_KEY"]
}
}
])
# 使用 Router 调用,自动轮询或随机选择 deployment
response = router.completion(
model="gpt-4o-group",
messages=[{"role": "user", "content": "负载均衡测试"}]
)
|
Router 的特性:
- 轮询/随机/最低延迟等多种调度策略
- 自动重试失败请求
- 限制失败 deployment 的权重(cooldown 机制)
- 支持模型分组的 fallback
成本追踪
LiteLLM 内置了所有主流模型的定价信息,调用后可以直接获取花费:
1
2
3
4
5
6
7
8
9
10
|
from litellm import completion, completion_cost
response = completion(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}]
)
# 计算本次调用的成本
cost = completion_cost(response)
print(f"本次调用花费: ${cost}")
|
如果要获取详细的 token 用量:
1
2
3
|
print(f"输入 tokens: {response.usage.prompt_tokens}")
print(f"输出 tokens: {response.usage.completion_tokens}")
print(f"总 tokens: {response.usage.total_tokens}")
|
Proxy Server —— 统一 API 网关
如果你有多个后端服务都需要调用 LLM,或者需要为团队提供统一的模型访问入口,Proxy Server 是最佳实践。
启动 Proxy
1
2
3
4
5
|
# 简单的单模型模式
litellm --model gpt-4o
# 使用配置文件的多模型模式
litellm --config config.yaml
|
Proxy 配置文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
# config.yaml
model_list:
- model_name: gpt-4o
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gemini-pro
litellm_params:
model: gemini/gemini-2.5-pro
api_key: os.environ/GEMINI_API_KEY
- model_name: deepseek
litellm_params:
model: openai/deepseek-chat
api_key: os.environ/DEEPSEEK_API_KEY
api_base: https://api.deepseek.com/v1
litellm_settings:
master_key: os.environ/LITELLM_MASTER_KEY # 保护 Proxy 自己的访问
drop_params: true # 忽略不支持的参数
|
从客户端调用 Proxy
启动 Proxy 后(默认监听 http://localhost:4000),任何支持 OpenAI SDK 的工具可以无缝接入:
1
2
3
4
5
6
7
8
9
10
11
|
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:4000/v1",
api_key="your-litellm-master-key" # 对应 config 中的 master_key
)
response = client.chat.completions.create(
model="gpt-4o", # config.yaml 中定义的 model_name
messages=[{"role": "user", "content": "Hello via LiteLLM Proxy"}]
)
|
重点是:不需要安装任何额外的 Python 包,只要支持 OpenAI 格式的客户端都可以直接用。这也意味着你可以用 curl 调用:
1
2
3
4
5
6
7
|
curl http://localhost:4000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-litellm-master-key" \
-d '{
"model": "claude-sonnet",
"messages": [{"role": "user", "content": "Hello"}]
}'
|
实战案例:构建一个多模型评测脚本
下面是一个完整的示例,对比不同模型在同一个问题上的响应时间和成本:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
import time
import os
from litellm import completion, completion_cost
# 配置 API Key
os.environ["OPENAI_API_KEY"] = "sk-xxx"
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-xxx"
os.environ["GEMINI_API_KEY"] = "AIza..."
os.environ["GROQ_API_KEY"] = "gsk_xxx"
models = [
"gpt-4o-mini",
"gpt-4o",
"claude-sonnet-4-20250514",
"gemini/gemini-2.5-flash",
"groq/llama-3.3-70b-versatile"
]
question = "解释一下什么是 CAP 定理,用 100 字以内。"
results = []
for model in models:
start = time.time()
response = completion(
model=model,
messages=[{"role": "user", "content": question}],
max_tokens=300
)
elapsed = time.time() - start
cost = completion_cost(response)
answer = response.choices[0].message.content
results.append({
"model": model,
"time": round(elapsed, 2),
"cost": round(cost, 6),
"tokens": response.usage.total_tokens,
"answer": answer[:80] + "..." if len(answer) > 80 else answer
})
# 打印结果对比表
print(f"{'Model':<35} {'时间(s)':<10} {'成本($)':<12} {'Tokens':<8}")
print("-" * 65)
for r in results:
print(f"{r['model']:<35} {r['time']:<10} {r['cost']:<12} {r['tokens']:<8}")
|
输出类似:
1
2
3
4
5
6
|
Model 时间(s) 成本($) Tokens
gpt-4o-mini 1.23 0.000123 148
gpt-4o 2.45 0.001521 156
claude-sonnet-4-20250514 3.12 0.004203 162
gemini/gemini-2.5-flash 1.87 0.000035 143
groq/llama-3.3-70b-versatile 0.95 0.000000 151
|
实战案例:Proxy 实现多模型 API 网关
假设你的团队同时使用 GPT-4o、Claude 和 DeepSeek,希望统一管理访问:
服务端配置 (config.yaml):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
model_list:
- model_name: fast-model
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY
rpm: 1000 # 每分钟最多 1000 请求
- model_name: strong-model
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
rpm: 100
- model_name: code-model
litellm_params:
model: openai/deepseek-chat
api_key: os.environ/DEEPSEEK_API_KEY
api_base: https://api.deepseek.com/v1
rpm: 500
litellm_settings:
master_key: os.environ/LITELLM_MASTER_KEY
set_verbose: False
general_settings:
# 启用成本追踪数据库
custom_db: true
database_url: os.environ/DATABASE_URL
|
客户端使用:团队成员通过统一的 API 端点调用,不用自己管理各种 API Key:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
from openai import OpenAI
client = OpenAI(
base_url="http://litellm-gateway.company.com:4000/v1",
api_key="team-key-xxx"
)
# 简单任务用 fast-model
quick_reply = client.chat.completions.create(
model="fast-model",
messages=[{"role": "user", "content": "翻译:Hello world"}]
)
# 复杂任务用 strong-model
analysis = client.chat.completions.create(
model="strong-model",
messages=[{"role": "user", "content": "写一篇深度的技术分析"}]
)
# 编程任务用 code-model
code = client.chat.completions.create(
model="code-model",
messages=[{"role": "user", "content": "写一个 Python 装饰器"}]
)
|
Proxy 会追踪每个用户的 token 消耗和花费,方便做成本分摊和限流。
嵌入(Embedding)和图片输入
LiteLLM 也支持 embedding 和 multimodal 输入:
Embedding
1
2
3
4
5
6
7
8
|
from litellm import embedding
response = embedding(
model="text-embedding-3-small",
input=["LiteLLM 是一个很棒的库"]
)
print(len(response.data[0].embedding)) # 1536
|
图片输入
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
from litellm import completion
response = completion(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张图里有什么?"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg"
}
}
]
}
]
)
|
常见问题
LiteLLM 和 LangChain 的关系是什么?
LangChain 是一个更上层的 AI 应用框架(包含 chain、agent、tool 等抽象),而 LiteLLM 专注于模型调用层的统一。两者可以配合使用:LiteLLM 作为 LangChain 底层的 LLM 调用后端。
是否支持 OpenAI 兼容的私有部署模型?
支持。通过 openai/ 前缀加 api_base 参数,可以调用任何兼容 OpenAI 接口的私有部署模型(如 vLLM、TGI、Ollama 等):
1
2
3
4
5
6
|
response = completion(
model="openai/custom-model",
api_base="http://localhost:8000/v1",
api_key="sk-xxx", # 随意填
messages=[{"role": "user", "content": "Hello"}]
)
|
如何处理不同模型支持的参数差异?
不同模型对参数的支持不同(比如 top_p、frequency_penalty 等)。LiteLLM 默认会过滤掉目标模型不支持的参数。也可以在调用时设置 drop_params=True 让它自动丢弃不支持的参数。
Proxy Server 的性能如何?
LiteLLM Proxy 本身只是一个轻量级的转发层,延迟开销通常在 1-5ms 之间(不包括 LLM 本身的时间)。在大流量场景下可以水平扩展,通过数据库共享配置和用量数据。
成本追踪是否准确?
LiteLLM 内置了 100+ 模型的定价表,并且持续更新。对于大部分主流模型,成本计算是准确的。如果你使用的是私有部署或自定义模型,可以手动注册成本参数。
总结
LiteLLM 解决了多 LLM 提供商集成中的核心痛点:统一接口、自动容错、成本追踪。它有两种使用方式:
- Python SDK:适合在代码中直接控制模型调用,提供
completion()、embedding()、Router 等功能
- Proxy Server:适合团队级统一网关,提供集中认证、限流、成本分摊、用量监控等功能
如果你正在开发多模型应用、构建 AI 网关,或者厌倦了为每个模型提供商写不同的适配代码,LiteLLM 值得一试。
参考资源