执行摘要

• 一句话：修复 EAGLE3 第一层 qkv_proj 前缀缺失层名问题
• 推荐动作：值得立即合并。这是一个精确的一行修复，完全解决了量化 EAGLE3 模型的加载失败问题，风险极低，且有实际模型验证（MiniMax-M3）。建议关注是否有其他类似的前缀路径不匹配问题存在于其他模块中。

功能与动机

PR body 指出：EAGLE3 第一层 decoder layer 覆盖了 self.self_attn.qkv_proj，但构建时使用 prefix=maybe_prefix(prefix, "qkv_proj")，生成 ...layers.0.qkv_proj 而不是标准的 ...layers.0.self_attn.qkv_proj。量化配置通过 exclude_modules 匹配前缀来排除注意力层，缺少 .self_attn 段导致排除失败，注意力层被错误量化，最终第一层 qkv 权重因形状不匹配无法加载。这阻止了任何量化（如 NVFP4）EAGLE3 draft 模型的服务。

实现拆解

1. 定位问题：在 vllm/model_executor/models/llama_eagle3.py 的 LlamaDecoderLayer.__init__ 中，EAGLE3 第一层 decoder layer 需要覆盖父类的 qkv_proj 以适应 2*hidden_size 的输入，但构造时 prefix 参数错误。
2. 修正前缀：将 maybe_prefix(prefix, "qkv_proj") 改为 maybe_prefix(prefix, "self_attn.qkv_proj")，使 prefix 匹配标准的模块路径（如 ...layers.0.self_attn.qkv_proj）。
3. 效果验证：量化配置的 exclude_modules 中的 "self_attn" 条目现在能正确排除注意力层，量化加载恢复正常。PR 作者已用 MiniMax-M3 模型和对应的量化版本验证。
4. 影响范围：仅修改一处代码，变更极小，对非量化模型无影响。

关键文件：

• vllm/model_executor/models/llama_eagle3.py（模块 投机解码；类别 source；类型 data-contract；符号 LlamaDecoderLayer.init）: 核心修复文件：将 EAGLE3 第一层 qkv_proj 的 prefix 从 'qkv_proj' 改为 'self_attn.qkv_proj'，使量化配置能正确匹配 exclude_modules。

关键符号：LlamaDecoderLayer.init

关键源码片段

vllm/model_executor/models/llama_eagle3.py

核心修复文件：将 EAGLE3 第一层 qkv_proj 的 prefix 从 'qkv_proj' 改为 'self_attn.qkv_proj'，使量化配置能正确匹配 exclude_modules。

# vllm/model_executor/models/llama_eagle3.py 第 55-64 行
# 覆盖第一层 qkv_proj，输入尺寸为 2*hidden_size（embeds + hidden_states 拼接）
self.self_attn.qkv_proj = QKVParallelLinear(
    qkv_input_size,
    self.self_attn.head_dim,
    self.self_attn.total_num_heads,
    self.self_attn.total_num_kv_heads,
    bias=qkv_bias,
    quant_config=quant_config,
    # 修正前：prefix=maybe_prefix(prefix, "qkv_proj")
    # 修正后添加 "self_attn." 前缀，使量化配置的 exclude_modules 能正确匹配注意力层
    prefix=maybe_prefix(prefix, "self_attn.qkv_proj"),
)

评论区精华

该 PR 无 review 评论。审核者 TheEpicDolphin 和 jeejeelee 均直接批准（LGTM），表明变更简单明确，无需额外讨论。

• 暂无高价值评论线程

风险与影响

• 风险：风险很低。变更仅涉及一行前缀字符串，且只在 EAGLE3 模型的第一层 decoder layer 中生效。非量化模型不受影响，量化模型的功能得到修复。可能的回归风险是如果未来有代码依赖错误的 prefix 字符串，但概率极小。
• 影响：直接解决了量化 EAGLE3 draft 模型（如 NVFP4）无法加载的阻塞问题。影响范围限于使用量化配置的 EAGLE3 投机解码场景。对于非量化用户无影响。
• 风险标记：单行修复风险极低

关联脉络

• 暂无明显关联 PR