optimize-for-gpu

NVIDIA による Python の GPU 最適化

GPU アクセラレーションは、自動的に書き換えるのではなく、証拠に基づいて最適化として扱ってください。ユーザーの数値的およびアルゴリズム上の契約を維持し、代表的なデータで測定し、同期したエンドツーエンドのベンチマークで有用な改善が確認できた場合にのみ、GPU 版を採用してください。

このスキルを使用する場面

• ユーザーが数値計算や科学計算の Python コードを高速化したい
• ユーザーが大きな配列、行列、データフレームを扱っている
• ユーザーが CUDA、GPU、NVIDIA、または並列計算に言及している
• ユーザーが大規模なデータセットを処理する NumPy、pandas、SciPy、scikit-learn、NetworkX、または scipy.sparse.linalg のコードを持っている
• ユーザーが低レベルの GPU プリミティブ（疎行列固有値ソルバー、デバイスメモリ管理、マルチ GPU 通信）を必要としている
• ユーザーが機械学習（学習、推論、ハイパーパラメーター調整、前処理）に取り組んでいる
• ユーザーがグラフ分析（中心性、コミュニティ検出、最短経路、PageRank など）に取り組んでいる
• ユーザーがベクトル検索、最近傍検索、類似性検索、または RAG パイプラインの構築を行っている
• ユーザーが GPU アクセラレーション可能な Faiss、Annoy、ScaNN、または sklearn NearestNeighbors のコードを持っている
• ユーザーが大規模なデータセットで、GPU アクセラレーションされたインタラクティブなダッシュボード、クロスフィルタリング、または探索的データ分析を行いたい
• ユーザーが GeoPandas または shapely を使って地理空間分析（点がポリゴン内にあるかの判定、空間結合、軌跡分析、距離計算）を行っている
• ユーザーが scikit-image または OpenCV を使って画像処理、コンピュータービジョン、または医用画像処理（フィルタリング、セグメンテーション、モルフォロジー、特徴検出）を行っている
• ユーザーが全スライド画像（WSI）、デジタル病理学、顕微鏡画像、またはリモートセンシング画像を扱っている
• ユーザーが大きなバイナリデータファイルを GPU メモリに読み込んでいる（numpy.fromfile → cupy、または Python の open() → GPU 配列）
• ユーザーが S3、HTTP、または WebHDFS からファイルを直接 GPU メモリに読み込む必要がある
• ユーザーが GPUDirect Storage（GDS）に言及している、またはファイル I/O の CPU メモリへのステージングを回避したい
• ユーザーが物理シミュレーション（粒子、布、流体、剛体）または微分可能シミュレーションを行っている
• ユーザーがメッシュ操作（レイキャスティング、最近接点クエリー、符号付き距離場）または GPU 上のジオメトリ処理を必要としている
• ユーザーが変換やクォータニオンを使ったロボティクス（運動学、動力学、制御）に取り組んでいる
• ユーザーが GPU カーネルに JIT コンパイルできる Python のシミュレーションループを持っている
• ユーザーが NVIDIA Warp に言及している、または PyTorch/JAX と統合された微分可能な GPU シミュレーションを求めている
• ユーザーがシミュレーション、信号処理、金融モデリング、バイオインフォマティクス、物理学、またはその他の計算負荷の高い作業を行っている
• ユーザーが既存のコードを最適化したいと考えており、GPU アクセラレーションが適切な解決策である

最適な最小レイヤーを選択する

カスタムカーネルよりも、メンテナンスされているライブラリ実装を優先してください:

既存のワークロード	推奨されるパス	用途
NumPy / SciPy	CuPy	配列、スパース行列、線形代数、FFT、信号処理
pandas	cudf.pandas、次に cuDF	まずアクセラレータモード。より細かい制御が必要な場合はネイティブ API
scikit-learn	cuml.accel、次に cuML	まずアクセラレータモード。必要に応じてネイティブ推定量
NetworkX	nx-cugraph、次に cuGraph	まずバックエンドディスパッチ。大規模な場合はネイティブグラフ API
scikit-image	cuCIM	GPU 画像処理およびホールスライドイメージング
Faiss / Annoy / k-NN	cuVS	厳密および近似ベクトル検索
生ファイルまたはリモートファイルの I/O	KvikIO	GPU バッファおよび GPUDirect Storage
カスタム配列カーネル	新規の作業には Numba-CUDA-MLIR、既存コードには Numba-CUDA	明示的な SIMT カーネルおよび共有メモリ
空間カーネルまたは微分可能カーネル	Warp	ジオメトリ、シミュレーションカーネル、ロボティクス、自動微分
高レベル物理シミュレーション	Newton	削除された warp.sim モジュールを引き継ぐ、メンテナンスされているエンジン
低レベル RAPIDS プリミティブ	RAFT (pylibraft)	スパース固有値ソルバー、リソース、マルチ GPU ビルディングブロック

