#47140 [Platform] Replace `torch.cuda.Event` with `torch.Event`

原始 PR 作者 jikunshang 合并时间 2026-06-30 23:40 文件变更 31 提交数 3 评论 10 代码增减 +60 / -70

执行摘要

全局替换 torch.cuda.Event 为 torch.Event，提升硬件兼容性

在 Issue #30679 中，项目计划将 torch.cuda API 迁移至 torch.accelerator 统一 API，以支持多种硬件后端。torch.cuda.Event 是首批可替换的 API 之一（在 PyTorch 2.9 中已就绪）。本 PR 是这一迁移的具体步骤，将代码中所有显式引用 torch.cuda.Event 的地方替换为 torch.Event，消除对特定后端的依赖。同时删除 XPU 平台上因 torch.cuda.Event 不可用而引入的 monkey-patch workaround。

建议合并。此 PR 是多硬件兼容性迁移的一部分，代码变更清晰，review 充分，风险低。合并后建议快速跟进后续 API 替换（如 torch.cuda.Stream）。

讨论亮点

Review 中 hmellor 提出了三点建议：

1) 将单独的 Event 正则模式合并到已有的 manual_seed 分组中，以减少模式数量（更高效）；
2) 为 torch.cuda.Event 提供专门的错误消息，与其他 torch.cuda API 区分；
3) 在 attention.py 中将事件列表创建合并为单行。所有建议均被采纳，体现在第二个 commit 中。

实现拆解

全局替换：在 31 个文件中将所有 torch.cuda.Event（作为类型注解和构造调用）替换为 torch.Event。涉及文件包括注意力模块（vllm/models/deepseek_v4/attention.py）、多流工具（vllm/utils/multi_stream_utils.py）、GPU 模型运行器（vllm/v1/worker/gpu_model_runner.py）、LoRA 上下文（vllm/model_executor/layers/fused_moe/experts/lora_context.py）、offloader prefetch（vllm/model_executor/offloader/prefetch.py）、分布式 KV connector 等多个子模块。所有替换均保持类型一致性：torch.cuda.Event → torch.Event，list[torch.cuda.Event] → list[torch.Event]。
移除 XPU workaround：在 vllm/models/deepseek_v4/xpu/xpu_sparse.py 中，DeepseekV4XPUAttention.__init__ 曾将 torch.cuda.Event 临时替换为 torch.xpu.Event 以绕过 XPU 运行时错误。由于基础 API 已替换为 torch.Event（XPU 原生支持），整个 __init__ 方法不再需要，被完全删除。
更新 pre-commit 检查：在 tools/pre_commit/check_torch_cuda.py 中，将 Event 加入正则模式（与 manual_seed 合并为一个组），并针对 torch.cuda.Event 输出专门的错误提示；同时将自身文件加入白名单以避免自检循环。
调整测试和 benchmark：修改 tests/... 和 benchmarks/... 中相关的 torch.cuda.Event 引用。

文件	模块	状态	重要度
`vllm/models/deepseek_v4/xpu/xpu_sparse.py`	模型层	modified	6.83
`vllm/models/deepseek_v4/attention.py`	模型层	modified	5.84
`tools/pre_commit/check_torch_cuda.py`	工具链	modified	5.74
`vllm/utils/multi_stream_utils.py`	工具层	modified	5.34
`vllm/v1/worker/gpu_model_runner.py`	运行时层	modified	5.28

关键符号

DeepseekV4XPUAttention.__init__（已删除） maybe_execute_in_parallel execute_in_parallel scan_file main（check_torch_cuda）

关键源码片段

vllm/models/deepseek_v4/xpu/xpu_sparse.py data-contract

删除 XPU 平台因 torch.cuda.Event 不可用而引入的 monkey-patch workaround，是本次替换中唯一改动逻辑而非类型注解的文件。

