使用 cuDF 在 GPU 上加速 pandas 表格计算:从 cudf.pandas 零改动加速到原生 GPU DataFrame API

原创2026-09-11 10:05:051,857 阅读
文章标签:AI 技能AI 插件人工智能科研生物信息学科学计算数据分析

使用 cuDF 在 GPU 上加速 pandas 表格计算:从 cudf.pandas 零改动加速到原生 GPU DataFrame API

cuDF 是 NVIDIA RAPIDS 生态中面向 GPU 的 DataFrame 库,提供与 pandas 高度一致的 API,用于在 GPU 上完成表格数据的加载、连接、聚合、过滤与转换。在本仓库的 optimize-for-gpu 技能 中,cuDF 被定位为 pandas 工作负载的标准 GPU 加速路径:既有零代码改动的 cudf.pandas 加速模式,也有追求极致性能的原生 cuDF API。读完本文,你将掌握 cuDF 的安装验证、两种使用模式的选择、核心 DataFrame/Series 操作、GPU 加速的 IO 与 GroupBy、JIT 编译的用户自定义函数、RMM 内存管理与多 GPU 扩展,以及从 pandas 平滑迁移的实战模式。

安装与环境验证

cuDF 是 RAPIDS 26.06 系列的一部分,要求 Python >= 3.11,运行环境为 Linux 或 WSL2,并需要匹配的 CUDA 12.x 或 13.x 驱动。RAPIDS 每个受维护的包都会同时发布 -cu12 与 -cu13 两个 wheel 变体,按本仓库的包管理约定,用 uv add 安装(若用户项目已配置其他包管理器,则遵循其既有约定):

uv add "cudf-cu12==26.6.*"    # For CUDA 12.x
uv add "cudf-cu13==26.6.*"    # For CUDA 13.x

cuDF 的 wheel 目前已直接发布到 PyPI,安装时不再强制要求 --extra-index-url=https://pypi.nvidia.com。仓库的 installation.md 中仍然带上了 NVIDIA 额外索引,其原因是"各包在 PyPI 上的可用性存在差异",对 cuDF 本身而言已非必需。安装后验证 GPU 后端可用:

import cudf
print(cudf.Series([1, 2, 3]))  # Should print a GPU series

需要提醒的是,cuDF 属于"Linux + CUDA only"的 RAPIDS wheel 组:本仓库的 tests/skill-requirements.toml 明确将 cudf-cu12 标记为不可用的环境类型,并注明原因是 "RAPIDS wheels are Linux + CUDA only (whole group)"。因此在没有 NVIDIA CUDA GPU、非 Linux/WSL2 或 CPU-only 的环境中,应保留 CPU 路径作为回退。

两种使用模式

cuDF 为加速 pandas 代码提供两条路径,仓库的决策框架 decision_framework.md 建议"优先采用加速器或后端模式,再进行原生重写",并遵循"最小侵入"的改造顺序。

模式一:cudf.pandas 加速器模式(零代码改动)。作为 pandas 的即插即用替代品,自动加速现有代码,对不受支持的操作回退到 CPU。适用于:快速加速既有代码、混合代码库、原型验证。注意它仍然有代理开销,且回退边界需要关注。

模式二:直接 cuDF API。将 import pandas 换成 import cudf,获得最大性能,无代理开销,但需要适配 cuDF 与 pandas 在行为上的一些差异。适用于:生产管线、追求最大性能、全新编写的 GPU 优先代码。

仓库中的 code_transformation_patterns.md 给出了最小的 pandas→cuDF 转换示范,仅需更换 import 与读取函数:

# Before (CPU)
import pandas as pd
df = pd.read_parquet("large_data.parquet")
result = df.groupby("category")["value"].mean()

# After (GPU) — change the import
import cudf
df = cudf.read_parquet("large_data.parquet")
result = df.groupby("category")["value"].mean()

# Or zero-code-change: python -m cudf.pandas your_script.py

cudf.pandas 加速器模式

从 pandas 到 GPU 的最快路径——无需修改任何业务代码。

激活方式

# Jupyter/IPython(必须在任何 pandas import 之前执行)
%load_ext cudf.pandas
import pandas as pd  # Now GPU-accelerated

