02 · Cooldown 配置项全景¶

本文是 LiteLLM cooldown 全部可配置参数的速查手册。按照"全局 → 单 deployment → 环境变量 → 优先级 → 可观测性"组织。

1. 全局：YAML `router_settings` / `litellm_settings`¶

1.1 `router_settings` 主表¶

写在 proxy_server_config.yaml 的 router_settings: 下。

字段	类型	默认	作用	代码位置
`cooldown_time`	int / float（秒）	`None` → 走默认 5	Router 全局 cooldown 时长	router.py:482
`disable_cooldowns`	bool	`False`	全局禁用 cooldown 机制	router.py:486
`allowed_fails`	int	`None`	启用 V1 模式：连续失败 N 次才 cooldown（不区分错误类型）	router.py
`allowed_fails_policy`	dict	`None`	启用 V1 模式：按错误类型分别配阈值（推荐用法）	详见 §3
`routing_strategy`	string	`simple-shuffle`	跟 cooldown 正交，但所有 strategy 都自动应用 cooldown 过滤	-

1.2 `litellm_settings` 相关字段¶

字段	类型	作用
`num_retries`	int	业务请求失败后内部重试次数。重试期间的失败不写 cooldown，最终失败才写。详见 03 §4
`request_timeout`	int	单次请求超时。超时（408）会触发 cooldown

1.3 配置示例¶

1.3.1 默认（你们 prod 当前）¶

# 全部不设,走代码默认
# - cooldown_time = 5s
# - V2 默认模式（按失败率触发）
# - 所有路径 1.1 ~ 1.4 都启用

1.3.2 调长 cooldown_time¶

router_settings:
  cooldown_time: 30           # 5s → 30s

1.3.3 启用 V1 模式（按累计失败触发）¶

litellm_settings:
  allowed_fails_policy:
    BadRequestErrorAllowedFails: 1000           # 1000 次才冷
    AuthenticationErrorAllowedFails: 3
    TimeoutErrorAllowedFails: 50
    RateLimitErrorAllowedFails: 100
    ContentPolicyViolationErrorAllowedFails: 100
    InternalServerErrorAllowedFails: 20

router_settings:
  cooldown_time: 60

1.3.4 全局禁用 cooldown¶

router_settings:
  disable_cooldowns: true

⚠️ 用前确认你真的不想让 Router 避让失败的 deployment。一般只在 dev / 调试时开。

2. 单 deployment：`model_info.cooldown_time`¶

写在 model_list 每个 deployment 的 model_info: 下。

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      cooldown_time: 120         # 这个 deployment 失败后冷 120s,覆盖 Router 全局

读取点：router.py:5767 在 deployment_callback_on_failure 里：

deployment_cooldown = (
    deployment_obj.get("model_info", {}).get("cooldown_time")
)

适用场景： - 知道某个 deployment 一旦挂会挂得久（比如某个第三方 provider 维护周期） - 某些 region 限流策略不一样，针对性调长

3. `allowed_fails_policy` 全字段¶

代码：router.get_allowed_fails_from_policy

类型映射：

Policy 字段	对应错误类	典型 HTTP 状态码
`BadRequestErrorAllowedFails`	`litellm.BadRequestError`	400
`AuthenticationErrorAllowedFails`	`litellm.AuthenticationError`	401
`TimeoutErrorAllowedFails`	`litellm.Timeout` / `litellm.APITimeoutError`	408
`RateLimitErrorAllowedFails`	`litellm.RateLimitError`	429
`ContentPolicyViolationErrorAllowedFails`	`litellm.ContentPolicyViolationError`	400（特殊 4xx）
`InternalServerErrorAllowedFails`	`litellm.InternalServerError`	500-599

每个字段值是"允许失败几次"。比如 RateLimitErrorAllowedFails: 100 意思是"同一 deployment 连续 429 失败 100 次才 cooldown"。

3.1 ⚠️ Policy 跟"第一关白名单"叠加¶

第一关 _is_cooldown_required 仍然先过。比如 BadRequestErrorAllowedFails: 1000 写了，但 400 错误根本不进 cooldown 流程（白名单挡掉），这个配置等于无效。Policy 只在"白名单允许的错误"上才生效。

实际上 V1 policy 主要在以下错误码生效： - 401（Authentication） - 408（Timeout） - 429（RateLimit） - 5xx（InternalServer）

400 虽然有 BadRequestErrorAllowedFails 字段但不实际触发——因为白名单先挡掉了。

3.2 `allowed_fails`（不区分类型）的兜底¶

litellm_settings:
  allowed_fails: 3      # 任何错误类型,失败 3 次就 cooldown

should_cooldown_based_on_allowed_fails_policy:410-415:

allowed_fails = (
    router.get_allowed_fails_from_policy(exception=...)   # 优先用 policy 里的
    or router.allowed_fails                               # 兜底用全局值
)

优先级：allowed_fails_policy 里有对应字段 > allowed_fails 全局值。

4. 环境变量¶

