你的应用/脚本里接了好几家模型供应商（OpenAI、Anthropic、Gemini、本地 ollama…），每家 API 格式不一样、key 管理散落各处、想统计花了多少钱也没有统一出口。litellm 就是那个统一网关：一个 OpenAI 兼容端点（/v1/chat/completions），背后路由到 100+ 供应商，统一 key 管理、成本统计、负载均衡。

什么时候用：

• 多供应商切换/容灾：一个 base_url 换模型不换代码；
• 统一 key 管理：代理层管 api_key，客户端不带 key；
• 成本统计：多模型用量统一记账；
• 与组合包 combo-model-access（litellm + logfire 可观测）对应。

什么时候别用：只用一家供应商且无成本诉求（直连更简单）；需要本地模型推理本身（那是 ollama 的活）。

# 来源: Trove 详细指南 · 验证于 2026-08-29
python3 -m venv ~/.litellm-venv && ~/.litellm-venv/bin/pip install -U "litellm[proxy]" -i https://pypi.tuna.tsinghua.edu.cn/simple
~/.litellm-venv/bin/litellm --version

预期输出: litellm 版本号（实测 1.98.0；清华 PyPI 镜像安装通过）

关键概念：openai/mock 模型（dummy key）可免真实 key 冒烟——本指南实测用它验证整个代理面。

装好确认：

• litellm --version 输出版本；
• 用 mock 配置起代理后 curl /health/liveliness 返回 ok。

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 步：装代理 + 验证版本

# 来源: Trove 详细指南 · 验证于 2026-08-29
python3 -m venv ~/.litellm-venv && ~/.litellm-venv/bin/pip install -U "litellm[proxy]" -i https://pypi.tuna.tsinghua.edu.cn/simple
~/.litellm-venv/bin/litellm --version

预期输出: litellm 版本号（实测 1.98.0）

卡住怎么办：

• pip 慢/超时 → 确认 -i 清华 PyPI 镜像前缀；
• venv 创建失败 → 确认 python3 存在且版本 ≥3.8。

第 2 步：写 mock 配置并启动

讲解：openai/mock 不需要真实 key，先验证代理面通了再接真实供应商。

# 来源: Trove 详细指南 · 验证于 2026-08-29
cat > /tmp/litellm-mock.yaml <<'YAML'
model_list:
  - model_name: mock-model
    litellm_params:
      model: openai/mock
      api_key: dummy-key
litellm_settings:
  drop_params: true
YAML
~/.litellm-venv/bin/litellm --config /tmp/litellm-mock.yaml --port 4000

预期输出: 代理启动日志（端口 4000 监听；实测 2026-08-29 mock 冒烟通过）

卡住怎么办：

• 端口被占 → 换 --port；
• 启动报错 → 检查 YAML 缩进（model_list 是列表，缩进必须一致）。

第 3 步：验证代理面（健康检查 + 模型列表 + 一次调用）

# 来源: Trove 详细指南 · 验证于 2026-08-29
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/v1/models
curl -s http://127.0.0.1:4000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"mock-model","messages":[{"role":"user","content":"hi"}]}'

预期输出: 健康检查返回 ok；模型列表含 mock-model；chat/completions 返回 mock 应答（2026-08-29 实测）

卡住怎么办：

• 模型列表空 → model_list 配置没加载，检查 --config 路径与 YAML；
• 调用 404 → 端点路径错（/v1/chat/completions，不是 /chat/completions）。

第 4 步：接真实供应商

讲解：把 model_list 换成真实供应商（示例 OpenAI；其他供应商格式见官方文档）。

# 来源: Trove 详细指南 · 验证于 2026-08-29
# 示例（真实 key 未在本地，未实测）：model_list 里配 litellm_params.model: openai/gpt-4o + api_key

预期输出: 见官方文档（本环境零 key 未实测真实供应商）

卡住怎么办：

• 401 → api_key 错误或没配；
• 模型名不认识 → 用 openai/<真实模型名> 格式。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• logfire × litellm：litellm 代理可把日志打到 logfire（可观测），互补关系（combo-model-access 成员）；
• claude-code-router × litellm：同为「多模型路由」定位相邻——ccr 管 Claude Code 本地路由，litellm 是通用网关；写面不同（ccr 配 ~/.claude-code-router，litellm 配 --config），静态判定 possible-compatible；
• 其余：写面不重叠（--config 指定配置），静态判定可共存。

• 症状：模型列表空 → model_list 配置没加载，检查 --config 路径与 YAML 缩进
• 症状：调用 404 → 端点路径错（/v1/chat/completions）
• 症状：真实供应商 401 → api_key 错误或没配
• 症状：pip 装不上 → 确认清华 PyPI 镜像前缀 + venv
• 症状：端口被占 → --port 换端口

四段式全文（症状→原因→解法→验证证据）：站内文档（如已收录）

# 来源: Trove 详细指南 · 验证于 2026-08-29
rm -rf ~/.litellm-venv

预期输出: 目录删除后 ~/.litellm-venv/bin/litellm 不存在

注意：litellm 不写系统配置；代理配置在你自己的 --config 文件，卸载 venv 不会动它。

• 问：openai/mock 是什么？答：litellm 内置的 mock 模型，不需要真实 key，用于验证代理面（实测通过）。
• 问：配置写在哪？答：完全由 --config 指定路径管理，不写系统/用户级配置；venv 在 ~/.litellm-venv。
• 问：和 claude-code-router 重复吗？答：定位相邻但形态不同——ccr 管 Claude Code 本地模型路由，litellm 是通用 OpenAI 兼容网关；可共存。
• 问：能接 ollama 吗？答：能，litellm_params.model 用 ollama/<模型名> 并配 api_base（未实测，官方支持）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：1.98.0（manifest 锁定；实测 2026-08-29）。
• 环境：Python venv（~/.litellm-venv 实测路径）。
• 网络：PyPI 走清华镜像（实测）。
• 写面：--config 指定配置 + venv，不写系统配置。
• 端口：默认 4000（示例）。

• 条目签名：BerriAI/litellm（MIT，原样收录 1.98.0）

• 实测：实测记录（本地留存）（venv 安装 + mock 代理启动 + /health/liveliness + /v1/models + chat/completions 冒烟；drop_params 配置）
• 未实测：真实供应商接入（零 key 红线）；负载均衡/成本统计细节；ollama 接入。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方文档层（docs.litellm.ai / PyPI 元数据，v1.98.0）：LiteLLM 完整用法 [官方文档 · LiteLLM 官方 · 2026-08-31（包 1.98.0）]
  官方用法全解——litellm[proxy] 隔离 venv 安装、--config 配置（model_list + litellm_settings）、代理启动与端口、健康检查 /health/liveliness、模型列表 /v1/models、mock 冒烟模型、统一 OpenAI 兼容端点