LiteLLM 新手入门安装指南：从下载安装到首次运行的保姆级教程

LiteLLM适合解决什么问题

LiteLLM是一个面向开发者和团队的AI网关工具，核心价值是把不同大模型服务封装成统一的调用入口。项目中原本需要分别适配OpenAI、Claude、Gemini、Azure OpenAI、本地Ollama等接口，接入LiteLLM后，可以尽量使用类似OpenAI Chat Completions的格式发起请求，从而降低切换模型、灰度测试和多模型备份的成本。

对新手来说，它最常见的使用方式有两种：一种是在代码里直接引入LiteLLM SDK，统一调用不同模型；另一种是启动LiteLLM Proxy，把它作为本地或团队内部的API服务。入门阶段建议先从Proxy模式开始，因为它更直观：安装完成后启动一个本地端口，再用curl、Postman或自己的应用访问这个端口，就能看到完整链路是否跑通。

安装前准备：环境、密钥和目录

开始前建议准备三样东西。第一，Python环境，推荐Python 3.10或更高版本；第二，可用的模型服务密钥，例如OpenAI兼容服务的API Key，或者准备好本地Ollama模型；第三，一个干净的项目目录，用来放置虚拟环境和配置文件。不要把密钥写进公开仓库，也不要在截图、日志、工单里暴露完整密钥。

Windows用户可以在PowerShell中执行命令，macOS和Linux用户可以在终端中执行命令。先确认Python是否可用：输入python --version或python3 --version。如果提示找不到命令，需要先从Python官网安装，并在安装时勾选加入PATH。随后建议创建专用目录，例如litellm-demo，避免和其他项目依赖混在一起。

第一步：创建虚拟环境

进入项目目录后，先创建虚拟环境。Windows可执行python -m venv .venv，再执行.venvScriptsactivate启用；macOS或Linux可执行python3 -m venv .venv，再执行source .venv/bin/activate启用。成功后，命令行前通常会出现(.venv)标识。

虚拟环境的意义是把LiteLLM及其依赖隔离在当前项目中，后续升级、卸载或排查问题会更简单。新手常见错误是没有启用虚拟环境就安装，导致命令执行时调用了系统环境里的旧版本依赖。若不确定当前pip对应哪个Python，可执行python -m pip --version查看路径。

第二步：安装LiteLLM

在虚拟环境启用状态下执行python -m pip install -U pip更新pip，然后执行python -m pip install litellm安装。安装完成后，可用litellm --version检查命令是否可用。如果提示找不到litellm，通常是虚拟环境未启用，或脚本目录没有被当前终端识别；此时重新激活虚拟环境，再执行一次版本检查。

如果安装速度较慢，可以更换可信的软件源，但不建议从来路不明的压缩包或脚本安装。生产环境更建议固定版本号，例如litellm==某个已验证版本，避免自动升级带来行为变化。入门学习阶段使用最新版问题不大，但每次升级前最好查看发布说明。

第三步：配置模型密钥

最小可用方式是通过环境变量传入密钥。以OpenAI兼容服务为例，macOS或Linux可执行export OPENAI_API_KEY="你的密钥"，Windows PowerShell可执行$env:OPENAI_API_KEY="你的密钥"。这里只在当前终端会话生效，关闭终端后需要重新设置；如果要长期使用，可写入系统环境变量，但仍要注意不要共享给无关人员。

更推荐的方式是使用配置文件。新建config.yaml，写入模型列表、模型别名和底层参数。示例思路是：把对外暴露的名称设为demo-chat，底层模型设为openai/gpt-4o-mini，密钥引用环境变量。这样应用侧只需要调用demo-chat，未来更换底层模型时，不必改业务代码。

第四步：首次启动Proxy服务

如果使用单模型快速测试，可执行litellm --model openai/gpt-4o-mini --port 4000。如果使用配置文件，可执行litellm --config config.yaml --port 4000。看到服务监听在http://0.0.0.0:4000或类似提示，说明Proxy已经启动。新手建议先在本机测试，不要一开始就开放到公网。

随后可以用接口测试工具向http://localhost:4000/v1/chat/completions发送请求，请求头包含Content-Type: application/json，请求体包含模型名、messages数组等字段。若返回了模型回复，说明从客户端到LiteLLM再到底层模型的链路已打通。若返回认证错误，先检查环境变量是否在同一个终端中设置；若返回模型不存在，检查模型名称是否与服务商要求一致。

第五步：给服务加上访问口令

只在本机临时测试时，可以使用较简单的启动方式；一旦给团队或应用调用，就应设置访问口令。LiteLLM支持通过Master Key控制访问，例如启动时添加--master_key参数，客户端请求时在Authorization头中携带对应值。这样可以避免任何能访问端口的人都能调用模型。

还要注意端口暴露范围。开发电脑上建议只监听本地；服务器部署时，应结合反向袋里、访问白名单、日志审计和限流策略。不要把密钥交给前端页面直接使用，前端应访问你的后端服务，由后端再转发到LiteLLM，否则密钥很容易被抓取。

常见问题与排查方法

问题一：pip install失败。先确认Python版本是否过低，再升级pip；如果报依赖冲突，优先新建空虚拟环境重装。问题二：命令行提示litellm不存在。确认虚拟环境是否启用，或使用python -m litellm尝试启动。问题三：端口4000被占用。换成--port 4001，或关闭占用该端口的旧进程。

问题四：接口返回401或403。多半是底层模型密钥错误、权限不足或LiteLLM访问口令未按要求传入。问题五：请求超时。检查本机网络、服务商状态、模型名称和请求体大小，必要时换一个轻量模型测试。问题六：返回格式和预期不一致。确认客户端是否使用OpenAI兼容路径，并检查LiteLLM版本与配置文件写法是否匹配。

实用建议与安全边界

入门阶段不要急着接入复杂业务，建议按“单模型可用、多模型配置、服务鉴权、日志与限流、应用接入”的顺序推进。每一步都保留可回退配置，例如把旧的config.yaml复制为备份文件。团队使用时，建议为开发、测试、生产分别维护配置，避免测试流量误打到生产模型。

在数据安全方面，不要把未脱敏的个人资料、内部机密、客户文本直接发送到外部模型；日志中也应避免记录完整请求内容和密钥。LiteLLM能帮助统一入口，但不能替代权限管理、成本控制和合规评估。首次运行成功后，可以继续探索路由策略、失败重试、模型降级、用量统计等能力，让它从一个本地测试工具逐步变成稳定的AI基础组件。