class DeepseekV4XPUAttention(DeepseekV4Attention):
    """XPU sparse MLA attention layer for DeepSeek V4."""

    backend_cls = DeepseekV4XPUSparseBackend
    use_flashmla_fp8_layout = True

    # 注意：__init__ 已被完全移除。
    # 之前因为 torch.cuda.Event() 在 XPU 上会引发 RuntimeError，
    # 这里曾将 torch.cuda.Event 临时替换为 torch.xpu.Event。
    # 现在基础 API 已改用 torch.Event（XPU 原生支持），
    # 所以不再需要 monkey-patch，直接继承基类的 __init__ 即可。

    def _fused_qnorm_rope_kv_insert(self, q, kv, positions, attn_metadata):
        ...

vllm/models/deepseek_v4/attention.py data-contract

核心注意力模块，修改了两处 torch.cuda.Event 的创建，并在类型注解中替换为 torch.Event。

# 在 DeepseekV4Attention.__init__ 中：
# 之前是：
# self.ln_events = [torch.cuda.Event() for _ in range(4)]
# 现在改为：
self.ln_events = [torch.Event() for _ in range(4)]
# [0]: GEMM start / post-GEMM event0. [1..3]: GEMM done events;
# [1] doubles as post-GEMM event1. Reuse is safe: GEMM fully joins
# before post-GEMM starts.

# 在 DeepseekV4Indexer.__init__ 中：
# 类型注解和创建均改为 torch.Event
torch.Event(), torch.Event()

tools/pre_commit/check_torch_cuda.py core-logic

更新 lint 规则，将 torch.cuda.Event 加入检测模式，并增加专门错误提示；同时将自身文件加入白名单。

_TORCH_CUDA_PATTERNS = [
    # ... 其他模式 ...
    r"\btorch\.cuda\.(manual_seed|manual_seed_all|Event)\b", # Event 与 manual_seed 合并为同一组
    r"\bwith\storch\.cuda\.device\b",
    # ...
]

ALLOWED_FILES = {
    # ...
    "tools/pre_commit/check_torch_cuda.py", # 避免自检报错
}

def scan_file(path: str) -> int:
    # ...
    for pattern in _TORCH_CUDA_PATTERNS:
        for match in re.finditer(pattern, content, re.MULTILINE):
            matched_text = match.group(0)
            # ... manual_seed 处理 ...
            if matched_text == "torch.cuda.Event":
                # 专门的错误提示，建议改用 torch.Event
                print(f"{path}:{line_num}: Found torch.cuda.Event API call. Use torch.Event instead.")
                return 1
            # 其他 torch.cuda API 的通用错误提示

评论区精华

合并 Event 到现有正则模式以优化性能 设计

hmellor 建议将单独新增的 `r"\btorch\.cuda\.Event\b"` 模式合并到已有的 `r"\btorch\.cuda\.(manual_seed|manual_seed_all)\b"` 分组中，以减少模式数量，提高 lint 扫描性能。

结论：已采纳，最终代码中使用 `(manual_seed|manual_seed_all|Event)` 一个分组。 · 已解决

为 torch.cuda.Event 提供专门错误消息 正确性

hmellor 建议在 scan_file 函数中为匹配到的 `torch.cuda.Event` 输出专门的错误提示，建议改用 torch.Event，而不是通用的错误信息。

结论：已采纳，添加了独立的 if 分支。 · 已解决

简化 attention.py 中的事件创建写法 style

hmellor 建议将 `torch.cuda.Event(), torch.cuda.Event()` 合并为内联形式 `[torch.Event(), torch.Event()]`。

结论：已采纳，最终代码使用单行列表创建。 · 已解决

风险与影响

风险很低，因为 torch.Event 是 PyTorch 2.9 引入的通用 API，在 CUDA 上行为与 torch.cuda.Event 完全一致，且 vLLM 依赖的 PyTorch 版本已满足要求。主要风险点：

1) 是否所有 torch.cuda.Event 用法均被覆盖（通过 lint 和全局替换可保证）；
2) 删除 XPU workaround 后需确认 torch.Event 在 XPU 上正常工作（PR 提交者来自 Intel，应已验证）；
3) 可能遗漏某些间接引用（如字符串或动态构造），但 lint 工具已添加检查。

