LiteLLM 本地模型运行教程：模型下载、路径设置与性能优化指南
为什么用 LiteLLM 运行本地模型
LiteLLM 常被用作 AI 网关工具，它的价值不只是“调用模型”，而是把不同模型后端统一成接近 OpenAI 风格的接口，方便应用侧少改代码完成接入。对于希望在本机、工作站或内网服务器上运行本地模型的团队来说，LiteLLM 可以把 Ollama、llama.cpp、vLLM、Transformers 等后端纳入统一管理，并提供路由、鉴权、日志、限流、重试等能力。
本地模型适合三类场景：第一，开发测试阶段不希望频繁改动业务代码；第二，资料不适合传到外部服务，需要在自有环境中处理；第三，已有多块显卡或高性能主机，希望降低长期推理成本。需要注意的是，LiteLLM 本身不是模型推理引擎，它更像统一入口和调度层，真正的推理速度仍取决于底层后端、模型大小、硬件配置和参数设置。
安装前准备：硬件、系统与目录规划
建议先确认运行环境。轻量级 7B 级别模型通常可在较新的消费级显卡或较大内存机器上运行，13B、30B 以上模型对显存、内存和磁盘要求明显提高。CPU 也能运行量化模型，但响应速度较慢，更适合低并发测试。系统方面，Linux 服务器最常见，macOS 适合个人开发，Windows 用户建议使用原生 Python 环境或 WSL，但路径写法要保持一致。
目录规划建议提前固定，例如把模型文件放在 /data/models，配置文件放在 /data/litellm，日志放在 /data/logs/litellm。不要把模型散放在下载目录或桌面路径中，否则后续迁移、备份和权限排查会很麻烦。模型目录应确保运行 LiteLLM 的用户具备读取权限，日志目录还需要写入权限。
安装 LiteLLM 与基础验证
推荐使用 Python 虚拟环境安装，便于和其他项目隔离。流程可以概括为：安装 Python 3.10 或更新版本，创建虚拟环境，安装 LiteLLM 包，再启动袋里服务。常见命令形式为 python -m venv .venv、source .venv/bin/activate、pip install litellm。如果要启用袋里服务，一般还会安装带 proxy 能力的相关依赖，具体以当前版本文档为准。
安装后先做最小化验证，不要一开始就接入复杂业务。可以执行版本查看命令，确认 Python 环境中调用的是刚安装的 LiteLLM，而不是系统其他位置的旧包。如果机器上有多个 Python，建议用 python -m pip 安装，避免 pip 指向错误环境。服务器部署时还要确认端口未被占用，安全组或防火墙规则允许内部调用。
模型下载：选择格式与来源
本地模型常见来源包括模型社区、厂商发布页以及组织内部模型仓库。下载时要关注四件事：模型许可、参数规模、量化格式、上下文长度。开发测试可优先选择 7B 或 8B 级别的 instruct 模型；如果显存有限，可选择 GGUF、AWQ、GPTQ 等量化版本；如果需要高吞吐服务，可考虑 vLLM 支持较好的格式。
以 Ollama 为后端时，模型通常由 Ollama 自己管理，LiteLLM 只需要连接 Ollama 服务并指定模型名称。这种方式安装简单，适合个人和小团队快速验证。以 llama.cpp 为后端时，通常需要下载 GGUF 文件并记录完整路径。以 vLLM 为后端时，更适合服务器环境，可服务 Hugging Face 格式模型目录，但对显存和驱动环境更敏感。
下载模型后建议校验文件完整性，至少确认文件大小、目录结构和配置文件是否齐全。不要随意使用来源不明的模型权重或脚本，尤其不要执行下载包里附带的未知安装脚本。生产环境中应建立白名单来源，并保存模型版本号、发布时间、量化方式和校验信息，便于回滚和问题追踪。
路径设置：让 LiteLLM 找到本地模型
LiteLLM 的核心配置通常写在 YAML 文件中，重点是把外部访问的模型别名映射到底层后端。例如应用侧请求 local-qwen，LiteLLM 配置中再把它指向 Ollama 的某个模型、llama.cpp 的服务地址，或 vLLM 暴露的接口。这样应用只关心统一模型名，后端替换时不需要大规模修改业务代码。
路径设置要避免三个常见错误。第一，使用相对路径导致服务在不同工作目录启动时找不到模型，建议统一写绝对路径。第二，容器部署时宿主机路径和容器内路径不一致，例如宿主机是 /data/models，容器内可能挂载为 /models，配置应写容器内可见路径。第三，权限不足，服务进程能看到目录但不能读取大文件，表现为启动正常、推理时报错。
如果使用 Ollama，通常不是直接写模型文件路径，而是先启动 Ollama 服务，再在 LiteLLM 中配置对应的模型名称和服务地址。如果使用 llama.cpp，可以先单独启动 llama.cpp server，并指定 -m 后接 GGUF 文件绝对路径，再让 LiteLLM 转发到该服务。这样排查更清晰：先确认推理后端独立可用，再检查 LiteLLM 网关配置。
启动服务与接口测试
配置完成后，建议先以前台方式启动 LiteLLM proxy，观察日志中是否成功加载配置、是否识别模型别名、端口是否正常监听。确认无误后再改为 systemd、supervisor、Docker 或容器编排方式守护运行。不要一开始就静默后台启动，否则路径错误、端口冲突、依赖缺失等问题不容易发现。
接口测试可分三步：先请求模型列表，确认别名可见；再发送极短提示词，验证完整链路；最后增加上下文长度和并发，观察延迟、显存、内存和日志。测试时应记录首字响应时间、总耗时、输出 token 速度和失败率。仅凭“能回答”不能说明配置可用于真实业务，稳定性和资源占用同样重要。
性能优化：从模型、后端到参数
性能优化首先从模型选择开始。参数越大，效果不一定线性提升，但资源占用会显著增加。很多企业知识问答、摘要、分类任务使用 7B 或 8B 指令模型已经够用；复杂推理、长文生成再考虑更大模型。量化可以明显降低显存压力，但过度量化可能影响回答质量，需要用实际业务样本评测。
第二是选择合适的推理后端。Ollama 易用，适合快速部署；llama.cpp 对 GGUF 支持成熟，CPU 与多平台兼容性较好；vLLM 更偏高吞吐服务，适合多用户并发请求。LiteLLM 层面的优化主要包括合理设置超时、重试次数、并发上限和路由策略，避免所有请求同时压到一个模型实例。
第三是控制请求参数。过大的 max_tokens 会拉长响应时间，过高的上下文长度会增加显存占用，高并发下尤其明显。线上应用应为不同任务设置不同模型和参数，例如短文本分类使用小模型、低输出长度；长文写作使用更大上下文；代码生成单独设置更严格的超时和日志追踪。
第四是缓存与批处理。对于重复问题、固定模板和高频系统提示词，可以在业务层做结果缓存或提示词缓存。需要注意缓存不能盲目开启，涉及用户私有内容时要谨慎设计键值和过期时间，避免把不该共享的内容返回给其他用户。
常见问题排查
问题一：LiteLLM 启动成功，但调用时报模型不存在。通常是配置中的模型别名与请求中的 model 字段不一致，或 YAML 缩进错误导致配置未被正确读取。解决方法是先查看启动日志中的模型列表，再用完全一致的名称测试。
问题二：提示连接后端失败。先确认 Ollama、llama.cpp server 或 vLLM 服务是否独立可访问，再检查地址、端口和容器网络。容器内访问宿主机服务时，不能简单照搬本机的 localhost，需使用容器可访问的地址。
问题三：模型加载很慢或直接退出。常见原因是显存不足、模型格式不匹配、驱动或依赖版本不合适。可先换更小模型验证链路，再逐步提高模型规模。不要在生产服务上反复尝试超出硬件能力的大模型，容易造成服务长时间不可用。
问题四：回答速度忽快忽慢。需要观察并发数、队列长度、上下文长度和其他进程占用。若多个服务共用同一块显卡，应限制每个服务的并发和最大输出长度。对外提供接口时，建议设置请求体大小、超时和限流，防止异常请求拖垮服务。
安全边界与上线建议
本地部署不等于天然安全。LiteLLM 作为统一入口，应至少配置访问密钥、内部网络访问范围、日志脱敏和错误信息收敛。不要把管理端口直接暴露到公共网络，也不要在日志中完整记录用户敏感输入、密钥或内部路径。配置文件中的密钥建议使用环境变量注入，避免写入仓库。
上线前建议准备三项机制：监控、回滚和分级配置。监控包括请求量、延迟、错误率、显存、内存和磁盘；回滚包括保留旧模型、旧配置和启动脚本；分级配置则是为开发、测试、生产分别维护配置文件，避免把实验参数带到正式环境。模型升级时不要直接覆盖原目录，最好使用版本化路径，例如 /data/models/qwen-7b-v1 与 /data/models/qwen-7b-v2 并存，通过 LiteLLM 配置切换。
总体来看，LiteLLM 本地模型方案的关键不是单条安装命令，而是“模型后端稳定、路径清晰、接口统一、参数可控”。先用小模型跑通链路，再逐步扩大模型规模和并发压力；先保证可观测和可回滚，再接入真实业务。按这个思路部署，后续无论替换模型、扩容服务还是接入更多应用，维护成本都会低很多。
