[Bug]: MTP Speculative Decoding with NVFP4: Weight Shape Mismatch

快速结论：该报错在 vLLM 使用 NVFP4 量化格式 + MTP (Medusa Tree Parallel) 投机解码时触发，主要原因是 Qwen3-Next 系列模型的 MTP 权重加载映射表（gate_up_proj）存在键名错误，以及 checkpoint 中的 quantization_config.ignore 规则覆盖不完整。优先检查 qwen3_next_mtp.py 中的映射定义和 config.json 中的 ignore 条目。

问题场景

用户在 vLLM 中运行 nvidia/Qwen3-Next-80B-A3B-Instruct-NVFP4 模型，启用 NVFP4 量化与 MTP 投机解码（speculative decoding）时，模型加载阶段抛出 AssertionError（权重形状不匹配）。该问题同时存在于多个环境（NVIDIA RTX PRO 6000 Blackwell、DGX Spark/GB10），且 vLLM 0.16.0rc2 及 0.23.0 版本均受影响。

报错原文

AssertionError at qwen3_next_mtp.py:217 → load_column_parallel_weight()

实际报错信息指向 load_column_parallel_weight 函数中的权重形状断言失败，由 gate_up_proj 键名错误引起。

原因分析

可能导致该问题的原因有三个（按优先级排序）：

主要（确认）：qwen3_next_mtp.py 中 gate_up_proj 的映射（line 230）定义错误，将 "gate_up_proj": ["up_proj", "down_proj"] 写为 ["up_proj", "down_proj"] 而非正确的 ["gate_proj", "up_proj"]。这导致权重加载时形状不匹配。
次要（确认）：checkpoint 的 config.json 中 quantization_config.ignore 使用了 "mtp.layers.0*" 作为通配符，仅匹配以 mtp.layers.0 开头的权重键，漏掉了 mtp.fc.weight、mtp.norm.weight、mtp.pre_fc_norm_embedding.weight、mtp.pre_fc_norm_hidden.weight 四个键。MTP 模块的权重本应为 bf16（不量化），因未被 ignore 规则覆盖导致 NVFP4 量化路径异常。
平台相关：在 DGX Spark（统一内存架构）上，MTP 模型初始化会触发 nvmlShutdown() 的二次调用，导致 pynvml 抛出 NVMLError_Uninitialized 异常。此问题仅影响该平台。

环境排查

vLLM 版本：0.16.0rc2 或 0.23.0（均受影响）
模型命名：nvidia/Qwen3-Next-80B-A3B-Instruct-NVFP4（其他 NVFP4 MTP 模型可能同理）
量化格式：NVFP4（FP8 下无此问题）
GPU 类型：NVIDIA RTX PRO 6000 Blackwell / DGX Spark (GB10) — DGX Spark 用户需额外排查 NVML 初始化问题
Python/CUDA/PyTorch 版本：Issue 中未作为根本原因，但确认环境为 Python 3.12.3 + PyTorch 2.10.0 + CUDA 12.8

解决步骤

根据 Issue 中已验证的修复方法，按以下顺序操作：

修复 gate_up_proj 映射错误（可优先尝试）
打开 vLLM 源码中的 qwen3_next_mtp.py，定位 line 230。将：
```
"gate_up_proj": ["up_proj", "down_proj"]
```
改为：
```
"gate_up_proj": ["gate_proj", "up_proj"]
```
修复 checkpoint 的 ignore 配置
在模型 checkpoint 的 config.json 中，找到 quantization_config.ignore 数组。将条目 "mtp.layers.0*" 替换为 "mtp.*"。例如：
```
"ignore": [
    ... 其他已有条目 ...,
    "mtp.*"
]
```
针对 DGX Spark 平台：修复 pynvml 未初始化异常
修改 vLLM 内置的 pynvml.py 文件中的 _nvmlCheckReturn() 函数，添加对 NVML_ERROR_UNINITIALIZED 的容忍处理：
```
def _nvmlCheckReturn(ret):
    if (ret != NVML_SUCCESS):
        if ret == NVML_ERROR_UNINITIALIZED:
            return None
        raise NVMLError(ret)
```
注意：此步骤仅对 DGX Spark 类平台（统一内存架构）有必要，标准独立 GPU 系统无需修改。

验证方法

应用上述修复后，重新启动 vLLM 并加载相同的 NVFP4 MTP 模型。如果 gate_up_proj 映射已修正且 ignore 规则覆盖了所有 MTP 权重键（合计 1553 个 bf16 权重），模型初始化应正常完成，不再抛出 AssertionError 或量化相关异常。对于 DGX Spark 平台，确认 NVML 相关报错已消除。