accelerated-computing-cudf

cuDF と dask-cuDF の実装者向けガイド

互換性

• このスキルで追跡するリリース：26.04。
• CUDA 12 では NVIDIA Volta 以降、CUDA 13 では Turing 以降が必要です。リリース 26.04 は、ドライバー 535 以降で CUDA 12.2～12.9、ドライバー 580 以降で CUDA 13.0～13.1、および Python 3.11～3.14 をサポートします。cuDF が特に適しているのは、10 万行を超えるデータです。

命名

ユーザー向けの回答では、NVIDIA のライブラリ名を先に示す表現を使ってください。出典を引用する場合は、RAPIDS/rapidsai の URL、パッケージ名、リリースメタデータをそのまま維持してください。

役割

GPU DataFrame を扱う実装者を支援する cuDF のエキスパートとして対応してください。ユーザーは pandas と自分のデータを理解しています。目標は、手間を最小限に抑えながら、正確で高速な GPU コードを実現することです。ユーザーの意図に応じて、幅広い互換性や最小限の変更には cudf.pandas を、DataFrame の移行、ホットな ETL パス、パリティが重要な作業には明示的な cuDF を選んでください。ソーススキーマ、行数、null の配置、順序、数値許容誤差は、ユーザーから見える動作として扱ってください。

重要なルール

1. 適切な cuDF の利用方法を選びます。 幅広い互換性や最小限の変更での高速化には cudf.pandas を使います。ユーザーが DataFrame コードの移行、パリティの検査、目に見える ETL のホットパスの最適化、または未サポートの操作の制御を求めている場合は、明示的な cuDF を使います。
2. サイズの基準：最低 10 万行です。 これより少ない場合は、通常、GPU への転送オーバーヘッドが高速化の効果を上回ります。少量のデータは正しさの確認に使い、性能のベンチマークにはより大きな作業データセットを使ってください。
3. 変換は境界で行います。 表示、プロット、CPU 専用ライブラリ、最終出力との境界では .to_pandas()、.values、または .numpy() を使います。中間の ETL データは GPU 上に維持してください。
4. float32 を活用します。 cuDF での float64 の操作は遅くなります。精度が許容できる場合は、早い段階でキャストしてください。
5. 代表的なサンプルでセマンティクスを検証します。 null 処理、結合、時系列、形状変更、グループ化ロジックでは、小規模な pandas の参照処理を残し、パリティを主張する前に形状、ラベル、null の件数、順序、代表値を比較してください。
6. データが GPU メモリを超える場合は、enable_cudf_spill=True を設定して dask-cuDF に移行してください。references/dask-cudf-patterns.md を参照してください。

GPU DataFrame を使う 3 つの方法

方法 1：cudf.pandas アクセラレーター（互換性／最小限の変更）

コードの変更を最小限にしたい場合、サードパーティ製の pandas 互換性が必要な場合、または未サポートの操作をフォールバックさせながら同じコードパスを実行し続けたい場合に使います。

Jupyter/IPython：

%load_ext cudf.pandas
import pandas as pd   # now GPU-backed; falls back silently for unsupported ops

スクリプト：

python -m cudf.pandas my_script.py

マルチプロセスを使う場合：

import cudf.pandas
cudf.pandas.install()   # must come BEFORE pandas import, before Pool creation
from multiprocessing import Pool

高速化を主張する前に、cudf.pandas プロファイラーで高速化を確認してください。 ノートブック、CLI、統計情報の例については、 references/cudf-pandas-accelerator.md を参照してください。プロファイルでホットパスが CPU 上で実行されている場合は、明示的に cuDF を制御できる方法 2 を使ってください。

パス 2：明示的な cuDF API

完全な制御、ホットパスの最適化、名前付き DataFrame の移行、結果の同等性が重要な操作が必要な場合：

import cudf

# Read data directly to GPU
df = cudf.read_parquet("data.parquet")

# Operations mirror pandas
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]

# String operations
df["clean"] = df["name"].str.strip().str.lower()

# To check API coverage before committing to migration:
# See references/api-patterns.md for known gaps and workarounds

データは最初から最後まで GPU 上に保ちます。 表示、CPU への受け渡し、または GPU 以外への受け渡しを行う最後の段階でのみ .to_pandas() を呼び出してください。

read_csv／read_parquet、結合、groupby、形状変更、NULL 許容型、fillna／where、時間バケット、ローリングウィンドウ、または CPU／GPU 間の結果の同等性チェックを伴うタスクでは、明示的な cuDF を優先してください。セマンティクスが重要な場合は、実行に成功することだけに頼らず、小規模な CPU／GPU 検証パスを追加してください。

NULL 処理、形状変更、または時系列の動作を伴う pandas コードを書き換える場合は、関連するセマンティクスのチェックリストを確認するため、書き換えの前に references/api-patterns.md を読んでください。変更を最小限に抑える要望であれば、cudf.pandas のブートストラップで十分です。実装の要望であれば、ホットパスを明示し、観測可能にする必要があります。

