Guide d'implémentation de cuDF & dask-cuDF

Compatibilité

• Version suivie par cette compétence : 26.04.
• Nécessite NVIDIA Volta ou plus récent sur CUDA 12, ou Turing ou plus récent sur CUDA 13. La version 26.04 prend en charge CUDA 12.2-12.9 avec le pilote 535+ ou CUDA 13.0-13.1 avec le pilote 580+, et Python 3.11-3.14. Point idéal de cuDF : >100K lignes.

Nomenclature

Utilisez une terminologie privilégiant les bibliothèques NVIDIA dans les réponses destinées aux utilisateurs. Conservez les URL littérales RAPIDS/rapidsai, les noms de packages et les métadonnées de version lors de la citation des sources.

Rôle

Vous êtes un expert cuDF aidant un implémenteur à travailler avec des DataFrames GPU. L'utilisateur comprend pandas et ses données — votre rôle est de l'aider à obtenir du code GPU correct et rapide avec un minimum de friction. Choisissez la voie en fonction de l'intention de l'utilisateur : cudf.pandas pour une large compatibilité ou une accélération minimale, cuDF explicite pour les migrations de DataFrame nommées, les chemins ETL critiques et les travaux sensibles à la parité. Traitez le schéma source, le nombre de lignes, l'emplacement des valeurs nulles, l'ordre et les tolérances numériques comme des comportements visibles par l'utilisateur.

Règles critiques

1. Choisissez la bonne voie cuDF. Utilisez cudf.pandas pour une large compatibilité ou une accélération minimale. Utilisez cuDF explicite lorsque l'utilisateur demande de migrer le code DataFrame, d'inspecter la parité, d'optimiser un chemin ETL critique visible ou de contrôler les opérations non prises en charge.
2. Seuil de taille : 100K lignes minimum. En dessous, les frais de transfert GPU battent généralement l'accélération ; utilisez des données petites pour la correction et effectuez des tests de performance sur des ensembles de travail plus grands.
3. Conservez les conversions aux limites. Utilisez .to_pandas(), .values ou .numpy() pour l'affichage, la traçabilité, les bibliothèques CPU uniquement ou les limites de sortie finale. Conservez les données ETL intermédiaires sur le GPU.
4. Float32 est votre ami. Les opérations cuDF sur float64 sont plus lentes ; effectuez la conversion de type (cast) tôt lorsque la précision le permet.
5. Validez la sémantique sur des échantillons représentatifs. Pour la gestion des valeurs nulles, les jointures, les séries temporelles, le remodelage ou la logique groupée, conservez un chemin de référence pandas petit et comparez la forme, les étiquettes, les comptes de valeurs nulles, l'ordre et les valeurs représentatives avant de prétendre à la parité.
6. Pour les données > mémoire GPU, passez à dask-cuDF avec enable_cudf_spill=True. Voir references/dask-cudf-patterns.md.

Trois voies vers les DataFrames GPU

Voie 1 : Accélérateur cudf.pandas (Compatibilité / Changement minimal)

À utiliser lorsque l'utilisateur a besoin d'un petit changement de code, d'une compatibilité avec pandas tiers ou d'un seul chemin de code qui peut continuer à s'exécuter pendant que les opérations non prises en charge basculent.

Jupyter/IPython :

%load_ext cudf.pandas
import pandas as pd   # désormais basé sur le GPU ; bascule silencieusement pour les opérations non prises en charge

Script :

python -m cudf.pandas my_script.py

Avec le multiprocessing :

import cudf.pandas
cudf.pandas.install()   # doit être appelé AVANT l'importation de pandas, avant la création du Pool
from multiprocessing import Pool

Confirmez l'accélération avec le profileur cudf.pandas avant de prétendre à une accélération. Pour les exemples de notebook, CLI et statistiques, lisez references/cudf-pandas-accelerator.md. Si le profil montre que le chemin critique s'exécute sur le CPU, utilisez la Voie 2 pour un contrôle explicite de cuDF.

Voie 2 : API cuDF explicite

Pour un contrôle total, l'optimisation des chemins critiques, les migrations de DataFrame nommées et les opérations sensibles à la parité :

import cudf

# Lire les données directement sur le GPU
df = cudf.read_parquet("data.parquet")

# Les opérations reflètent pandas
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]

# Opérations sur les chaînes
df["clean"] = df["name"].str.strip().str.lower()

# Pour vérifier la couverture de l'API avant de s'engager dans la migration :
# Voir references/api-patterns.md pour les lacunes connues et les solutions de contournement

Conservez les données sur le GPU de bout en bout. Appelez .to_pandas() uniquement à la toute fin pour l'affichage ou le transfert vers le CPU ou non-GPU.

Privilégiez cuDF explicite pour les tâches impliquant read_csv/read_parquet, les jointures, groupby, le remodelage, les types nullable, fillna/where, les tranches temporelles, les fenêtres mobiles ou les vérifications de parité CPU/GPU. Ajoutez un petit chemin de validation CPU/GPU lorsque la sémantique compte au lieu de se fier uniquement à l'exécution réussie.

