# PR #44013 完整报告

- 仓库：`vllm-project/vllm`
- 标题：Migrate header files to torch stable abi
- 合并时间：2026-06-02 23:09
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/44013

---

## 执行摘要

此 PR 将仅被 libtorch stable ABI 内核使用的头文件从 `csrc/` 下迁移到 `csrc/libtorch_stable/`，并更新所有 `#include` 引用以及 pre-commit 配置。这是清理性重构，无功能变化，但增强了编译时的 ABI 稳定性保证，为后续内核迁移奠定基础。

## 功能与动机

在之前将 CUDA 内核迁移到使用 libtorch stable ABI 的过程中（基于 #43717 讨论），许多头文件被遗留在了 `csrc/` 下的原始位置，导致目录结构不统一且可能引入非稳定依赖。本 PR 旨在：
- 将仅被 stable 内核使用的头文件移入 `csrc/libtorch_stable/`，物理隔离稳定与非稳定代码。
- 更新所有包含路径和 pre-commit 配置，维持编译和代码格式一致性。

## 实现拆解

1. **文件移动**：通过 git rename 将 `broadcast_load_epilogue_c2x.hpp`、`launch_bounds_utils.h`、`ggml-common.h` 等移动到 `csrc/libtorch_stable/` 对应子目录。
2. **更新包含路径**：在 `scaled_mm_epilogues_c2x.hpp` 中将 `#include "cutlass_extensions/epilogue/broadcast_load_epilogue_c2x.hpp"` 简化为 `#include "broadcast_load_epilogue_c2x.hpp"`；在 `gguf_kernel.cu` 中将原本通过 `../../../quantization/gguf/` 相对路径引用的 5 个头文件改为直接文件名。
3. **调整格式化排除**：修改 `.pre-commit-config.yaml` 中 clang-format 的 `exclude` 规则，将旧路径替换为新路径，避免格式化上游头文件。
4. **路径风格回溯**：曾尝试使用 `stable_libtorch/` 显式前缀（如 `#include "stable_libtorch/..."`），但随后还原为简洁路径，以降低维护负担并与已有风格一致。

### `csrc/libtorch_stable/cutlass_extensions/epilogue/scaled_mm_epilogues_c2x.hpp`

展示了头文件迁移后 include 路径的典型变更，是理解迁移模式的关键文件。

```cpp
#pragma once

#include <torch/csrc/stable/tensor.h>

// 头文件从 cutlass_extensions/epilogue/ 子目录移至 libtorch_stable 同级，
// 因此包含路径从相对子目录简化为直接文件名。
#include "broadcast_load_epilogue_c2x.hpp"

/*
   This file defines custom epilogues for fusing channel scales, token scales,
   bias, and activation zero-points onto a GEMM operation using the
   CUTLASS 2.x API, for sm80 (Ampere) NVIDIA GPUs.
*/
namespace vllm::c2x {
using namespace cute;
// ...
}

```

## 评论区精华

- **janeyx99**：" 我们可以将所有 stable 头文件移到新目录，但风险是未使用的头文件可能退化；一旦有 .cpp 引入，-DTORCH_TARGET_VERSION 标志会强制执行稳定性。"
- **Harry-Chen**：建议外部文件使用显式前缀（如 `stable_libtorch/`）以突出意图，但最终团队选择简洁路径以减少改动量。

## 风险与影响

- **构建风险**：非 stable 代码若未及时更新包含路径可能编译失败，但由于这些头文件原本仅被 stable 内核引用，影响面有限。
- **测试覆盖**：PR 虽然运行了已有测试（如 `test_fused_qk_norm_rope.py` 等），但未增加专项测试来验证移动后的包含正确性；GGUF 相关测试依赖于手动检查。
- **开发者影响**：未来新增 stable 内核时，应将头文件置于 `libtorch_stable/` 并采用简洁相对包含路径，同时更新 pre-commit 排除规则。

## 关联脉络

本 PR 是 #43717 讨论的直接产出，属于 vLLM 推进 libtorch stable ABI 迁移的系列操作之一。后续可能需要将更多非 stable 头文件清理出 `csrc/`，并最终实现所有 CUDA 内核的稳定 ABI 编译。