LiteLLM配置教程：统一代理OpenAI与本地模型请求
如果你手头同时有 OpenAI 的 API Key、本地跑的 Ollama 模型，甚至还有 Anthropic 的密钥，每个应用都要单独适配一套 SDK 和地址，维护起来会很麻烦。
LiteLLM 解决的就是这个问题：它提供一个兼容 OpenAI 格式的统一接口，你只需要在配置文件里列出模型和密钥，应用端始终请求同一个地址即可。
这篇配置教程从安装讲到验证，适合刚接触 LiteLLM 的运维和开发人员。
安装前需要确认的运行环境
LiteLLM 是一个 Python 项目，推荐用 Python 3.9 以上版本运行。
你可以直接 pip 安装，也可以用 Docker 启动，两种方式最终都读取同一个 config.yaml。
- 如果机器上已有 Python 环境，执行
pip install litellm[proxy]安装代理依赖。 - 如果更倾向容器化，准备好 Docker 后直接拉取镜像即可，不需要在宿主机装 Python。
- 提前准备好各模型服务的 API Key，例如
OPENAI_API_KEY或本地 Ollama 的访问地址。 - 确认服务器能访问目标模型 API，本地模型则确认端口可连通。
安装完成后，litellm --version 能输出版本号，说明命令行工具已就绪。
编写 config.yaml 定义模型和路由
LiteLLM 的所有模型配置都写在一个 YAML 文件里。
最小可用配置包含 model_list，每一项需要 model_name（对外暴露的名称）和 litellm_params（实际调用的模型和密钥）。
model_list:
- model_name: gpt-4o-mini
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY
- model_name: local-llama
litellm_params:
model: ollama/llama3
api_base: http://127.0.0.1:11434关键点有两个。
第一，model_name 是应用端请求时填写的名字，可以自定义；
第二，model 字段需要带上前缀，例如 openai/ 或 ollama/，LiteLLM 靠这个前缀决定走哪家 SDK。
密钥建议用 os.environ/变量名 引用环境变量，不要把明文写进文件。
如果需要统一管理访问权限，还可以在配置里加 general_settings 设置 master_key，之后请求必须带上这个密钥才能调用。
启动代理并验证请求
配置文件写好后，用命令行启动代理服务：
litellm --config /path/to/config.yaml --port 4000看到服务监听 4000 端口的日志后，另开一个终端用 curl 验证：
curl http://127.0.0.1:4000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-1234" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "你好"}]
}'如果返回了正常的 JSON 响应，说明模型路由已经生效。
这里的 model 填的是配置里的 model_name，不是原始模型名。
请求头里的 Bearer 值对应你在配置中设置的 master_key，如果没有设置可以省略。
用 Docker 启动时，把配置目录挂载进容器并指定端口即可，例如 docker run -v $(pwd)/config.yaml:/app/config.yaml -p 4000:4000 ghcr.io/berriai/litellm:main-latest --config /app/config.yaml。
镜像标签可能随项目更新变化，执行前建议核对官方镜像说明。
常见报错和避坑提醒
配置过程中最容易遇到三类问题。
401 未授权：先检查请求头是否带了正确的 master_key，再检查环境变量里的 API Key 是否真的被加载。
用 env | grep OPENAI 可以确认环境变量是否存在。
模型找不到：请求里的 model 必须和 model_name 完全一致，大小写和连字符都不能错。
如果配置了多个模型，确认 YAML 缩进没有把列表项写到错误层级。
本地模型连接失败：Ollama 默认只监听本机，如果 LiteLLM 跑在容器里，127.0.0.1 指向的是容器自身。
需要把 api_base 改成宿主机可达的地址，或者让两者在同一网络下通信。
另外，修改 config.yaml 后必须重启 LiteLLM 进程才会生效，热加载不是默认行为。
密钥不要提交到代码仓库，生产环境建议通过环境变量或密钥管理服务注入。
怎么确认配置真正可用
除了 curl 单次请求，还可以调用 LiteLLM 的模型列表接口，确认服务识别到了哪些模型：curl http://127.0.0.1:4000/v1/models。
返回结果中的 id 就是应用端可以请求的模型名。
如果应用已经接入了 OpenAI SDK，只需要把 base_url 改成 http://你的地址:4000/v1，其余代码基本不用动。
建议先在测试环境跑通一次完整请求，再切换到生产流量，避免配置错误影响线上调用。
LiteLLM 配置的核心就是一份 YAML 加一个启动命令，难点集中在模型前缀、密钥引用和网络连通性上。
按上面的步骤逐项核对，大多数启动问题都能定位到具体配置行。
