LiteLLM：统一 100+ LLM API 的代理网关¶

为什么要学 LiteLLM¶

在实际项目中，你可能同时使用 OpenAI、Anthropic、Gemini、Mistral、本地 Ollama 等多个模型。每个提供商的 API 格式、认证方式、错误处理都不同，维护成本随着模型数量线性增长。

LiteLLM 解决的核心问题是：用一套统一的 OpenAI 格式 API 调用任何 LLM 提供商。它既是一个 Python SDK，也可以作为独立的代理服务器部署。对于团队来说，LiteLLM Proxy 还提供了 API Key 管理、预算控制、负载均衡、请求日志等企业级功能。

适用场景： - 多模型切换和 A/B 测试 - 团队统一 LLM 网关（统一计费和管理） - 模型容灾（主模型挂了自动切备用模型） - 成本控制（设置预算上限） - 开发时快速比较不同模型效果

核心概念¶

白话解释¶

概念	白话说明
completion()	统一调用函数，格式兼容 OpenAI，但可以路由到任何模型
LiteLLM Proxy	独立部署的代理服务器，提供 OpenAI 兼容 API 端点
Router	路由器，支持负载均衡、容灾切换、按策略分配请求
Fallbacks	备用模型列表，主模型失败时自动切换
Budget Manager	预算管理器，按 key/用户/团队设置花费上限
Virtual Key	虚拟 API Key，不暴露真实 key，可设权限和额度
Callbacks	回调系统，将日志发送到 Langfuse/Helicone/自定义端点
Model Group	模型组，将多个部署归为一组实现负载均衡

支持的提供商（部分）¶

类别	提供商
商用API	OpenAI, Anthropic, Google Gemini, Mistral, Cohere
云平台	Azure OpenAI, AWS Bedrock, Google Vertex AI
开源推理	Ollama, vLLM, Together AI, Groq, Fireworks
国内厂商	DeepSeek, 智谱AI, 百度文心
其他	Replicate, Perplexity, OpenRouter

安装配置¶

SDK 安装¶

pip install litellm

Proxy Server 安装¶

# 安装带 proxy 支持的版本
pip install litellm[proxy]

# 或使用 Docker
docker pull ghcr.io/berriai/litellm:main-latest

环境变量配置¶

# .env
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GEMINI_API_KEY=xxx
GROQ_API_KEY=gsk_xxx
DEEPSEEK_API_KEY=xxx

验证¶

import litellm
response = litellm.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hi"}]
)
print(response.choices[0].message.content)

快速上手¶

基本调用（SDK 方式）¶

import litellm

# OpenAI
response = litellm.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "什么是 Docker？一句话回答。"}]
)
print(response.choices[0].message.content)

# Anthropic（同样的调用格式）
response = litellm.completion(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "什么是 Docker？一句话回答。"}]
)
print(response.choices[0].message.content)

# Ollama 本地模型
response = litellm.completion(
    model="ollama/llama3.1",
    messages=[{"role": "user", "content": "什么是 Docker？一句话回答。"}]
)
print(response.choices[0].message.content)

流式输出¶

import litellm

response = litellm.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一首关于编程的诗"}],
    stream=True
)

for chunk in response:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

异步调用¶

import asyncio
import litellm

async def main():
    response = await litellm.acompletion(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "异步调用测试"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

进阶用法¶

1. 部署 LiteLLM Proxy Server¶

创建 config.yaml:

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: sk-xxx

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: sk-ant-xxx

  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: xxx

  # 负载均衡：同一个名字多个部署
  - model_name: fast-model
    litellm_params:
      model: groq/llama-3.1-70b-versatile
      api_key: gsk_xxx
  - model_name: fast-model
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: sk-xxx

general_settings:
  master_key: sk-litellm-master-xxx  # 管理员 key

启动：

litellm --config config.yaml --port 4000

# 或用 Docker
docker run -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

使用（完全兼容 OpenAI SDK）：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-litellm-master-xxx"
)

response = client.chat.completions.create(
    model="fast-model",  # 自动负载均衡
    messages=[{"role": "user", "content": "hello"}]
)

2. 容灾与 Fallback¶

import litellm
from litellm import Router

router = Router(
    model_list=[
        {
            "model_name": "primary",
            "litellm_params": {"model": "gpt-4o-mini", "api_key": "sk-xxx"}
        },
        {
            "model_name": "fallback-1",
            "litellm_params": {"model": "claude-3-5-sonnet-20241022", "api_key": "sk-ant-xxx"}
        },
        {
            "model_name": "fallback-2",
            "litellm_params": {"model": "groq/llama-3.1-70b-versatile", "api_key": "gsk_xxx"}
        },
    ],
    fallbacks=[
        {"primary": ["fallback-1", "fallback-2"]}
    ],
    retry_after=5  # 5秒后重试
)

