执行摘要

• 一句话：DeepSeek V4 模型迁移至硬件隔离目录 vllm/models/
• 推荐动作：建议重点阅读 DeepseekV4FP8Config 的懒解析设计（expert_dtype 延迟读取）和注册表的 _resolve_module_name 扩展点。此 PR 展示了 vLLM 未来多后端模型架构的方向，值得团队学习并作为新模型迁移的蓝本。

功能与动机

根据 issue #42770 的需求，vLLM 计划将模型实现迁移到 vllm/models/ 下，以支持多硬件后端的隔离和演化。此 PR 作为第一步，将 DeepSeek V4 模型（包括基础模型和 MTP）从旧位置搬移至新布局，并引入硬件隔离目录结构和注册表支持。

实现拆解

1. 创建目录和入口模块：新增 vllm/models/__init__.py 空包和 vllm/models/deepseek_v4/__init__.py，后者根据 current_platform.is_rocm() 在 TYPE_CHECKING 或非 ROCm 时从 nvidia 子包导入，否则从 amd 子包导入。
2. 提取量化配置：将原模型文件中的 DeepseekV4FP8Config 类移动到 vllm/models/deepseek_v4/quant_config.py，保留所有属性（expert_dtype、is_scale_e8m0、get_quant_method 等），使其成为独立的数据契约模块。
3. 搬迁核心模型代码：将 vllm/model_executor/models/deepseek_v4.py 重命名为 vllm/models/deepseek_v4/nvidia/deepseek_v4.py，移除已被提取的量化配置和相关导入，并调整辅助导入（如 from .utils → from vllm.model_executor.models.utils）。同样地，deepseek_v4_mtp.py 也搬迁到相同目录。
4. 更新模型注册表：在 vllm/model_executor/models/registry.py 中将 DeepseekV4ForCausalLM 和 DeepSeekV4MTPModel 的模块路径指向 vllm.models.deepseek_v4；新增 _resolve_module_name 函数，允许注册表条目使用全限定模块名；修改 inspect_model_cls 方法以支持非标准路径下的文件哈希缓存。
5. 补充 AMD 后端替身：在 vllm/models/deepseek_v4/amd/ 目录下创建符号链接文件（如 deepseek_v4.py → ../nvidia/deepseek_v4.py），确保 AMD 平台能加载相同实现，同时为未来独立分化预留空间。

额外配套：更新了 vllm/model_executor/layers/quantization/__init__.py 中的导入路径，以及测试文件 tests/models/test_deepseek_v4_mega_moe.py 的导入引用。

关键文件：

• vllm/models/deepseek_v4/nvidia/deepseek_v4.py（模块 模型定义；类别 source；类型 rename-or-move；符号 DeepseekV4FP8Config, init, expert_dtype, is_scale_e8m0）: DeepSeek V4 模型核心实现，从旧目录搬迁至此并进行导入路径清理；模型层（如 DeepseekV4MLP、DeepseekV4ForCausalLM）保持不变。
• vllm/models/deepseek_v4/quant_config.py（模块 量化配置；类别 source；类型 data-contract；符号 DeepseekV4FP8Config, init, expert_dtype, is_scale_e8m0）: 新增的量化配置模块，封装 DeepseekV4FP8Config 类，实现专家数据类型感知的 MoE 调度。
• vllm/model_executor/models/registry.py（模块 模型注册；类别 source；类型 data-contract；符号 _resolve_module_name）: 模型注册表核心修改，支持全限定模块路径，新增 _resolve_module_name 函数，提供寄存器文件哈希缓存的兼容性。
• vllm/models/deepseek_v4/__init__.py（模块 入口模块；类别 source；类型 data-contract）: 模块入口，负责根据平台分发到 nvidia 或 amd 实现。
• vllm/models/deepseek_v4/nvidia/deepseek_v4_mtp.py（模块 MTP模块；类别 source；类型 rename-or-move）: MTP 推测解码模型实现，搬迁并调整导入路径。

关键符号：DeepseekV4FP8Config.init, DeepseekV4FP8Config.expert_dtype, DeepseekV4FP8Config.is_scale_e8m0, DeepseekV4FP8Config.get_name, DeepseekV4FP8Config.override_quantization_method, DeepseekV4FP8Config.get_quant_method, DeepseekV4FP8Config.is_mxfp4_quant, _resolve_module_name

