LiteLLM 模型代理指南
# LiteLLM 模型代理指南
LiteLLM 负责模型 API 接入、模型别名和路由。客户端用法见 Claude Code，模型服务部署见 Ollama，Agent 编排概念见 AI 应用指南。
本文于 2026-10-17 核对官方配置入口；具体模型、鉴权和路由参数需与所安装版本匹配。
# 一、LiteLLM 是什么
客户端 → LiteLLM 模型别名与协议接入 → 云端 API / 本地 Ollama
| 层 | 本文示例 | 谁连接它 |
|---|---|---|
| 客户端 | Claude Code / API 脚本 | 用户 |
| 代理 | http://localhost:4000 | 客户端 |
| 本地模型服务 | http://localhost:11434 | LiteLLM |
一个可达的代理可以被多个项目共用；配置文件放在哪个目录，并不会自动限制哪些项目有权连接。
# 二、安装与快速开始
pip install 'litellm[proxy]'
模型映射只维护一份配置。以下本地示例使用 qwen3:8b；先在 Ollama 端准备该模型，资源要求应在本机验证。
model_list:
- model_name: local-chat
litellm_params:
model: ollama_chat/qwen3:8b
api_base: http://localhost:11434
2
3
4
5
保存为 litellm_config.yaml 后启动：
litellm --config ./litellm_config.yaml --port 4000
model_name 是客户端使用的别名，litellm_params.model 才是后端模型标识。Ollama provider 配置 (opens new window)
# 三、配置文件详解
| 字段 | 职责 |
|---|---|
model_list | 代理对外提供的模型及后端映射 |
model_name | 客户端提交的模型名 |
litellm_params.model | provider 前缀和实际模型 |
api_base | 后端服务地址，不是代理自身地址 |
api_key | 需要鉴权的后端密钥；可引用 os.environ/变量名 |
router_settings | 显式配置路由策略，不表示默认自动选择最低价格 |
配置文件作用域与管理
--config 选择当前代理进程加载的文件。放在项目目录或用户目录是管理约定，不等于网络或权限隔离。多个实例使用不同端口；共用实例时通过模型别名区分后端，通过鉴权与预算策略控制使用范围。
litellm --config ./project-a.yaml --port 4001
litellm --config ./project-b.yaml --port 4002
2
配置后端凭据时从环境变量读取，避免写入公开仓库：
# 此字段放在相应模型的 litellm_params 下
api_key: os.environ/PROVIDER_API_KEY
2
# 四、典型使用场景
| 需求 | 维护位置 |
|---|---|
| OpenAI 兼容客户端连接本地模型 | 上面的模型配置，客户端使用 /v1/chat/completions |
| Claude Code 连接本地或其他后端 | 统一客户端配置，使用 Messages API |
| 切换云端模型 | 更新该 provider 的模型映射和凭据，客户端继续使用配置的别名 |
| 多项目使用不同配置 | 不同代理端口，或同代理的不同模型别名和授权 |
curl http://localhost:4000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"local-chat","messages":[{"role":"user","content":"你好"}]}'
2
3
此请求只验证基础对话路径。启用代理鉴权后，还需提供已授权的代理 key。
# 五、路由策略详解
同名 model_name 下配置多个部署时，才有相应的候选部署可供路由。负载分配与失败后的 fallback 是不同配置，不能用一个策略名称代替整套容错设计。
| 官方策略示例 | 选择依据 |
|---|---|
simple-shuffle | 随机分配，结合可用部署 |
least-busy | 当前请求负载 |
latency-based-routing | 延迟 |
usage-based-routing | 用量 |
策略名、缓存依赖和可用功能以 LiteLLM 路由文档 (opens new window) 为准。模型别名只是映射，不会补齐后端缺少的工具调用或上下文能力。
# 六、与 Claude Code 配合使用
复用“二、安装与快速开始”的模型配置，不再复制一份后端 YAML。Claude Code 使用 Anthropic Messages API，LiteLLM 提供 /v1/messages；客户端的 base URL 填代理根地址。
# PROXY_API_KEY 为你实际配置并获授权的代理凭据
ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_AUTH_TOKEN="$PROXY_API_KEY" \
ANTHROPIC_API_KEY='' \
ANTHROPIC_MODEL=local-chat \
claude
2
3
4
5
6
local-chat 必须与 model_name 一致。凭据属于代理，而后端 provider 的 key 属于 LiteLLM 配置，两者不要混用。LiteLLM 官方 Claude Code 集成 (opens new window)
环境变量与项目隔离
内联环境变量只影响本次启动及其子进程；export 影响当前 shell 后续启动的进程，不会修改已运行客户端。.env 文件不会自动被所有工具加载。使用 direnv 时，先审阅 .envrc，再授权当前项目；密钥文件加入 .gitignore。
直接连接 Ollama 的配置见 Ollama：Claude Code 接入，不必为了单一本地后端额外运行代理。
# 七、常见问题
| 现象 | 依次检查 |
|---|---|
| 无法连接 | curl http://localhost:11434/api/tags，再检查代理进程和端口 |
| 找不到模型 | 代理配置中的别名与客户端模型名是否一致 |
| 鉴权失败 | 区分代理 key 与后端 provider key |
| 文本可用但工具调用失败 | 后端模型的工具能力、请求协议、流式事件格式 |
| 参数被拒绝 | 核对后端支持的参数；不要用 drop_params 掩盖必需能力缺失 |
| 改配置不生效 | 核对进程实际加载的 --config、客户端是否重新启动 |
# 八、相关链接
# 九、阅读边界
本页集中维护代理与客户端的连接链路；模型安装、GPU 排错在 Ollama 文章维护，Agent 工具执行和记忆代码在 LangChain 实践 维护。