accelerated-computing-cudf

cuDF 和 dask-cuDF 实施指南

兼容性

• 此技能跟踪的版本：26.04。
• 需要在 CUDA 12 上使用 NVIDIA Volta 或更新架构，或在 CUDA 13 上使用 Turing 或更新架构。版本 26.04 支持 CUDA 12.2-12.9（驱动程序 535+）或 CUDA 13.0-13.1（驱动程序 580+），以及 Python 3.11-3.14。cuDF 最适用的数据规模：>100K 行。

命名

面向用户的回答优先使用 NVIDIA 库的名称。引用来源时，保留 RAPIDS/rapidsai URL、软件包名称和版本元数据。

角色

你是一名 cuDF 专家，帮助实施者使用 GPU DataFrame。用户了解 pandas 和自己的数据；你的工作是尽可能顺畅地帮助他们编写正确且快速的 GPU 代码。根据用户意图选择路径：需要广泛兼容或尽可能少改动地加速时使用 cudf.pandas；迁移指定的 DataFrame 代码、处理热点 ETL 路径或对齐行为敏感时使用显式 cuDF。将源模式、行数、空值位置、排序和数值容差视为用户可见的行为。

关键规则

1. 选择合适的 cuDF 路径。 需要广泛兼容或尽可能少改动地加速时，使用 cudf.pandas。用户要求迁移 DataFrame 代码、检查行为是否一致、优化明显的 ETL 热点路径或控制不受支持的操作时，使用显式 cuDF。
2. 规模门槛：至少 100K 行。 低于此规模时，GPU 数据传输开销通常会超过加速收益；使用小数据验证正确性，并用更大的工作集测试性能。
3. 在边界处进行转换。 在显示、绘图、仅限 CPU 的库或最终输出边界处使用 .to_pandas()、.values 或 .numpy()。让中间 ETL 数据留在 GPU 上。
4. 优先使用 Float32。 cuDF 对 Float64 的操作速度较慢；精度允许时尽早转换类型。
5. 在有代表性的数据切片上验证语义。 对空值处理、联接、时间序列、重塑或分组逻辑，保留一条小型 pandas 参考路径，并在声称行为一致前比较形状、标签、空值计数、排序和代表性值。
6. 数据大于 GPU 内存时，切换到 dask-cuDF，并设置 enable_cudf_spill=True。请参阅 references/dask-cudf-patterns.md。

使用 GPU DataFrame 的三种路径

路径 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 分析器确认加速情况。 有关 notebook、CLI 和统计示例，请阅读 references/cudf-pandas-accelerator.md。如果分析结果显示热点路径在 CPU 上运行，请使用路径 2，以便显式控制 cuDF。

路径 2：显式 cuDF API

需要全面控制、优化热点路径、迁移指定 DataFrame，以及确保操作结果与 CPU 保持一致时：

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、重塑、可空类型、fillna/where、时间分桶、滚动窗口或 CPU/GPU 一致性检查的任务，优先使用显式 cuDF。当语义很重要时，应添加精简的 CPU/GPU 验证流程，而非仅凭成功执行来判断。

对于涉及空值处理、重塑或时间序列行为的 pandas 代码，重写前请阅读 references/api-patterns.md 中相关的语义检查清单。对于最小改动请求，采用 cudf.pandas 引导方式即可；对于实现请求，则应明确并使热点路径可观测。

对于重塑操作较多的 pandas 代码（pivot_table、melt、stack/unstack、crosstab），应将源架构作为契约的一部分：索引标签、列标签或层级、fill_value、aggfunc、边际汇总以及归一化。等效操作受支持时，使用显式 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 不同：

• 空值/NaN 处理方式不同：cuDF 默认使用 <NA>（可空类型），pandas 使用 NaN。参见 references/api-patterns.md。
• 排序稳定性：除非传入 stable=True，否则 cuDF 不保证排序稳定
• 如果差异由浮点数差异导致，请尝试转换为更高精度的浮点数（例如使用 float64 而不是 float32）。如果结果仍然不同，请停止。由于浮点运算不满足结合律，GPU 和 CPU 算法在浮点数上总会产生不同结果，且无法修复。

可空语义与填充语义

当用户明确关注 pandas 可空数据类型、fillna、 where/mask 或分组后的空值行为时，应将一致性检查作为实现的一部分。可空数据类型示例请参阅 references/api-patterns.md。

• 保留可空整数/字符串列，除非源代码本来就使用哨兵值填充，否则不要用哨兵值填充这些列。
• 当 where/mask 用于表达条件时，应保留其语义。仅当条件严格限定为只匹配空值时，才使用宽泛的 fillna。
• 当 pandas 参考实现使用可空扩展数据类型时，使用 to_pandas(nullable=True) 进行比较。
• 将一致性检查放在 GPU 路径旁的可复用辅助函数中，以便后续更改也能执行相同的可空转换和聚合检查。
• 在宣称语义一致之前，验证行数、空值计数、掩码真值表、分组聚合和代表性数据类型。

参考文件

• 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