litellm

你会遇到什么

这个工具解决什么问题：多个服务/多个人都要接模型，每个都配一遍 API key 和供应商地址？LiteLLM 是服务端网关：一个 OpenAI 兼容端点（默认端口 4000）统一接 100+ 模型供应商，带统一 key 管理、成本追踪、负载均衡。客户端只认一个 base_url。 什么时候用：

• 你要给多服务/多用户一个统一模型入口；
• 你要集中管理 key、看成本、做负载均衡；
• 你要在代理层做模型切换（改配置不动客户端）。

什么时候别用：单服务单模型直连——网关是额外一层，没有多消费方就不需要。 和相邻工具的边界：与 claude-code-router / cc-switch 层级不同——litellm 是服务端网关（多服务统一入口），后两者是客户端配置/路由；判定 possible-compatible，共装未实测。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：pip 装 litellm[proxy]（建议隔离 venv），litellm --config <yaml> --port <port> 启动代理。配置（model_list + litellm_settings）由 --config 指定路径，归用户管理，不写系统/用户级配置。健康检查 /health/liveliness，模型列表 /v1/models。 关键概念：

• model_list：模型清单（model_name + litellm_params.model/api_key）；
• openai/mock：免 key 冒烟模型（dummy key 可验证代理面）；
• drop_params：忽略供应商不支持的参数（冒烟配置里实测）。

装完它动哪里：不动系统配置；代理配置在 --config 指定路径；venv 在 ~/.litellm-venv（本路径实测）。

一步步来

第 1 步：装进隔离 venv（为什么 venv：litellm 依赖重，隔离环境卸载最干净）

讲解：litellm[proxy] 依赖多，装进独立 venv（~/.litellm-venv）避免污染系统 Python，卸载时删目录即完成。国内 PyPI 官方慢，用清华镜像（2026-08-29 实测 80s 装完）。

python3 -m venv ~/.litellm-venv
~/.litellm-venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple litellm[proxy]
~/.litellm-venv/bin/litellm --version

预期输出: LiteLLM: Current Version = 1.98.0

装好确认：

• --version 输出 1.98.0；
• 后续命令都用 ~/.litellm-venv/bin/litellm（或先激活 venv）。

卡住怎么办：

• pip 超时 → 确认命令带清华镜像前缀；
• venv 创建失败 → 确认 Python >= 3.8 且 venv 模块可用。

第 2 步：写最小代理配置（mock 冒烟，零账号）

讲解：真实使用需在配置里填模型 API key；本环境零账号，用 openai/mock + dummy key 冒烟——能完整验证代理面（启动、健康检查、模型列表），真实转发再换真实 key。

cat > /tmp/ltm-config.yaml <<'EOF'
model_list:
- model_name: mock-gpt
litellm_params:
model: openai/mock
api_key: dummy
litellm_settings:
drop_params: true
EOF

预期输出: 配置文件就绪（2026-08-29 实测）

装好确认：

• /tmp/ltm-config.yaml 内容正确。

卡住怎么办：

• 配置格式报错 → 检查 YAML 缩进与字段名（model_list/litellm_settings）。

第 3 步：启动代理 + 冒烟

讲解：litellm --config ... --port 8099 启动（默认 4000，这里用 8099 避免撞端口）。然后健康检查与模型列表验证代理面。

~/.litellm-venv/bin/litellm --config /tmp/ltm-config.yaml --port 8099

预期输出: Uvicorn running on http://0.0.0.0:8099（Application startup complete；2026-08-29 实测）

curl -s http://127.0.0.1:8099/health/liveliness
curl -s http://127.0.0.1:8099/v1/models

预期输出: "I'm alive!"；{"data":[{"id":"mock-gpt",...}]}（2026-08-29 实测）

装好确认：

• 启动日志出现 Uvicorn running；
• 两个 curl 返回预期内容。

卡住怎么办：

• 端口被占 → 换 --port（默认 4000，lsof -i :4000 查看）；
• 启动失败 → 先看配置（第 2 步）与日志。

怎么确认修好了

第 1 步：确认版本与命令面

讲解：venv 内的 litellm --version 输出 1.98.0，说明安装与 PATH 指向都对；之后所有命令统一用 ~/.litellm-venv/bin/litellm。

~/.litellm-venv/bin/litellm --version

预期输出: LiteLLM: Current Version = 1.98.0

卡住怎么办：

• 命令找不到 → 检查 venv 是否创建成功、路径是否写对；
• 版本不符 → 重新 pip install 并确认镜像前缀；
• 报 Missing dependency websockets / 提示装 litellm[proxy] → 装的是基础包 litellm（无 extras），litellm --version 会尝试启动代理而报缺依赖——必须装 litellm[proxy]（2026-08-31 隔离实测复现）。

