直接用 cudf 替换 pandas 报 AttributeError 是因 cudf 不提供顶层 DataFrame 导入路径，须用 cudf.DataFrame；且 API 不完全兼容，如无 .to_numpy()、无 .apply(axis=1)、字符串操作受限、groupby.apply 不支持自定义函数等。
为什么直接用 cudf 替换 pandas 会报 AttributeError: module 'cudf' has no attribute 'DataFrame'
因为 cudf 的 API 并非 100% 兼容 pandas，最典型的是：它不提供顶层 DataFrame 类的直接导入路径。你写 from cudf import DataFrame 会失败，正确写法是 import cudf 后用 cudf.DataFrame。
常见错误还包括误调用 pandas 特有方法（如 .to_numpy()、.values），cudf 返回的是 GPU 上的 cudf.Series 或 cudf.DataFrame，底层是 cupy 数组，不能直接当 numpy 用。
- 初始化必须显式用
cudf.DataFrame(...)，不能靠pd.DataFrame(...).to_cudf()（这方法根本不存在） - 读 CSV 要用
cudf.read_csv()，不是pd.read_csv().to_cudf() - 字符串操作（如
.str.contains()）支持有限，正则引擎不同，部分 flag 不生效
哪些 pandas 操作在 cudf 中实际会变慢甚至崩溃
cudf 对“列式计算”友好，但对“逐行逻辑”或“高分支条件”极度不友好。比如 .apply(lambda x: ...) 在 cudf 中默认走 CPU 回退（fallback），性能可能比 pandas 还差；若强行用 axis=1，会触发 full-copy 到 host 再计算，GPU 优势彻底消失。
-
.apply(func, axis=1)—— 绝对避免，改用向量化表达式（cudf.Series.where()、cudf.DataFrame.assign()配合布尔索引） -
.groupby(...).apply(...)—— cudf 目前仅支持聚合类函数（'sum','mean'），自定义函数基本不可用 -
.merge()大表 join 时若 key 有 null，可能触发隐式 CPU fallback，建议先.dropna()或用how='inner' -
.sort_values()在字符串列上比 pandas 慢，因 cuDF 的字符串字典编码开销大
如何安全地把 pandas 代码迁移到 cudf（保留调试能力）
不要全量替换。推荐用“接口抽象层”方式过渡：封装一个 df_lib 变量，在顶部控制使用 pandas 还是 cudf，所有构造、IO、计算都通过它调用。这样能快速对比结果一致性，也方便定位哪步出问题。
立即学习“Python免费学习笔记（深入）”；
import os
DF_LIB = cudf if os.environ.get("USE_GPU") else pd
<p>df = DF_LIB.read_csv("data.csv")
df = df[df.x > 0] # 这种布尔索引两边行为一致
result = df.groupby("cat").y.sum() # 聚合也基本兼容
关键点：
- 所有
df.调用必须限定在 cudf 支持的方法子集内（查 cudf docs 的 “API Coverage” 表） - 涉及 dtype 转换（如
.astype('category')）要小心：cudf 的 category 是整数编码，和 pandas 语义不同，.cat.categories不可用 - 调试时加
assert df.to_pandas().equals(expected_pd_df)，但注意.to_pandas()是同步拷贝，大数据慎用
GPU 显存不足时，cudf 报 RMM_ERROR_OUT_OF_MEMORY 怎么办
cudf 默认使用 RAPIDS Memory Manager（RMM）统一管理 GPU 显存，但它不会自动释放中间对象——Python 的 del df 不等于 GPU 显存回收。必须显式调用 gc.collect() + rmm.reinitialize() 才能清空。
- 启动时预分配：用
rmm.reinitialize(pool_allocator=True, initial_pool_size=2（2GB 池）避免碎片 - 每轮大计算后加
import gc; gc.collect()，再检查rmm.get_current_device_resource().get_mem_info() - 读大文件别用
cudf.read_csv()一次性加载，改用dask_cudf分块，或先用 pandas 采样确认 schema，再指定dtype减少显存占用 - 字符串列最吃显存，能转成
category就转，但注意 cudf 的category不支持.cat.codes直接取码，得用.factorize()
cudf 不是“开箱即速”的 pandas 替代品，它的加速收益高度依赖数据形态和操作类型。最容易被忽略的是：字符串处理、复杂 groupby、任意 apply 这三类操作，GPU 不仅不快，还可能因隐式 CPU fallback 导致整体更慢。上线前务必用真实数据集做端到端 time & memory profile。
