LiteLLM：一个统一的本地代理和 cloud

#为什么使用兼顾本地与云端的 LiteLLM 代理

典型的混合架构存在两个问题。首先，应用代码中充斥着 if provider == 'openai' / elif provider == 'ollama' 这类判断。其次，'本地 vs 云端' 的决策在代码编写时就被固定：一旦 Ollama 失败，应用即崩溃；若想针对特定任务切换至 Claude，必须重新部署。

LiteLLM 同时解决了这两个问题。在应用端，您与一个兼容 OpenAI 的统一端点交互（chat/completions、embeddings、streaming）。在基础设施端，config.yaml 文件描述您的模型：逻辑别名、后端、API 密钥、回退优先级。您可以更改路由，无需修改代码。

#工作原理

代理默认暴露4000端口。您的应用会向 /chat/completions 发送POST请求，包含 model: "chat-fr"。LiteLLM 查看其 config.yaml 配置文件，发现 chat-fr 指向 ollama/qwen3.5:9b 本地地址 localhost:11434，发起请求，将响应标准化为OpenAI格式，然后将结果返回给应用。

应用端

只需一个 URL（http://localhost:4000）、一个虚拟密钥，使用标准 OpenAI SDK 即可。

代理端

model_list 将别名（如chat-fr、code-rapide、analyse-doc）映射到真实的后端。

Routing

同一个别名对应多个后端 = 负载均衡、后备切换、自动重试。

可观测性

日志、延迟，以及按请求和虚拟密钥统计的成本，可导出至 Langfuse、Prometheus 或 Postgres 数据库。

#先决条件

Python 3.10+

LiteLLM是一个pip包。使用独立的虚拟环境或pipx即可。

Ollama 正在运行

在 http://localhost:11434 上运行，且已拉取至少一个模型。如有需要，请参阅 Ollama 安装指南。

云API密钥（可选）

OPENAI_API_KEY、ANTHROPIC_API_KEY：如果您希望将请求路由到云端作为后备方案，则需要这些密钥。

一个 .env 文件

为避免在 config.yaml 中明文提交密钥。

#1. 安装

pip install 'litellm[proxy]'

proxy 扩展依赖包包含 FastAPI、uvicorn 以及可选依赖项（Postgres，以及需要共享速率限制时使用的 Redis）。用于快速测试，这些就足够了。用于生产环境，则建议采用官方 Docker 镜像。

docker run -d --name litellm \
  -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml

请确认运行情况：

curl http://localhost:4000/health/liveliness

#2. 最简 LiteLLM config.yaml 配置文件

在项目旁边创建 config.yaml 文件。配置文件包含三个部分：model_list（别名）、litellm_settings（全局行为）和 general_settings（认证、数据库）。

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: code-rapide
    litellm_params:
      model: ollama/qwen3-coder:30b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 60

使用以下配置启动代理：

litellm --config config.yaml --port 4000

在应用层，OpenAI Python SDK 直接与代理通信。应用代码中无需依赖 LiteLLM :

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-fake-local",  # le proxy n'exige pas de vraie clé par défaut
)

resp = client.chat.completions.create(
    model="chat-fr",
    messages=[{"role": "user", "content": "Résume la photosynthèse en 3 lignes."}],
)
print(resp.choices[0].message.content)

#3. 添加OpenAI和Anthropic

从不硬编码密钥。请将密钥存入配置文件旁边的 .env 文件中：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

随后在YAML中使用 os.environ 语法引用变量——LiteLLM将在启动时进行替换 :

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: analyse-doc
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY

到这一步，您已有三个逻辑别名。应用代码为私密对话选择 chat-fr，为较长的请求选择 chat-gros，为 PDF 阅读选择 analyse-doc。代码中不会出现任何密钥。

#4. 按模型路由与自动回退

代理服务器的真正价值就在这里体现出来。需要了解两个机制：在同一个 model_name 下配置多个条目（负载均衡），以及 fallbacks 配置键（出错时切换到备用模型）。

