LiteLLM 实战：用一个代理统管所有本地与云端大模型

家庭实验室（Homelab）跑 AI 的人，迟早会遇到同一个烦恼：Ollama 在 11434 端口，llama.cpp 在 8080，Text Generation WebUI 在 7860，再加上 OpenAI、Anthropic、Groq 三套云端 API——每个都是不同的密钥、不同的端点、不同的 SDK。LiteLLM 的价值，就是把这堆散乱的推理端点收拢成一个 OpenAI 兼容的统一网关。

LiteLLM on the Homelab

端点碎片化：Homelab 的真实痛点

随着本地 AI 生态扩张，端点管理会迅速演变成一场灾难。原文列出了接入 LiteLLM 之前的典型困境：每个应用都要写针对不同 provider 的条件分支逻辑，造成代码重复；需要管理 6 套以上的凭据和端点，配置复杂度爆炸；更要命的是没有兜底机制——当 Ollama 宕机时，整个应用直接崩溃。

此外还有一系列缺失能力：无法在多个 Ollama 实例间做负载均衡；想看成本只能手动记日志；没有内建的限流保护；想加监控或链路追踪也异常困难。这些问题单独看都不致命，但叠加起来会让一个本可以专注于业务的开发者陷入无止境的运维泥潭。

LiteLLM 的解法：一个代理统管全部

LiteLLM 的核心承诺是「one proxy to rule them all」。所有应用只需对接一个端点 http://homelab:4000/v1/*，并且这个端点完全兼容 OpenAI SDK——意味着任何现有的 OpenAI 客户端代码几乎零改动就能切过来。

模型层做了抽象：你请求 gpt-4o-mini 时，背后可能被路由到本地模型，也可能是远端 API，应用无需关心。更关键的能力包括自动故障转移（先试本地、失败再走付费 API）、多实例负载均衡、内建的 token 计数与成本估算、按模型或全局的限流，以及带指数退避和抖动的重试逻辑。

Provider 分两类：本地驻留 vs 云端 API

本地 provider 包括 ollama（推荐大多数场景使用）、llama_cpp、vllm（高吞吐但配置更复杂）、tgi 等。远端 provider 覆盖 openai、anthropic、groq、cohere、mistralai，以及阿里云^广告百炼（ali_bailian）、字节火山引擎（volcengine）等国内厂商。这种统一抽象意味着切换或新增 provider 只是改配置，而非重写代码。

vLLM 值得单独说明：它是由加州大学伯克利分校开发的高吞吐量推理引擎，核心创新是 PagedAttention 内存管理机制，能将 KV Cache 的 GPU 显存利用率从传统方式的 40-60% 提升到 90% 以上，大幅提高并发吞吐。代价是部署门槛更高——需要独立的 CUDA 环境、显存充裕的 GPU，以及比 Ollama 更复杂的启动参数配置。对于 Homelab 场景，Ollama 凭借一键安装和自动量化管理更适合入门；只有当并发请求量较大（例如多人共享或跑自动化流水线）时，才有必要引入 vLLM。LiteLLM 对两者都提供原生支持，切换只需修改 litellm_provider 字段，应用层代码无需感知底层推理引擎的差异。

路由策略：瀑布式降级是精髓

LiteLLM 决定请求去向有几种模式，其中「瀑布式路由」（Waterfall Routing）最能体现它在 Homelab 场景的价值。

简单列表：按顺序试到成功

最基础的策略是按 model_list 顺序逐个尝试，直到某个成功。例如请求先打 Ollama 的 qwen2.5-coder:14b，失败后转 deepseek-r1:14b，再失败才兜底到 OpenAI 的 gpt-4o-mini。

负载均衡：分摊到多实例

当单个 Ollama 实例压力过大时，可以配置多个指向不同 api_base（如 ollama1.local、ollama2.local、ollama3.local）的池成员，各自设置 rpm 限制。LiteLLM 会把请求分摊到三个实例，每个都遵守自己的每分钟请求上限以防过载。

瀑布式降级链：从免费本地到高价云端

这是最实用的模式，按能力和成本分层：

model_list:
  # Tier 1: 快速本地
  - model_name: local_fast
    litellm_provider: ollama
    model_name: qwen2.5-coder:14b
    api_base: http://localhost:11434
    tpm: 5000
  # Tier 2: 能力更强的本地大模型
  - model_name: local_capable
    litellm_provider: ollama
    model_name: deepseek-r1:14b
    tpm: 3000
  # Tier 3: 成本敏感的远端兜底
  - model_name: remote_backup
    litellm_provider: openai
    model: gpt-3.5-turbo
  # Tier 4: 质量关键时才用的高端远端
  - model_name: remote_premium
    litellm_provider: openai
    model: gpt-4o

