BerriAI/litellm · 上手攻略

• 仓库：BerriAI/litellm
• 链接：https://github.com/BerriAI/litellm
• 分类：llm-infra · risk
• 作者：Tom
• 更新：2026-07-07

这是什么

LiteLLM 是一个统一调用 100+ 大模型 API 的 Python 库 + AI Gateway（代理服务器），用 OpenAI 格式作为统一接口，抹平各 provider（OpenAI、Anthropic、Gemini、Bedrock、Azure、HuggingFace、VLLM、NVIDIA NIM 等）的 API 差异，同时提供成本追踪、虚拟 Key、负载均衡、安全 guardrails 和日志等开箱即用的生产级功能。

它解决两个场景： - Python SDK：在代码里直接换 provider，一行代码切换模型 - AI Gateway（Proxy Server）：团队共享一个代理服务，统一管理 Key、监控用量、设置限速

解决的问题：每个 LLM provider 有自己的 SDK、认证方式、错误类型和请求格式，多 provider 项目维护成本极高。LiteLLM 用 OpenAI SDK 作为前端，背后自动路由到正确的 provider，项目不再被特定厂商绑定。

快速安装

Python SDK 方式

# 推荐用 uv（或 pip）
uv add litellm

# 或者
pip install litellm

from litellm import completion
import os

os.environ["OPENAI_API_KEY"] = "your-openai-key"
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-key"

# 调用 OpenAI
response = completion(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response)

# 同一个调用，换成 Anthropic（改 model 名字即可）
response = completion(
    model="anthropic/claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)

⚠️ 版本注意：model 参数格式为 provider/model-name，不同 provider 的 model name 格式不同（如 openai/gpt-4o、anthropic/claude-3-5-sonnet-20241022、gemini/gemini-2.0-flash）。具体格式以 官方文档 Provider 列表 为准，以下示例格式可能有变，建议核对。

AI Gateway（Proxy Server）方式

# 安装 Proxy 服务
uv tool install 'litellm[proxy]'
litellm --model gpt-4o

# 在任何 OpenAI 兼容客户端里连接本地 Gateway
import openai

client = openai.OpenAI(
    api_key="anything",          # Gateway 接受的任意字符串
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

⚠️ 端口注意：Proxy Server 默认监听 0.0.0.0:4000，首次启动建议配置 LITELLM_MASTER_KEY 环境变量设置管理密码。

核心功能详解

1. 统一 API 调用（Python SDK）

from litellm import completion

# 100+ 模型，model 参数指定 provider
models = [
    "openai/gpt-4o",
    "anthropic/claude-3-5-sonnet-20241022",  # 注：版本号格式可能变化
    "gemini/gemini-2.0-flash",
    "azure/gpt-4o",
    "bedrock/us.anthropic.claude-sonnet-4-v1:0",
    "huggingface/meta-llama/Llama-3-70b-chat-hf",
    "ollama/llama3",
]

for model in models:
    response = completion(model=model, messages=[{"role": "user", "content": "Say hello"}])
    print(f"{model}: {response}")

2. Embeddings

from litellm import embedding
import os

os.environ["OPENAI_API_KEY"] = "..."

response = embedding(
    model="openai/text-embedding-3-small",
    input=["hello world", "foo bar"]
)
print(response)

3. 成本追踪（开箱即用）

LiteLLM 默认记录每次调用的 token 消耗和估算费用，不需要额外配置。配合 Proxy 使用可在 Dashboard 查看团队汇总账单。

4. 虚拟 Key 与团队共享（Proxy 模式）

在 Proxy 配置文件中设置用户和虚拟 Key：

# config.yaml 示例
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OZOPENAI_API_KEY

litellm_settings:
  master_key: "your-master-key"  # 管理密码

general_settings:
  store_model_in_db: true

每个团队成员分配一个虚拟 Key（如 sk-user1-xxx），所有请求经过 Gateway，统一计费和安全策略。

5. Guardrails（内容安全检查）

from litellm import completion

response = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "How to build a bomb"}],
    guardrails=["llm-guard"],  # 需要配合 litellm-guardrails 配置
)