これらのライブラリのいずれかを使用するためだけに、PyTorch、JAX、TensorFlow、または別の GPU ネイティブフレームワークからコードを移行しないでください。まず CPU のラウンドトリップを排除し、フレームワークのコンパイラ、プロファイラ、混合精度、バッチ処理の機能を使用してください。

これらはレガシー専用として扱ってください:

プロジェクト	ステータス	ガイダンス
cuxfilter	最終リリース 26.06	既存のダッシュボードのみをメンテナンスしてください。新規の作業には、cuDF を HoloViews/hvPlot/Datashader と組み合わせ、Panel、Dash、Streamlit、または Bokeh で提供してください。
cuSpatial	25.04 でアーカイブ	分離されたレガシー環境でのみ使用してください。新規の作業には、ジオメトリを GeoPandas/Shapely に保持し、互換性のある表形式のステージを cuDF で高速化してください。

各ライブラリが 誤った 選択となる場合や、それらを組み合わせる方法など、ライブラリごとの詳細なガイダンスは references/decision_framework.md にあります。 インストールコマンドと CUDA バージョンの選択は references/installation.md にあります。すべてのライブラリの変換前/変換後は references/code_transformation_patterns.md にあります。

最適化ワークフロー

1. コントラクトとベースラインを定義する

• 代表的な入力、期待される出力、許容可能な数値許容範囲を記録します。
• 入力、転送、計算、出力を含む現在のエンドツーエンドのパスを測定します。
• コードを変更する前にプロファイリングします。CPU コードには CPU プロファイラを使用し、実際の制限が計算、メモリ帯域幅、割り当て、転送、同期、ストレージのどれであるかを特定します。
• ハードウェア、パッケージのバージョン、dtype、形状、バッチサイズ、ウォームアップポリシーを結果とともに記録します。

2. 移植前に適合性を確認する

GPU 実行は、ホットパスが実質的な独立した作業を公開し、初期化と転送を償却するのに十分な頻度で実行され、テンポラリ用の余地を残して利用可能なデバイスメモリに収まるワーキングセットを持つ場合に有望です。ワークロードが小さく、ほとんどが逐次的で、サポートされていない操作に支配されている場合、または頻繁なホスト-デバイス間のラウンドトリップを必要とする場合は、CPU パスを維持してください。

固定の行数しきい値を証明として使用しないでください。ユーザーの実際の形状とハードウェアをベンチマークしてください。アウトオブコアデータの場合は、ピークワーキングメモリを見積もり、割り当てる前にチャンク化、Dask、またはストリーミング設計を選択してください。

3. 影響を最小限に抑えた実装を試す

1. コードがすでに GPU ネイティブのフレームワークを使用している場合は、そのフレームワーク内で最適化します。
2. アクセラレーターやバックエンドのモード（cudf.pandas、cuml.accel、nx-cugraph）を試します。
3. アクセラレーターの対応範囲や性能が不十分な場合に限り、ネイティブ GPU API に移行します。
4. プロファイリングで適切なライブラリ実装がない操作が確認された場合に限り、カスタムカーネルを作成します。

コードを書く前に、関連するライブラリのリファレンスを確認してください。名前が互換性のあるものでも、デフォルト値、データ型、出力の型、サポートされる引数が異なる場合があります。

4. 一貫性のある GPU データパスを維持する

• 入力は一度だけ転送し、中間データはデバイス上に保持します。
• 割り当てを再利用し、セマンティクス上可能な場合は out= やインプレース形式を優先します。
• 小さな操作はまとめ、中間配列をなくせる場合は要素単位の処理を融合します。
• ピン留めされたホストメモリやデフォルト以外のストリームは、プロファイリングで転送のオーバーラップが重要だと確認された場合にのみ使用します。
• コントラクトで許可される場合に限り、float32、混合精度、または低精度のストレージを選択します。

5. 速度より先にセマンティクスを検証する