# 命令行
# python -m cudf.pandas your_script.py
# python -m cudf.pandas --profile your_script.py  # 带性能剖析

# 程序化激活
import cudf.pandas
cudf.pandas.install()
import pandas as pd  # Now GPU-accelerated

关键点:如果当前会话已经导入过 pandas,必须重启 kernel/进程后再激活。

工作原理

  • import pandas 返回一个代理模块,内部包装 cuDF 与 pandas;
  • 每个操作首先在 GPU(cuDF)上尝试执行,失败则自动回退到 CPU(pandas);
  • 仅在必要时才发生 GPU 与 CPU 之间的数据传输;
  • 默认使用托管内存(managed memory),可处理大于 GPU 显存的数据集;
  • 目前通过 pandas 超过 18.7 万个单元测试中的 93%。

剖析 GPU 与 CPU 执行

%%cudf.pandas.profile        # 按 cell 显示 GPU vs CPU 操作占比
%%cudf.pandas.line_profile   # 逐行显示 GPU/CPU 耗时

访问底层对象

proxy_df.as_gpu_object()  # 直接获取 cuDF DataFrame
proxy_df.as_cpu_object()  # 直接获取 pandas DataFrame

注意:取出底层对象后,自动回退机制将不再生效。

兼容的第三方库

cuGraph、cuML、Hvplot、Holoview、Ibis、NumPy、Matplotlib、Plotly、PyTorch、Seaborn、Scikit-Learn、SciPy、TensorFlow、XGBoost。

不兼容:Joblib。分布式场景请改用 Dask-cuDF。

已知限制

  • 连接(join)操作不保证 pandas 的行顺序(为了性能);
  • 同一会话中不能同时使用 import cudf 与 cudf.pandas;
  • pickle 对象在原生 pandas 与 cudf.pandas 之间不可互换;
  • 代理数组继承自 numpy.ndarray,可能引发设备到主机的过早传输;
  • 如需强制纯 CPU 执行,设置环境变量 CUDF_PANDAS_FALLBACK_MODE=1。

核心 API:DataFrame 与 Series

创建 DataFrame 与 Series

import cudf

# 从字典创建
df = cudf.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0], "c": ["x", "y", "z"]})

# 从 pandas 创建
import pandas as pd
gdf = cudf.DataFrame.from_pandas(pd.DataFrame({"a": [1, 2, 3]}))
# 或直接构造
gdf = cudf.DataFrame(pandas_df)

# Series
s = cudf.Series([1, 2, 3, None, 5])

# 转回 pandas
pdf = gdf.to_pandas()

常用操作(与 pandas 一致)

df.head(10)
df.tail(5)
df.describe()
df.info()
df.dtypes
df.columns
df.shape

# 选择
df["a"]                     # 单列 → Series
df[["a", "b"]]             # 多列 → DataFrame
df.loc[2:5, ["a", "b"]]   # 标签索引
df.iloc[0:3]               # 整数位置索引

# 过滤
df[df["a"] > 2]
df.query("a > 2 and b < 6")  # 支持 @var 引用局部变量

# 排序
df.sort_values("a", ascending=False)
df.sort_index()

# 缺失值
df.fillna(0)
df.dropna()
df.isna()

# 聚合
df["a"].sum()
df["a"].mean()
df["a"].std()
df["a"].value_counts()

# 变换
df["a"].clip(lower=1, upper=5)
df["a"].apply(lambda x: x * 2)  # JIT 编译执行

# 合并
cudf.concat([df1, df2])
df1.merge(df2, on="key")
df1.merge(df2, on="key", how="left")  # left, right, inner, outer

# Arrow 互操作(零拷贝)
arrow_table = df.to_arrow()
df = cudf.DataFrame.from_arrow(arrow_table)

IO 操作

cuDF 的 GPU 加速文件读写对大型文件通常比 pandas 快一个数量级。

Parquet(性能优先推荐)

# 读取
df = cudf.read_parquet("data.parquet")
df = cudf.read_parquet("data.parquet", columns=["a", "b"])  # 仅读指定列

# 写入
df.to_parquet("output.parquet")

# 不加载数据直接查看元数据
cudf.io.parquet.read_parquet_metadata("data.parquet")

