Cooldown 机制变更历史（Diff in Cooldown）
追溯 LiteLLM 冷却机制从诞生到最新版本的每一个关键变更。
关注"什么功能/逻辑是什么时候、在哪个 commit 引入的"。
1. 演进总览
2024-08 冷却逻辑诞生（内嵌在 router.py）
│
2024-09 模块化拆分 + v2 错误率百分比阈值（里程碑）
│
2024-10 Prometheus 监控集成 + 单元测试覆盖
│
2024-11 Redis 性能优化
│
2025-01 单部署保护机制
│
2025-02 allowed_fails_policy 自定义冷却策略
│
2025-08 敏感数据屏蔽（安全增强）
│
2025-10 空状态码防护
│
2025-11 cooldown key 缓存优化（性能）
│
2025-12 最小请求阈值防误触发
│
2026-02 encrypted_content_affinity 新特性
│
2026-03 异步 Redis 写入（性能）
│
2026-05 Responses API cooldown 集成
2. 关键里程碑详解
2.1 冷却逻辑模块化 (2024-09-14)
- 提交:
63ed808ea4 — Ishaan Jaff
- 变更: 将冷却逻辑从
litellm/router.py（删除 185 行）拆分为独立的 litellm/router_utils/cooldown_handlers.py（新增 187 行）
- 意义: cooldown 机制首次作为独立模块存在，代码结构清晰化，便于维护和扩展
2.2 v2 错误率百分比阈值 (2024-09-14)
- 提交:
c8d15544c8 (#5698) — Ishaan Jaff
- 变更: 从绝对失败计数（
allowed_fails）切换为百分比阈值（DEFAULT_FAILURE_THRESHOLD_PERCENT = 0.5）
- 意义: 这是 cooldown 判断逻辑的根本性改变。v1 只看"失败了几次"，v2 看"失败率是多少"——使得冷却策略在不同流量场景下更加灵活
2.3 单部署保护机制 (2025-01-17)
- 提交:
80f7af510b (#7823) — Krish Dholakia
- 变更: 当模型组仅有单个部署时，增加特殊冷却逻辑
- 引入常量:
SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD（默认 1000）
- 背景: GitHub issue #7822 — 用户反馈单部署模型组被冷却后所有流量中断
- 逻辑:
- 429 错误 → 不冷却（避免总中断）
- 100% 失败率 + 流量 ≥ 1000 → 冷却（确认是真故障）
- 50%+ 错误率 → 不冷却
2.4 allowed_fails_policy 集成 (2025-02-25)
- 提交:
f6fa2399cc (#8668) — Ishaan Jaff
- 变更: 允许通过
allowed_fails 或 allowed_fail_policy 参数控制冷却触发阈值
- 意义: 用户可以自定义冷却触发条件，v1 逻辑正式成为可配置选项
2.5 敏感数据保护 (2025-08-11)
- 提交:
bc9d0484e4 (#13329) — Krrish Dholakia
- 变更:
cooldown_cache.py 中屏蔽错误字符串，集成 sensitive_data_masker.py
- 背景: 冷却缓存中存储的异常信息可能包含用户 prompt 数据
- 处理: 错误字符串前 50 字符可见，其余被掩码
2.6 最小请求阈值 (2025-12-12)
- 提交:
f25344484f (#17464) — Devaj Mody
- 变更: 新增
DEFAULT_FAILURE_THRESHOLD_MINIMUM_REQUESTS 常量（默认 5）
- 背景: 之前 1 个请求失败就可能触发 100% 错误率冷却
- 解决: 必须达到最低请求数（默认 5）才应用错误率冷却
2.7 异步 Redis 写入 (2026-03-19)
- 提交:
bbd5ed9699 — Ishaan Jaff
- 变更:
CooldownCache 新增 async_add_deployment_to_cooldown() 方法
- 背景: 异步路径下同步 Redis SET 阻塞事件循环
- 意义: 性能优化，异步路径不再被 Redis 写入阻塞
2.8 Responses API Cooldown 集成 (2026-05-13)
- 提交:
2e5ebf826f (#27820) — Mateo Wang
- 变更: Responses API 失败时注册 cooldown + stale encrypted_content 快速失败
- 意义: 最新的 cooldown 集成点，将冷却机制扩展到 Responses API 场景
3. 完整变更时间线
| 日期 |
提交 |
作者 |
描述 |
| 2024-08-07 |
d1e519afd1 |
Ishaan Jaff |
use router_cooldown_handler |
| 2024-08-07 |
579f09b334 |
Ishaan Jaff |
fix logging cool down deployment |
| 2024-09-14 |
63ed808ea4 |
Ishaan Jaff |
[里程碑] 从 router.py 拆分出 cooldown_handlers.py |
| 2024-09-14 |
c8d15544c8 |
Ishaan Jaff |
[里程碑] v2 错误率百分比阈值 (#5698) |
| 2024-09-14 |
c8eff2dc65 |
Ishaan Jaff |
Prometheus 异常状态追踪 (#5706) |
| 2024-10-04 |
224460d4c9 |
Ishaan Jaff |
修复 Prometheus 自定义 logger cooldown 事件 (#6060) |
| 2024-10-16 |
891e9001b5 |
Ishaan Jaff |
添加 router cooldown 单元测试 (#6258) |
| 2024-10-29 |
44e7ffd05c |
Krish Dholakia |
Redis 性能优化 ~100ms (#6483) |
| 2024-11-19 |
7463dab9c6 |
Ishaan Jaff |
provider budget routing 集成 (#6827) |
| 2025-01-17 |
80f7af510b |
Krish Dholakia |
[里程碑] 单部署保护 (#7823) |
| 2025-02-17 |
b5709ca408 |
Ishaan Jaff |
修复 SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD |
| 2025-02-19 |
208e5c6f35 |
Ishaan Jaff |
修复单部署 cooldown |
| 2025-02-25 |
f6fa2399cc |
Ishaan Jaff |
[里程碑] allowed_fails_policy (#8668) |
| 2025-06-27 |
041db0268c |
Ishaan Jaff |
修复 cooldown_time = 0 的处理 (#12108) |
| 2025-08-11 |
bc9d0484e4 |
Krrish Dholakia |
[安全] 敏感数据屏蔽 (#13329) |
| 2025-10-08 |
5a1b6fe1a6 |
IQHL (Novo Nordisk) |
空 exception_status 跳过冷却 |
| 2025-11-21 |
f542011076 |
Alexsander Hamir |
cooldown key 缓存优化 (#16954) |
| 2025-12-12 |
f25344484f |
Devaj Mody |
[里程碑] 最小请求阈值 (#17464) |
| 2026-02-24 |
058fac848e |
Sameer Kankute |
encrypted_content_affinity 机制 |
| 2026-03-19 |
bbd5ed9699 |
Ishaan Jaff |
[性能] 异步 Redis cooldown 写入 |
| 2026-05-13 |
2e5ebf826f |
Mateo Wang |
Responses API cooldown 集成 (#27820) |
4. 文件级变更详情
4.1 cooldown_handlers.py
| 日期 |
提交 |
变更内容 |
| 2024-09-14 |
63ed808ea4 |
从 router.py 拆分创建，187 行 |
| 2024-09-14 |
c8d15544c8 |
v2 错误率百分比逻辑 |
| 2025-01-17 |
80f7af510b |
单部署保护 + 常量外迁至 constants.py |
| 2025-02-17~25 |
b5709ca408~f6fa2399cc |
allowed_fails_policy 集成 |
| 2025-08-11 |
bc9d0484e4 |
敏感数据屏蔽 |
| 2025-10-08 |
5a1b6fe1a6 |
空 exception_status 跳过冷却 |
| 2025-12-12 |
f25344484f |
最小请求阈值 |
| 2026-03-19 |
bbd5ed9699 |
异步 Redis 写入支持 |
4.2 cooldown_cache.py
| 日期 |
提交 |
变更内容 |
| 2024-09-14 |
c8d15544c8 |
初始创建（v2 逻辑配套） |
| 2024-10-29 |
44e7ffd05c |
Redis 性能优化 |
| 2025-08-11 |
bc9d0484e4 |
错误字符串敏感数据屏蔽 |
| 2025-11-21 |
f542011076 |
cooldown key 缓存优化 |
| 2026-03-19 |
bbd5ed9699 |
新增 async_add_deployment_to_cooldown() |
4.3 cooldown_callbacks.py
| 日期 |
提交 |
变更内容 |
| 2024-09-14 |
c8eff2dc65 |
Prometheus 异常状态追踪 |
| 2024-10-04 |
224460d4c9 |
修复 Prometheus 自定义 logger cooldown 事件 |
| 2024-10-16 |
891e9001b5 |
单元测试覆盖 |
| 2024-11-19 |
7463dab9c6 |
provider budget routing 集成 |
4.4 constants.py (cooldown 相关)
| 日期 |
提交 |
常量 |
| 2025-01-17 |
80f7af510b |
SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD |
| 2025-12-12 |
f25344484f |
DEFAULT_FAILURE_THRESHOLD_MINIMUM_REQUESTS |
4.5 encrypted_content_affinity_check.py
| 日期 |
提交 |
变更内容 |
| 2026-02-24 |
058fac848e |
初始创建，加密内容亲和性部署 |
| 2026-05-13 |
2e5ebf826f |
集成 cooldown 注册 + stale encrypted_content 快速失败 |
5. 最近半年变更重点 (2025-12 ~ 2026-06)
| 日期 |
重点方向 |
提交 |
说明 |
| 2025-12-12 |
错误率冷却改进 |
f25344484f |
最小请求阈值防误触发 |
| 2026-02-24 |
新特性 |
058fac848e |
encrypted_content_affinity 机制诞生 |
| 2026-03-19 |
性能优化 |
bbd5ed9699 |
异步 Redis cooldown 写入 |
| 2026-05-13 |
集成扩展 |
2e5ebf826f |
Responses API cooldown + encrypted_content 快速失败 |
趋势: 最近半年的变更重心从 cooldown 核心逻辑转向三个方向：
1. 性能优化 — 异步 IO，避免阻塞事件循环
2. 新 API 集成 — Responses API 的冷却支持
3. 加密内容场景 — encrypted_content_affinity 与 cooldown 的联动
6. 核心贡献者
| 贡献者 |
角色 |
主要贡献 |
| Ishaan Jaff |
主要维护者 |
模块化拆分、v2 逻辑、allowed_fails_policy、异步优化 |
| Krish/Krrish Dholakia |
核心开发者 |
单部署保护、Redis 优化、敏感数据屏蔽 |
| Devaj Mody |
贡献者 |
最小请求阈值 |
| Mateo Wang |
贡献者 |
Responses API cooldown 集成 |
| Sameer Kankute |
贡献者 |
encrypted_content_affinity |
| Alexsander Hamir |
贡献者 |
cooldown key 缓存优化 |
7. 分支说明
- 默认分支:
litellm_internal_staging（开发分支，PR 合入目标）
- 稳定分支:
main（从 staging 合并，用于发布）
- 所有 cooldown 变更均通过 PR 合入
litellm_internal_staging，再合并到 main
- 本地 fork（Setsuna-Yukirin/litellm）当前在
main 分支
文档生成时间: 2026-06-01
数据来源: git log 分析 + 源码阅读