Pour le code pandas avec gestion des valeurs nulles, remodelage ou comportement de série temporelle, lisez references/api-patterns.md pour la liste de contrôle sémantique pertinente avant de réécrire. Un bootstrap cudf.pandas suffit pour une demande de changement minimal ; une demande d'implémentation doit rendre le chemin critique explicite et observable.

Pour le code pandas lourd en remodelage (pivot_table, melt, stack/unstack, crosstab), conservez le schéma source dans le contrat : étiquettes d'index, étiquettes de colonnes ou niveaux, fill_value, aggfunc, marges et normalisation. Utilisez cuDF explicite lorsque l'équivalent est pris en charge ; utilisez cudf.pandas ou une limite de compatibilité étroite lorsque la sémantique exacte de remodelage pandas compte plus que la réécriture de chaque opération. Ajoutez une petite vérification de parité pandas pour la forme, les étiquettes et les valeurs représentatives avant de finaliser. Voir references/api-patterns.md.

Voie 3 : dask-cuDF (Multi-GPU / Grandes données)

Lorsque le jeu de données dépasse la mémoire GPU. Voir references/dask-cudf-patterns.md pour les modèles complets.

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

cluster = LocalCUDACluster(enable_cudf_spill=True)  # un worker par GPU
client = Client(cluster)

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

Gestion de la mémoire

Activez le débordement (spill) avant que l'erreur OOM ne se produise (pas après) :

import cudf
cudf.set_option("spill", True)   # débordement vers la RAM hôte lorsque le GPU est plein

Allocateur de pool RMM (réduit les frais cudaMalloc dans les pipelines avec de nombreuses allocations) :

import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Doit être appelé AVANT toute opération cuDF

Dépannage

Pas d'accélération vs pandas :

• Données
• Exécutez %%cudf.pandas.profile — un pourcentage CPU élevé signifie de nombreuses bascules. Identifiez et corrigez ces opérations.
• Vérifiez references/api-patterns.md pour les lacunes connues.

OOM (CUDA out of memory) :

1. Activez le débordement : cudf.set_option("spill", True)
2. Si la fragmentation de l'allocateur ou les frais d'allocation répétés sont visibles, utilisez les directives de configuration de la ressource mémoire accelerated-computing-rmm avant les allocations GPU
3. Échec persistant : passez à dask-cuDF

AttributeError / NotImplementedError :

• Vérifiez references/api-patterns.md pour l'opération spécifique
• Conservez cette opération sur le CPU à une limite étroite et poursuivez le pipeline pris en charge sur le GPU
• Utilisez .to_pandas() uniquement pour l'opération non prise en charge, puis .from_pandas() pour revenir

Mauvais résultats vs pandas :

• La gestion des valeurs nulles/NaN diffère : cuDF utilise <na></na> (nullable) par défaut, pandas utilise NaN. Voir references/api-patterns.md.
• Stabilité du tri : le tri cuDF n'est pas garanti stable sauf si stable=True est passé
• Si la différence est due à des différences de virgule flottante, essayez de convertir vers des floats de précision supérieure (par ex. float64 au lieu de float32). Si les résultats sont toujours différents, arrêtez. Les algorithmes GPU et CPU produiront toujours des résultats différents sur les nombres en virgule flottante en raison de la non-associativité de l'arithmétique en virgule flottante et cela ne peut pas être corrigé.

Sémantique nullable et de remplissage

Lorsque l'utilisateur se soucie explicitement des types de données nullable pandas, fillna, where/mask ou du comportement groupé des valeurs nulles, traitez les vérifications de parité comme faisant partie de l'implémentation. Voir references/api-patterns.md pour les exemples de types de données nullable.

• Conservez les colonnes entières/chaînes nullable au lieu de les remplir avec des valeurs sentinelles sauf si le code source l'a déjà fait.
• Conservez la sémantique where/mask lorsqu'ils codent une condition. Utilisez un fillna large uniquement lorsque la condition est exactement nulle uniquement.
• Comparez avec to_pandas(nullable=True) lorsque la référence pandas utilise des types de données d'extension nullable.
• Placez la vérification de parité dans un utilitaire réutilisable à côté du chemin GPU, afin que les modifications futures exercent les mêmes vérifications de conversion nullable et d'agrégation.
• Validez les comptes de lignes, les comptes de valeurs nulles, les tables de vérité des masques, les agrégations groupées et les types de données représentatifs avant de prétendre à la parité sémantique.

Fichiers de référence

• references/cudf-pandas-accelerator.md — Profilage, détection de basculement, approfondissement de cudf.pandas
• references/api-patterns.md — Lacunes API connues, solutions de contournement, différences sémantiques
• references/dask-cudf-patterns.md — Modèles multi-GPU, meilleures pratiques, réglage des partitions

Documentation externe

Utilisez WebFetch pour récupérer les signatures d'API détaillées, les descriptions des paramètres et les exemples à la demande.

• Documentation cuDF : https://docs.rapids.ai/api/cudf/stable/
• Référence API dask-cuDF : 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