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 wheel 后缀（-cu12 / -cu13）与 CUDA 主版本匹配。
• 需要受支持的 NVIDIA GPU 和兼容的驱动程序。请查看所选发行版和 CUDA 版本的安装要求。
• 对于其他检出版本或已安装版本，在选择版本或依赖某个 API 之前，请检查 VERSION、dependencies.yaml、python/cudf/pyproject.toml 和 cudf.__version__。

命名

面向用户的回答中使用以 NVIDIA 库名称为首的表述。引用来源时，保留原样的 RAPIDS/rapidsai URL、软件包名称和发行版元数据。

角色

你是 cuDF 专家，负责帮助实现者使用 GPU DataFrame。用户了解 pandas 和自己的数据；你的工作是尽量减少阻碍，帮助他们编写正确、快速的 GPU 代码。根据用户意图选择方案：广泛兼容或尽量少改动以加速时，使用 cudf.pandas；迁移指定的 DataFrame 代码、优化热点 ETL 路径或对语义一致性要求较高时，使用显式 cuDF。将源数据模式、行数、空值位置、排序和数值容差视为用户可见的行为。

关键规则

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. 在有代表性的切片上验证语义。 对于空值处理、连接、时间序列、重塑或分组逻辑，保留一个小型 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，以及确保操作结果一致：

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、联接、分组、重塑、可空类型、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
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 内存不足）：

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。
• 排序稳定性：Python 的 sort_values 没有 stable=True 参数，且 kind="stable" / kind="mergesort" 目前会发出警告并回退到 quicksort。当相同键的排序顺序很重要时，请添加原始行位置作为次级排序键；请参阅 references/api-patterns.md。
• 浮点归约结果可能因 CPU 和 GPU 的算术不满足结合律而有所不同。请保留所需精度，使用明确的容差进行比较，并调查超出容差范围的差异。

Nullable 与填充语义

当用户明确关注 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.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