Ubuntu 和 WSL 如何安装 LiteLLM Proxy

在较新的 Debian、Ubuntu 和 WSL 环境中，直接执行 pip install 可能出现 externally-managed-environment 错误。这是 PEP 668 的保护机制：系统不允许 pip 直接修改由操作系统管理的 Python 环境。

安装 LiteLLM Proxy 时，不建议使用 sudo pip 或长期依赖 --break-system-packages。更稳妥的方式是使用 pipx；如果还需要修改源码或管理项目依赖，则使用虚拟环境。

方案一：使用 pipx 安装

pipx 会为命令行工具创建独立的 Python 环境，同时将命令加入用户的 PATH。对于只需要运行 LiteLLM Proxy 的场景，这是最省事的方案。

sudo apt update
sudo apt install -y pipx
pipx ensurepath

执行完 pipx ensurepath 后，重新打开终端。如果当前终端需要立即生效，可以运行：

source ~/.bashrc

pipx install 'litellm[proxy]'

如果已经安装，升级时执行：

pipx upgrade litellm

litellm --help

能够正常显示命令帮助，就说明 LiteLLM 已加入 PATH。

如果要为 LiteLLM 固定版本、保存配置或参与开发，建议为它建立单独的虚拟环境。

sudo apt update
sudo apt install -y python3-venv python3-full

python3 -m venv ~/.venvs/litellm
source ~/.venvs/litellm/bin/activate

python -m pip install --upgrade pip
python -m pip install 'litellm[proxy]'
litellm --help

使用结束后退出虚拟环境：

deactivate

下次使用时只需重新激活：

source ~/.venvs/litellm/bin/activate

下面以本机 Ollama 中的 llama3.2 为例。先确认 Ollama 服务和模型已经可用：

ollama pull llama3.2
ollama list

启动 LiteLLM Proxy：

litellm --model ollama/llama3.2 --port 4000

另开一个终端检查 OpenAI 兼容接口：

curl http://localhost:4000/v1/models

如果代理启动正常，接口会返回模型信息。生产环境还需要配置访问密钥、请求限流和日志策略，不能直接把未鉴权的端口暴露到公网。更完整的代理配置可参考 LiteLLM Proxy 官方文档。

不要使用 sudo pip install。选择 pipx 或虚拟环境，确保依赖不会覆盖系统 Python 包。

先执行：

pipx ensurepath
source ~/.bashrc

如果使用虚拟环境，则确认已经运行：

source ~/.venvs/litellm/bin/activate

安装基础编译环境后重试：

sudo apt install -y build-essential python3-dev

指定其他端口：

litellm --model ollama/llama3.2 --port 4001

以下命令会绕过系统 Python 的保护机制：

pip install 'litellm[proxy]' --break-system-packages

它适合一次性的隔离测试环境，不适合作为日常安装方案。系统 Python 被覆盖后，可能影响依赖它的操作系统工具。