abi-stable

PyTorch 稳定 ABI 迁移

将 C++/CUDA PyTorch 扩展代码迁移到稳定 ABI，使针对一个 PyTorch 版本构建的扩展无需重新编译，也能继续与未来版本兼容。

前置条件

需要 PyTorch 2.11+。 进行任何更改前，请先验证已安装的版本：

python3 -c "import torch; print(torch.__version__)"

如果版本低于 2.11，请停止并告知用户需要先升级 PyTorch。 稳定 ABI 头文件（torch/csrc/stable/）在 PyTorch 2.7 中引入，但大多数迁移所需的 API 接口直到 2.11 才完善。

参考文档

开始迁移前，请阅读项目的参考文档：

• 官方指南：https://docs.pytorch.org/docs/stable/notes/libtorch_stable_abi.html
• C++ API 参考：https://docs.pytorch.org/cppdocs/stable.html

如需查看实际迁移的具体前后示例，请参阅 references/migration-example.md。

如需查看完整的 API 映射（旧 API -> 稳定 ABI 替代项），请参阅 references/api-mapping.md。

迁移工作流

步骤 1：确定要迁移的文件

查找所有包含 PyTorch 头文件（例如以下文件）的 .cpp、.cu 和 .cuh 文件：

• <torch/extension.h>
• <ATen/ATen.h>
• <ATen/cuda/CUDAContext.h>
• <c10/cuda/CUDAGuard.h>
• <torch/library.h>

步骤 2：更新 include

移除旧的 include，并替换为稳定 ABI 头文件：

// REMOVE these:
// #include <torch/extension.h>
// #include <ATen/ATen.h>
// #include <ATen/cuda/CUDAContext.h>
// #include <c10/cuda/CUDAGuard.h>
// #include <torch/library.h>

// ADD these (include only what you need):
#include <torch/csrc/stable/tensor.h>
#include <torch/csrc/stable/library.h>
#include <torch/csrc/stable/ops.h>
#include <torch/csrc/stable/accelerator.h>

#include <torch/headeronly/core/ScalarType.h>
#include <torch/headeronly/util/Exception.h>
#include <torch/headeronly/util/shim_utils.h>

// For CUDA stream access:
#include <torch/csrc/inductor/aoti_torch/c/shim.h>
#include <cuda_runtime.h>

步骤 3：替换 API

应用 references/api-mapping.md 中所述的替换项。 最常见的替换如下：

旧 API	稳定 ABI 替代项
at::Tensor / torch::Tensor	torch::stable::Tensor
TORCH_CHECK(...)	STD_TORCH_CHECK(...)
c10::cuda::CUDAGuard	torch::stable::accelerator::DeviceGuard
at::empty({...}, options)	torch::stable::new_empty(ref_tensor, {sizes}, dtype)
at::zeros({...}, options)	torch::stable::new_zeros(ref_tensor, {sizes}, dtype)
TORCH_LIBRARY_IMPL	STABLE_TORCH_LIBRARY_IMPL
m.impl("name", &func)	m.impl("name", TORCH_BOX(&func))

步骤 4：更新构建配置

如果通过 aoti_torch_get_current_cuda_stream 访问 CUDA 流，请在项目的 setup.py（或 CMakeLists.txt）中， 将 -DUSE_CUDA 添加到 cxx 和 nvcc 编译器标志中。

步骤 5：构建并迭代

构建项目并逐步修复编译错误。常见问题记录在 references/common-issues.md 中。

关键规则

以下是 AI 模型常犯的错误，请严格遵守：

1. 不要使用 torch::stable::new_empty_strided——此 API 不存在。 要创建跨步张量，请先创建维度转置后的连续张量， 然后调用 torch::stable::transpose()。

2. 不要定义可从 Python 访问的虚拟 _C 模块。

3. 不要自行声明 aoti_torch_get_current_cuda_stream。 请从 torch/csrc/inductor/aoti_torch/c/shim.h 中引入该函数。

4. 不要手动装箱内核。 在 m.impl() 调用中使用 TORCH_BOX(&func)。

5. 不要将 switch 语句改成 if/else 代码块。 稳定 ABI 完全支持 switch 语句。

6. 将 TORCH_CHECK 替换为 STD_TORCH_CHECK 时，只替换函数名。 不要更改检查的内容或参数。

7. 替换 tensor.data_ptr<T>() 时，只读访问应使用 tensor.const_data_ptr<T>()。不要更改模板类型。

8. **对于 DeviceGuard，**传入 tensor.get_device_index()，而不是 tensor.device()。

9. **对于 CUDA 流，**从张量获取设备索引 （tensor.get_device_index()），不要使用 torch::stable::accelerator::getCurrentDeviceIndex()。

10. 标量类型枚举使用 torch::headeronly::ScalarType::Float（不要使用 torch::kFloat32）、torch::headeronly::ScalarType::Half（不要使用 torch::kFloat16）， 以此类推。