使用 cuDF 在 GPU 上加速 pandas 表格计算:从 cudf.pandas 零改动加速到原生 GPU DataFrame API
使用 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。
性能优化清单
- 先用 cudf.pandas 完成最容易的接入——零代码改动、自动 GPU/CPU 回退。
- 追求最大性能再切到原生 cuDF API——避开代理开销与回退拷贝成本。
- 优先 Parquet 而非 CSV——列式格式、GPU 读取更快、谓词下推、压缩更好。
- 使用 RMM 池分配器——避免逐次
cudaMalloc的开销。 - 开启写时复制——
cudf.set_option("copy_on_write", True)减少切片与视图带来的内存。 - 把数据重塑为"长"形态(行多、列少)——GPU 按行并行。
- 绝不迭代——只用向量化操作。
for row in df.iterrows()会让 GPU 加速失去意义。 - 数据集规模门槛:GPU 在 10,000–100,000+ 行时才真正出彩,小数据集可能 CPU 更快。注意仓库 SKILL.md 同时强调:不要用固定的行数阈值作为"是否值得迁移"的证据,应使用用户实际的数据形状与硬件做基准测试。
- 使用向量化字符串操作(
.str.访问器)而非逐行的字符串 UDF。 - cuDF 不原生支持的行级数学用 CuPy。
- 复杂逐元素操作用 Numba CUDA kernel。
- 让所有 RAPIDS 库对齐同一个 RMM 分配器,避免内存碎片。
- 分布式场景用 Dask-cuDF 并配合
persist(),让数据常驻 GPU 内存。
与 pandas 的关键差异
- 结果顺序默认不确定(groupby、join 等)。用
sort=True或cudf.set_option("mode.pandas_compatible", True)。 - 所有类型均可空。缺失值为
<NA>而非 NaN;含缺失值的整型列保持整型(不做 float 强制转换)。 - 不支持迭代。
for val in series不可用;确需迭代时先转成 pandas。 - 列名必须唯一,不允许重复列名。
- 没有任意 Python 对象。
objectdtype 只存字符串。 .apply()走 Numba JIT,UDF 内只支持 Python 子集——无任意 Python 对象、无外部库调用。- 浮点结果可能有细微差异,源于 GPU 并行操作顺序不同。应使用基于容差的比较。
- GroupBy 默认
sort=False(pandas 默认sort=True)。 - 不支持 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。