一、架构总览
┌─────────────────────────────────────────────────────────┐
│ Dify 应用层 │
│ (Chatflow / Workflow / Agent / 知识库 RAG) │
│ │
│ 模型供应商: OpenAI-API-Compatible │
│ Base URL: http://litellm-proxy:4000/v1 │
└──────────────────────┬──────────────────────────────────┘
│ OpenAI 兼容协议
▼
┌─────────────────────────────────────────────────────────┐
│ LiteLLM Proxy Server (:4000) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ 路由策略 │ │ Fallback 降级 │ │ 负载均衡 │ │
│ │ (Router) │ │ │ │ (LoadBalance) │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ 预算/限流 │ │ API Key 管理 │ │ 用量追踪 │ │
│ │ (Budget) │ │ (Virtual Key) │ │ (Logging) │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
└───────┬───────────────┬───────────────┬─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│ OpenAI │ │ Anthropic│ │ Azure │ ... 更多供应商
│ GPT-4o │ │ Claude │ │ / 本地 │
└─────────┘ └──────────┘ └──────────┘核心价值：Dify 只需对接一个 LiteLLM 端点，由 LiteLLM 统一管理底层多供应商的密钥、路由、降级、限流和成本控制。
二、Step 1：部署 LiteLLM Proxy
2.1 Docker Compose 部署（推荐生产环境）
Yaml
# docker-compose.litellm.yml
version: '3.8'
services:
litellm:
image: ghcr.io/berriai/litellm:main-latest
container_name: litellm-proxy
ports:
- "4000:4000" # 对外 API 端口
volumes:
- ./litellm_config.yaml:/app/config.yaml
command:
- "--config"
- "/app/config.yaml"
- "--port"
- "4000"
- "--host"
- "0.0.0.0" # ⚠️ 必须绑定 0.0.0.0，不能用 localhost！
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- AZURE_API_KEY=${AZURE_API_KEY}
# 数据库（可选，用于持久化 Virtual Key 和日志）
- DATABASE_URL=postgresql://litellm:litellm@litellm-db:5432/litellm
depends_on:
- litellm-db
restart: unless-stopped
litellm-db:
image: postgres:16-alpine
container_name: litellm-db
environment:
- POSTGRES_USER=litellm
- POSTGRES_PASSWORD=litellm
- POSTGRES_DB=litellm
volumes:
- litellm_pgdata:/var/lib/postgresql/data
restart: unless-stopped
volumes:
litellm_pgdata:2.2 LiteLLM 核心配置文件（多模型多路由）
Yaml
# litellm_config.yaml
model_list:
# ═══════════════════════════════════════════
# 模型组 1：主力对话模型（负载均衡 + 多供应商）
# ═══════════════════════════════════════════
- model_name: gpt-4o # Dify 中使用的模型名
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
model_info:
max_tokens: 128000
mode: chat
- model_name: gpt-4o # 同名 = 自动负载均衡
litellm_params:
model: azure/gpt-4o
api_key: os.environ/AZURE_API_KEY
api_base: https://my-resource.openai.azure.com
api_version: "2024-06-01"
model_info:
max_tokens: 128000
mode: chat
# ═══════════════════════════════════════════
# 模型组 2：轻量快速模型
# ═══════════════════════════════════════════
- model_name: fast-chat
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY
- model_name: fast-chat # 备选：Claude Haiku
litellm_params:
model: anthropic/claude-3-5-haiku-20241022
api_key: os.environ/ANTHROPIC_API_KEY
# ═══════════════════════════════════════════
# 模型组 3：Embedding 模型
# ═══════════════════════════════════════════
- model_name: text-embedding
litellm_params:
model: openai/text-embedding-3-small
api_key: os.environ/OPENAI_API_KEY
# ═══════════════════════════════════════════
# 模型组 4：本地模型（通过 vLLM / Ollama）
# ═══════════════════════════════════════════
- model_name: local-llama
litellm_params:
model: openai/meta-llama/Llama-3.1-70B-Instruct
api_base: http://vllm-server:8000/v1
api_key: vllm-dummy-key # 本地服务不需要真实 Key
# ═══════════════════════════════════════════════
# 路由策略（Router Settings）
# ═══════════════════════════════════════════════
router_settings:
routing_strategy: usage-based-routing # 按使用量智能分发
num_retries: 3 # 失败自动重试 3 次
timeout: 30 # 单次请求超时 30s
fallbacks:
# 主模型失败 → 自动降级
- model: gpt-4o
fallback_model: fast-chat # gpt-4o 挂了 → 用 fast-chat
- model: fast-chat
fallback_model: local-llama # fast-chat 挂了 → 用本地模型
context_window_fallbacks:
# 上下文超限时自动切换
- model: gpt-4o
fallback_model: local-llama # 假设本地模型支持更长上下文
# ═══════════════════════════════════════════════
# 通用设置
# ═══════════════════════════════════════════════
litellm_settings:
drop_params: true # 自动丢弃不支持的参数
set_verbose: false # 生产环境关闭详细日志
# 成本/用量追踪（可选）
success_callback: ["langfuse"] # 接入 Langfuse 可观测性
general_settings:
master_key: sk-litellm-master-key-xxxx # Proxy 管理密钥
database_url: os.environ/DATABASE_URL2.3 启动与验证
Bash
# 启动
docker compose -f docker-compose.litellm.yml up -d
# 验证模型列表
curl http://localhost:4000/v1/models \
-H "Authorization: Bearer sk-litellm-master-key-xxxx"
# 测试对话
curl http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer sk-litellm-master-key-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'三、Step 2：Dify 中接入 LiteLLM
3.1 ⚠️ 网络连通性（最常见的坑）
关键：Dify 运行在 Docker 中时，
localhost指向容器自身，不是宿主机！
最佳实践：将 LiteLLM 加入 Dify 的 Docker 网络：
Yaml
# 在 Dify 的 docker-compose.yml 中追加 litellm 服务
services:
# ... 已有 dify 服务 ...
litellm-proxy:
image: ghcr.io/berriai/litellm:main-latest
container_name: litellm-proxy
ports:
- "4000:4000"
volumes:
- ./litellm_config.yaml:/app/config.yaml
command: ["--config", "/app/config.yaml", "--port", "4000", "--host", "0.0.0.0"]
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
networks:
- default # 加入 Dify 同一网络！
restart: unless-stopped这样 Dify 中就可以直接用 http://litellm-proxy:4000/v1。
3.2 在 Dify 中配置模型
进入 Dify → 设置 → 模型供应商 → OpenAI-API-Compatible（或搜索 "OpenAI API Compatible" 安装插件），点击 添加模型：
┌──────────────────────────────────────────────────────┐ │ 添加模型 (OpenAI API Compatible) │ │ │ │ 模型名称: gpt-4o │ │ 模型类型: LLM │ │ API Key: sk-litellm-master-key-xxxx │ │ API endpoint: http://litellm-proxy:4000/v1 │ │ 上下文长度: 128000 │ │ 最大 tokens: 4096 │ │ 函数调用: ✅ 支持 │ │ 流式输出: ✅ 支持 │ │ 模式: Chat │ │ │ │ [ 验证 ] [ 保存 ] │ └──────────────────────────────────────────────────────┘
为 LiteLLM 配置文件中定义的每个模型重复上述步骤：
注意：Dify 中的"模型名称"必须与 LiteLLM
config.yaml中的model_name完全一致。
3.3 设置默认模型
在 设置 → 默认模型设置 中：
系统推理模型：选择
gpt-4oEmbedding 模型：选择
text-embedding
四、Step 3：多路由工程化管理策略
4.1 负载均衡（同一模型名多部署）
Yaml
# litellm_config.yaml 中同一 model_name 出现多次 = 自动负载均衡
model_list:
- model_name: gpt-4o # 实例 1: OpenAI 官方
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
- model_name: gpt-4o # 实例 2: Azure OpenAI
litellm_params:
model: azure/gpt-4o
api_key: os.environ/AZURE_API_KEY
api_base: https://my-azure.openai.azure.com
- model_name: gpt-4o # 实例 3: OpenAI 代理商
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_PROXY_KEY
api_base: https://my-proxy.com/v1路由策略选项：
Yaml
router_settings:
routing_strategy: usage-based-routing # 按用量（权重自动调整）
# 其他可选策略:
# - simple-shuffle # 随机轮询
# - least-busy # 最少并发
# - latency-based-routing # 延迟优先
# - cost-based-routing # 成本优先4.2 Fallback 自动降级链
Yaml
router_settings:
fallbacks:
# 三级降级链
- model: gpt-4o
fallback_model:
- fast-chat # 1st fallback
- local-llama # 2nd fallback (本地兜底)
# 上下文窗口超限降级
context_window_fallbacks:
- model: gpt-4o # 128K 上下文
fallback_model: local-llama # 切换到更大上下文窗口的本地模型
# 内容策略降级
content_policy_fallbacks:
- model: gpt-4o # 被内容策略拦截时
fallback_model: fast-chat4.3 预算与限流管理
Yaml
# litellm_settings 中添加
litellm_settings:
max_budget: 100 # 全局月度预算 $100
budget_duration: "30d"
# 通过 API 创建 Virtual Key 实现精细化管控
# curl -X POST http://localhost:4000/key/generate \
# -H "Authorization: Bearer sk-litellm-master-key-xxxx" \
# -d '{
# "models": ["gpt-4o", "fast-chat"],
# "max_budget": 50,
# "budget_duration": "30d",
# "rpm_limit": 100,
# "tpm_limit": 100000,
# "metadata": {"team": "dify-app-prod"}
# }'4.4 为不同 Dify 应用分配不同 Virtual Key
Bash
# 为生产应用创建专用 Key
curl -X POST http://localhost:4000/key/generate \
-H "Authorization: Bearer sk-litellm-master-key-xxxx" \
-H "Content-Type: application/json" \
-d '{
"models": ["gpt-4o", "fast-chat", "text-embedding"],
"max_budget": 200,
"budget_duration": "30d",
"rpm_limit": 500,
"metadata": {"env": "production", "app": "customer-service-bot"}
}'
# → 返回: sk-litellm-virtual-key-aaa...
# 为开发环境创建受限 Key
curl -X POST http://localhost:4000/key/generate \
-H "Authorization: Bearer sk-litellm-master-key-xxxx" \
-H "Content-Type: application/json" \
-d '{
"models": ["fast-chat"],
"max_budget": 10,
"budget_duration": "30d",
"metadata": {"env": "dev", "app": "playground"}
}'
# → 返回: sk-litellm-virtual-key-bbb...在 Dify 中分别添加两个 OpenAI-API-Compatible 供应商配置，使用不同的 Virtual Key，即可实现生产/开发环境的模型隔离和预算控制。
五、Step 4：Dify 工作流中的模型路由实战
5.1 在工作流中按场景选择模型
在 Dify Workflow 中不同节点使用不同 LiteLLM 模型别名：
[Start] → [IF/ELSE: 查询复杂度判断] ├─ Simple → [LLM: fast-chat] → 轻量回答 └─ Complex → [LLM: gpt-4o] → 深度推理 ↓ [Knowledge Retrieval] (Embedding: text-embedding) ↓ [LLM: gpt-4o] → 最终回答
5.2 模型切换无需改 Dify 配置
最大优势：当需要切换底层模型（如 GPT-4o → Claude 3.5 Sonnet）时，只需修改 litellm_config.yaml：
Yaml
# 只改这里，Dify 完全不用动！
- model_name: gpt-4o # 对 Dify 暴露的名不变
litellm_params:
model: anthropic/claude-3-5-sonnet-20241022 # 底层换了
api_key: os.environ/ANTHROPIC_API_KEY重启 LiteLLM 即可，Dify 侧零修改。
六、运维与可观测性
6.1 LiteLLM Admin UI
LiteLLM 自带管理面板 http://localhost:4000/ui：
📊 实时用量统计（按模型/按 Key）
🔑 Virtual Key 管理
💰 成本追踪
📋 请求日志与错误追踪
6.2 接入 Langfuse 做全链路追踪
Yaml
# litellm_config.yaml
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]6.3 健康检查
Bash
# 定期检查 LiteLLM 健康
curl http://localhost:4000/health/liveliness
curl http://localhost:4000/health/readiness
# 检查所有模型连通性
curl http://localhost:4000/health \
-H "Authorization: Bearer sk-litellm-master-key-xxxx"七、常见问题排查
八、完整工程化清单
✅ LiteLLM Proxy 部署（Docker，绑定 0.0.0.0） ✅ 多模型配置（model_list 定义所有模型别名） ✅ 负载均衡（同名模型多实例） ✅ Fallback 降级链（fallbacks + context_window_fallbacks） ✅ 预算限流（Virtual Key + max_budget + rpm_limit） ✅ Dify OpenAI-API-Compatible 接入（正确 Base URL + API Key） ✅ 网络连通（同一 Docker 网络或 host.docker.internal） ✅ 多环境 Key 隔离（生产/开发不同 Virtual Key） ✅ 可观测性（Admin UI + Langfuse + 健康检查） ✅ 模型热切换（改 config.yaml 重启即可，Dify 零修改）
这套架构的核心优势在于 Dify 专注应用编排，LiteLLM 专注模型治理——两者通过标准 OpenAI API 解耦，各自独立演进，是生产级 AI 应用基础设施的最佳实践之一。