Qwen3.5 crash with `cache_implementation=”static”` — `KeyError: ‘linear_attention’`

Qwen3.5 crash with `cache_implementation="static"` — `KeyError: 'linear_attention'`

快速结论：该报错发生在使用 Qwen3.5 等混合线性注意力模型调用 generate() 并指定 cache_implementation="static" 时，原因是 HuggingFace Transformers 的掩码预构建函数未处理 linear_attention 层类型。优先排查是否使用了静态缓存模式。

问题场景

用户在 Transformers 5.10.1 中尝试使用 Qwen3.5 混合线性注意力模型（hybrid linear-attention model），通过 generate() 方法并启用静态缓存（cache_implementation="static" 或预构建 StaticCache 传入 past_key_values=）时触发报错。动态缓存（默认模式）正常工作。

报错原文

KeyError: 'linear_attention'  (in create_masks_for_generate)

原因分析

generate() 在预编译缓存时会通过 create_masks_for_generate 函数预构建注意力掩码，该函数将 config.layer_types 中的每个条目映射到 LAYER_PATTERN_TO_MASK_FUNCTION_MAPPING。但 Qwen3.5、Qwen3-Next、MiniMax 等混合线性注意力模型包含 linear_attention 层类型，该类型在该映射表中没有对应条目（这些模型在其前向传播中自行构建逐层掩码——注意力层使用 create_causal_mask，线性层使用单独的 2D/None 掩码）。因此，请求静态/可编译缓存会导致 generate() 在到达模型前就抛出该 KeyError。

注意：这些模型上的 _can_compile_fullgraph = False 在运行时不会拦截此路径——它仅在测试跳过守卫中被读取，而不会在 _valid_auto_compile_criteria 中使用，因此用户可达该问题且该断裂路径未经测试。

环境排查

Transformers 版本（影响版本：5.10.1，latest release）
Qwen3.5 模型配置中包含 linear_attention 层类型
是否使用了 cache_implementation="static" 或预构建 StaticCache
CUDA 和 PyTorch 版本（用于验证模型在 GPU 上运行）

解决步骤

临时规避：改用动态缓存（默认设置），即不要指定 cache_implementation="static" 或传入 StaticCache。示例：model.generate(ids, max_new_tokens=4)。
可优先尝试——应用官方修复：该问题已在 PR #46446 中修复。升级 Transformers 到包含该修复的版本（预计在下一发行版中），或手动应用 PR 中的修改。
手动补丁（临时方案）：在 create_masks_for_generate 函数中，当遇到未注册掩码函数的层类型时，改为返回原始注意力掩码以便模型自行构建，而不是抛出异常。修改位置参考 transformers/src/transformers/generation/configuration_utils.py 中的相关函数。

验证方法

运行以下最小复现代码，确认不再出现 KeyError: 'linear_attention'，且能正常生成结果：

import torch
from transformers import Qwen3_5ForCausalLM
from transformers.models.qwen3_5.configuration_qwen3_5 import Qwen3_5TextConfig

cfg = Qwen3_5TextConfig(
    vocab_size=2048, hidden_size=256, intermediate_size=256, num_hidden_layers=8,
    num_attention_heads=4, num_key_value_heads=2, head_dim=64,
    linear_conv_kernel_dim=4, linear_key_head_dim=32, linear_value_head_dim=32,
    linear_num_key_heads=2, linear_num_value_heads=4, pad_token_id=0, bos_token_id=1, eos_token_id=2,
)
model = Qwen3_5ForCausalLM(cfg).to("cuda").eval()
ids = torch.randint(10, 2000, (1, 16), device="cuda")
model.generate(ids, max_new_tokens=4, cache_implementation="static", disable_compile=True)
# 应正常执行，不抛出 KeyError