1. 01
   多个配置条目，一个别名

   您可以声明两次 model_name: chat-fr：一项指向本地 Ollama，另一项指向云端 Mistral 模型。LiteLLM 根据策略分配请求，默认使用 simple-shuffle；如果您希望优化成本，也可以使用 usage-based-routing。
2. 02
   显式回退

   在 litellm_settings 中声明，当第一个服务返回错误或超时时，由哪个别名接管。故障转移会自动在备用后端上触发重试。
3. 03
   健康检查运行中

   LiteLLM会定期向每个模型发送心跳检测。若某个Ollama服务停止响应，则被标记为不健康并从可用池中移除，直到其恢复——您的请求会自动切换至云端。

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: chat-fr-cloud
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 30
  fallbacks:
    - chat-fr: ["chat-fr-cloud"]
  context_window_fallbacks:
    - chat-fr: ["chat-fr-cloud"]

使用此配置时，您的应用始终调用 model: "chat-fr"。如果 Ollama 不可用、请求超时，或提示词超出您在本地分配的上下文窗口（为节省显存而调低了 num_ctx），代理就会无缝切换到 GPT-4o-mini。应用不会察觉这一切换，只会收到回复，可能稍慢一些。

#5. 成本跟踪和速率限制

混合技术栈存在隐藏成本：您以为使用的是本地模型，实际上 30% 的请求已经切换到了 GPT-4o。LiteLLM 根据内部价格表（与公开价目表保持同步）计算每个请求的成本。

为持久保存日志并提供仪表盘，请连接一个Postgres数据库：

general_settings:
  master_key: sk-litellm-prod-changeme
  database_url: "postgresql://litellm:pass@localhost:5432/litellm"
  store_model_in_db: true

litellm_settings:
  success_callback: ["langfuse"]   # ou prometheus, datadog, etc.
  cache: true

连接 Postgres 后，管理界面（http://localhost:4000/ui）会按虚拟密钥、模型和用户显示费用。您还可以创建设有预算上限的虚拟密钥——这样就能方便地向团队提供访问权限，而不必担心费用失控。

每 100 万输出 token 的成本数量级（2026 年 6 月公开价格，需根据您的供应商重新计算）：

本地 Ollama（Qwen 3.5 9B Q4）

0 $ 边际成本——仅包含您的电力和 GPU 折旧费用。

OpenAI gpt-4o-mini

每 100 万个输出 token 约 0.60 美元，非常适合作为低成本备用方案。

Anthropic Claude Haiku 4.5

约 5 美元/100 万 token 输出，价格较高，但在文档分析方面具备出色的性价比。

OpenAI gpt-4o

每 100 万个输出 token 约 10 美元，建议仅用于 4o-mini 表现不够好的任务。

在速率限制方面，为每个模型设定 RPM（每分钟请求数）和 TPM（每分钟 token 数）的上限。LiteLLM 会根据您的配置将请求排队，或返回 429 错误：

model_list:
  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
      rpm: 60
      tpm: 100000

#故障排除

别名存在，却提示“Model not found”

请检查YAML的缩进。litellm_params下的多余空格会导致代理静默忽略该配置项。运行 litellm --config config.yaml --debug 可查看实际加载的 model_list。

降级机制未触发

num_retries必须≥1，而且必须达到超时时限。默认情况下，Ollama侧的request_timeout设置得很长——将其缩短至30秒，让备用方案能及时触发。

在 Ollama 上出现 401 错误

ollama/* 不接受 API 密钥。如果您在 Ollama 配置项中设置了 api_key，请将其移除。LiteLLM 会原样传递该密钥，导致调用失败。

费用显示错误或为零

价格表取决于 LiteLLM 版本。请更新（pip install -U 'litellm[proxy]'）。对于未列出的自定义模型，需手动在 litellm_params 中声明 input_cost_per_token 和 output_cost_per_token。

在 Ollama 上出现异常延迟

代理每分钟进行一次健康检查。如果 Ollama 加载模型缓慢（冷启动），检查会超时并标记模型为不健康。请增大 health_check_interval 或使用 ollama run X --keepalive 60m 预加载模型。

#深入了解

采用这套配置后，您的所有 AI，无论在本地还是云端，都有一个统一入口，并可无缝切换。顺理成章的后续步骤如下：