LiteLLM 万能模型代理

统一调用 100+ 大模型的代理层，支持 OpenAI、Anthropic、Gemini、Ollama、DeepSeek 等，提供统一 API 接口和智能路由。

官网：https://docs.litellm.ai/ GitHub：https://github.com/BerriAI/litellm

---

一、LiteLLM 是什么

1.1 定位

LiteLLM 是一个大模型统一代理层，解决以下问题：

• 协议转换：不同模型 API 格式不同，LiteLLM 统一为 OpenAI 格式
• 多模型管理：一个配置文件管理所有模型供应商
• 智能路由：按成本、延迟、可用性自动选择模型
• 负载均衡：多 API Key / 多实例分流
• 降级容错：某个模型挂了自动切到备用模型
• 成本监控：统一统计 Token 消耗和费用

1.2 核心价值

价值	说明
统一接口	所有模型都用 OpenAI 格式调用
灵活切换	改配置即可换模型，不用改代码
成本优化	自动选最便宜的可用模型
高可用	故障自动转移，避免单点
本地兼容	本地 Ollama 模型也能统一管理

---

二、安装与快速开始

2.1 安装

# 安装代理服务（包含所有依赖）
pip install 'litellm[proxy]'

# 或仅安装 SDK
pip install litellm

2.2 最简配置

创建 litellm_config.yaml：

model_list:
  - model_name: gpt-3.5-turbo
    litellm_params:
      model: openai/gpt-3.5-turbo
      api_key: "你的-OPENAI-KEY"

启动代理：

litellm --config litellm_config.yaml --port 4000

测试：

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-dummy" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "你好"}]
  }'

---

三、配置文件详解

3.1 基础结构

# 全局设置
litellm_settings:
  drop_params: true          # 自动丢弃模型不支持的参数
  set_verbose: false         # 详细日志
  master_key: "sk-admin-key" # 管理 API 密钥

# 模型列表
model_list:
  - model_name: 对外暴露的模型名
    litellm_params:
      model: 供应商/实际模型名
      api_key: "API密钥"
      api_base: "API地址"    # 可选，自定义端点

# 路由策略（可选）
router_settings:
  routing_strategy: least-budget  # 路由策略
  num_retries: 3                  # 重试次数
  timeout: 60                     # 超时时间

3.2 支持的模型供应商

供应商	前缀	示例
OpenAI	openai/	openai/gpt-4o
Anthropic	anthropic/	anthropic/claude-3-5-sonnet
Gemini	gemini/	gemini/gemini-2.5-flash
Ollama	ollama/	ollama/deepseek-r1:14b
DeepSeek	deepseek/	deepseek/deepseek-chat
通义千问	qwen/	qwen/qwen-turbo
智谱	zhipu/	zhipu/glm-4
月之暗面	moonshot/	moonshot/kimi-chat
本地自定义	openai/ + api_base	任意 OpenAI 兼容服务

3.3 配置文件作用域与管理

配置文件放置位置

litellm_config.yaml 只是普通文件，作用域取决于放置位置：

放置位置	作用域	说明
./litellm_config.yaml（项目目录）	项目级别	只在这个项目使用
~/.litellm/config.yaml（用户目录）	用户级别	当前用户所有项目可用
/etc/litellm/config.yaml（系统目录）	系统级别	所有用户可用

启动时指定任意路径：

litellm --config /path/to/litellm_config.yaml --port 4000

代理服务的全局特性

一旦启动，LiteLLM 代理就是全局服务：

• 运行在 localhost:4000，任何项目、任何工具都能连接
• 只要代理不重启，配置一直生效
• 多个客户端可以同时使用同一个代理

项目 A (Claude Code) ──┐
项目 B (Python 脚本) ──┼──> localhost:4000 (LiteLLM) ──> 各种模型
项目 C (Open WebUI) ───┘

项目级别隔离方案

如果不同项目需要不同模型配置，有两种方式：

方式 A：一个代理，多个模型名（推荐）

同一个配置文件定义多个模型，项目按需选择：

model_list:
  - model_name: project-a-model    # 项目 A 用
    litellm_params:
      model: ollama/deepseek-r1:14b

  - model_name: project-b-model    # 项目 B 用
    litellm_params:
      model: gemini/gemini-2.5-flash
      api_key: "xxx"

各项目配置自己的环境变量：

# 项目 A
export ANTHROPIC_MODEL="project-a-model"

# 项目 B
export ANTHROPIC_MODEL="project-b-model"

方式 B：多个代理实例（不同端口）

# 项目 A 的代理
litellm --config ~/project-a/litellm.yaml --port 4001

# 项目 B 的代理
litellm --config ~/project-b/litellm.yaml --port 4002

各项目连不同端口：

# 项目 A
export ANTHROPIC_BASE_URL="http://localhost:4001"

# 项目 B
export ANTHROPIC_BASE_URL="http://localhost:4002"

推荐目录结构

