[Bug]: Tied word embeddings (tie_word_embeddings) crash with NotImplementedError for ModelOpt-quantized models after #39612

快速结论：此报错发生在使用 ModelOpt 量化的模型（如 NVFP4 或 FP8）且启用了 tie_word_embeddings 时，在 vLLM 启动阶段触发。优先检查你的 vLLM 版本是否已包含针对 tie_weights 的修复补丁，或回退至合并 #39612 之前的版本。

问题场景

用户在 vLLM 的 EngineCore 启动时，加载含有 tie_word_embeddings: true 且经过 ModelOpt 量化（NVFP4 或 FP8）的模型（例如 Gemma 系列）时失败。非量化且带有 tie_word_embeddings 的模型不受影响。

报错原文

  File ".../vllm/model_executor/models/.py", in load_weights
    self.lm_head = self.lm_head.tie_weights(self.model.embed_tokens)
  File ".../vllm/model_executor/layers/vocab_parallel_embedding.py", line 560, in tie_weights
    return self.quant_method.tie_weights(self, embed_tokens)
  File ".../vllm/model_executor/layers/quantization/base_config.py", line 55, in tie_weights
    raise NotImplementedError
NotImplementedError

原因分析

根本原因在于 PR #39612 修改了 ParallelLMHead.tie_weights 的实现：原先直接共享权重（self.weight = embed_tokens.weight），现在改为委托给量化方法（self.quant_method.tie_weights(self, embed_tokens)），并在基类 QuantizeMethodBase 中添加了一个仅引发 NotImplementedError 的桩方法。

只有 UnquantizedEmbeddingMethod 实现了 tie_weights，但一个被量化的 ParallelLMHead 会接收到一个线性方法（linear method），而所有线性方法（包括 UnquantizedLinearMethod、ModelOptNvFp4LinearMethod、ModelOptFp8LinearMethod）都没有实现 tie_weights。因此，任何被量化的、绑定权重的 lm_head 都会触发基类的 NotImplementedError，无论该 lm_head 本身是否被量化或已在排除模块列表中。

环境排查

确认 vLLM 版本：当前 main 分支（包含 #39612 的提交，如 6635279d8）。
确认模型配置中 tie_word_embeddings 设置为 true。
确认模型已用 ModelOpt 量化（NVFP4 或 FP8）。
该 bug 与 GPU 计算能力无关。

解决步骤

更新 vLLM 至最新版本：检查 vLLM 仓库是否已合入修复补丁（可关注 #39612 的后续讨论或相关 PR）。
临时回退：如果无法等待修复，可回退至合并 #39612 之前的 vLLM 版本。
尝试手动修补（仅适用于有经验的用户）：根据 Issue 中的建议，可以修改 QuantizeMethodBase.tie_weights 使其安全地绑定共享权重（layer.weight = embed_tokens.weight）而非直接报错；或者在 LinearMethodBase、UnquantizedLinearMethod 等线性方法中实现 tie_weights。

验证方法

使用最小重现脚本（无需下载模型）测试：

from vllm.model_executor.layers.quantization.base_config import QuantizeMethodBase
from vllm.model_executor.layers import linear
from vllm.model_executor.layers import vocab_parallel_embedding as vpe
from vllm.model_executor.layers.quantization import modelopt

base = QuantizeMethodBase.tie_weights
for name, cls in [
    ("UnquantizedEmbeddingMethod", vpe.UnquantizedEmbeddingMethod),
    ("UnquantizedLinearMethod", linear.UnquantizedLinearMethod),
    ("ModelOptNvFp4LinearMethod", modelopt.ModelOptNvFp4LinearMethod),
    ("ModelOptFp8LinearMethod", modelopt.ModelOptFp8LinearMethod),
]:
    print(name, "overrides tie_weights:", cls.tie_weights is not base)

# 以下调用在修复前会引发 NotImplementedError
linear.UnquantizedLinearMethod().tie_weights(None, None)

如果修复生效，UnquantizedLinearMethod 和 ModelOpt 的线性方法应显示 overrides tie_weights: True，且最后一行不再报错。对于端到端测试，可尝试加载一个 ModelOpt NVFP4 的 Gemma 模型（带 tie_word_embeddings=true），观察引擎初始化是否成功。