# 增量写入(按分区列分目录)
writer = cudf.io.parquet.ParquetDatasetWriter("output_dir/", partition_cols=["year"])
writer.write_table(df)
writer.close()

CSV

df = cudf.read_csv("data.csv")
df = cudf.read_csv("data.csv", usecols=["a", "b"], dtype={"a": "int32"})
df.to_csv("output.csv", index=False)

JSON

df = cudf.read_json("data.json")
df = cudf.read_json("data.json", lines=True)  # JSON Lines 格式
df.to_json("output.json")

ORC

df = cudf.read_orc("data.orc")
df.to_orc("output.orc")

其他格式

格式 读取 写入 是否 GPU 加速
Avro cudf.read_avro() 不支持 是(仅读取)
Text cudf.read_text() 不支持 是(仅读取)
HDF5 cudf.read_hdf() df.to_hdf() 否(走 pandas)
Feather cudf.read_feather() df.to_feather() 否(走 pandas)

优先用 Parquet 而非 CSV——列式格式在 GPU 上读取更快、支持谓词下推(predicate pushdown)、压缩效果更好。

GroupBy 操作

基础 GroupBy

df.groupby("category").sum()
df.groupby(["category", "subcategory"]).mean()
df.groupby("category").agg({"value": "sum", "count": "max"})
df.groupby("category").agg({"value": ["sum", "min", "max"], "count": "mean"})

支持的聚合函数

通用:count、size、nunique、nth、collect、unique 数值:sum、mean、var、std、median、idxmin、idxmax、min、max、quantile 专用:corr、cov

GroupBy Transform

df.groupby("category").transform("max")  # 结果广播到组内每一行

GroupBy Apply

df.groupby("category").apply(lambda x: x.max() - x.min())

警告:Apply 按组串行执行用户函数,组多且小时会很慢。尽量使用向量化聚合。

JIT 编译的 GroupBy(自定义聚合)

def custom_agg(df):
    return df["value"].max() - df["value"].min() / 2

result = df.groupby("category").apply(custom_agg, engine="jit")

JIT 限制:不支持 null 值,仅支持 int32/64 与 float32/64,不能返回新列。

重要:排序行为差异

cuDF 默认 sort=False(pandas 默认排序)。要与 pandas 一致:

df.groupby("category", sort=True).sum()
# 或全局设置:
cudf.set_option("mode.pandas_compatible", True)

字符串操作

cuDF 通过 .str 访问器提供 GPU 加速的字符串操作,API 与 pandas 完全一致:

s = cudf.Series(["Hello World", "foo bar", "RAPIDS GPU", None])

# 大小写
s.str.lower()
s.str.upper()
s.str.title()
s.str.capitalize()

# 模式匹配
s.str.contains("World")
s.str.startswith("Hello")
s.str.endswith("GPU")
s.str.match(r"^[A-Z]")

# 提取与替换
s.str.extract(r"(\w+)\s(\w+)")
s.str.replace("World", "GPU")
s.str.slice(0, 5)

# 拆分与拼接
s.str.split(" ")
s.str.cat(sep=", ")

# 信息类
s.str.len()
s.str.isalpha()
s.str.isdigit()

# cuDF 独有操作(pandas 没有)
s.str.normalize_spaces()   # 折叠空白
s.str.tokenize()           # 分词
s.str.ngrams(2)            # 生成 n-gram
s.str.edit_distance(other) # Levenshtein 编辑距离
s.str.url_encode()
s.str.url_decode()

用户自定义函数(UDF)

Series.apply() —— JIT 编译

s = cudf.Series([1, 2, 3, 4, 5])

def square_plus_one(x):
    return x ** 2 + 1

s.apply(square_plus_one)  # 经 Numba 编译为 GPU kernel

带参数:

def add_constant(x, c):
    return x + c

s.apply(add_constant, args=(42,))

DataFrame.apply() —— 逐行(axis=1)

def row_func(row):
    return row["a"] + row["b"] * 2

df.apply(row_func, axis=1)  # 通过类似 dict 的语法按列名访问

UDF 中的空值处理

空值自动传播:

s = cudf.Series([1, cudf.NA, 3])
def f(x):
    return x + 1
s.apply(f)  # Returns [2, <NA>, 4]

显式空值判断:

def f(x):
    if x is cudf.NA:
        return 0
    return x + 1

