Cache config max_cache_length only honored for Quantized Cache

快速结论：该问题发生在使用 HuggingFace Transformers 的 generate() 方法并设置了 cache_implementation="static" 时。优先排查你是否在 generation_config.cache_config 中传入了 max_cache_len，但实际生效的缓存长度并非你指定的值，而是由 max_length 自动计算得出。

问题场景

用户在 HuggingFace Transformers 库的 generate() 调用中，使用 cache_implementation="static" 静态缓存路径，并希望通过 cache_config={"max_cache_len": N} 控制缓存的最大长度。但实际观察发现，cache_config 中的 max_cache_len 被静默忽略，缓存长度被自动计算为 max_new_tokens + input_length - 1。这导致当用户频繁使用不同的 max_new_tokens 调用 generate() 时，缓存需要重新分配并触发 Inductor 重新编译，严重影响性能。

报错原文

用户并未直接看到完整报错信息，而是观察到以下行为：

- 设置 cache_config={"max_cache_len": 2048}，输入 prompt 为 32 tokens，max_new_tokens=16
- 实际：model._cache.max_cache_len == 47，layers[0].keys.shape == [1, 8, 47, 64]
- 缓存长度被硬编码为 max_length - 1（即 max_new_tokens + input_length - 1 = 16 + 32 - 1 = 47）

性能后果（在 Llama-3.2-1B, A10G, bf16, 1024-token prompt 场景下）：
- 第一次调用 generate() 使用 max_new_tokens=128
- 第二次调用 generate() 使用 max_new_tokens=256
- 实际：第二次调用会触发全量 StaticCache 重新分配 + Inductor 重新编译
- 结果：耗时从约 2.7 秒飙升到 27 秒，并产生 +19 个新编译产物

原因分析

可能原因：Transformers 源码 generation/utils.py 中 _prepare_cache_for_generation 函数（位于约第 1932-1935 行）在处理 cache_config 时存在分支逻辑错误。量化缓存（Quantized Cache）分支会正确读取 cache_config 中的 max_cache_len，但静态缓存（Static Cache）分支硬编码了 max_cache_len = max_length - 1，完全不检查 cache_config 参数。因此用户设置的 max_cache_len 在静态缓存路径上被静默忽略。

环境排查

Transformers 版本：至少 v5.10.1 及之前版本存在问题（Issue 引用该版本源码）。建议先更新到修复后的版本。
确认是否使用了 cache_implementation="static"。
确认是否在 generation_config.cache_config 中正确设置了 max_cache_len。
如果使用较老版本，检查 generation/utils.py 中 _prepare_cache_for_generation 函数的逻辑是否包含量化/静态分支的区分。

解决步骤

升级 Transformers 到修复版本：该问题已在 PR #46446 中修复（Issue 标记为 “Resolved in #46446″）。请升级到包含该修复的版本。如果没有官方 release，可手动 Cherry-pick PR #46446 的改动，或从 main 分支构建。
验证修复：升级后，重新测试 cache_config={"max_cache_len": 2048} 配合 cache_implementation="static" 的场景，确认 model._cache.max_cache_len 现在等于你指定的值（如 2048），而不是自动计算的 max_new_tokens + input_length - 1。
（临时方案，不推荐）如果短期内无法升级，可通过手动在 StaticCache 初始化时传入 max_cache_len 来规避。但请注意此方案不保证在所有 Transformers 版本中兼容，且可能需要修改用户代码。

验证方法

编写简单脚本来验证修复：

使用一个固定 prompt（例如 32 tokens）。
设置 generation_config.cache_implementation="static"。
设置 generation_config.cache_config={"max_cache_len": 2048}。
调用 model.generate() 后，检查 model._cache.max_cache_len 是否等于 2048。
如果等于 2048，说明修复已生效。
在 Llama-3.2-1B 等模型上，进一步验证：先用 max_new_tokens=128 调用，再用 max_new_tokens=256 调用，观察是否不再触发缓慢的重新编译。