cn-accelerated-computing-cudf：cuDF GPU 数据框架开发指南

cuDF & dask-cuDF 实现者指南

兼容性

• 本技能跟踪的版本：26.04。
• 需要 NVIDIA Volta 或更新架构（CUDA 12 环境），或 Turing 或更新架构（CUDA 13 环境）。26.04 版本支持 CUDA 12.2-12.9（需驱动 535+）或 CUDA 13.0-13.1（需驱动 580+），以及 Python 3.11-3.14。cuDF 最佳适用场景：行数 >10 万。

命名规范

在面向用户的回答中使用 NVIDIA 库优先的表述。引用来源时保留字面含义的 RAPIDS/rapidsai 的 URL、包名和发布元数据。

角色定位

你是 cuDF 专家，帮助实现者使用 GPU 数据框架。用户理解 pandas 和他们的数据——你的任务是以最小摩擦帮助他们写出正确、快速的 GPU 代码。根据用户意图选择合适的路径：需要广泛兼容性或最小改动加速时使用 cudf.pandas；需要进行具名 DataFrame 迁移、热 ETL 路径和语义一致性敏感工作时使用显式 cuDF。将源 schema、行数、空值位置、排序方式和数值容差视为用户可见的行为。

关键规则

1. 选择合适的 cuDF 路径。 广泛兼容性或最小改动加速使用 cudf.pandas。当用户要求迁移 DataFrame 代码、检查语义一致性、优化可见的 ETL 热路径或控制不支持的操作时，使用显式 cuDF。
2. 数据量门槛：最少 10 万行。 低于此值时，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 数据框架的三条路径

路径 1：cudf.pandas 加速I器（兼容性 / 最小改动）

当用户需要较小的代码改动、第三方 pandas 兼容性，或一条可以在不支持操作回退时继续运行的代码路径时使用。

Jupyter/IPython：

%load_ext cudf.pandas
import pandas as pd   # 现在由 GPU 后端驱动；不支持的操作静默回退

脚本：

python -m cudf.pandas my_script.py

与 multiprocessing 配合使用：

import cudf.pandas
cudf.pandas.install()   # 必须在 pandas 导入之前、Pool 创建之前调用
from multiprocessing import Pool

在声称加速之前，使用 cudf.pandas 分析器确认加速效果。 关于 Notebook、CLI 和统计信息示例，请阅读 references/cudf-pandas-accelerator.md。如果分析显示热路径 仍在 CPU 上运行，请使用路径 2 进行显式 cuDF 控制。

路径 2：显式 cuDF API

用于完全控制、热路径优化、具名 DataFrame 迁移和 语义一致性敏感的操作：

import cudf

# 直接将数据读入 GPU
df = cudf.read_parquet("data.parquet")

# 操作与 pandas 一致
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]

# 字符串操作
df["clean"] = df["name"].str.strip().str.lower()

# 在提交迁移前检查 API 覆盖范围：
# 参见 references/api-patterns.md 了解已知缺口和解决方法

保持数据端到端在 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），将源 schema 作为契约的一部分：索引标签、列标签或层级、fill_value、aggfunc、边际和归一化。在等价的操作用显式 cuDF；当 pandas 确切的 reshape 语义比重写每个操作更重要时，使用 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)  # 每 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)   # GPU 满时溢出到主机 RAM

RMM 池分配器（减少多分配流水线中的 cudaMalloc 开销）：

import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# 必须在任何 cuDF 操作之前调用

故障排除

与 pandas 相比无加速：

• 数据少于 10 万行？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。
• 排序稳定性：cuDF 排序不保证稳定，除非传递 stable=True
• 如果差异源于浮点数差异，尝试转换为更高精度的浮点数（例如 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