影响 31 个文件，涉及注意力计算、KV 传输、offloader、benchmark 等多个模块，但均为机械替换，不影响运行结果。对用户透明，无需任何配置或 API 更改。对开发人员，不再需要为不同后端编写 Event 特殊处理，降低维护成本。

跨平台兼容性依赖新版 PyTorch XPU workaround 移除需验证

关联 Issue

#30679 [RFC]: Replace `torch.cuda` API with `torch.accelerator` for better hardware compatiblity.

完整报告

执行摘要

一句话：全局替换 torch.cuda.Event 为 torch.Event，提升硬件兼容性
推荐动作：建议合并。此 PR 是多硬件兼容性迁移的一部分，代码变更清晰，review 充分，风险低。合并后建议快速跟进后续 API 替换（如 torch.cuda.Stream）。

功能与动机

实现拆解

全局替换：在 31 个文件中将所有 torch.cuda.Event（作为类型注解和构造调用）替换为 torch.Event。涉及文件包括注意力模块（vllm/models/deepseek_v4/attention.py）、多流工具（vllm/utils/multi_stream_utils.py）、GPU 模型运行器（vllm/v1/worker/gpu_model_runner.py）、LoRA 上下文（vllm/model_executor/layers/fused_moe/experts/lora_context.py）、offloader prefetch（vllm/model_executor/offloader/prefetch.py）、分布式 KV connector 等多个子模块。所有替换均保持类型一致性：torch.cuda.Event → torch.Event，list[torch.cuda.Event] → list[torch.Event]。
移除 XPU workaround：在 vllm/models/deepseek_v4/xpu/xpu_sparse.py 中，DeepseekV4XPUAttention.__init__ 曾将 torch.cuda.Event 临时替换为 torch.xpu.Event 以绕过 XPU 运行时错误。由于基础 API 已替换为 torch.Event（XPU 原生支持），整个 __init__ 方法不再需要，被完全删除。
更新 pre-commit 检查：在 tools/pre_commit/check_torch_cuda.py 中，将 Event 加入正则模式（与 manual_seed 合并为一个组），并针对 torch.cuda.Event 输出专门的错误提示；同时将自身文件加入白名单以避免自检循环。
调整测试和 benchmark：修改 tests/... 和 benchmarks/... 中相关的 torch.cuda.Event 引用。

关键文件：

vllm/models/deepseek_v4/xpu/xpu_sparse.py（模块模型层；类别 source；类型 data-contract；符号 init）: 删除 XPU 平台因 torch.cuda.Event 不可用而引入的 monkey-patch workaround，是本次替换中唯一改动逻辑而非类型注解的文件。
vllm/models/deepseek_v4/attention.py（模块模型层；类别 source；类型 data-contract）: 核心注意力模块，修改了两处 torch.cuda.Event 的创建，并在类型注解中替换为 torch.Event。
tools/pre_commit/check_torch_cuda.py（模块工具链；类别 source；类型 core-logic）: 更新 lint 规则，将 torch.cuda.Event 加入检测模式，并增加专门错误提示；同时将自身文件加入白名单。
vllm/utils/multi_stream_utils.py（模块工具层；类别 source；类型 core-logic）: 多流并行工具，修改了 maybe_execute_in_parallel 和 execute_in_parallel 的参数类型注解。
vllm/v1/worker/gpu_model_runner.py（模块运行时层；类别 source；类型 data-contract）: GPU 模型运行器，涉及 speculative decoding 中异步拷贝事件的类型注解。

关键符号：DeepseekV4XPUAttention.init（已删除）, maybe_execute_in_parallel, execute_in_parallel, scan_file, main（check_torch_cuda）

关键源码片段

`vllm/models/deepseek_v4/xpu/xpu_sparse.py`

删除 XPU 平台因 torch.cuda.Event 不可用而引入的 monkey-patch workaround，是本次替换中唯一改动逻辑而非类型注解的文件。

