执行摘要
此 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 配置，维持编译和代码格式一致性。
实现拆解
- 文件移动：通过 git rename 将
broadcast_load_epilogue_c2x.hpp、launch_bounds_utils.h、ggml-common.h 等移动到 csrc/libtorch_stable/ 对应子目录。
- 更新包含路径：在
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 个头文件改为直接文件名。
- 调整格式化排除：修改
.pre-commit-config.yaml 中 clang-format 的 exclude 规则，将旧路径替换为新路径，避免格式化上游头文件。
- 路径风格回溯：曾尝试使用
stable_libtorch/ 显式前缀（如 #include "stable_libtorch/..."），但随后还原为简洁路径，以降低维护负担并与已有风格一致。
csrc/libtorch_stable/cutlass_extensions/epilogue/scaled_mm_epilogues_c2x.hpp
展示了头文件迁移后 include 路径的典型变更，是理解迁移模式的关键文件。
#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 编译。
参与讨论