字符串 UDF

字符串 UDF 内部支持:==、!=、>=、<=、startswith()、endswith()、find()、rfind()、count()、in、strip/lstrip/rstrip()、upper/lower()、replace()、+(拼接)、len() 以及布尔判断。

若字符串 UDF 需要创建中间字符串,请为堆分配预留空间:

from cudf.core.udf.utils import set_malloc_heap_size
set_malloc_heap_size(int(2e9))  # 2 GB

滚动窗口 UDF

import math

s = cudf.Series([16, 25, 36, 49, 64, 81], dtype="float64")

def max_sqrt(window):
    result = 0
    for val in window:
        result = max(result, math.sqrt(val))
    return result

s.rolling(window=3, min_periods=3).apply(max_sqrt)

限制:滚动窗口 UDF 不支持 null 值。

直接在 cuDF 列上编写 Numba CUDA Kernel

需要最大控制力时,可以编写直接操作 cuDF 列的 CUDA kernel:

from numba import cuda

@cuda.jit
def gpu_multiply(in_col, out_col, multiplier):
    i = cuda.grid(1)
    if i < in_col.size:
        out_col[i] = in_col[i] * multiplier

df["result"] = 0.0
gpu_multiply.forall(len(df))(df["a"], df["result"], 10.0)

这种"cuDF 处理 DataFrame + Numba 自定义 kernel"的组合,正是仓库决策框架中明确推荐的组合方式之一(decision_framework.md 的 Combining Libraries 一节)。但仓库同时提醒:在剖析证明没有合适的库实现之前,不要投入自定义 kernel。

UDF 限制汇总

  • 仅数值型(非 Decimal)类型支持完整;字符串为部分支持;
  • 不支持 **kwargs;
  • UDF 中未实现位运算;
  • GroupBy JIT:不支持 null,仅 int32/64 与 float32/64,不能返回新列;
  • 滚动窗口 UDF:不支持 null。

缺失数据处理

  • 缺失值用 <NA> 表示(而非 NaN)——cuDF 使用独立的 null 掩码,而非 NaN 哨兵值;
  • 所有 dtype 均可空(包括整型——缺失整型不会被强制转成 float);
  • 向整型列插入 np.nan 会变成 <NA>,且不会发生 float 转换。
s = cudf.Series([1, None, 3, None, 5])

s.isna()                # 布尔掩码
s.notna()
s.fillna(0)             # 标量填充
s.fillna({"a": 0, "b": 1})  # 按列 dict 填充
s.dropna()

# 聚合默认跳过 NA
s.sum()                 # skipna=True(默认)
s.sum(skipna=False)     # 传播 NA

# GroupBy 默认排除 NA 组
df.groupby("a", dropna=False).sum()  # 包含 NA 组

数据类型

类别 类型
整型 int8、int16、int32、int64、uint32、uint64
浮点 float32、float64
时间 datetime64[s/ms/us/ns]
时间差 timedelta[s/ms/us/ns]
类别 CategoricalDtype
字符串 object / string
十进制 Decimal32Dtype、Decimal64Dtype、Decimal128Dtype
列表 ListDtype(嵌套列表)
结构体 StructDtype(类字典)

所有类型均可空。列表列有 .list 访问器(get()、len()、contains()、sort_values()、unique()、concat());结构体列有 .struct 访问器(field()、explode())。

没有承载任意 Python 对象的 object dtype——object dtype 只存储字符串。

内存管理

RMM(RAPIDS 内存管理器)

cuDF 使用 RMM 进行 GPU 内存分配,可根据工作负载配置:

import rmm

# 池分配器(生产环境推荐——避免每次分配的 cudaMalloc 开销)
pool = rmm.mr.PoolMemoryResource(
    rmm.mr.CudaMemoryResource(),
    initial_pool_size="1GiB",
    maximum_pool_size="4GiB"
)
rmm.mr.set_current_device_resource(pool)

# 托管内存(允许数据集大于 GPU 显存)
rmm.mr.set_current_device_resource(rmm.mr.ManagedMemoryResource())

# 托管内存 + 池(两者优点结合)
pool = rmm.mr.PoolMemoryResource(
    rmm.mr.ManagedMemoryResource(),
    initial_pool_size="1GiB"
)
rmm.mr.set_current_device_resource(pool)

