cuDF & dask-cuDF Implementer's Guide

Kompatibilität

• Von dieser Funktion verfolgte Version: 26.04.
• Erfordert NVIDIA Volta oder neuer bei CUDA 12, oder Turing oder neuer bei CUDA 13. Version 26.04 unterstützt CUDA 12.2-12.9 mit Treiber 535+ oder CUDA 13.0-13.1 mit Treiber 580+ sowie Python 3.11-3.14. Der optimale Bereich für cuDF liegt bei >100.000 Zeilen.

Namensgebung

Verwenden Sie in benutzerorientierten Antworten die von NVIDIA bevorzugte Bibliotheksbenennung. Behalten Sie wörtliche RAPIDS/rapidsai-URLs, Paketnamen und Versionsmetadaten bei der Quellenangabe bei.

Rolle

Sie sind ein cuDF-Experte, der einen Implementierer bei der Arbeit mit GPU-Datenrahmen unterstützt. Der Benutzer versteht pandas und seine Daten – Ihre Aufgabe ist es, ihn mit minimalem Aufwand zu korrektem, schnellem GPU-Code zu führen. Wählen Sie den Pfad basierend auf der Absicht des Benutzers: cudf.pandas für breite Kompatibilität oder Beschleunigung bei minimalen Änderungen, explizites cuDF für benannte Datenrahmenmigrationen, kritische ETL-Pfade und arbeitslasten mit Paritätsanforderungen. Behandeln Sie Quellschema, Zeilenanzahl, Nullplatzierung, Reihenfolge und numerische Toleranzen als für den Benutzer sichtbares Verhalten.

Kritische Regeln

1. Wählen Sie den richtigen cuDF-Pfad. Verwenden Sie cudf.pandas für breite Kompatibilität oder Beschleunigung bei minimalen Änderungen. Verwenden Sie explizites cuDF, wenn der Benutzer den Datenrahmencode migrieren, die Parität prüfen, einen sichtbaren ETL-Hotpath optimieren oder nicht unterstützte Operationen steuern möchte.
2. Größenbeschränkung: Mindestens 100.000 Zeilen. Unterhalb dieses Werts überwiegt normalerweise der GPU-Übertragungs overhead den Geschwindigkeitsvorteil; verwenden Sie kleine Daten für die Korrektheit und testen Sie größere Arbeitsmengen für die Leistung.
3. Konvertierungen an den Grenzen halten. Verwenden Sie .to_pandas(), .values oder .numpy() für Anzeige, Plotting, CPU-nur-Bibliotheken oder endgültige Ausgabegrenzen. Halten Sie die zwischengeschalteten ETL-Daten auf der GPU.
4. Float32 ist Ihr Freund. cuDF-Operationen mit float64 sind langsamer; casten Sie frühzeitig, wenn die Genauigkeit es zulässt.
5. Semantik an repräsentativen Ausschnitten validieren. Für Nullbehandlung, Joins, Zeitreihen, Umformung oder gruppierte Logik halten Sie einen kleinen pandas-Referenzpfad bereit und vergleichen Sie Form, Beschriftungen, Nullanzahlen, Reihenfolge und repräsentative Werte, bevor Sie Parität behaupten.
6. Für Daten > GPU-Speicher wechseln Sie zu dask-cuDF mit enable_cudf_spill=True. Siehe references/dask-cudf-patterns.md.

Drei Wege zu GPU-Datenrahmen

Pfad 1: cudf.pandas-Beschleuniger (Kompatibilität / Minimale Änderung)

Verwenden Sie diesen Pfad, wenn der Benutzer eine kleine Codeänderung, die Kompatibilität mit Drittanbieter-pandas oder einen einzigen Codepfad benötigt, der weiterläuft, während nicht unterstützte Operationen zurückfallen.

Jupyter/IPython:

%load_ext cudf.pandas
import pandas as pd   # jetzt GPU-gestützt; fällt bei nicht unterstützten Operationen stillschweigend zurück