~/.litellm/
├── config.yaml          # 主配置（常用模型）
├── project-a.yaml       # 项目专属配置
└── logs/                # 日志目录

---

四、典型使用场景

4.1 场景一：连接本地 Ollama 模型

需求：让支持 OpenAI API 的工具（Claude Code、Open WebUI 等）使用本地模型。

配置 litellm_config.yaml：

litellm_settings:
  drop_params: true

model_list:
  - model_name: claude-3-5-sonnet    # 对外伪装成 Claude 模型
    litellm_params:
      model: ollama/deepseek-r1:14b  # 实际用本地 Ollama 模型
      api_base: http://localhost:11434

启动：

litellm --config litellm_config.yaml --port 4000

使用（以 Claude Code 为例）：

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-dummy-key"
claude

原理：Claude Code 以为在调用 Claude，LiteLLM 把请求转发给本地 Ollama，并转换协议格式。

请求事件流详解

整个链路涉及三个组件，两个端口：

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│  LiteLLM Proxy       │────▶│  Ollama Service │
│  (终端客户端)    │     │  (localhost:4000)    │     │  (localhost:11434)│
│                 │◀────│                      │◀────│                 │
└─────────────────┘     └──────────────────────┘     └─────────────────┘
   Anthropic格式           协议转换 + 模型映射          本地模型推理
   /v1/messages            Anthropic → Ollama          deepseek-r1:14b

各组件职责：

组件	端口	职责
Claude Code	—	终端交互，发 Anthropic 格式请求
LiteLLM	4000	接收请求 → 匹配模型名 → 协议转换 → 转发
Ollama	11434	加载本地模型，执行推理，流式返回

完整请求步骤：

1. 用户在 Claude Code 输入问题
2. Claude Code 构造 Anthropic /v1/messages 请求
   → model: "claude-3-5-sonnet"（客户端选中的模型名）
   → 发送到 ANTHROPIC_BASE_URL = http://localhost:4000
3. LiteLLM 收到请求，在 model_list 中匹配 model_name
   → 命中 claude-3-5-sonnet → 实际后端 ollama/deepseek-r1:14b
4. LiteLLM 做协议转换
   → Anthropic 格式 → Ollama /api/chat 格式
   → 转发到 api_base = http://localhost:11434
5. Ollama 加载 deepseek-r1:14b 执行推理
   → 流式生成 token，逐块返回给 LiteLLM
6. LiteLLM 把 Ollama 响应转回 Anthropic 格式
   → 流式返回给 Claude Code
7. Claude Code 逐字显示回答

两个端口的区别：

• --port 4000：LiteLLM 自己的监听端口，客户端连它
• api_base: http://localhost:11434：告诉 LiteLLM 后端 Ollama 在哪，LiteLLM 连它

排查问题时按链路逐段验证：

1. curl http://localhost:11434/api/tags → Ollama 是否正常
2. curl http://localhost:4000/v1/models → LiteLLM 是否正常、模型是否加载
3. Claude Code 输入 /status → 客户端是否连到代理

4.2 场景二：用 Gemini API 驱动 Claude Code（省钱方案）

需求：Claude Code 客户端 + Gemini API（更便宜）。

litellm_settings:
  drop_params: true

model_list:
  - model_name: claude-3-5-sonnet
    litellm_params:
      model: gemini/gemini-2.5-flash
      api_key: "你的-GEMINI-API-KEY"

启动和使用同上。

4.3 场景三：多模型智能路由

需求：多个模型备选，自动选最便宜/最快的。

model_list:
  - model_name: my-chat-model       # 同一个对外名称
    litellm_params:
      model: openai/gpt-3.5-turbo
      api_key: "sk-xxx"
  - model_name: my-chat-model       # 同一个对外名称，多个后端
    litellm_params:
      model: anthropic/claude-3-haiku
      api_key: "sk-ant-xxx"
  - model_name: my-chat-model
    litellm_params:
      model: ollama/deepseek-r1:7b  # 本地模型作为兜底
      api_base: http://localhost:11434

router_settings:
  routing_strategy: least-budget    # 优先选最便宜的
  num_retries: 2
  fallbacks: [
    {"my-chat-model": ["ollama/deepseek-r1:7b"]}  # 失败降级到本地
  ]

调用时只需要指定 model: my-chat-model，LiteLLM 自动选择后端。

4.4 场景四：API Key 池负载均衡

需求：多个 API Key 轮流使用，避免限流。

model_list:
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-key-1"
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-key-2"
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-key-3"

router_settings:
  routing_strategy: round-robin  # 轮询

4.5 场景五：统一监控所有模型调用

启动代理后，访问管理界面：

# 启动时指定管理密钥
litellm --config config.yaml --port 4000 --master_key sk-admin

# 访问 UI
open http://localhost:4000/ui

可以查看：

• 每个模型的调用次数、Token 消耗
• 成功率、延迟统计
• 成本分析
• 实时日志