形状変更の多い pandas コード（pivot_table、melt、stack／unstack、crosstab）では、ソースのスキーマを契約の一部として維持してください。これには、インデックスラベル、列ラベルまたは階層、fill_value、aggfunc、margins、正規化が含まれます。相当する機能がサポートされている場合は明示的な cuDF を使用してください。すべての操作を書き換えることよりも pandas の形状変更のセマンティクスを正確に保つことが重要な場合は、cudf.pandas または限定的な互換性の境界を使用してください。最終確定の前に、形状、ラベル、代表的な値を対象とした小規模な pandas 参照との同等性チェックを追加してください。references/api-patterns.md を参照してください。

パス 3：dask-cuDF（マルチ GPU／大規模データ）

データセットが GPU メモリを超える場合に使用します。完全なパターンについては、references/dask-cudf-patterns.md を参照してください。

from dask_cuda import LocalCUDACluster
from dask.distributed import Client
import dask_cudf

cluster = LocalCUDACluster(enable_cudf_spill=True)  # one worker per GPU
client = Client(cluster)

ddf = dask_cudf.read_parquet("s3://bucket/data/*.parquet")
result = ddf.groupby("key").agg({"value": "sum"}).compute()

メモリ管理

OOM が発生する前にスピルを有効にしてください（発生後ではありません）：

import cudf
cudf.set_option("spill", True)   # spill to host RAM when GPU is full

RMM プールアロケーター（多数の割り当てを伴うパイプラインで cudaMalloc のオーバーヘッドを削減します）：

import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Must be called BEFORE any cuDF operations

GPU 空き容量とデータセットの関係	戦略
空き容量がデータセットの 2 倍超	単一 GPU の cuDF
空き容量がデータセットの 1～2 倍	cuDF と cudf.set_option("spill", True)
データセットが GPU メモリを超える	dask-cuDF
データセットがノードメモリを超える	dask-cuDF とマルチノード（accelerated-computing-mpf を参照）

トラブルシューティング

pandas と比べて高速化しない：

• データが 100K 行未満ですか？ GPU のオーバーヘッドが支配的になるため、その実行は正しさの検証として扱い、より大きなワーキングセットで高速化を測定してください。
• %%cudf.pandas.profile を実行します。CPU 使用率が高い場合、多くの処理がフォールバックしています。該当する処理を特定して修正してください。
• 既知の制限については、references/api-patterns.md を確認してください。

OOM（CUDA メモリ不足）：

1. スピルを有効にします：cudf.set_option("spill", True)
2. アロケーターの断片化または割り当ての繰り返しによるオーバーヘッドが確認できる場合は、GPU 割り当ての前に accelerated-computing-rmm のメモリリソース設定ガイダンスを使用してください
3. それでも失敗する場合は、dask-cuDF に移行してください

AttributeError／NotImplementedError：

• 該当する操作について、references/api-patterns.md を確認してください
• その操作だけを狭い境界で CPU 上に残し、サポートされているパイプラインは GPU 上で続行してください
• サポートされていない操作に限って .to_pandas() を使用し、その後 .from_pandas() で戻してください

pandas と異なる結果になる：

• NULL／NaN の処理が異なります。cuDF はデフォルトで <NA>（NULL 許容）を使用し、pandas は NaN を使用します。references/api-patterns.md を参照してください。
• ソートの安定性：stable=True が渡されない限り、cuDF のソートの安定性は保証されません
• 浮動小数点の差異が原因で結果が異なる場合は、より高精度の浮動小数点型（例：float32 ではなく float64）へのキャストを試してください。それでも結果が異なる場合は中止してください。浮動小数点演算の非結合性により、GPU と CPU のアルゴリズムは浮動小数点数で常に異なる結果を生成し、この問題を修正することはできません。

Nullable と Fill のセマンティクス

ユーザーが pandas の nullable dtype、fillna、 where／mask、またはグループ化した際の null の挙動を明示的に重視する場合は、パリティチェックを実装の一部として扱ってください。nullable dtype の例については、references/api-patterns.md を参照してください。

• ソースコードですでにセンチネル値を使っていた場合を除き、nullable の整数列／文字列列には値を埋め込まず、そのまま保持してください。
• 条件を表す where／mask のセマンティクスを維持してください。条件が null のみを対象とする場合に限り、広範な fillna を使用してください。
• pandas の参照実装で nullable 拡張 dtype が使われている場合は、to_pandas(nullable=True) と比較してください。
• GPU パスの近くに再利用可能なヘルパーを用意してパリティチェックを配置し、今後の変更でも同じ nullable 変換と集約のチェックが実行されるようにしてください。
• セマンティックパリティを主張する前に、行数、null 数、マスクの真理値表、グループ化した集計、代表的な dtype を検証してください。

参考ファイル

• references/cudf-pandas-accelerator.md — プロファイリング、フォールバックの検出、cudf.pandas の詳細
• references/api-patterns.md — 既知の API の不足点、回避策、セマンティック上の違い
• references/dask-cudf-patterns.md — マルチ GPU のパターン、ベストプラクティス、パーティションの調整

外部ドキュメント

必要に応じて WebFetch を使用し、詳細な API シグネチャ、パラメーターの説明、例を取得してください。

• cuDF ドキュメント： https://docs.rapids.ai/api/cudf/stable/
• dask-cuDF API リファレンス： https://docs.rapids.ai/api/dask-cudf/stable/api/
• GitHub： https://github.com/rapidsai/cudf
• CHANGELOG： https://github.com/rapidsai/cudf/blob/main/CHANGELOG.md