LiteLLM macOS 安装教程：Apple Silicon 与 Intel 电脑配置步骤整理

LiteLLM 适合解决什么问题

LiteLLM 是一个面向开发者和团队的 AI 网关工具，核心作用是把不同大模型服务的调用方式统一起来。对于本地开发、应用原型验证、团队内部模型切换、成本统计、请求转发和兼容 OpenAI 风格接口等场景，它都比较实用。安装在 macOS 后，可以把本机作为开发环境中的统一入口，让前端应用、脚本、自动化任务或后端服务不必分别适配多套接口。

在 Mac 上部署 LiteLLM 的重点并不复杂，但需要处理好三件事：Python 版本、不同芯片架构下的依赖路径、服务启动后的配置文件。Apple Silicon 机型通常是 arm64 架构，Intel 机型是 x86_64 架构，两者都可以安装，只是在 Homebrew 目录、终端环境和部分依赖编译行为上存在差异。

安装前准备：确认系统和环境

建议使用 macOS 12 或更新版本，并确保已安装命令行工具。打开“终端”，先执行系统工具检查：xcode-select --install。如果系统提示已安装，可以继续下一步。然后确认芯片类型：uname -m。返回 arm64 代表 Apple Silicon，返回 x86_64 代表 Intel。

LiteLLM 依赖 Python 运行环境，建议使用 Python 3.10 至 3.12 之间的稳定版本。不要直接混用系统自带 Python，因为系统环境常被其他软件占用，后续升级和卸载也更容易产生冲突。更稳妥的方式是使用 Homebrew 安装 Python，再配合虚拟环境隔离项目依赖。

安装 Homebrew 与 Python

如果 Mac 已经安装 Homebrew，可先执行 brew --version 检查。未安装时，可前往 Homebrew 官方站点复制安装命令。安装完成后，需要根据芯片类型确认路径。Apple Silicon 常见路径是 /opt/homebrew/bin，Intel 常见路径是 /usr/local/bin。若终端提示找不到 brew，需要把对应路径加入 shell 配置文件，例如 .zshrc。

接着安装 Python：brew install python。安装完成后执行 python3 --version 和 pip3 --version，确认版本正常。如果你已经通过 pyenv 管理多版本 Python，也可以使用 pyenv 安装指定版本，但要确保当前项目目录激活的是目标版本。对于刚接触 AI 工具安装教程的用户，Homebrew 加虚拟环境已经足够稳定。

创建项目目录与虚拟环境

建议为 LiteLLM 单独创建目录，方便管理配置、日志和启动脚本。可以执行：mkdir -p ~/ai-tools/litellm && cd ~/ai-tools/litellm。然后创建虚拟环境：python3 -m venv .venv。激活环境：source .venv/bin/activate。成功后，终端前方通常会显示 .venv，表示当前安装的 Python 包只会进入该项目环境。

激活虚拟环境后，先升级基础工具：python -m pip install --upgrade pip setuptools wheel。之后安装 LiteLLM：pip install litellm。安装完成后执行 litellm --version，如果能显示版本号，说明命令已经可用。若提示 command not found，通常是虚拟环境未激活，或 shell 缓存未刷新，可重新进入目录并执行 source .venv/bin/activate。

编写 LiteLLM 配置文件

LiteLLM 可以通过命令行直接测试，也可以使用配置文件启动服务。实际使用中更推荐配置文件方式，因为模型名称、密钥、路由规则和参数更清晰。可在项目目录新建 config.yaml，写入模型列表。示例思路是定义 model_name 作为本地调用时使用的名称，再在 litellm_params 中填入真实服务提供方、模型标识和密钥环境变量。

密钥不要直接写死在配置文件里，尤其是项目需要同步到代码仓库时。建议使用环境变量，例如 export OPENAI_API_KEY="你的密钥"。如果还接入其他模型服务，也应分别设置对应环境变量。为了方便长期使用，可以把变量写入本机专用的环境文件，再在启动前加载；但不要把包含密钥的文件上传到公开仓库或共享网盘。

启动服务并验证接口

在虚拟环境激活状态下，执行：litellm --config config.yaml --port 4000。启动成功后，本机通常会监听 http://localhost:4000。可以使用 curl 或接口调试工具访问兼容接口，验证模型能否响应。若你的应用原本使用 OpenAI 风格接口，通常只需要把 base_url 改成本机 LiteLLM 地址，再把模型名改成配置文件中的 model_name。