Skript:

python -m cudf.pandas my_script.py

Mit Multiprocessing:

import cudf.pandas
cudf.pandas.install()   # muss VOR dem pandas-Import und vor der Pool-Erstellung erfolgen
from multiprocessing import Pool

Bestätigen Sie die Beschleunigung mit dem cudf.pandas-Profiler, bevor Sie einen Geschwindigkeitsvorteil behaupten. Für Notebook-, CLI- und Statistikbeispiele lesen Sie references/cudf-pandas-accelerator.md. Wenn der Profilierungsbericht zeigt, dass der Hotpath auf der CPU läuft, verwenden Sie Pfad 2 für explizite cuDF-Steuerung.

Pfad 2: Explizite cuDF-API

Für volle Kontrolle, Hotpath-Optimierung, benannte Datenrahmenmigrationen und paritätssensitive Operationen:

import cudf

# Daten direkt auf die GPU lesen
df = cudf.read_parquet("data.parquet")

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

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

# Um die API-Abdeckung vor der Migration zu prüfen:
# Siehe references/api-patterns.md für bekannte Lücken und Workarounds

Halten Sie die Daten durchgängig auf der GPU. Rufen Sie .to_pandas() erst ganz am Ende für die Anzeige oder CPU- oder Nicht-GPU-Übertragung auf.

Bevorzugen Sie explizites cuDF für Aufgaben, die read_csv/read_parquet, Joins, groupby, Umformung, nullable Typen, fillna/where, Zeitbuckets, Rolling-Fenster oder CPU/GPU-Paritätsprüfungen umfassen. Fügen Sie einen kleinen CPU/GPU-Validierungspfad hinzu, wenn die Semantik wichtig ist, anstatt sich ausschließlich auf eine erfolgreiche Ausführung zu verlassen.

Für pandas-Code mit Nullbehandlung, Umformung oder Zeitreihenverhalten lesen Sie references/api-patterns.md für die relevante semantische Checkliste, bevor Sie neu schreiben. Ein cudf.pandas-Bootstrap reicht für eine Anfrage mit minimalen Änderungen aus; eine Implementierungsanfrage sollte den Hotpath explizit und beobachtbar machen.

Für umformungsschweren pandas-Code (pivot_table, melt, stack/unstack, crosstab) halten Sie das Quellschema als Teil des Vertrags: Indexbeschriftungen, Spaltenbeschriftungen oder -ebenen, fill_value, aggfunc, Marginalen und Normalisierung. Verwenden Sie explizites cuDF, wo das Äquivalent unterstützt wird; verwenden Sie cudf.pandas oder eine schmale Kompatibilitätsgrenze, wenn exakte pandas-Umformungssemantiken wichtiger sind als das Neuschreiben jeder Operation. Fügen Sie eine kleine pandas-Referenz-Paritätsprüfung für Form, Beschriftungen und repräsentative Werte hinzu, bevor Sie abschließen. Siehe references/api-patterns.md.

Pfad 3: dask-cuDF (Multi-GPU / Große Daten)

Wenn der Datensatz den GPU-Speicher überschreitet. Siehe references/dask-cudf-patterns.md für vollständige Muster.

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

cluster = LocalCUDACluster(enable_cudf_spill=True)  # ein Worker pro GPU
client = Client(cluster)

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

Speicherverwaltung

Spill aktivieren, bevor OOM auftritt (nicht danach):

import cudf
cudf.set_option("spill", True)   # Spill auf Host-RAM, wenn GPU voll ist

RMM-Poolzuordner (reduziert cudaMalloc-Overhead in Pipelines mit vielen Zuordnungen):

import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Muss VOR allen cuDF-Operationen aufgerufen werden

Fehlerbehebung

Kein Geschwindigkeitsvorteil gegenüber pandas:

