1. 什么是 LiteLLM？ #

LiteLLM 是一个 Python 库，用来统一调用各种大模型 API。你写一套代码，只需改模型名和 API Key，就能切换 OpenAI、DeepSeek、Claude、通义千问等不同厂商的模型。

通俗理解：就像「万能遥控器」——不同品牌的电视遥控器按键不一样，但万能遥控器可以控制所有电视，你只需要选「哪个品牌」。LiteLLM 就是大模型调用的「万能遥控器」。

2. 前置知识：大模型 API 是什么？ #

大模型（如 GPT、Claude、DeepSeek）通常通过 HTTP API 提供能力：你发送一段文本（提示），模型返回生成的文本。

不同厂商的 API 格式不同：

• 请求地址：OpenAI 用 api.openai.com，DeepSeek 用 api.deepseek.com
• 参数名：有的用 model，有的用 model_id
• 认证方式：都是 API Key，但请求头名称可能不同

LiteLLM 把这些差异统一成一套接口，你只需指定 model="deepseek/deepseek-chat" 或 model="gpt-3.5-turbo"，它会自动选择正确的地址和格式。

3. 为什么需要 LiteLLM？ #

痛点	LiteLLM 的解决方式
多模型切换麻烦	同一套代码，改 model 参数即可
API 格式不统一	统一成 completion(model, messages) 接口
密钥管理分散	用环境变量，按厂商名设置即可
错误处理各异	统一错误处理和重试逻辑

4. 安装 #

基础安装（仅调用 API）：

pip install litellm

含代理服务器（需启动 litellm --model xxx 时）：

pip install 'litellm[proxy]'

若使用 uv：uv add litellm 或 uv add 'litellm[proxy]'

5. 使用DeepSeek #

使用 DeepSeek 模型。运行前请设置环境变量 DEEPSEEK_API_KEY，或在 .env 中配置。

# 导入 litellm
import litellm

# 调用 DeepSeek：model 格式为 "厂商/模型名"
# 运行前请设置环境变量 DEEPSEEK_API_KEY，例如：set DEEPSEEK_API_KEY=sk-xxx
response = litellm.completion(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "用一句话介绍 Python"}],
)

# 从返回结果中取出模型生成的文本
print(response.choices[0].message.content)

运行方式：保存为 demo.py，执行 pip install litellm 后运行 python demo.py。需先设置环境变量 DEEPSEEK_API_KEY。

6. 核心用法：completion #

6.1 基本调用格式 #

litellm.completion() 是同步调用，参数格式与 OpenAI 类似。

# 导入 litellm
import litellm

# completion 参数说明：
# - model: 模型名，格式为 "厂商/模型" 或直接 "openai/gpt-3.5-turbo"
# - messages: 对话消息列表，每项为 {"role": "user"|"assistant"|"system", "content": "..."}
response = litellm.completion(
    model="deepseek/deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "1+1 等于几？"},
    ],
)

# 获取模型回复
text = response.choices[0].message.content
print(text)

6.2 常用模型名称格式 #

厂商	模型格式示例	环境变量
DeepSeek	deepseek/deepseek-chat	DEEPSEEK_API_KEY
OpenAI	openai/gpt-3.5-turbo	OPENAI_API_KEY
通义千问	tongyi/qwen-turbo	DASHSCOPE_API_KEY

7. 流式输出（stream=True） #

当回复较长时，可以开启流式输出，边生成边打印，提升体验。

# 导入 litellm 库
import litellm

# 调用 completion 方法，设置 stream=True 开启流式输出
response = litellm.completion(
    model="deepseek/deepseek-chat",  # 指定调用的模型
    messages=[{"role": "user", "content": "用三句话介绍北京"}],  # 设置对话内容
    stream=True,  # 启动流式响应
)

# 遍历流式返回的每一个分块
for chunk in response:
    # 判断当前分块的 choices 是否为空，若为空则跳过本轮循环
    if not chunk.choices:
        continue

    # 提取分块中的 delta 信息
    delta = chunk.choices[0].delta
    # 取出本次分块的内容，如果 delta 为空则置为 ""
    content = (delta.content if delta else "") or ""
    # 如果当前内容不为空，则实时输出到终端，不换行
    if content:
        print(content, end="", flush=True)

    # 判断本分块是否收到 stop 信号，如果是则结束循环
    if chunk.choices[0].finish_reason == "stop":
        break

# 输出换行，防止终端光标断行问题
print()

8. 异步调用（acompletion） #

在异步程序中（如 FastAPI、asyncio）使用 acompletion，避免阻塞。

# 导入 litellm 和 asyncio
import litellm
import asyncio


# 定义异步函数
async def main():
    # 使用 await 调用 acompletion
    response = await litellm.acompletion(
        model="deepseek/deepseek-chat",
        messages=[{"role": "user", "content": "你好"}],
    )
    print(response.choices[0].message.content)


# 运行异步函数
if __name__ == "__main__":
    asyncio.run(main())

9. 模型回退（fallbacks） #

当主模型调用失败（如超时、配额不足）时，自动尝试备用模型。

# 导入 litellm 库，用于调用多种大模型接口
import litellm

# 调用 completion 方法生成对话回复
response = litellm.completion(
    # 指定主模型为 deepseek/deepseek-chat
    model="deepseek/deepseek-chat",
    # 设置消息内容，用户发送"你好"
    messages=[{"role": "user", "content": "你好"}],
    # 如果主模型失败，依次尝试 gpt-3.5-turbo 和 gpt-4 作为备用
    fallbacks=["openai/gpt-3.5-turbo", "openai/gpt-4"],
)

# 输出模型生成的回复内容（第一条回复）
print(response.choices[0].message.content)

注意：备用模型需要已配置对应的 API Key（如 OPENAI_API_KEY）。