本地测试通过后，可以为不同用途设置不同端口或不同配置文件。例如开发环境使用较低成本模型，测试复杂推理时切换到能力更强的模型。LiteLLM 的优势正是在这里：上层应用只面对统一入口，底层模型可以按需求调整，减少重复改代码的成本。

Apple Silicon 与 Intel 电脑的差异处理

Apple Silicon 设备通常性能和能耗表现较好，但要注意终端是否运行在原生 arm64 环境。若你曾经使用兼容模式安装过工具，可能会出现 /opt/homebrew 与 /usr/local 混用，导致 Python、pip、brew 指向不同目录。可以通过 which python3、which pip3、which brew 逐一检查。路径混乱时，优先保持同一套 Homebrew 和同一套 Python。

Intel 设备安装流程基本一致，常见问题更多集中在旧系统版本、Python 版本偏低或编译工具缺失。如果 pip 安装依赖时报错，可先升级 pip、setuptools、wheel，再确认 xcode-select --install 已完成。对于公司设备，还可能存在网络策略或权限限制，应使用合规的内部网络和软件源，不建议随意修改系统级安全设置。

可选方案：使用 Docker 部署

如果不想管理 Python 依赖，也可以使用 Docker 方式运行 LiteLLM。前提是已经安装适用于 Mac 的 Docker Desktop，并确认容器能够正常启动。Docker 方式的优点是环境更独立，适合多人协作或需要快速迁移的团队；缺点是首次配置稍多，且本机资源占用会更明显。

使用容器时，同样要把配置文件挂载到容器内，并通过环境变量传入密钥。Apple Silicon 用户需要留意镜像架构兼容性，优先选择支持多架构的官方或可信镜像。若出现镜像拉取慢、容器启动后端口不可访问等情况，应先检查 Docker Desktop 状态、端口映射和本机防火墙规则。

常见问题与排查方法

问题一：安装成功但命令无法执行。多数是虚拟环境没有激活，或 pip 安装到了另一个 Python 环境。执行 which litellm、which python、pip show litellm 可定位路径。建议始终先进入项目目录，再激活 .venv。

问题二：启动后模型调用失败。先检查配置文件缩进是否正确，YAML 对空格非常敏感；再检查环境变量是否已在当前终端生效。可以执行 echo $OPENAI_API_KEY 查看是否存在值，但不要把密钥截图或发送给他人。

问题三：端口被占用。默认端口如 4000 可能被其他服务使用，可改用 litellm --config config.yaml --port 4001。也可以使用 lsof -i :4000 查看占用进程，再决定是否关闭。

问题四：接口返回权限或额度错误。这通常不是 LiteLLM 本身安装失败，而是上游服务账号、模型权限、区域限制或额度配置导致。应到对应服务后台核对模型可用性、密钥状态和调用配额。

安全边界与使用建议

LiteLLM 作为统一入口，会集中处理多家模型服务的请求和密钥，因此安全管理非常重要。第一，密钥只放在本机环境变量、受控密钥管理系统或内部配置中心，不要写入公开代码。第二，服务默认建议只监听本机地址，除非明确需要提供给局域网内其他设备访问。第三，不要把客户资料、商业机密、个人身份信息等敏感内容随意发送到外部模型服务。

团队使用时，建议为不同项目创建独立密钥，并设置访问范围和调用上限。配置文件要纳入版本管理时，应只提交模板文件，例如 config.example.yaml，把真实密钥留在本地。上线前还应增加日志脱敏、异常告警和调用监控，避免因为配置错误造成请求失败或费用异常。

升级、回滚与日常维护

升级 LiteLLM 前，先记录当前版本：litellm --version，并备份 config.yaml。然后在虚拟环境中执行 pip install --upgrade litellm。升级后至少验证三项：服务能否启动、模型路由是否正常、原有应用是否能完成一次完整请求。如果发现新版本行为不符合预期，可使用 pip install litellm==指定版本 回滚。

日常维护中，建议把安装目录、配置文件、启动命令和依赖版本记录到团队文档。对于个人开发者，最简单的维护方式是保留 requirements.txt：pip freeze > requirements.txt。迁移到新 Mac 时，重新创建虚拟环境后执行 pip install -r requirements.txt，即可快速恢复依赖。

整体来看，LiteLLM 在 macOS 上的安装门槛不高，真正影响稳定性的往往是 Python 环境、配置文件缩进、密钥管理和端口占用。Apple Silicon 与 Intel 电脑只要分别处理好工具路径和依赖版本，就可以获得一致的使用体验。完成本地部署后，再逐步接入更多模型和监控能力，会比一开始就搭建复杂架构更稳妥。