让 CuPy 与 Numba 与 RMM 对齐

cuDF 与 CuPy、Numba 混用时,应让所有库使用同一个分配器,避免内存碎片:

# CuPy
from rmm.allocators.cupy import rmm_cupy_allocator
import cupy
cupy.cuda.set_allocator(rmm_cupy_allocator)

# Numba
from rmm.allocators.numba import RMMNumbaManager
from numba import cuda
cuda.set_memory_manager(RMMNumbaManager)

写时复制(Copy-on-Write)

cudf.set_option("copy_on_write", True)
# 或:export CUDF_COPY_ON_WRITE=1

切片、.head()、浅拷贝以及产生视图的方法在其中一个被修改前共享内存。对衍生出大量 DataFrame 的工作流,可显著降低内存占用。

内存剖析

rmm.statistics.enable_statistics()
stats = rmm.statistics.get_statistics()
# 返回:current_bytes, current_count, peak_bytes, peak_count, total_bytes, total_count

互操作性

CuPy(零拷贝)

import cupy as cp

# cuDF → CuPy
arr = df.to_cupy()             # DataFrame → 二维 CuPy 数组
arr = cp.asarray(df["col"])    # Series → 一维 CuPy 数组
arr = df["col"].values         # Series → 一维 CuPy 数组

# CuPy → cuDF
df = cudf.DataFrame(cupy_2d_array)
s = cudf.Series(cupy_1d_array)

# 经 DLPack
df = cudf.from_dlpack(cupy_array.__dlpack__())

Arrow(零拷贝)

arrow_table = df.to_arrow()
df = cudf.DataFrame.from_arrow(arrow_table)

RAPIDS 生态

  • cuML:可直接接收 cuDF DataFrame 用于 ML 管线;
  • cuGraph:接收 cuDF DataFrame 用于图分析(仓库 code_transformation_patterns.md 中即展示了 cudf.read_csv 读入边表后用 G.from_cudf_edgelist 建图);
  • Dask-cuDF:分布式 GPU DataFrame(见下节)。

CUDA Array Interface

cuDF Series 暴露 __cuda_array_interface__,可与任何兼容库(CuPy、Numba、PyTorch 等)零拷贝共享。仓库 SKILL.md 特别提醒:优先使用 CUDA Array Interface 或 DLPack 做零拷贝交换,但仍需验证 device、dtype、连续性、所有权与流语义,不能假设所有转换都免费。

多 GPU:Dask-cuDF

当数据集超出单张 GPU 显存,或需要多 GPU 并行时:

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

# 每张 GPU 一个 worker
cluster = LocalCUDACluster()
client = Client(cluster)

# 从文件读取
ddf = dask_cudf.read_csv("path/*.csv")
ddf = dask_cudf.read_parquet("path/")

# 从 cuDF DataFrame 创建
ddf = dask_cudf.from_cudf(df, npartitions=16)

# 操作(惰性执行——调用 .compute() 才真正执行)
result = ddf.groupby("a").sum().compute()

# 常驻 GPU 内存以便重复访问
ddf = ddf.persist()

与 cuDF 的关键差异:不支持 .iloc;必须调用 .compute() 物化结果;未实现 transpose。

性能优化清单

  1. 先用 cudf.pandas 完成最容易的接入——零代码改动、自动 GPU/CPU 回退。
  2. 追求最大性能再切到原生 cuDF API——避开代理开销与回退拷贝成本。
  3. 优先 Parquet 而非 CSV——列式格式、GPU 读取更快、谓词下推、压缩更好。
  4. 使用 RMM 池分配器——避免逐次 cudaMalloc 的开销。
  5. 开启写时复制——cudf.set_option("copy_on_write", True) 减少切片与视图带来的内存。
  6. 把数据重塑为"长"形态(行多、列少)——GPU 按行并行。
  7. 绝不迭代——只用向量化操作。for row in df.iterrows() 会让 GPU 加速失去意义。
  8. 数据集规模门槛:GPU 在 10,000–100,000+ 行时才真正出彩,小数据集可能 CPU 更快。注意仓库 SKILL.md 同时强调:不要用固定的行数阈值作为"是否值得迁移"的证据,应使用用户实际的数据形状与硬件做基准测试。
  9. 使用向量化字符串操作(.str. 访问器)而非逐行的字符串 UDF。
  10. cuDF 不原生支持的行级数学用 CuPy。
  11. 复杂逐元素操作用 Numba CUDA kernel。
  12. 让所有 RAPIDS 库对齐同一个 RMM 分配器,避免内存碎片。
  13. 分布式场景用 Dask-cuDF 并配合 persist(),让数据常驻 GPU 内存。

