执行摘要

• 一句话：修复 MTP head 量化排除未生效问题
• 推荐动作：建议合并。这是一个精准的 bugfix，设计简洁，阅读价值高——展示了 vLLM 量化排除机制的依赖细节（prefix 匹配）。

功能与动机

MTP 模型加载时，检查点将 MTP 层和 lm_head 保留为 BF16（通过 exclude_modules 排除量化），但因 SharedHead 的 prefix 默认为空字符串，量化配置的 fnmatch 无法匹配该 head，导致 head 被量化（权重大小不匹配）进而崩溃。

实现拆解

1. 修改 SharedHead 构造函数：增加 prefix: str = "" 参数，并在构造 ParallelLMHead 时传入 prefix=f"{prefix}.head"。
2. 修改 Step3p5AMultiTokenPredictorLayer 构造函数：在创建 SharedHead 时传入 prefix=f"{prefix}.shared_head"。
3. 仅修改 vllm/model_executor/models/step3p5_mtp.py 一个文件，变更量 +11/-2。

关键文件：

• vllm/model_executor/models/step3p5_mtp.py（模块 模型层；类别 source；类型 data-contract；符号 SharedHead.init, Step3p5AMultiTokenPredictorLayer.init）: 唯一修改文件，修复 MTP head 量化排除问题

关键符号：SharedHead.init, Step3p5AMultiTokenPredictorLayer.init

关键源码片段

vllm/model_executor/models/step3p5_mtp.py

唯一修改文件，修复 MTP head 量化排除问题

class SharedHead(nn.Module):
    def __init__(
        self,
        config: PretrainedConfig,
        quant_config: QuantizationConfig | None = None,
        prefix: str = "", # 新增：传入完整前缀，用于量化 exclude 匹配
    ) -> None:
        super().__init__()
        self.norm = GemmaRMSNorm(config.hidden_size, config.rms_norm_eps)
        # 给 head 传递 prefix，使量化配置的 exclude_modules 匹配器
        # 能正确跳过排除的层；原来默认 "" 永远不匹配，导致 BF16 head 被量化
        self.head = ParallelLMHead(
            config.vocab_size,
            config.hidden_size,
            quant_config=quant_config,
            prefix=f"{prefix}.head", # 关键修复：传入带前缀的字符串
        )
​
class Step3p5AMultiTokenPredictorLayer(nn.Module):
    def __init__(
        self,
        vllm_config: VllmConfig,
        prefix: str,
    ) -> None:
        ...
        # 传递 prefix，与 mtp_block 一致
        self.shared_head = SharedHead(
            config=config, quant_config=quant_config, prefix=f"{prefix}.shared_head"
        )
        self.mtp_block = Step3p5DecoderLayer(
            vllm_config,
            prefix=f"{prefix}.mtp_block",
        )

评论区精华

无实质讨论（仅 Mergify 机器人提示 pre-commit 失败，以及作者说明 CI 失败为已知 flaky 测试）。审核者 pavanimajety 直接批准。

• 暂无高价值评论线程

风险与影响

• 风险：风险极低：仅单文件修改，逻辑清晰，传入 prefix 后量化排除逻辑与 mtp_block 一致，不会影响其他模型。未添加新测试覆盖此边界场景。
• 影响：修复了 Step-3.7-Flash-NVFP4 等模型在 MTP 模式下的加载崩溃问题，对使用 MTP 量化的用户有直接影响。对其他模型无影响。
• 风险标记：缺少测试覆盖

关联脉络

• 暂无明显关联 PR