10. 多模型切换 #

# 导入 litellm 库
import litellm

# 可以根据所用模型，预先在环境变量中配置 API 密钥，例如 DEEPSEEK_API_KEY 或 OPENAI_API_KEY

# 定义一个统一的对话接口
def chat(model, prompt):
    # 使用 litellm.completion 方法生成回复
    response = litellm.completion(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    # 返回模型的第一条回复内容
    return response.choices[0].message.content


# 程序主入口
if __name__ == "__main__":
    # 定义用户输入的问题
    prompt = "用一句话介绍 LiteLLM"
    # 设置要调用的模型列表
    models = ["deepseek/deepseek-chat", "openai/gpt-3.5-turbo"]
    # 若已配置 OPENAI_API_KEY，可加入 "openai/gpt-3.5-turbo"
    for m in models:
        try:
            # 调用 chat 函数获取回复
            reply = chat(m, prompt)
            # 输出模型和回复内容
            print(f"[{m}] {reply}")
        except Exception as e:
            # 若调用出错，输出错误信息
            print(f"[{m}] 调用失败: {e}")

11. 环境变量与 API Key #

LiteLLM 通过环境变量读取各厂商的 API Key，无需在代码中硬编码。

厂商	环境变量
DeepSeek	DEEPSEEK_API_KEY
OpenAI	OPENAI_API_KEY
Anthropic (Claude)	ANTHROPIC_API_KEY
通义千问	DASHSCOPE_API_KEY

推荐使用 .env 文件管理，配合 python-dotenv 加载。

12. litellm[proxy]：代理服务器 #

12.1 什么是 litellm[proxy]？ #

litellm[proxy] 是 LiteLLM 的可选依赖，安装后可以启动一个本地代理服务器。客户端不直接调用各厂商 API，而是统一请求这个代理，由代理转发到对应模型。适合团队共享、统一管理密钥和负载均衡。

通俗理解：就像「前台」——所有人找前台，前台再帮你联系各个部门。客户端只和代理打交道，代理负责选模型、带密钥、转发请求。

12.2 安装 #

pip install litellm[proxy]

若使用 uv：uv add 'litellm[proxy]'

12.3 启动代理 #

# 指定模型并启动，默认监听 0.0.0.0:4000
litellm --model deepseek/deepseek-chat

启动前需设置 DEEPSEEK_API_KEY。代理启动后，会提供与 OpenAI 兼容的接口，客户端可把 base_url 指向 http://localhost:4000 调用。

12.4 使用配置文件启动（--config） #

当需要配置多个模型、自定义 API 地址或超时等参数时，可把配置写在 YAML 文件中，用 --config 指定。

config.yaml 示例：

# Model routing list
model_list:
  # Public model name exposed to clients
  - model_name: deepseek/deepseek-chat
    litellm_params:
      # Upstream model
      model: deepseek/deepseek-chat
      # DeepSeek official OpenAI-compatible endpoint
      api_base: https://api.deepseek.com/v1
      # Read key from environment variable
      api_key: sk-fe9bb5999fbd432795bb3a9297c31e36
      timeout: 60
      stream_timeout: 30

# General settings
general_settings:
  # Proxy auth key from environment variable
  master_key: sk-1234567890
  # Database URL
  database_url: postgresql://postgres:123456@localhost:5432/litellm
  # Store prompts in spend logs
  store_prompts_in_spend_logs: true
  # Store model in database
  store_model_in_db: true

# LiteLLM behavior settings
litellm_settings:
  # Keep SSL certificate verification enabled
  ssl_verify: true
  set_verbose: false

启动命令：

litellm --config config.yaml

代理会读取 config.yaml，按其中 model_list 加载模型。客户端调用时，model 填 model_name（如 deepseek/deepseek-chat）。

api_key 写法：os.environ/DEEPSEEK_API_KEY 表示从环境变量读取，避免在配置中写明文密钥。

12.5 调试模式（--detailed_debug） #

排查问题时，可加上 --detailed_debug，在终端输出更详细的请求、响应和错误信息。

prisma generate
litellm --config config.yaml --detailed_debug

输出包括：请求 URL、请求体、响应状态、错误堆栈等，便于定位超时、认证或模型不可用等问题。

访问管理界面

http://127.0.0.1:4000/ui

12.6 客户端调用代理 #

# 导入 OpenAI 客户端库（LiteLLM 代理兼容 OpenAI 格式）
from openai import OpenAI

# 创建 OpenAI 客户端实例，指定代理服务器的 base_url 和任意 api_key
client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-1234567890",
)

# 调用 chat.completions.create 方法，向指定模型发送一条消息请求
response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "你好"}],
)

# 输出响应结果的第一条回复内容
print(response.choices[0].message.content)

运行顺序：先启动代理 litellm --model deepseek/deepseek-chat，再运行上述客户端脚本。

12.7 小结 #

要点	说明
安装	pip install 'litellm[proxy]'
启动	litellm --model 模型名 或 litellm --config config.yaml
配置文件	--config config.yaml 指定 YAML 配置，支持多模型、自定义 api_base 等
调试	--detailed_debug 输出详细请求/响应日志
默认端口	4000
客户端	使用 OpenAI 客户端，base_url 指向代理地址

13. 总结 #

• LiteLLM 提供统一的 completion() / acompletion() 接口，一套代码调用多种模型。
• 模型名 格式为 厂商/模型，如 deepseek/deepseek-chat。
• API Key 通过环境变量配置，按厂商名设置。
• 流式输出 使用 stream=True，异步调用 使用 acompletion()，模型回退 使用 fallbacks 参数。
• litellm[proxy] 可安装代理依赖，用 litellm --model 模型名 或 litellm --config config.yaml 启动本地网关，--detailed_debug 可开启调试日志。