关键源码片段

vllm/models/deepseek_v4/__init__.py

模块入口，负责根据平台分发到 nvidia 或 amd 实现。

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""DeepSeek V4 model — hardware-isolated entry point.
​
The actual implementation lives under ``nvidia/`` and ``amd/``; this module
picks the right one for the current platform and re-exports the public
classes used by the model registry and quantization config lookup.
"""
​
from typing import TYPE_CHECKING
​
from vllm.platforms import current_platform
​
from .quant_config import DeepseekV4FP8Config
​
# 根据硬件平台选择对应的实现模块。
# TYPE_CHECKING 时始终走 NVIDIA 分支以便静态类型检查；
# 运行时由 current_platform.is_rocm() 决定。
if TYPE_CHECKING or not current_platform.is_rocm():
    from .nvidia.deepseek_v4 import DeepseekV4ForCausalLM
    from .nvidia.deepseek_v4_mtp import DeepSeekV4MTP
else:
    # AMD 分支，运行时覆盖；使用 type: ignore 保持类型兼容
    from .amd.deepseek_v4 import DeepseekV4ForCausalLM # type: ignore[assignment]
    from .amd.deepseek_v4_mtp import DeepSeekV4MTP # type: ignore[assignment]
​
__all__ = [
    "DeepSeekV4MTP",
    "DeepseekV4FP8Config",
    "DeepseekV4ForCausalLM",
]

评论区精华

1. 硬件目录命名争议：zyongye 询问是否应使用 cuda/rocm 以匹配 current_platform API。WoosukKwon 未直接答复，计划未来调整。
2. 类型安全漏洞：gemini-code-assist[bot] 建议在 deepseek_v4_mtp.py 中使用 assert 显式检查 speculative_config 非 None，而非用 type: ignore。代码最终保留了 type: ignore，未采纳建议。
3. 新的 type: ignore 来源：zyongye 询问为何新增 # type: ignore[assignment]，WoosukKwon 解释因为旧目录被 mypy 排除，而新目录纳入检查。
4. 平台分发模式提取：zyongye 提议将硬件分发逻辑提取为公共模板，WoosukKwon 同意留待后续 PR 实现。

• 硬件目录名称为 nvidia/amd 而非 cuda/rocm (design): 未明确答复，但 WoosukKwon 计划未来逐步调整。
• MTP 模块中 speculative_config 未显式检查 (correctness): WoosukKwon 未回应，代码中保留 type: ignore ，未采纳 assert 。
• 为何需要新的 type: ignore 注解 (other): 解释清楚，无进一步操作。
• 提取硬件分发通用模板 (design): 待后续 PR 实现。

风险与影响

• 风险：

  1. 模型加载路径变更：旧文件 vllm/model_executor/models/deepseek_v4.py 被删除，外部直接导入该路径的代码将被破坏。团队需确认无外部依赖或同步更新。
  2. AMD 符号链接隐藏分化：AMD 目录当前通过符号链接共享 NVIDIA 代码，可能掩盖未来的硬件差异，需计划后续分解。
  3. 类型安全遗漏：MTP 模块中 speculative_config 未显式检查，如果模型在非推测解码上下文中被实例化，可能触发 AttributeError。
  4. 测试覆盖不足：仅调整测试文件导入路径，未新增针对新目录结构或平台分发的测试用例。
     - 影响：用户影响：低。模型加载功能保持不变，仅内部代码目录结构变化。直接导入旧路径的用户需更新导入语句。
     系统影响：中。模型注册和加载流程变更为支持全限定模块路径，为后续模型迁移铺平道路。
     团队影响：中。引入了新模型目录结构和平台分发模板，后续模型将遵循此模式。需维护 vllm/models/ 下的硬件隔离子包。

• 风险标记：模型加载路径变更, AMD 符号链接隐藏分化, 类型安全遗漏

关联脉络

• PR #42930 [Bugfix] Fix DSV4 MTP after ROCm mHC integration: 涉及相同的 DeepSeek V4 MTP 模块，本次搬迁也修改了该文件。
• PR #42541 [Bugfix] fix swiglu limit issue for humming backend + deepseek v4: 涉及 DeepSeek V4 模型的 MoE 量化配置，本次重构移动了量化配置类。