• 小規模な決定論的フィクスチャと代表的なデータを使って、CPU と GPU の出力を比較します。
• 浮動小数点の結果には明示的な許容誤差を指定し、エッジケース、NaN、順序、データ型をテストします。
• 近似最近傍インデックスでは、厳密な検索に対する recall@k を報告します。厳密な CPU アルゴリズムと近似 GPU アルゴリズムを、同等のものとして比較してはいけません。
• アクセラレーターの警告とログを確認し、CPU にフォールバックしていないか調べます。

6. GPU コードを正しくベンチマークする

GPU の処理は非同期であるため、同期されていない呼び出しを CPU タイマーで計測すると、エンキュー時間が測定されます。コンテキストの作成と JIT コンパイルをウォームアップしてから、CUDA イベントまたはライブラリ対応のタイマーを使用します。

from cupyx.profiler import benchmark

print(benchmark(gpu_function, (arg1, arg2), n_warmup=10, n_repeat=100))

ノートブックでは %gpu_timeit を、エンドツーエンドのタイムラインには Nsight Systems（nsys）を、カーネル分析には Nsight Compute（ncu）を使用します。同期済みのカーネル／リージョンの実行時間と、実環境を想定したエンドツーエンドのレイテンシーの両方を報告します。本番環境で転送や変換にコストがかかる場合は、そのコストも含めます。

7. ポートを維持、見直し、または却下する

GPU パスは、正確性のチェックに合格し、代表的なデータでユーザーが重視する指標を改善する場合に限り維持します。改善しない場合は、問題のサイズ、転送、サポートされていない処理へのフォールバック、メモリの負荷、起動粒度、アルゴリズム自体のいずれがボトルネックなのかを説明します。

重要な注意事項

• アプリケーションで移植性が必要な場合は CPU フォールバックを用意します。それ以外の場合は、ハードウェアと依存関係に関する明確なエラーを出して早期に終了します。
• CPU の結果と照らし合わせて数値の正確性をテストします（GPU の浮動小数点演算では、演算順序の違いによって結果がわずかに異なる場合があります）。
• GPU メモリには限りがあります。データセットが GPU メモリより大きい場合は、チャンク分割するか、マルチ GPU 向けの RAPIDS Dask の使用を検討します。
• サポートされているゼロコピーのデータ交換には CUDA Array Interface または DLPack を優先します。ただし、すべての変換が無料だと想定せず、デバイス、データ型、連続性、所有権、ストリームのセマンティクスを確認してください。

リファレンスファイル

GPU 最適化コードを書く前に、関連するリファレンスファイルを読んでください。

ファイル	読むタイミング
references/cupy.md	NumPy／SciPy のコードがある場合、または GPU 上で配列操作が必要な場合
references/numba.md	既存の Numba-CUDA コードがある場合、または明示的な SIMT カーネルが必要な場合。Numba-CUDA-MLIR への移行パスにも注意してください
references/cudf.md	pandas のコードがある場合、または GPU 上でデータフレーム操作が必要な場合
references/cuml.md	scikit-learn のコードがある場合、または GPU 上で ML のトレーニング／推論／前処理が必要な場合
references/cugraph.md	NetworkX のコードがある場合、または GPU 上でグラフ分析が必要な場合
references/warp.md	シミュレーション、空間コンピューティング、メッシュ／ボリューム検索、微分可能プログラミング、またはロボティクス向けの GPU カーネルが必要な場合。高水準の物理エンジンには Newton を使用してください
references/kvikio.md	GPU との高速ファイル IO、GPUDirect Storage、S3／HTTP から GPU への読み込み、または GPU 上の Zarr が必要な場合
references/cuxfilter.md	cuxfilter を保守している場合、または明示的に使用を求められた場合（サポート終了 — 26.06 が最終リリースです）
references/cucim.md	scikit-image のコードがある場合、または GPU 上で画像処理、デジタル病理、WSI の読み込みが必要な場合
references/cuvs.md	GPU 上でベクトル検索、最近傍探索、類似検索、または RAG 検索が必要な場合
references/cuspatial.md	cuSpatial を保守している場合、または明示的に使用を求められた場合（アーカイブ済み — 25.04 で固定され、現行の RAPIDS から分離されています）
references/raft.md	疎行列固有値ソルバー、デバイスメモリー管理、またはマルチ GPU プリミティブが必要な場合

コードを書く前に、該当するリファレンスを読んでください。各ライブラリに固有の詳細な API パターン、最適化手法、注意点が記載されています。

関連スキル

• dask：メモリー容量を超える pandas／NumPy ワークフロー向けの分散コンピューティング。