---

五、路由策略详解

策略	说明	适用场景
simple	按顺序尝试，成功就返回	简单备用
least-budget	选当前剩余预算最多的	成本控制
least-latency	选延迟最低的	性能优先
round-robin	轮询分配	负载均衡
random	随机选择	测试场景
usage-based-routing	基于历史用量智能选择	复杂生产环境

---

六、与 Claude Code 配合使用

6.1 完整配置步骤

1. 创建配置文件 litellm_config.yaml

litellm_settings:
  drop_params: true

model_list:
  - model_name: claude-3-5-sonnet-20241022
    litellm_params:
      model: ollama/deepseek-r1:14b
      api_base: http://localhost:11434

2. 启动 LiteLLM 代理

litellm --config litellm_config.yaml --port 4000

3. 配置 Claude Code 环境变量

# 在项目目录创建 .env，或直接导出
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-dummy-key"
export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"

4. 启动 Claude Code

claude

5. 验证

在 Claude Code 中输入 /status，确认模型和连接状态。

6.2 注意事项

• 工具调用：确保本地模型支持 function calling（deepseek-r1 支持）
• 上下文窗口：代码分析需要大上下文，建议 Ollama 模型配置 num_ctx 32768
• 思考过程：deepseek-r1 的 <think> 标签可能会被 Claude Code 显示，可在 LiteLLM 中配置过滤

6.3 环境变量管理与项目隔离

环境变量作用域

Claude Code 通过环境变量连接 LiteLLM，不同配置方式作用域不同：

配置方式	作用域	说明
终端直接 export	当前会话	关掉终端失效
写入 ~/.zshrc / ~/.bashrc	全局	所有终端永久生效
项目 .env + direnv	项目级别	进入目录自动加载，离开自动恢复
claude config set	Claude Code 全局	Claude Code 内部配置

推荐：direnv 实现项目级隔离

direnv 可以让你进入项目目录时自动加载环境变量，离开时自动恢复，实现项目级别的模型配置隔离。

安装与配置：

# 1. 安装 direnv
brew install direnv

# 2. 在 shell 配置中启用（~/.zshrc 或 ~/.bashrc）
eval "$(direnv hook zsh)"   # zsh 用户
# eval "$(direnv hook bash)" # bash 用户

# 3. 重启终端或 source 配置
source ~/.zshrc

项目配置：

# 进入项目目录
cd my-project

# 创建 .env 文件
cat > .env << 'EOF'
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-dummy-key"
export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"
EOF

# 允许 direnv 加载（首次需要授权）
direnv allow .

# 验证
echo $ANTHROPIC_BASE_URL
# 输出: http://localhost:4000

效果：

• 进入 my-project 目录：自动设置环境变量，Claude Code 用本地模型
• 离开目录：环境变量自动恢复，不影响其他项目

多项目配置示例

~/project-a/
└── .env  → ANTHROPIC_MODEL="project-a-model"（本地 deepseek）

~/project-b/
└── .env  → ANTHROPIC_MODEL="project-b-model"（Gemini）

~/project-c/
└── （无 .env）→ 使用全局配置或官方 Claude

安全提示

• .env 文件包含 API Key，不要提交到 Git
• 在 .gitignore 中添加 .env
• 可以提供 .env.example 作为模板

---

七、常见问题

7.1 模型不支持某些参数怎么办？

litellm_settings:
  drop_params: true  # 自动丢弃不支持的参数

7.2 如何调试请求？

# 启动时开启详细日志
litellm --config config.yaml --port 4000 --detailed_debug

7.3 本地 Ollama 模型名怎么写？

格式：ollama/模型名:标签

model: ollama/deepseek-r1:14b
model: ollama/qwen2.5:7b
model: ollama/llama3.1:8b

7.4 如何设置请求超时？

router_settings:
  timeout: 120  # 秒，默认 60
  num_retries: 3

7.5 生产环境部署建议

• 使用 Docker 部署
• 配置 Redis 做缓存和状态共享
• 设置 master_key 保护管理接口
• 配合 Nginx 做反向代理和 HTTPS

---

八、相关链接

• 官方文档：https://docs.litellm.ai/
• Proxy 文档：https://docs.litellm.ai/docs/simple_proxy
• 模型支持列表：https://docs.litellm.ai/docs/providers
• GitHub：https://github.com/BerriAI/litellm
• Claude Code 配置：见 Claude Code 文档

---

九、总结

维度	说明
定位	大模型统一代理层
核心能力	协议转换、多模型管理、智能路由、负载均衡
适用场景	多模型切换、成本优化、高可用、本地模型接入
学习曲线	中等，配置文件驱动
与 Ollama 关系	Ollama 提供本地模型，LiteLLM 做统一接入和路由

一句话：LiteLLM 是「大模型界的 Nginx」，一个代理层统一管理所有模型，灵活切换、智能路由、高可用。