执行摘要

• 一句话：迁移DSV4算子至模型目录
• 推荐动作：建议快速合入，以解锁后续重构步骤。该 PR 是 DSV4 模型重构的必要环节，逻辑简单可靠。

功能与动机

作为 DeepSeek V4 模型目录重构的一部分，将原本分散在 attention backend 目录下的算子迁移至统一的 vllm/models/deepseek_v4/ 目录，为后续的硬件隔离、内核版本管理奠定基础。

实现拆解

1. 在 vllm/models/deepseek_v4/ 下创建 common/ops/ 和 nvidia/ops/ 子目录，分别存放通用算子与 NVIDIA 特有内核。
2. 将原有的 vllm/v1/attention/ops/deepseek_v4_ops/ 下的 .py 文件按类别移动：通用逻辑（cache_utils.py, fused_indexer_q.py, fused_compress_quant_cache.py 等）移至 common/ops/；Cutedsl 依赖的内核（dequant_gather_k_cutedsl.py, fused_indexer_q_cutedsl.py 等）移至 nvidia/ops/。
3. 更新所有引用旧路径的文件，包括 compressor.py, attention.py, rocm_aiter_mla_sparse_dsv4.py 以及多个测试文件（test_fused_indexer_q_rope_quant.py, test_fused_q_kv_rmsnorm.py, test_compressor_kv_cache.py），导入路径指向新位置。
4. 调整重名文件内部的惰性导入路径，例如 cache_utils.py 中 dequantize_and_gather_k_cache 函数内对 Cutedsl 实现的引用。
5. 创建必要的 __init__.py 包初始化文件，确保正确的包结构。
   整个过程为纯机械性移动，未修改任何业务逻辑。

关键文件：

• vllm/models/deepseek_v4/compressor.py（模块 DSV4模型；类别 source；类型 data-contract）: 核心压缩器后端，导入路径从旧 ops 目录切换至新 common/ops，是主要变更影响方之一。
• vllm/models/deepseek_v4/attention.py（模块 DSV4模型；类别 source；类型 data-contract）: DeepSeek V4 注意力层，同样更新了算子导入路径。
• vllm/models/deepseek_v4/common/__init__.py（模块 DSV4模型；类别 source；类型 infrastructure）: 新建包初始化文件，使 common/ops 成为可导入的包。
• vllm/v1/attention/backends/mla/rocm_aiter_mla_sparse_dsv4.py（模块 注意力后端；类别 source；类型 dependency-wiring）: ROCm 稀疏注意力实现，更新了 dequantize_and_gather_k_cache 的导入路径。
• vllm/models/deepseek_v4/common/ops/cache_utils.py（模块 DSV4算子；类别 infra；类型 rename-or-move）: 被重命名的算子文件，内部包含一个惰性导入，引用了 nvidia 特定实现，同样更新了路径。
• vllm/models/deepseek_v4/common/ops/fused_indexer_q.py（模块 DSV4算子；类别 infra；类型 rename-or-move）: 被重命名的算子文件，内部更新了 Cutedsl 惰性导入路径。

关键符号：未识别

关键源码片段

vllm/models/deepseek_v4/compressor.py

核心压缩器后端，导入路径从旧 ops 目录切换至新 common/ops，是主要变更影响方之一。

# vllm/models/deepseek_v4/compressor.py (head)
​
from vllm.model_executor.layers.linear import MergedColumnParallelLinear
from vllm.models.deepseek_v4.common.ops.fused_compress_quant_cache import (
    _fused_kv_compress_norm_rope_insert_indexer_attn,
    _fused_kv_compress_norm_rope_insert_indexer_mxfp4_attn,
    _fused_kv_compress_norm_rope_insert_sparse_attn,
)
from vllm.models.deepseek_v4.common.ops.fused_indexer_q import MXFP4_BLOCK_SIZE
from vllm.platforms import current_platform
# ... 其余导入保持不变

vllm/models/deepseek_v4/attention.py

DeepSeek V4 注意力层，同样更新了算子导入路径。

# vllm/models/deepseek_v4/attention.py (head)
​
from vllm.models.deepseek_v4.common.ops import (
    combine_topk_swa_indices,
    compute_global_topk_indices_and_lens,
    dequantize_and_gather_k_cache,
    fused_indexer_q_rope_quant,
    fused_inv_rope_fp8_quant,
    fused_q_kv_rmsnorm,
)
from vllm.utils.deep_gemm import fp8_einsum
from vllm.utils.torch_utils import direct_register_custom_op
# ... 其余导入保持不变

vllm/models/deepseek_v4/common/ops/cache_utils.py

被重命名的算子文件，内部包含一个惰性导入，引用了 nvidia 特定实现，同样更新了路径。

# vllm/models/deepseek_v4/common/ops/cache_utils.py (head)
​
def dequantize_and_gather_k_cache(...):
    if has_cutedsl():
        # 原来的导入 : from .dequant_gather_k_cutedsl import ...
        from vllm.models.deepseek_v4.nvidia.ops.dequant_gather_k_cutedsl import (
            dequantize_and_gather_k_cache_cutedsl,
        )
        # 调用 cutedsl 实现

评论区精华

本 PR 未收到人工审查建议，仅机器人进行自动化代码规范检查。

• 暂无高价值评论线程

风险与影响

• 风险：风险极低，因为不涉及任何功能变更。主要风险在于个别导入路径可能遗漏更新导致运行时错误。PR 已同步更新所有调用方和测试，且 CI 应能覆盖。建议合入后关注 DSV4 相关测试是否通过。
• 影响：对最终用户无影响。对开发团队，DSV4 相关代码的结构更加清晰，算子与模型文件同处一处，便于维护和扩展。所有导入变更都在本次 PR 中完成，不影响其他模块。
• 风险标记：无逻辑变更, 导入路径调整, 硬件隔离重构

关联脉络

• PR #43004 [Model Refactoring] Migrate DeepSeek V4 to vllm/models/ [1/N]: 同一重构系列的第一步，建立了 vllm/models/deepseek_v4/ 基本结构并移动了模型主文件。
• PR #43039 [Model Refactoring] Move DeepSeek V4 layers to models/deepseek_v4/ [2/N]: 第二步，将注意力、压缩器等 layer 文件移到模型目录，为本 PR 移动算子做了前置准备。
• PR #43077 [Model Refactoring] Rename deepseek_v4.py to model.py [4/N]: 第四步，完成核心文件重命名，与前三步共同构成完整重构。