逻辑是：先用快速本地模型；过载或不合适就切能力更强的本地模型；仍不足或被限流时才用 gpt-3.5-turbo；只有复杂推理才动用 gpt-4o。这套设计让「本地优先、按需升级」成为默认行为，既省钱又保证可用性。

tpm（Tokens Per Minute）和 rpm（Requests Per Minute）是 LiteLLM 中两个独立维度的限流参数，分别从「消耗的 token 总量」和「请求次数」两个角度保护下游服务。两者作用不同：rpm 更适合保护推理服务器的并发连接数上限，tpm 则更贴近实际计算负载——一个长文档摘要请求可能只算 1 次 rpm 却消耗数千 token。对于本地 Ollama 实例，建议同时设置两者：rpm 防止请求堆积导致队列超时，tpm 防止单个大请求把 GPU 长时间占满而饿死其他用户。当某个池成员触达其限流阈值时，LiteLLM 会自动将后续请求路由到列表中的下一个可用模型，这正是瀑布式降级在实践中自动触发的机制。

部署方式：从简单到高级

原文给出三条部署路径。Docker 容器是推荐方式，易于移植和隔离，通过 -v 挂载配置和模型目录，-e 注入各家 API 密钥，映射 4000 端口即可运行；也提供了对应的 docker-compose.yml 写法。直接 pip 安装适合需要调试或修改源码的开发场景，pip install litellm 后用 litellm --config config.yaml --port 4000 启动。Kubernetes Helm Chart 面向在 TrueNAS SCALE 上跑 K8s 的高级用户，通过 helm install 并以 --set 传入模型列表和密钥。

配置详解与实战场景

config.yaml 的核心是 model_list，每个条目定义模型名、provider、api_base 以及可选的 tpm（每分钟 token）、rpm（每分钟请求）、max_parallel_calls 等限流参数。全局设置则涵盖 default_timeout、num_retries 重试、Redis 缓存、CSV 用量日志、budget 预算控制等。

原文给出三个典型场景配置：成本敏感的开发助手——最大化本地使用，云端仅作紧急兜底；质量优先的内容生成——本地起草、云端（gpt-4o 或 Claude）润色；预算受控的生产服务——设置每月 50 美元上限，并把本地模型从预算追踪中排除（因为它们「免费」），用优先级权重让便宜/免费的模型优先。

应用集成几乎零成本

由于 LiteLLM 完全兼容 OpenAI 协议，Python 只需把官方 OpenAI SDK 的 base_url 指向 http://homelab.local:4000/v1，api_key 填任意非空字符串即可；请求里的 model 字段写配置中定义的别名（如 ollama_qwen_coder），路由完全交给 LiteLLM 处理。JavaScript/TypeScript 同理，curl 测试也直接走标准的 /v1/chat/completions、/v1/embeddings 等路径。

进阶能力与运维要点

LiteLLM 还支持 Redis 响应缓存（对 FAQ、代码解释等重复请求尤其有效）、CSV 用量日志与自定义 metadata/tags 追踪、请求/响应的自定义 transformer，以及与 LangFuse 集成实现深度可观测性——自动追踪所有调用、按项目或用户统计成本、可视化复杂链路。

在最佳实践层面，原文强调配置纳入 Git 版本管理、密钥绝不入库、分环境配置；监控上要盯住健康检查、错误率、p50/p95/p99 延迟和 token 消耗；安全上注意 LiteLLM 默认绑定 0.0.0.0，建议通过反向代理加真实鉴权，并对公开应用做输入校验和内容过滤。

LangFuse 是一个开源的 LLM 可观测性平台，可以自托管部署（Docker Compose 即可跑起来），专门用于追踪和分析 LLM 应用的调用链路。与通用监控工具（如 Prometheus + Grafana）相比，LangFuse 理解 LLM 特有的概念——它以「Trace → Span → Generation」的层级结构记录每次完整交互，能展示提示词内容、模型响应、延迟分布、token 消耗及折算成本，并支持按用户 ID、项目标签进行多维度分析。在 Homelab 场景中，LiteLLM 与 LangFuse 的集成只需在配置中填入 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY，之后所有经过 LiteLLM 网关的请求都会自动上报，无需修改任何应用代码。这对于排查「为什么这个请求突然变慢」或「上个月哪个模型花了最多钱」类问题尤其直观。

结语：降低复杂度比省钱更重要

原文一句话点出了 LiteLLM 的本质：它的目标不是降成本（虽然往往顺带做到），而是降低复杂度、提升可靠性。通过把多个 AI provider 各异的 API、配额和故障模式抽象掉，开发者得以把精力重新投向真正重要的事——构建有用的应用、解决真实问题。你的 Homelab 由此不再是一堆零散的 AI 工具，而成为一个连贯、有韧性的创新平台。对于正在被端点碎片化困扰的自建 AI 玩家，LiteLLM 是一个值得认真评估的网关层。