LiteLLM 配置使用教程

本教程将引导您完成 LiteLLM 的基本配置和使用，并深入解读其高级功能。

一、 运行效果展示

配置完成后，您可以将不同的大语言模型统一到一个 API 端点下进行调用。

运行状态截图:

实际调用效果:

二、 快速搭建过程

1. 核心配置文件 (config.yaml) 解读

以下是一个基础的 LiteLLM 配置文件示例，它定义了模型列表、下游密钥和路由设置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# config.yaml

# 模型列表：定义所有你希望代理的上游模型
model_list:
  - model_name: doubao-coding
    litellm_params:
      model: openai/doubao-seed-code-preview-latest
      api_base: https://ark.cn-beijing.volces.com/api/coding/v1
      api_key: 62dd0301-9734-4e9a-bf83-16153b9b5717

  - model_name: modelscope-random
    litellm_params:
      model: openai/ZhipuAI/GLM-4.6
      api_base: https://api-inference.modelscope.cn/v1
      api_key: ms-cb3e60b0-d2df-4972-8dc3-c69326cfd5b9

# 通用设置：定义 LiteLLM Proxy 的通用规则
general_settings:
  valid_keys:
    - "sk-MC9W4Q0U58943Y6HV984N205UY90823Q4NMUV5C012"

# 路由设置：控制请求的超时和重试策略
router_settings:
  timeout: 300
  num_retries: 3

2. model_list 配置详解

model_list 是配置文件的核心，用于定义您要代理的所有上游模型。

1
2
3
4
5

- model_name: doubao-coding # 自定义下游调用的模型名称
  litellm_params:
    model: openai/doubao-seed-code-preview-latest # 'openai/' 前缀表示以 OpenAI 格式请求, '/' 后填写实际上游模型名称
    api_base: https://xxxxxx.xxx/xxx/xxxxx/v1 # 填写实际上游模型的 API 地址，通常以 'v1' 结尾
    api_key: xxxxxxxxxxxxxxxxxxx # 填写实际上游模型的 API 密钥

提示: 如果您想添加多个上游模型，只需复制并粘贴以上代码块，并修改相应的参数即可。请务必保持正确的 YAML 缩进。

3. general_settings 配置详解

general_settings 用于配置 Proxy 的通用规则，例如身份验证和日志记录。

1
2
3
4
5
6
7
8

general_settings:
  # 在这里定义允许访问 LiteLLM 服务的下游 API 密钥
  valid_keys:
    - "sk-MC9W4Q0U58943Y6HV984N205UY90823Q4NMUV5C012"
    - "sk-dafhdesowiufhaoefh2834905ru43qhftgnq09rda" 
  
  # 将日志输出到标准输出流 (stdout)
  logging: stdout 

4. 其他常用配置项

路由设置 (router_settings)

1
2
3

router_settings:
  timeout: 300 # 全局请求超时时间（秒）
  num_retries: 3 # 全局请求重试次数

速率限制 (rate_limits)

您可以为特定的模型设置请求频率限制。

1
2
3

rate_limits:
  - model: sonnet-4 # 需要限制的模型名称
    rpm: 60 # 每分钟最大请求次数

三、 高级功能：官方文档深度解读

基于以上配置，LiteLLM 已经可以满足个人中转使用的基本需求。如果您希望探索更多企业级功能，可以参考 LiteLLM 官方文档。以下内容来自 Gemini-2.5-Pro 对官方文档的模块化解读。

文档结构总览

LiteLLM 的配置主要通过 YAML 文件或环境变量进行，其核心模块分为以下几部分：

1. model_list: 模型定义。核心部分，定义所有要代理的大语言模型。
2. litellm_settings: LiteLLM 自身行为设置。控制日志、回调、网络、缓存和故障转移等核心功能。
3. general_settings: Proxy/服务器通用设置。负责用户管理、数据库、安全和计费等服务器级别的功能。
4. router_settings: 高级路由设置。负责在多个模型部署之间进行智能路由、负载均衡和故障恢复。
5. environment_variables: 环境变量。许多配置也支持通过环境变量设置，方便在 Docker 等容器化环境中使用。

模块化功能详解

模块一：模型定义 (model_list)

这是基础配置，每个模型定义包含：

