accelerated-computing-cudf

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

互換性

• このスキルで追跡している開発リリースは 26.12（VERSION：26.12.00）です。デプロイ要件には、選択したインストール済みリリースを使用してください。
• サポートマトリックスは dependencies.yaml で確認してください（Python バージョンは py_version グループ、CUDA バージョンは cuda_version グループ）。cuDF、pylibcudf、libcudf、RMM のリリースバージョンを一致させ、pip ホイールのサフィックス（-cu12／-cu13）を CUDA のメジャーバージョンに合わせてください。
• サポート対象の NVIDIA GPU と互換性のあるドライバーが必要です。選択したリリースと CUDA バージョンのインストール要件を確認してください。
• 別のチェックアウトやインストール済みリリースを使用する場合は、バージョンを選択したり API に依存したりする前に、VERSION、dependencies.yaml、python/cudf/pyproject.toml、cudf.__version__ を確認してください。

命名

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

役割

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

重要なルール

1. 適切な cuDF の方法を選択してください。 幅広い互換性や最小限の変更による高速化には cudf.pandas を使用してください。DataFrame コードの移行、同等性の確認、目に見える ETL のホットパスの最適化、または非対応の操作の制御をユーザーが求めている場合は、明示的な cuDF を使用してください。
2. 実際のワーキングセットでベンチマークしてください。 GPU 転送とカーネル起動のオーバーヘッドは、小規模なワークロードでは支配的になる場合があります。10 万行は開始時の目安であり、最低要件ではありません。正確性の確認には小規模データを、性能の確認には代表的なデータを使用してください。
3. 変換は境界で行ってください。 CPU 専用ライブラリ、表示、または最終出力との境界では .to_pandas() または .to_numpy() を使用してください。.values と .to_cupy() が返すのは GPU 配列であり、NumPy 配列ではありません。中間 ETL データは GPU 上に保持してください。
4. 精度は意図的に選択してください。 Float32 はメモリ使用量を減らし、スループットを向上させる可能性がありますが、精度が必要な場合は 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 上で実行されている場合は、方法 2 を使って cuDF を明示的に制御してください。

パス 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、形状変更、nullable 型、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
import dask.dataframe as dd

dask.config.set({"dataframe.backend": "cudf"})

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

ddf = dd.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 非同期アロケーター（多数の割り当てを行うパイプラインでは、割り当てのオーバーヘッドを軽減できます）。cuDF の割り当てを行う前に設定し、その割り当てが使用中の間はリソースを保持してください。

import rmm
memory_resource = rmm.mr.CudaAsyncMemoryResource()
rmm.mr.set_current_device_resource(memory_resource)

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

トラブルシューティング

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

• 作業セットが小さいですか？転送と起動のオーバーヘッドを測定し、代表的なデータサイズでベンチマークしてください。
• %%cudf.pandas.profile を実行してください。CPU 使用率が高い場合、多くの処理がフォールバックしています。該当する処理を特定して修正してください。
• 既知の未対応項目については references/api-patterns.md を確認してください。

OOM（CUDA out of memory）：

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>（nullable）を使用し、pandas は NaN を使用します。references/api-patterns.md を参照してください。
• ソートの安定性：Python の sort_values に stable=True パラメーターはなく、kind="stable"／kind="mergesort" は現在、警告を出して quicksort にフォールバックします。同じキーの並び順が重要な場合は、元の行位置をタイブレーカーとして追加してください。references/api-patterns.md を参照してください。
• 浮動小数点の集約では、演算に結合則が成り立たないため、CPU と GPU で結果が異なることがあります。必要な精度を維持し、明示的な許容誤差を指定して比較し、その許容誤差を超える差異を調査してください。

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.nvidia.com/cudf/
• dask-cuDF API リファレンス： https://docs.nvidia.com/dask-cudf/
• GitHub： https://github.com/NVIDIA/cudf
• 変更履歴： https://github.com/NVIDIA/cudf/blob/main/CHANGELOG.md