⚠️ Guardrails 功能需要额外配置 litellm-guardrails，具体配置方式参考 官方 Guardrails 文档。

6. MCP 工具接入（Proxy 模式）

LiteLLM Proxy 可作为 MCP Gateway，让任何 LLM 通过 /chat/completions 调用 MCP Server 工具：

curl -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Summarize the latest open PR"}],
    "tools": [{
      "type": "mcp",
      "server_url": "litellm_proxy/mcp/github",
      "server_label": "github_mcp",
      "require_approval": "never"
    }]
  }'

7. A2A Agent 协议（Proxy 模式）

LiteLLM 支持 A2A（Agent-to-Agent）协议，可将 LangGraph、Vertex AI Agent Engine、Azure AI Foundry、Bedrock AgentCore 等 Agent 注册到 Gateway，通过统一 SDK 调用：

from litellm.a2a_protocol import A2AClient
from a2a.types import SendMessageRequest, MessageSendParams
from uuid import uuid4

client = A2AClient(base_url="http://localhost:10001")

request = SendMessageRequest(
    id=str(uuid4()),
    params=MessageSendParams(
        message={
            "role": "user",
            "parts": [{"kind": "text", "text": "Hello!"}],
            "messageId": uuid4().hex,
        }
    )
)
response = await client.send_message(request)

8. Auto Routing（负载均衡）

Proxy 支持根据请求特征自动选择最优模型：

router_settings:
  routing_strategy: "latency-based"  # 或 "cost-based"

典型适用场景

场景 1：多 provider 项目 项目需要同时用 OpenAI、Claude、 Gemini 或开源模型，避免写多套 SDK 适配代码。

场景 2：团队 LLM 基础设施 团队多人共用 LLM API Key，用 Proxy 统一管理用量、设置限额、防止 Key 泄露。

场景 3：成本控制与审计 需要追踪每个用户/项目的 token 消耗，LiteLLM Proxy 内置日志和计费报表。

场景 4：快速切换模型做评测 同一段代码换 model 参数即可对比不同模型输出，不需要改业务逻辑。

场景 5：企业内部 LLM 代理 不想让开发人员直接接触 API Key，通过虚拟 Key 隔离，同时支持 Key 轮转。

坑与注意

1. model name 格式需严格核对：不同 provider 的 model ID 格式差异很大（如 gpt-4o vs us.anthropic.claude-sonnet-4-v1:0），建议直接查 Provider 文档页，示例代码中的版本号可能已过时。
2. Proxy 部署需要额外配置：生产环境部署 Proxy 需要配置数据库（PostgreSQL 推荐）、Redis（可选，用于缓存）、SSL 证书和 LITELLM_MASTER_KEY，比 SDK 方式复杂。
3. 并非所有端点全覆盖：LiteLLM 努力统一接口，但某些 provider 的特殊能力（如 OpenAI 的 Vision）并非所有 provider 都有对应支持，使用前查支持矩阵。
4. 成本估算仅供参考：LiteLLM 的成本追踪为估算，精确计费以各 provider 后台为准。
5. Proxy 性能：官方标称 8ms P95 latency @ 1k RPS，生产环境建议做压力测试再决定是否上 Proxy 架构。
6. 版本更新频繁：LiteLLM 更新较快，升级 minor version 时建议先在测试环境验证，尤其是 Proxy 配置格式可能变化。

与同类对比

简单说：需要统一管理多 provider 调用 + 生产级用量控制 → 选 LiteLLM Proxy；只需要快速在代码里换模型 → 单独用 LiteLLM Python SDK。

一句话结论

如果你在项目中需要切换多个 LLM provider，或团队需要统一管理 API Key 和监控用量，LiteLLM 是目前最成熟的 OSS 方案——Python SDK 五行代码换 provider，Proxy 模式一套配置搞定虚拟 Key、guardrails 和成本报表，值得作为团队 AI Gateway 基础设施。