• model_name: 您给模型起的“别名”，供客户端调用。
• litellm_params: 连接到真实模型所需的信息（model, api_key, api_base 等）。
• model_info (可选): 为模型提供元数据。
  • id: 模型的唯一标识符。
  • mode: 模型类型，例如 embedding（用于生成向量）。
  • input_cost_per_token / output_cost_per_token: 定义输入/输出 Token 的成本，用于计费和预算控制。
  • max_tokens: 模型支持的最大上下文长度。
  • base_model: 模型的基础模型（例如 gpt-4）。

解读：model_info 的加入让 LiteLLM 不仅能代理模型，还能对模型的成本和能力进行管理。

模块二：可靠性与故障恢复 (litellm_settings & router_settings)

这是 LiteLLM 作为企业级网关的核心价值，确保服务稳定。

• default_fallbacks: 默认备用模型。当一个模型请求失败时，自动切换到此列表中的备用模型。
• context_window_fallbacks: 上下文超长备用。当请求因上下文超长而失败时，自动切换到上下文更长的模型。
• content_policy_fallbacks: 内容安全备用。当请求因内容审查失败时，切换到审查策略不同的模型。
• cooldown_time / allowed_fails: 熔断机制。如果一个模型在短时间内连续失败多次 (allowed_fails)，则将其“冷却” (cooldown_time)，暂时停止向其发送请求。
• num_retries / retry_policy: 自动重试。可以针对不同类型的错误（如认证失败、超时）设置不同的重试策略。

解读：这一整套机制（备用、熔断、重试）极大地提高了服务的健壮性，使 LiteLLM 能自动处理各种异常。

模块三：可观测性 (Logging & Callbacks) (litellm_settings)

让您清楚地了解系统内部的运行状况。

• success_callback / failure_callback: 成功/失败回调。当请求成功或失败时，将日志和元数据发送到指定的第三方服务，如 Langfuse, OpenTelemetry (OTel), Sentry, Datadog 等。
• json_logs: 将日志输出为 JSON 格式，方便机器解析和收集。
• set_verbose: 开启详细调试日志，用于深度问题排查（不建议在生产环境开启）。
• turn_off_message_logging: 出于隐私或合规考虑，关闭对请求体（Prompt 和 Response）的记录，只记录元数据。

解读：LiteLLM 不仅是转发工具，还能深度集成到您现有的监控体系中，实现企业级的日志、追踪和监控。

模块四：性能优化 (Caching) (litellm_settings)

减少重复请求，降低成本和延迟。

• cache: true: 开启缓存功能。
• cache_params: 配置缓存后端。
  • type: redis: 使用 Redis 作为缓存数据库，是生产环境的常见选择。
  • qdrant_semantic_cache_embedding_model: 语义缓存。这是一个高级功能，它不仅缓存完全相同的请求，还能通过向量相似度判断“语义上相似”的请求，并直接返回缓存结果。
  • ttl: 缓存的存活时间 (Time To Live)。

解读：缓存是节省成本和提升响应速度的利器。特别是语义缓存，能极大地提升常见问题的响应效率。

模块五：用户与安全管理 (general_settings)

负责管理谁能用、怎么用。

• master_key: 代理的超级管理员密钥。
• database_url: 连接数据库的 URL。这是实现虚拟密钥、用户预算、消费记录等功能的基础。配置数据库后，LiteLLM 就从一个简单的代理变成了功能完善的模型管理平台。
• disable_spend_logs: 关闭消费记录，如果您不关心计费。
• enable_jwt_auth: 支持使用 JWT (JSON Web Tokens) 进行认证，方便与现有用户系统集成。
• key_management_system: 集成专业的密钥管理服务（如 google_kms 或 azure_kms），进一步提升安全性。

解读：这部分配置让 LiteLLM 具备了多租户管理能力。您可以为不同用户或团队生成虚拟 API Key，并对他们的消费和权限进行精细化管理。

模块六：高级路由策略 (router_settings)

当您为同一个模型配置了多个部署时（例如，一个 OpenAI 的 gpt-4 和一个 Azure 的 gpt-4），此功能非常有用。

• routing_strategy: 定义路由策略。
  • simple-shuffle: 随机选择一个部署。
  • least-busy: 选择最空闲的（根据当前的 TPM/RPM）。
  • latency-based-routing: 选择延迟最低的。
  • usage-based-routing-v2: 基于使用情况的路由（优先选择成本最低或限额剩余最多的）。
    解读：高级路由策略实现了智能负载均衡和成本优化。LiteLLM 可以动态地将请求发送到当前最健康、最快或最便宜的模型部署上。