env	默认值	作用	代码位置
`DEFAULT_COOLDOWN_TIME_SECONDS`	`5`	默认 cooldown 时长	constants.py:43
`SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD`	`1000`	路径 1.2 单 deployment 高流量阈值	constants.py:82-83
`DEFAULT_FAILURE_THRESHOLD_PERCENT`	`0.5`	路径 1.3 失败率阈值	constants.py:38
`DEFAULT_FAILURE_THRESHOLD_MINIMUM_REQUESTS`	`5`	路径 1.3 最小请求数	constants.py:86
`DEFAULT_ALLOWED_FAILS`	`3`	`litellm.allowed_fails` 默认值	constants.py:41

⚠️ 这些常量都是模块导入时一次性 os.getenv，运行中改 env 不生效。改完必须重启 Pod（详见心跳文档 §2.2 导入即冻结陷阱）。

5. `cooldown_time` 优先级（4 层）¶

time_to_cooldown 在写 Redis 前的最终值，优先级从高到低：

flowchart LR
    A["1. 单 deployment<br/>model_info.cooldown_time"] -->|不存在则| B
    B["2. 上游响应头<br/>Retry-After"] -->|不存在则| C
    C["3. Router 全局<br/>router.cooldown_time"] -->|不存在则| D
    D["4. 默认<br/>DEFAULT_COOLDOWN_TIME_SECONDS = 5"]

    style A fill:#dfd
    style D fill:#fdd

代码逻辑见 router.py:5767-5772:

time_to_cooldown = (
    deployment_cooldown        # 1. 单 deployment
    or header_cooldown         # 2. 上游响应头(429 时常带 Retry-After)
    or self.cooldown_time      # 3. Router 全局
    or DEFAULT_COOLDOWN_TIME_SECONDS  # 4. 默认 5
)

5.1 关于上游 `Retry-After` header¶

OpenAI / Azure / Anthropic 等 provider 在 429 / 503 时通常返回:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
...

LiteLLM 自动解析这个 header 并用作 cooldown_time。这是上游推荐的"正确"等待时长——按它走避免无效重试。

如果上游没返回 Retry-After（不规范的 provider），就走 router 全局 / 默认值。

6. 可观测性¶

6.1 Prometheus 指标¶

prometheus.py 里的 cooldown 相关指标：

指标	类型	说明
`litellm_deployment_cooled_down`	Counter	累计 cooldown 触发次数（按 model_name / deployment_id 标签）
`litellm_deployment_complete_outage`	Gauge	deployment 是否完全 outage（1 = 在 cooldown 中，0 = 健康）

调用点：cooldown_callbacks.py:74-80:

prometheusLogger.set_deployment_complete_outage(...)
prometheusLogger.increment_deployment_cooled_down(...)

PromQL 示例：

# 每分钟 cooldown 触发次数（按 model_name 分组）
sum by (model_name) (rate(litellm_deployment_cooled_down_total[1m]))

# 当前正在 cooldown 的 deployment
sum by (model_name) (litellm_deployment_complete_outage)

6.2 直接读 Redis¶

.venv312/bin/python -c "
import os, redis
r = redis.Redis(host=os.environ['REDIS_HOST'], port=int(os.environ['REDIS_PORT']),
                password=os.environ.get('REDIS_PASSWORD'))
keys = r.keys('deployment:*:cooldown')
for k in keys:
    print(f'{k.decode()}  TTL={r.ttl(k)}s')
"

输出例：

deployment:25a8bd00-b1ba-489d-92f6-d878bbe46bae:cooldown  TTL=4s

→ 可以直接判断当前哪些 deployment 在 cooldown 中。

6.3 没有的能力¶

❌ 没有专门的 admin API（如 /cooldown/list）查 cooldown 列表
❌ /v1/model/info 不带 cooldown 状态
❌ /health 端点不带 cooldown 状态（/health 是心跳的范畴，跟 cooldown 无关）

→ 监控只能靠 Prometheus 或 Redis 直查。

7. 完整配置组合速查¶

7.1 默认（什么都不配）¶

走代码默认：cooldown_time=5、V2 默认模式、所有 4 条触发路径生效。适合小流量 / 多 deployment 场景。

7.2 推荐：稍微宽容一点¶

router_settings:
  cooldown_time: 30                   # 默认 5 秒太短
  routing_strategy: latency-based-routing

适合：流量中等、希望失败 deployment 多冷一会儿、靠 latency-based 自动避开慢 deployment。

7.3 严格：累计失败计数¶

litellm_settings:
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 1     # 1 次 401 就冷,Auth 错误是"真坏"
    TimeoutErrorAllowedFails: 50           # 偶发超时容忍度高
    RateLimitErrorAllowedFails: 100        # 限流容忍度更高
    InternalServerErrorAllowedFails: 20    # 5xx 中等容忍

router_settings:
  cooldown_time: 60                        # 冷 1 分钟
  routing_strategy: latency-based-routing

适合：流量大、deployment 多、希望抗瞬时抽风。

7.4 全开（极端调试）¶

router_settings:
  disable_cooldowns: true                  # 完全关闭

代价：上游 deployment 挂了不会自动避让，每次请求都可能撞上挂的 deployment 然后失败。仅 dev / 排障时用。

下一步¶

调优思路 + 跟 num_retries / fallback / latency-based 叠加：03-best-practices.md
常见排障 + 暗坑（多 Pod / single deployment / wildcard）：04-troubleshooting.md