torch CUDA graphs with HF generate

快速结论：在调用 Hugging Face Transformers 模型的 .generate() 时启用 torch CUDA graphs 失败，原因是动态 KV cache 导致输入/输出尺寸不固定，stream capture 中断。优先排查是否使用了 cache_implementation="static" 并确保解码阶段为贪婪/采样模式。

问题场景

用户在调用 Hugging Face Transformers 模型的 .generate() 方法时，尝试使用 torch CUDA graphs 进行推理加速（例如自行将模型整体包裹在 CUDA graph wrapper 中），但 stream capture 失败。单独使用模型的 forward 调用时 CUDA graphs 正常工作并取得约 2 倍加速。

报错原文

stream capture fails when calling .generate()
graph breaking errors

原因分析

主要原因是生成过程中 KV cache 大小动态变化，导致模型输入/输出张量的形状不固定（动态 KV cache），这会破坏 CUDA graph 的一次性图捕获条件。PyTorch CUDA graphs 要求所有张量形状在捕获期间保持不变。Hugging Face Transformers 团队确认这是已知问题，已通过引入 StaticCache（固定大小 KV cache）解决。

环境排查

Transformers 版本：确保 >= 4.38.0（StaticCache 合并后的版本）
PyTorch 版本：需支持 CUDA graphs（torch >= 1.10 基本支持，建议使用较新版本）
CUDA 版本：确认已正确安装且驱动兼容
显卡：需要 CUDA 计算能力 >= 6.0
模型配置：检查是否已启用 StaticCache

解决步骤

升级 Transformers 库：确保使用包含 #27931 和 #29374 PR 的版本（推荐 Transformers >= 4.38.0）。
启用 StaticCache：在调用 .generate() 时传入参数 cache_implementation="static"，该选项会预分配固定大小的 KV cache，从而满足 CUDA graphs 的形状稳定性要求。
限制解码策略：StaticCache + CUDA graphs 目前仅支持 greedy decoding 和 sampling 解码方式，确保 generate 的 do_sample 等参数设置为 False 或标准采样模式。
可选：使用 torch.compile 间接支持：团队开发者示范了使用 torch.compile 配合 StaticCache 可达到类似效果（参考示例代码示例 gist），但官方推荐优先使用 cache_implementation="static"。
避免自行包裹整个模型：之前自行用 CUDA graph wrapper 包裹整个模型的方式会因动态 KV cache 导致 graph 中断，官方方案已集成于 generate 内部逻辑。

验证方法

运行 model.generate(..., cache_implementation="static") 后，观察无 stream capture 错误，且生成速度相比未启用 CUDA graphs 时有明显提升（可通过 torch.cuda.cudart().cudaProfilerStart() 或 nsys 等工具捕获 CUDA graph 使用情况确认）。