class DeepseekV4XPUAttention(DeepseekV4Attention):
    """XPU sparse MLA attention layer for DeepSeek V4."""

    backend_cls = DeepseekV4XPUSparseBackend
    use_flashmla_fp8_layout = True

    # 注意：__init__ 已被完全移除。
    # 之前因为 torch.cuda.Event() 在 XPU 上会引发 RuntimeError，
    # 这里曾将 torch.cuda.Event 临时替换为 torch.xpu.Event。
    # 现在基础 API 已改用 torch.Event（XPU 原生支持），
    # 所以不再需要 monkey-patch，直接继承基类的 __init__ 即可。

    def _fused_qnorm_rope_kv_insert(self, q, kv, positions, attn_metadata):
        ...

`vllm/models/deepseek_v4/attention.py`

核心注意力模块，修改了两处 torch.cuda.Event 的创建，并在类型注解中替换为 torch.Event。

# 在 DeepseekV4Attention.__init__ 中：
# 之前是：
# self.ln_events = [torch.cuda.Event() for _ in range(4)]
# 现在改为：
self.ln_events = [torch.Event() for _ in range(4)]
# [0]: GEMM start / post-GEMM event0. [1..3]: GEMM done events;
# [1] doubles as post-GEMM event1. Reuse is safe: GEMM fully joins
# before post-GEMM starts.

# 在 DeepseekV4Indexer.__init__ 中：
# 类型注解和创建均改为 torch.Event
torch.Event(), torch.Event()

`tools/pre_commit/check_torch_cuda.py`

更新 lint 规则，将 torch.cuda.Event 加入检测模式，并增加专门错误提示；同时将自身文件加入白名单。

_TORCH_CUDA_PATTERNS = [
    # ... 其他模式 ...
    r"\btorch\.cuda\.(manual_seed|manual_seed_all|Event)\b", # Event 与 manual_seed 合并为同一组
    r"\bwith\storch\.cuda\.device\b",
    # ...
]

ALLOWED_FILES = {
    # ...
    "tools/pre_commit/check_torch_cuda.py", # 避免自检报错
}

def scan_file(path: str) -> int:
    # ...
    for pattern in _TORCH_CUDA_PATTERNS:
        for match in re.finditer(pattern, content, re.MULTILINE):
            matched_text = match.group(0)
            # ... manual_seed 处理 ...
            if matched_text == "torch.cuda.Event":
                # 专门的错误提示，建议改用 torch.Event
                print(f"{path}:{line_num}: Found torch.cuda.Event API call. Use torch.Event instead.")
                return 1
            # 其他 torch.cuda API 的通用错误提示

评论区精华

Review 中 hmellor 提出了三点建议：

合并 Event 到现有正则模式以优化性能 (design): 已采纳，最终代码中使用 (manual_seed|manual_seed_all|Event) 一个分组。
为 torch.cuda.Event 提供专门错误消息 (correctness): 已采纳，添加了独立的 if 分支。
简化 attention.py 中的事件创建写法 (style): 已采纳，最终代码使用单行列表创建。

风险与影响

风险：风险很低，因为 torch.Event 是 PyTorch 2.9 引入的通用 API，在 CUDA 上行为与 torch.cuda.Event 完全一致，且 vLLM 依赖的 PyTorch 版本已满足要求。主要风险点：
1) 是否所有 torch.cuda.Event 用法均被覆盖（通过 lint 和全局替换可保证）；
2) 删除 XPU workaround 后需确认 torch.Event 在 XPU 上正常工作（PR 提交者来自 Intel，应已验证）；
3) 可能遗漏某些间接引用（如字符串或动态构造），但 lint 工具已添加检查。
- 影响：影响 31 个文件，涉及注意力计算、KV 传输、offloader、benchmark 等多个模块，但均为机械替换，不影响运行结果。对用户透明，无需任何配置或 API 更改。对开发人员，不再需要为不同后端编写 Event 特殊处理，降低维护成本。
- 风险标记：跨平台兼容性依赖新版 PyTorch, XPU workaround 移除需验证

关联脉络

暂无明显关联 PR

#47140 [Platform] Replace `torch.cuda.Event` with `torch.Event`

执行摘要

全局替换 torch.cuda.Event 为 torch.Event，提升硬件兼容性

实现拆解

评论区精华

风险与影响

关联 Issue

完整报告

参与讨论