03-特性与参数
LiteLLM 特性与参数配置
版本：LiteLLM 1.50+ |作者：Pozicaiman |日期：2026-07-27
定位：LiteLLM 核心特性、关键参数配置与性能指标详解
关键词：特性列表、参数配置、性能调优、路由策略
适用版本：Python 3.8+ / LiteLLM 1.50+
一、核心特性
LiteLLM 围绕「统一接入、可靠路由、成本可控、安全合规」四大目标，提供了一系列覆盖请求全生命周期的企业级特性。下表汇总了 12 项核心特性及其适用场景，便于快速建立整体认知。
| 序号 | 特性 | 说明 | 适用场景 |
|---|---|---|---|
| 1 | 统一 OpenAI 兼容 API | 所有 provider 使用相同接口格式，调用方无需感知底层差异 | 多 provider 切换、SDK 统一封装 |
| 2 | 100+ Provider 支持 | 覆盖 OpenAI / Anthropic / Gemini / Azure / Bedrock 等主流厂商 | 异构模型管理、混合云部署 |
| 3 | 负载均衡 | 支持加权 / 最少连接 / 延迟优先等多种路由策略 | 高可用部署、多副本分流 |
| 4 | Fallback 故障转移 | 主模型失败自动切换至备选模型，保障请求成功率 | 容灾保障、SLA 敏感业务 |
| 5 | 响应缓存 | 支持 Redis / 内存缓存，避免重复调用相同请求 | 降低成本、降低延迟 |
| 6 | 速率限制 | 支持 RPM / TPM 限制，粒度覆盖 per-key / per-team | 流量控制、配额管理 |
| 7 | 成本追踪 | 提供 per-key / team / model 维度的预算管理与花费统计 | 成本控制、计费分摊 |
| 8 | 虚拟密钥 | 带预算和限制的 API Key，可独立颁发与回收 | 多租户管理、对外授权 |
| 9 | Guardrails | 输入输出内容过滤，支持预设词表与自定义规则 | 安全合规、内容审核 |
| 10 | 流式响应 | SSE streaming 支持，兼容 OpenAI 流式协议 | 实时交互、打字机效果 |
| 11 | 可观测性 | 集成 Prometheus / Langfuse / Helicone 等监控追踪平台 | 监控追踪、链路分析 |
| 12 | 多语言 SDK | 提供 Python / JS SDK，并集成 Langchain / LlamaIndex | 开发者友好、快速集成 |
特性分层说明：特性 1-2 属于「统一接入层」；特性 3-4 属于「可靠路由层」；特性 5-8 属于「成本与配额层」；特性 9-11 属于「安全与可观测层」；特性 12 属于「生态集成层」。理解分层有助于在架构设计时按需启用。
二、关键参数配置
LiteLLM 的参数配置分为三个层面：Proxy Server 全局参数控制网关整体行为；Router 路由参数控制请求分发与容错策略；Model 配置参数控制单个模型实例的调用细节。此外，Cache 配置参数独立控制缓存行为。下面分别详述。
2.1 Proxy Server 核心参数
Proxy Server 参数主要通过环境变量注入，影响网关进程的运行行为。生产环境需重点关注的参数已标注「★」。
| 参数名 | 默认值 | 说明 | 调优建议 |
|---|---|---|---|
PORT | 4000 | Proxy 监听端口 | 生产环境建议 8080，避免与开发端口冲突 |
LITELLM_LOG | INFO | 日志级别 | 生产用 WARNING，减少日志量 |
DROP_PARAMS★ | False | 丢弃目标 provider 不支持的参数 | True 避免因参数不兼容报错 |
SET_VERBOSE_MODE | False | 详细日志输出 | 仅调试时开启 True |
FAST_API_SLACK_ALERTING★ | False | Slack 告警通知 | 生产开启，及时感知异常 |
REDIS_HOST★ | None | Redis 地址 | 分布式部署必须设置 |
REDIS_PORT | 6379 | Redis 端口 | 保持默认，注意防火墙放行 |
REDIS_PASSWORD★ | None | Redis 密码 | 生产必须设置，避免未授权访问 |
DATABASE_URL★ | None | PostgreSQL 连接串 | 日志持久化 / 预算管理必须 |
LITELLM_SALT_KEY★ | None | 密钥加密盐值 | 生产必须设置，保护虚拟密钥 |
STORE_MODEL_IN_DB | False | 从 DB 加载模型配置 | 动态管理模型时开启 |
MAX_WORKERS | 8 | uvicorn worker 数 | 按 CPU 核数调整，建议 2×CPU |
REQUEST_TIMEOUT | 600 | 请求超时(秒) | 按场景调整，长文本建议 900 |
LITELLM_LICENSE | None | 企业版 License | 启用 SSO / 审计等企业功能 |
DISABLE_ERROR_LOGS | False | 禁用错误日志 | 不建议关闭，影响排障 |
配置示例（
.env文件）：PORT=8080LITELLM_LOG=WARNINGDROP_PARAMS=TrueREDIS_HOST=redis.internalREDIS_PORT=6379REDIS_PASSWORD=********DATABASE_URL=postgresql://litellm:****@db.internal:5432/litellmLITELLM_SALT_KEY=sk-salt-********MAX_WORKERS=16
2.2 Router 路由参数
Router 参数定义在litellm_settings配置块中，控制请求在多个 model deployment 之间的分发、重试与容错逻辑。
| 参数名 | 默认值 | 说明 | 调优建议 |
|---|---|---|---|
routing_mode | simple-shuffle | 路由策略 | 生产用 least-busy，避免热点 |
num_retries | 3 | 重试次数 | 保持默认，过大易放大下游压力 |
retry_after | 1 | 重试间隔(秒) | 建议配合指数退避 |
fallbacks | [] | 故障转移链 | 按需配置，形成主备梯队 |
allowed_fails | 3 | 允许失败次数 | 触发 cooldown 前的容忍度 |
cooldown_time | 60 | 冷却时间(秒) | 保持默认，过短易抖动 |
retry_policy | None | 重试策略 | 按状态码精细配置 |
timeout | 30 | 超时(秒) | 流式场景建议 60 |
cache | None | 缓存配置 | 分布式用 Redis |
cache_params.max_size | 1000 | 缓存大小 | 按内存与命中率调整 |
enable_pre_call_checks | False | 调用前检查 | 生产开启，提前校验上下文窗口等 |
context_window_fallbacks | [] | 上下文窗口回退 | 长文本场景必备 |
路由策略对比：
simple-shuffle：随机加权，实现简单，适合均匀部署least-busy：选择当前请求数最少的实例，适合长连接 / 流式latency-based-routing：选择历史延迟最低的实例，适合延迟敏感场景usage-based-routing：按 TPM 使用率选择，适合配额均衡
配置示例：
litellm_settings:routing_mode:least-busynum_retries:3retry_after:1timeout:30allowed_fails:3cooldown_time:60enable_pre_call_checks:truefallbacks:-gpt-4:[gpt-4-backup,claude-3-opus]context_window_fallbacks:-gpt-4:[claude-3-opus]retry_policy:InternalServerErrorRetries:2RateLimitErrorRetries:3
2.3 Model 配置参数
Model 配置定义在model_list中，每个条目对应一个可调用的 deployment。同一个model_name可挂载多个 deployment，Router 会按策略在它们之间分发。下面给出一份带详细注释的完整 YAML 配置示例。
model_list:-model_name:gpt-4# 用户调用的模型名(对外暴露的逻辑名)litellm_params:model:azure/gpt-4-turbo# 实际 provider 模型(provider/model 格式)api_base:https://xxx.openai.azure.com# provider API 地址api_key:os.environ/AZURE_API_KEY# 从环境变量读取密钥api_version:"2024-02-15-preview"# Azure API 版本weight:50# 权重(负载均衡,按比例分流)rpm:100# 每分钟请求限制(RPM)tpm:100000# 每分钟 token 限制(TPM)max_tokens:4096# 最大输出 token 数timeout:30# 非流式超时秒数stream_timeout:60# 流式超时秒数input_cost_per_token:0.00001# 输入成本/token(用于成本追踪)output_cost_per_token:0.00003# 输出成本/token(用于成本追踪)# 同名挂载多 deployment,Router 自动负载均衡-model_name:gpt-4litellm_params:model:openai/gpt-4-turboapi_key:os.environ/OPENAI_API_KEYweight:50# 与上面各 50% 权重rpm:200tpm:200000# Anthropic 模型示例-model_name:claude-3-opuslitellm_params:model:anthropic/claude-3-opus-20240229api_key:os.environ/ANTHROPIC_API_KEYmax_tokens:4096timeout:30input_cost_per_token:0.000015output_cost_per_token:0.000075# Gemini 模型示例-model_name:gemini-prolitellm_params:model:gemini/gemini-1.5-proapi_key:os.environ/GEMINI_API_KEYtimeout:60stream_timeout:120配置要点：
model_name是对外逻辑名，调用方始终用此名；model是 provider 真实模型名。- 同一个
model_name挂载多个 deployment 即可启用负载均衡，无需额外配置。weight决定流量分配比例；rpm/tpm用于速率限制与配额保护。input_cost_per_token/output_cost_per_token是成本追踪的依据，务必准确填写。- 敏感信息统一用
os.environ/VAR_NAME引用，避免明文写入配置。
2.4 Cache 配置参数
缓存配置通过litellm_settings.cache块定义，命中缓存可直接返回结果，避免重复调用上游。下表列出核心参数。
| 参数名 | 默认值 | 说明 | 调优建议 |
|---|---|---|---|
type | redis | 缓存类型 | 生产用 redis，单机可用 local |
host | None | Redis 地址 | 分布式部署必填 |
port | 6379 | Redis 端口 | 保持默认 |
ttl | 86400 | 缓存 TTL(秒) | 按场景调整，实时性要求高则调小 |
namespace | None | 命名空间 | 多租户隔离用 |
disable | False | 禁用缓存 | 调试时临时关闭 |
max_size | 1000 | 最大缓存条目数 | 按内存与命中率调整 |
semantic_cache | False | 语义缓存 | 降低成本但需 embedding 模型 |
配置示例：
litellm_settings:cache:truecache_params:type:redishost:redis.internalport:6379password:os.environ/REDIS_PASSWORDttl:3600namespace:prod-tenant-amax_size:5000# semantic_cache: true # 开启语义缓存需额外配置 embedding model# semantic_cache_embedding_model: openai/text-embedding-3-small调用端启用缓存：在请求中传入
cache={"no-cache": false, "no-store": false}即可命中；如需强制刷新，设置no-store: true。
三、性能指标
3.1 基准性能数据
以下数据基于单节点（8 核 16G）标准部署、Redis 缓存、PostgreSQL 持久化的测试环境，供容量规划参考。实际数值随 provider 响应速度、网络质量与请求模式而变化。
| 指标 | 数值 | 说明 |
|---|---|---|
| 请求吞吐量 | 1000+ RPS | 单节点 (8C16G)，Proxy 层处理能力 |
| P99 延迟开销 | < 50ms | Proxy 层额外延迟(不含上游模型耗时) |
| 并发连接 | 10000+ | 单节点可支撑的并发连接数 |
| Cache 命中率 | 30-60% | 重复请求场景下的命中率区间 |
| 故障切换 | < 2s | Fallback 触发到备选返回的时间 |
| 启动时间 | < 5s | 冷启动到就绪状态 |
| 内存占用 | 200-500MB | 基础内存(不含缓存与日志缓冲) |
| CPU 占用 | 1-2 core | 中等负载(500 RPS)下的 CPU 使用 |
指标解读：
- 吞吐量瓶颈通常不在 Proxy 本身，而在上游 provider 的响应速度；水平扩展 Proxy 副本可线性提升。
- P99 延迟开销主要来自参数校验、路由决策与日志写入，开启
enable_pre_call_checks会略有增加。- Cache 命中率高度依赖请求模式：客服 FAQ 场景可达 60%+，而多轮对话场景通常 < 20%。
- 故障切换时间包含重试与 fallback 两次调用，超时设置过大会显著拉长该时间。
3.2 性能调优方向
性能调优应遵循「先观测、后调优」原则，借助可观测性指标定位瓶颈，再有针对性地调整。以下为 5 个核心优化方向。
| 序号 | 优化方向 | 关键措施 | 预期收益 |
|---|---|---|---|
| 1 | Worker 调优 | MAX_WORKERS按 CPU 核数调整，建议 2×CPU；过大会增加调度开销 | 提升吞吐量 20-30% |
| 2 | 连接池优化 | 复用 HTTP 连接，减少 TLS 握手开销；调整httpx连接池上限 | 降低 P99 延迟 10-15% |
| 3 | 缓存策略 | 高频重复请求开启缓存，按场景调整 TTL；语义缓存覆盖相似问题 | 命中率提升至 50%+，成本下降 |
| 4 | 路由优化 | least-busy策略避免热点；按 TPM 使用率均衡分发 | 消除单点过载，提升整体稳定性 |
| 5 | 批量请求 | 使用 Batch API 合并多个独立请求，减少往返次数 | 单位成本下降，吞吐提升 |
调优顺序建议：先确保
MAX_WORKERS与连接池配置合理（硬件层）→ 再启用缓存与路由优化（策略层）→ 最后通过 Batch API 等手段优化请求模式（业务层）。逐层验证收益，避免多变量同时调整导致难以归因。
小结：本章梳理了 LiteLLM 的 12 项核心特性与四类关键参数配置。核心要点：Proxy 参数影响网关运行行为，Router 参数决定路由容错策略，Model 参数控制单实例调用细节，Cache 参数独立管理缓存。性能层面，LiteLLM Proxy 层开销极低（P99 < 50ms），瓶颈多在上游 provider，调优应聚焦 worker、连接池、缓存与路由策略。后续章节将进入应用场景与安装部署的实战环节。