abi-stable

PyTorch Stable ABI への移行

C++/CUDA PyTorch 拡張コードを Stable ABI に移行し、あるバージョンの PyTorch に対してビルドした拡張が、再コンパイルなしで将来のバージョンでも動作するようにします。

前提条件

PyTorch 2.11 以降が必要です。 変更を加える前に、インストール済みのバージョンを確認してください。

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

バージョンが 2.11 未満の場合は作業を中止し、まず PyTorch をアップグレードする必要があることをユーザーに伝えてください。Stable 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 → Stable 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：インクルードを更新する

古いインクルードを削除し、Stable 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	Stable 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：ビルド設定を更新する

プロジェクトの setup.py（または CMakeLists.txt）で、aoti_torch_get_current_cuda_stream を介して CUDA ストリームにアクセスする場合は、cxx と nvcc の両方のコンパイラーフラグに -DUSE_CUDA を追加してください。

ステップ 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 ブロックに変更しないでください。Stable ABI は switch 文で問題なく動作します。

6. TORCH_CHECK を STD_TORCH_CHECK に置き換える場合は、関数名だけを置き換えてください。チェックの内容や引数は変更しないでください。

7. tensor.data_ptr<T>() を置き換える場合、読み取り専用アクセスには tensor.const_data_ptr<T>() を使用してください。テンプレート型は変更しないでください。

8. DeviceGuard には tensor.device() ではなく tensor.get_device_index() を渡してください。

9. CUDA ストリームについては、デバイスインデックスを torch::stable::accelerator::getCurrentDeviceIndex() ではなく、テンソルから取得してください（tensor.get_device_index()）。

10. スカラー型の列挙値には torch::kFloat32 ではなく torch::headeronly::ScalarType::Float を、torch::kFloat16 ではなく torch::headeronly::ScalarType::Half を使用してください。