与 pandas 的关键差异

  1. 结果顺序默认不确定(groupby、join 等)。用 sort=True 或 cudf.set_option("mode.pandas_compatible", True)。
  2. 所有类型均可空。缺失值为 <NA> 而非 NaN;含缺失值的整型列保持整型(不做 float 强制转换)。
  3. 不支持迭代。for val in series 不可用;确需迭代时先转成 pandas。
  4. 列名必须唯一,不允许重复列名。
  5. 没有任意 Python 对象。object dtype 只存字符串。
  6. .apply() 走 Numba JIT,UDF 内只支持 Python 子集——无任意 Python 对象、无外部库调用。
  7. 浮点结果可能有细微差异,源于 GPU 并行操作顺序不同。应使用基于容差的比较。
  8. GroupBy 默认 sort=False(pandas 默认 sort=True)。
  9. 不支持 pandas 的 ExtensionDtype。

这些行为差异也正是仓库 SKILL.md 强调"在编写代码前先阅读对应库的参考文档——API 名字兼容不代表默认值、dtype、输出类型与支持参数一致"的原因。

常见迁移模式

模式一:零改动(cudf.pandas)

%load_ext cudf.pandas
import pandas as pd
# 其余代码完全保持不变

模式二:直接替换 import

# 之前
import pandas as pd
df = pd.read_csv("data.csv")
result = df.groupby("col").mean()

# 之后
import cudf
df = cudf.read_csv("data.csv")
result = df.groupby("col").mean()

模式三:用向量化替代迭代

# 之前(pandas——即使在 CPU 上也很慢)
for idx, row in df.iterrows():
    df.at[idx, "c"] = row["a"] + row["b"]

# 之后(cuDF)
df["c"] = df["a"] + df["b"]

模式四:用向量化替代 apply()

# 之前
df["result"] = df.apply(lambda row: row["a"] ** 2 + row["b"], axis=1)

# 之后(向量化——快得多)
df["result"] = df["a"] ** 2 + df["b"]

模式五:GPU 计算,边界处转 CPU

# GPU 上加载与处理
gdf = cudf.read_parquet("data.parquet")
result = gdf.groupby("key").agg({"val": "sum"})

# 仅在需要时转成 pandas(绘图、导出等)
pdf = result.to_pandas()
pdf.plot()

模式六:cuDF 不支持的计算交给 CuPy

import cupy as cp

# 对 cuDF 不支持的运算转成 CuPy 处理
arr = df[["x", "y", "z"]].to_cupy()
norms = cp.linalg.norm(arr, axis=1)
df["norm"] = cudf.Series(norms)

配置项汇总

cudf.set_option("copy_on_write", True)            # 开启写时复制
cudf.set_option("mode.pandas_compatible", True)    # 匹配 pandas 行为
cudf.describe_option()                             # 列出全部选项
环境变量 用途
CUDF_COPY_ON_WRITE=1 开启写时复制
CUDF_PANDAS_RMM_MODE 控制 cudf.pandas 的内存分配器
CUDF_PANDAS_FALLBACK_MODE=1 强制 cudf.pandas 纯 CPU 执行

结语

cuDF 为本仓库 optimize-for-gpu 技能覆盖的 pandas 类工作负载提供了"先零改动加速、再按需原生重写"的两级路径:cudf.pandas 适合快速验证与混合代码库,原生 cuDF API 适合生产级最大性能。在动手前,建议先按仓库 SKILL.md 的优化工作流定义数值契约、建立端到端基线,验证语义正确后再做基准对比;对于超出单 GPU 显存的数据,则沿 Dask-cuDF 路径扩展。更多 GPU 库的选型与组合建议,可继续阅读 decision_framework.md 与 installation.md。

登录后查看全文
scientific-agent-skills