第 2 步：启动代理并做健康检查（冒烟）

讲解：代理能启动、健康检查返回 I'm alive!、模型列表返回 mock-gpt，说明代理面完整可用；真实使用只需把配置里的 mock 换成真实模型与 key。

~/.litellm-venv/bin/litellm --config /tmp/ltm-config.yaml --port 8099

预期输出: Uvicorn running on http://0.0.0.0:8099（Application startup complete）

curl -s http://127.0.0.1:8099/health/liveliness
curl -s http://127.0.0.1:8099/v1/models

预期输出: "I'm alive!"；{"data":[{"id":"mock-gpt",...}]}

卡住怎么办：

• 端口被占 → 换 --port（默认 4000，lsof -i :4000 查看）；
• 启动失败 → 先看配置（第 2 步）与日志。

其它环境的表现（常见变体）

• 默认端口：代理默认监听 4000；本文用 8099 是为避免与常见服务撞端口，按需调整。
• Windows / macOS：pip 安装命令一致（仍建议清华镜像）；无系统级配置写面，代理配置全部由 --config 指向的文件决定。
• 隔离卸载：venv 场景下删掉 ~/.litellm-venv 目录即完成清理，不留系统残留。
• 后台进程：litellm 代理是前台/托管进程，不需要时 pkill 停止（如 pkill -f litellm）。

日常使用

启动与入口

• 启动：~/.litellm-venv/bin/litellm --config <路径> [--port <端口>]；
• 客户端统一用 http://127.0.0.1:<端口>（OpenAI 兼容）。

常用操作

操作一：写最小代理配置（mock 冒烟）

cat > /tmp/ltm-config.yaml <<'EOF'
model_list:
- model_name: mock-gpt
litellm_params:
model: openai/mock
api_key: dummy
litellm_settings:
drop_params: true
EOF

预期输出: 配置文件就绪（2026-08-29 实测）

操作二：启动代理服务

~/.litellm-venv/bin/litellm --config /tmp/ltm-config.yaml --port 8099

预期输出: Uvicorn running on http://0.0.0.0:8099（Application startup complete；2026-08-29 实测）

操作三：健康检查与模型列表

curl -s http://127.0.0.1:8099/health/liveliness
curl -s http://127.0.0.1:8099/v1/models

预期输出: "I'm alive!"；{"data":[{"id":"mock-gpt",...}]}（2026-08-29 实测）

数据与目录

• venv：~/.litellm-venv/；
• 代理配置：--config 指定路径（用户管理，如 /tmp/ltm-config.yaml）。

卸载与清理

note: 删除隔离 venv 即完成卸载；代理进程先停（kill）

pkill -f 'litellm.*--config' 2>/dev/null || true
rm -rf ~/.litellm-venv

预期输出: 无残留（venv 删除后命令面消失）

手动确认清单（如需彻底清理）：

• 代理配置（--config 指定路径，如 /tmp/ltm-config.yaml）
• 监听端口进程（默认 4000，lsof -i :4000 查看）

依赖警告

• 版本：[1.98.0, 1.98.0] 锁定（2026-08-29 实测版本）。
• 环境：Python >= 3.8；建议隔离 venv（依赖重）。
• 网络：PyPI 官方慢，必须清华镜像（2026-08-29 实测 80s）；启动时拉取远端模型价格表（raw.githubusercontent.com）超时会回退本地备份并打 WARNING，不影响功能（2026-08-31 隔离实测）。
• 端口：默认 4000（--port 可改）。
• 写面：无系统/用户级配置；代理配置归用户（--config 路径）。
• 后台进程：litellm 代理为前台/托管进程（pkill 停止）。
• 共装：与 logfire / claude-code-router 判定 possible-compatible（层级不同，写面不重叠推断）。

FAQ（常见问题）

• 问：会改我的配置吗？答：不写系统/用户级配置；代理配置由 --config 指定路径，归用户管理。
• 问：和 claude-code-router / cc-switch 重复吗？答：层级不同——litellm 是服务端网关（多服务统一入口），后两者是客户端配置/路由；判定 possible-compatible，共装未实测。
• 问：真实模型怎么接？答：在 model_list 填供应商模型名 + api_key（如 openai/gpt-4o、anthropic/claude-*）；一个 base_url 供所有客户端用（OpenAI 兼容）。
• 问：没有 API key 能试吗？答：能——openai/mock 模型 + dummy key 可完整验证代理面（2026-08-29 实测），真实转发需真实 key。
• 问：国内 pip 装不上？答：用安装段的清华镜像前缀（2026-08-29 实测）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。