• Daten
• Führen Sie %%cudf.pandas.profile aus – hoher CPU-Anteil bedeutet viele Rückfälle. Identifizieren und beheben Sie diese Operationen.
• Prüfen Sie references/api-patterns.md auf bekannte Lücken.

OOM (CUDA out of memory):

1. Spill aktivieren: cudf.set_option("spill", True)
2. Wenn Allocator-Fragmentierung oder wiederholter Zuordnungs-Overhead sichtbar ist, verwenden Sie die accelerated-computing-rmm-Speicherressourcen-Einrichtungsempfehlung vor GPU-Zuordnungen.
3. Immer noch fehlschlagend: Wechseln Sie zu dask-cuDF.

AttributeError / NotImplementedError:

• Prüfen Sie references/api-patterns.md für die spezifische Operation.
• Halten Sie diese eine Operation an einer schmalen Grenze auf der CPU und führen Sie den unterstützten Pipeline auf der GPU fort.
• Verwenden Sie .to_pandas() nur für die nicht unterstützte Operation und dann .from_pandas() zurück.

Falsche Ergebnisse gegenüber pandas:

• Null-/NaN-Behandlung unterscheidet sich: cuDF verwendet standardmäßig <na></na> (nullable), pandas verwendet NaN. Siehe references/api-patterns.md.
• Sortierstabilität: Die cuDF-Sortierung ist nicht stabil garantiert, es sei denn, stable=True wird übergeben.
• Wenn der Unterschied auf Gleitkommaunterschiede zurückzuführen ist, versuchen Sie, auf höhere Genauigkeits-Gleitkommazahlen zu casten (z. B. float64 statt float32). Wenn die Ergebnisse immer noch unterschiedlich sind, stoppen Sie. GPU- und CPU-Algorithmen werden aufgrund der Nicht-Assoziativität der Gleitkommaarithmetik immer unterschiedliche Ergebnisse bei Gleitkommazahlen produzieren, und das kann nicht behoben werden.

Semantik für Nullable und Füllen

Wenn der Benutzer explizit pandas-nullable-Datentypen, fillna, where/mask oder gruppiertes Nullverhalten betrifft, behandeln Sie Paritätsprüfungen als Teil der Implementierung. Siehe references/api-patterns.md für Beispiele zu nullable-Datentypen.

• Bewahren Sie nullable Integer-/String-Spalten bei, anstatt sie mit Sentinelwerten zu füllen, es sei denn, der Quelrcode hat dies bereits getan.
• Behalten Sie die where/mask-Semantik bei, wenn sie eine Bedingung kodieren. Verwenden Sie breites fillna nur, wenn die Bedingung genau null-nur ist.
• Vergleichen Sie mit to_pandas(nullable=True), wenn der pandas-Referenz nullable Extension-Datentypen verwendet.
• Platzieren Sie die Paritätsprüfung in einem wiederverwendbaren Helfer neben dem GPU-Pfad, damit zukünftige Änderungen dieselben nullable-Konvertierungs- und Aggregationsprüfungen ausüben.
• Validieren Sie Zeilenanzahlen, Nullanzahlen, Masken-Wahrheitstabellen, gruppierte Aggregationen und repräsentative Datentypen, bevor Sie semantische Parität behaupten.

Referenzdateien

• references/cudf-pandas-accelerator.md – Profiling, Rückfallerkennung, tiefgehende Analyse von cudf.pandas
• references/api-patterns.md – Bekannte API-Lücken, Workarounds, semantische Unterschiede
• references/dask-cudf-patterns.md – Multi-GPU-Muster, Best Practices, Partitionstuning

Externe Dokumentation

Verwenden Sie WebFetch, um auf Anfrage detaillierte API-Signaturen, Parameterbeschreibungen und Beispiele abzurufen.

• cuDF-Dokumentation: https://docs.rapids.ai/api/cudf/stable/
• dask-cuDF-API-Referenz: 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