LiteLLM 实战：一个模型网关统一调度本地 Ollama 和云端 API，应用侧零感知

玩本地 AI 的朋友基本都会遇到一个尴尬：家里跑着 Ollama，服务器上挂了个 vLLM，云端还充了 DeepSeek、Qwen 的 API key。三个端点、三套 key，应用想切换模型，要么改配置，要么装一堆连接器，折腾到最后自己都记不清哪个模型在哪儿跑。今天这篇就给你一个干净利落的解法——LiteLLM，一个 OpenAI 兼容的模型网关，把所有大模型统一成一个入口。

LiteLLM 到底解决了什么问题

一句话概括：LiteLLM 是一个代理层，对外只暴露一个 OpenAI 格式的 API 端点，对内帮你把请求路由到 100 多家模型提供商（Ollama、vLLM、OpenAI、Anthropic、DeepSeek、通义千问……全都支持）。它干三件事：

• 统一入口：应用永远只连 LiteLLM 一个地址，模型随便加随便换。
• 路由与降级：同一个模型别名背后可以挂多个真实模型，一个挂了自动切下一个。
• 用量与预算：所有请求的 token 消耗、成本、失败率，一个面板全看到。

对 IT 大叔这种多节点、多模型的家用环境来说，这玩意儿几乎是刚需：本地模型跑量大、云端模型跑质量，一个网关统一调度，应用侧零感知。

部署：一条 Docker 命令起服务

推荐用 docker-compose，配置和升级都省心。先建个工作目录，写一个 docker-compose.yml：

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm
    restart: unless-stopped
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=postgresql://litellm:litellm@db:5432/litellm
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml"]
    depends_on:
      - db

  db:
    image: postgres:16
    container_name: litellm-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=litellm
      - POSTGRES_PASSWORD=litellm
      - POSTGRES_DB=litellm
    volumes:
      - ./pgdata:/var/lib/postgresql/data

这里我配了个 Postgres 来存用量日志和 key，方便后面看统计。如果你只想要一个轻量网关、不在乎历史记录，也可以把 DATABASE_URL 那行删掉，LiteLLM 会退回本地文件存储。起服务：

docker compose up -d

核心配置：把模型都挂进来

接下来是重头戏 config.yaml。下面这份配置同时挂上了本地的 Ollama、vLLM，以及云端的 DeepSeek 和 Qwen，还定义了一个带降级逻辑的别名：

model_list:
  # 本地 Ollama
  - model_name: qwen2.5-7b-local
    litellm_params:
      model: ollama/qwen2.5:7b
      api_base: http://192.168.1.10:11434

  # 本地 vLLM
  - model_name: qwen2.5-72b-vllm
    litellm_params:
      model: openai/qwen2.5-72b
      api_base: http://192.168.1.20:8000/v1

  # 云端 DeepSeek
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

  # 云端 Qwen
  - model_name: qwen-plus
    litellm_params:
      model: openai/qwen-plus
      api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: os.environ/DASHSCOPE_API_KEY

# 别名 + 降级：先试本地 72B，挂了自动切云端 Qwen
litellm_settings:
  model_alias_map:
    smart: qwen2.5-72b-vllm

router_settings:
  fallbacks:
    - {"qwen2.5-72b-vllm": ["qwen-plus"]}

注意几个关键点：本地模型用 ollama/ 前缀配 api_base；云端模型要么走 openai/ 前缀 + 自定义 base URL，要么用厂商专属前缀（如 deepseek/）。API key 我用了 os.environ/XXX 这种写法，意思是去容器环境变量里读，别把 key 明文写进 yaml——这样配置文件可以放心提交到 git。

验证：一个 curl 打通所有模型

服务起来后，测试一下网关能不能正常工作。先不用 key（本地没开鉴权的情况下），直接请求本地 Ollama 那个模型：

curl -s http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b-local",
    "messages": [{"role": "user", "content": "用一句话解释什么是模型网关"}]
  }'

返回的结构和 OpenAI 完全一致，choices[0].message.content 里就是回复。再测一下带降级的别名 smart——它会优先打本地 72B，如果 vLLM 那台机器没开机，LiteLLM 会自动把请求转发到云端的 qwen-plus，整个过程对调用方完全透明。

进阶：给网关加把锁

网关是要暴露给多个应用用的，不能裸奔。给 LiteLLM 生成一个虚拟 key，应用拿着这个 key 才能调：

# 生成一个总 key
curl -s http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -d '{"models": ["qwen2.5-7b-local", "smart", "deepseek-chat"]}'

返回的 key 字段就是虚拟 key，你可以给每个应用发一个，还能精确限制它只能用哪几个模型、每月花多少钱。这个”按应用发 key + 限模型限预算”的能力，是 LiteLLM 相比直接连 Ollama 最值钱的地方——你终于知道是哪台应用在偷偷烧 token 了。

小结

LiteLLM 不是替代 Ollama 或 vLLM，而是站在它们前面当”总调度”。本地多模型 + 云端 API 混搭的 homelab，强烈建议上一个：一个端点、一套鉴权、一份用量账单，应用侧从此不用再关心模型到底跑在哪台机器上。配置文件不复杂，Docker 一条命令就能起，跑通了你会后悔没早点装。