# primary 失败会自动切到 fallback-1，再失败切 fallback-2
response = await router.acompletion(
    model="primary",
    messages=[{"role": "user", "content": "test"}]
)

3. 预算控制¶

# config.yaml 中设置
general_settings:
  master_key: sk-master-xxx
  database_url: postgresql://user:pass@localhost/litellm

# 通过 API 创建有预算限制的 key
# POST /key/generate
# {
#   "max_budget": 10.0,  # 最多花 $10
#   "budget_duration": "monthly",
#   "models": ["gpt-4o-mini", "claude-sonnet"]  # 限制可用模型
# }

Python 使用：

import litellm

litellm.max_budget = 50.0  # 全局预算上限 $50
litellm.budget_duration = "daily"

# 超预算时会抛出 BudgetExceededError

4. 请求日志与可观测性¶

import litellm

# 发送到 Langfuse
litellm.success_callback = ["langfuse"]
litellm.failure_callback = ["langfuse"]

# 或自定义回调
def my_logger(kwargs, response, start_time, end_time):
    print(f"模型: {kwargs['model']}")
    print(f"耗时: {end_time - start_time}")
    print(f"Token: {response.usage.total_tokens}")
    print(f"成本: ${litellm.completion_cost(response)}")

litellm.success_callback = [my_logger]

5. 嵌入模型统一调用¶

import litellm

# OpenAI embeddings
resp = litellm.embedding(
    model="text-embedding-3-small",
    input=["Hello world", "你好世界"]
)

# Cohere embeddings（同样格式）
resp = litellm.embedding(
    model="cohere/embed-english-v3.0",
    input=["Hello world"]
)

# 获取向量
vectors = [item["embedding"] for item in resp.data]

6. 成本追踪¶

import litellm

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

# 计算成本
cost = litellm.completion_cost(completion_response=response)
print(f"本次调用成本: ${cost:.6f}")

# 或者查询模型价格
info = litellm.get_model_info("gpt-4o")
print(f"输入价格: ${info['input_cost_per_token']}")
print(f"输出价格: ${info['output_cost_per_token']}")

常见问题¶

Q1: LiteLLM Proxy 和直接用 SDK 有什么区别¶

方式	适用场景
SDK (litellm.completion)	单人开发、脚本、快速原型
Proxy Server	团队共用、需要 key 管理/计费/日志

Proxy 本质上是一个 OpenAI API 兼容的网关，任何支持 OpenAI API 的工具都可以直接接入。

Q2: 如何知道一个模型的调用格式¶

# LiteLLM 会自动处理格式转换，你只需要知道模型名称前缀
# openai/xxx    → OpenAI
# anthropic/xxx → Anthropic
# groq/xxx      → Groq
# ollama/xxx    → Ollama
# deepseek/xxx  → DeepSeek
# bedrock/xxx   → AWS Bedrock

# 查看所有支持的模型
print(litellm.model_list)

Q3: 和 OpenRouter 有什么区别¶

OpenRouter 是托管服务（你要向他们付费）
LiteLLM 是自建网关（你直接向各模型提供商付费）
LiteLLM 可以部署在自己的基础设施上，数据不经过第三方

Q4: 如何处理速率限制（Rate Limit）¶

router = Router(
    model_list=[...],
    routing_strategy="least-busy",  # 路由到最不忙的部署
    num_retries=3,
    retry_after=2,
    allowed_fails=2  # 允许失败2次后标记部署为不可用
)

Q5: 支持 Function Calling / Tool Use 吗¶

支持。LiteLLM 会将 OpenAI 格式的 tools 参数自动转换为各模型的原生格式：

response = litellm.completion(
    model="anthropic/claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "查询天气"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
        }
    }]
)

参考资源¶

资源	链接
GitHub 仓库	https://github.com/BerriAI/litellm
官方文档	https://docs.litellm.ai
支持的模型列表	https://docs.litellm.ai/docs/providers
Proxy 部署文档	https://docs.litellm.ai/docs/proxy/quick_start
PyPI	https://pypi.org/project/litellm
Docker Hub	https://github.com/BerriAI/litellm/pkgs/container/litellm

小结： LiteLLM 是 LLM 领域的"反向代理"——就像 Nginx 统一了后端服务，LiteLLM 统一了 LLM API。无论你是个人开发者想快速切换模型，还是团队需要统一的 AI 网关，LiteLLM 都是基础设施级别的必备工具。