cuML Notebooks 实战指南用官方示例快速上手 GPU 加速机器学习RAPIDS cuML【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cuml本文以 NVIDIA cuML 仓库中notebooks/目录的官方示例为主线系统梳理这些自包含self-containedNotebook 的定位、运行环境、逐篇技术要点与底层实现路径覆盖时间序列ARIMA、聚类K-Means、回归线性回归、最近邻、随机森林与目标编码Target Encoding等 cuML 核心能力。读完本文你将掌握如何借助官方 Notebook 快速验证 cuML 的 API 用法、GPU 与 CPU 结果对比方法以及多节点多 GPUMNMG场景下的 Dask 编程范式并知道每条示例背后对应的源码与数据文件便于进一步深入阅读。一、Notebooks 目录的定位官方示例的活文档cuML 仓库在 notebooks/README.md 中明确说明了这批 Notebook 的设计目标它们提供 cuML 的使用示例且设计为完全自包含self-contained——即不依赖外部下载的数据集或网络服务可在RAPIDS Docker 容器runtime 版本以及 RAPIDS Nightly Docker 容器中直接运行甚至能在离线air-gapped系统上运行。容器本身已内置 cuML、cuDF、cuPy 等依赖这也是自包含能成立的前提。围绕这批 Notebook仓库还配套了完整的测试与数据支撑数据文件集中在 notebooks/data/ 下time_series/存放 ARIMA 演示用的三个 CSVpopulation_estimate.csv、net_migrations_auckland_by_age.csv、guest_nights_by_region.csvweather/存放 NOAA 气象数据noaa_rdu.csv另有mortgage.npy.gz与fashion/目录MNIST 风格的手写数字数据CI 脚本 ci/test_notebooks.sh 与 ci/utils/nbtest.sh、ci/utils/nbtestlog2junitxml.py 负责以可重复的方式执行这些 Notebook 并将日志转换为 JUnit XML 格式保证示例可用这一状态是持续被验证的而非口头承诺。从源码结构看这些 Notebook 覆盖的功能模块均有对应的 Python 封装与 C 内核实现例如python/cuml/cuml/cluster/kmeans.pyx、python/cuml/cuml/tsa/arima.pyx、python/cuml/cuml/ensemble/randomforestclassifier.py等具体对应关系见下文各节。二、快速上手入门 Notebook 与运行环境2.1 入门指引notebooks/README.md明确指出想要快速了解 cuML 的整体工作方式请先看文档树中的入门 Notebook docs/source/estimator_intro.ipynb即 Training and Evaluating Machine Learning Models。这个 Notebook 以合成数据为载体串起了 cuML 最常用的四个基础场景任务类型模型配套评估指标用到的 cuML API分类Random Forest Classifieraccuracy_scorecuml.ensemble.RandomForestClassifier、cuml.datasets.classification.make_classification、cuml.model_selection.train_test_split降维/可视化UMAPtrustworthinesscuml.manifold.umap.UMAP、cuml.datasets.make_blobs聚类DBSCANadjusted_rand_scorecuml.cluster.dbscan.DBSCAN、cuml.datasets.make_blobs、cuml.metrics.cluster.adjusted_rand_score回归Linear Regressionr2_scorecuml.linear_model.LinearRegression、cuml.datasets.make_regression、cuml.metrics.r2_score例如其中分类部分的典型调用方式from cuml.datasets.classification import make_classification from cuml.ensemble import RandomForestClassifier from cuml.metrics import accuracy_score from cuml.model_selection import train_test_split X, y make_classification(n_classes2, n_features10, n_samples1000, random_state0) X_train, X_test, y_train, y_test train_test_split(X, y, random_state0) clf RandomForestClassifier(n_estimators50, random_state0).fit(X_train, y_train) print(accuracy_score(y_test, clf.predict(X_test)))这一篇适合作为零基础读者进入 cuML 的第一站它展示了 cuML 与 scikit-learn 高度相似的fit / predict / score心智模型。2.2 运行环境前提推荐使用 RAPIDS 官方 Docker 容器的runtime版本README 中也提到了 Nightly 容器容器内已预装 cuML、cuDF、cuPy 与配套的 Dask 生态若需在本地手动搭建可参考仓库根目录的 BUILD.md 与 conda/environments/ 下的环境定义按 CUDA 版本与架构区分如all_cuda-129_arch-x86_64.yaml、all_cuda-133_arch-aarch64.yaml等部分 Notebook如线性回归示例对 GPU 显存有明确要求具体见下文对应小节。三、Notebook 总览从时间序列到多 GPU 分布式notebooks/README.md以表格形式给出了各 Notebook 的标题、状态与描述。下表在继承原表全部信息的基础上补充了各示例的核心 API 与关键知识点Notebook状态描述核心 API / 主题arima_demo.ipynbWorking使用 ARIMA 对时间序列数据进行预测cuml.tsa.arima.ARIMA非季节/季节模型、置信区间、缺失值、外生变量kmeans_demo.ipynbWorking用 k-means 预测并与 Scikit-learn 的 k-means 可视化对比cuml.cluster.KMeansk-means||初始化vssklearn.cluster.KMeansk-meanskmeans_mnmg_demo.ipynbWorking使用 Dask 分布式输入进行多节点多 GPUMNMGk-means 预测cuml.dask.cluster.kmeans.KMeans、LocalCUDAClusterlinear_regression_demo.ipynbWorking演示使用 OLS 线性回归进行预测cuml.linear_model.LinearRegressionalgorithmeig、r2_scorenearest_neighbors_demo.ipynbWorking使用最近邻算法进行预测cuml.neighbors.NearestNeighbors基于 FAISS单精度random_forest_demo.ipynbWorking使用随机森林分类并演示如何 pickle cuML 模型cuml.ensemble.RandomForestClassifier、pickle序列化random_forest_mnmg_demo.ipynbWorking使用 MNMG 随机森林解决分类问题cuml.dask.ensemble.RandomForestClassifiertarget_encoder_walkthrough.ipynbWorking借助 criteo 数据集理解目标编码为何优于 one-hot 与 label 编码cuml.preprocessing.TargetEncodern_folds、smooth、split_method需要说明的是原 README 表格中还列出了 Forest Inference Demo将 XGBoost 模型保存/加载到 FIL 中推理但该forest_inference_demo.ipynb未包含在当前仓库快照中因此上表未给出其链接感兴趣的读者可以关注 RAPIDS 社区维护的扩展 Notebook 集合。四、逐篇技术导读与源码印证4.1 时间序列ARIMA 预测arima_demo.ipynb这是notebooks/目录下最完整的一篇示例527 行完整覆盖了 cuML ARIMA 的核心能力。其数据来自 notebooks/data/time_series/ 下的三个 CSVnet_migrations_auckland_by_age.csv奥克兰分年龄净迁移、population_estimate.csv人口估计、guest_nights_by_region.csv分地区过夜人次。CSV 的约定是序列按列存放、首列为日期、首行为变量名。1非季节模型ARIMA(p,d,q)模型由三部分组成差分Integrated差分d次直至平稳、自回归AR用p个历史值回归、移动平均MA用q个历史误差项回归并可选拟合常数项截距。示例先是简单的 MA(2)from cuml.tsa.arima import ARIMA # q2 且带截距输入可以是 cuDF DataFrame 或 array-likehost/device 均可 model_mig ARIMA(df_mig, order(0, 0, 2), fit_interceptTrue) model_mig.fit() fc_mig model_mig.forecast(10) # 未来 10 步预测随后是ARIMA(1,2,1)示例由于人口数据存在二次趋势一次差分不足以使其平稳故取d2并同时演示样本内预测与样本外预测model_pop ARIMA(df_pop, order(1, 2, 1), fit_interceptTrue) model_pop.fit() pred_pop model_pop.predict(80, 160) # 样本内 样本外混合预测2置信区间指定置信水平如 95%即可获得预测区间forecast返回预测值、下界、上界三元组fc_pop, lower_pop, upper_pop model_pop.forecast(23, level0.95)3季节模型ARIMA(p,d,q)(P,D,Q)s季节模型额外引入季节自回归SAR与季节移动平均SMA分量可对数据施加一次或二次季节差分也可将非季节差分与季节差分组合使用注意约束pP 2。示例对月度的guest_nights_by_region数据明显 12 期年周期 非季节趋势拟合ARIMA(1,1,1)(1,1,1)12model_guests ARIMA(df_guests, order(1, 1, 1), seasonal_order(1, 1, 1, 12), fit_interceptFalse) model_guests.fit() fc_guests model_guests.forecast(40)4缺失观测ARIMA 支持数据中的缺失观测也可在序列开头补NaN以实现不同长度序列的批量计算。注意缺失值必须以NaN表示df.fillna(np.nan)且在序列开头补齐的位置无法形成预测无截距时该处预测值恒为 0。5外生变量exogenous variables由于模型是批量batch工作的外生变量存在明确约束endog的每一列对应exog的固定列数外生变量不能在序列间共享需要时需复制所有序列必须有相同数量的外生变量。exog的形状必须为(n_obs, batch_size * n_exog)列按 batch id 分组预测/forecast 时需提供形状为(nsteps, batch_size * n_exog)的未来外生变量值。此外内生变量可含缺失值外生变量不可。实现层面ARIMA的 Python 封装位于 python/cuml/cuml/tsa/arima.pyx底层 C 内核在 cpp/src/arima/arima_common.cu、batched_arima.cu、batched_kalman.cu采用批量卡尔曼滤波估计专门针对大批量时间序列场景做了性能设计相关测试见 python/cuml/cuml/tests/test_arima.py注测试文件实际位于python/cuml/tests/目录树仓库中以python/cuml/tests/test_arima.py为准。4.2 聚类K-Means 单 GPU 与 MNMGkmeans_demo / kmeans_mnmg_demo单 GPU 版 notebooks/kmeans_demo.ipynb的亮点开篇提供了一个可选的线程安全配置 Cell在 CPU 核数很多的机器上OpenBLAS 等 BLAS 库可能过度创建线程导致资源争用甚至挂起。该 Cell 通过设置OPENBLAS_NUM_THREADS1、OMP_NUM_THREADS1、MKL_NUM_THREADS1与JOBLIB_MULTIPROCESSING0将后端限制为单线程必须在导入 numpy/sklearn 之前执行使用cuml.datasets.make_blobs在 GPU 上生成 10 万样本、25 维、8 个簇的数据并说明输入可以是 NumPyhost、Numba/cuda_array_interface 兼容数组device或 cuDF DataFrame对比实验scikit-learn 用k-means初始化cuML 用k-means||可扩展的 k-means 初始化比随机选点更稳定用adjusted_rand_score对比标签一致性阈值1e-4kmeans_cuml cuKMeans(initk-means||, n_clusters8, random_state0) kmeans_cuml.fit(device_data) cuml_score adjusted_rand_score(host_labels, kmeans_cuml.labels_.get())可视化部分把 sklearn 的中心点蓝色实心圆与 cuML 的中心点红色空心圆叠加在散点图上Notebook 也提示由于两种初始化策略不同中心点未必完全一致。MNMG 版 notebooks/kmeans_mnmg_demo.ipynb的亮点cuML 的 MNMG 实现采用One Process Per GPUOPG布局每个 Dask worker 对应一块 GPU用LocalCUDACluster(threads_per_worker1)单机即可拉起与单 GPU 版的差异在于每次迭代可并行执行仅在各迭代间共享中心点同样支持可扩展的 k-means 初始化输入必须是 Dask DataFrame 或 Dask Arraypredict()/transform()返回与输入相同的类型Dask cuDF / Dask cuPy数据生成用cuml.dask.datasets.make_blobs对比基准用dask_ml.cluster.KMeans因为 sklearn 没有 MNMG 等价实现同样以adjusted_rand_score判定是否一致期望 1.0。实现层面单 GPU 封装在 python/cuml/cuml/cluster/kmeans.pyxMNMG 封装在 python/cuml/cuml/dask/cluster/kmeans.pyC 内核位于 cpp/src/kmeans/kmeans_fit.cu、kmeans_predict.cu、kmeans_transform.cu对应测试为 python/cuml/tests/test_kmeans.py 与 cpp/tests/mg/kmeans_test.cu。4.3 回归OLS 线性回归linear_regression_demo.ipynbnotebooks/linear_regression_demo.ipynb 演示最基础的 OLS 线性回归响应变量y是预测变量X的线性组合。关键要点显存注意事项Notebook 顶部明确提示默认n_samples 2**20约 105 万在显存低于 16GB 的 GPU 上可能 OOM需改为2**19数据生成cuml.make_regression生成 399 维特征转成 cuDF DataFrame 后用cuml.train_test_split划分test_size0.2并拷贝一份 Pandas 版本供 sklearn 使用对比实验sklearn 用fit_interceptTrue, n_jobs-1cuML 用cuLinearRegression(fit_interceptTrue, algorithmeig)特征值分解求解最后用cuml.metrics.regression.r2_score对比 R² 分数ols_cuml cuLinearRegression(fit_interceptTrue, algorithmeig) ols_cuml.fit(X_cudf, y_cudf) predict_cuml ols_cuml.predict(X_cudf_test) r2_score_cuml r2_score(y_cudf_test, predict_cuml)实现层面封装在 python/cuml/cuml/linear_model/linear_regression.pyxC 实现位于 cpp/src/glm/glm.cu配合ols.cuh求解算法支持 eig 等选项测试见 python/cuml/tests/test_linear_regression.py 与 cpp/tests/sg/ols.cu。4.4 最近邻Nearest Neighborsnearest_neighbors_demo.ipynbnotebooks/nearest_neighbors_demo.ipynb 演示从一组输入样本中查询 k 近邻。参数规模为n_samples2**17、n_features40、n_query2**13、n_neighbors4。对比实验knn_sk skNearestNeighbors(algorithmbrute, n_jobs-1) knn_sk.fit(host_data) D_sk, I_sk knn_sk.kneighbors(host_data[:n_query], n_neighbors) knn_cuml cuNearestNeighbors() knn_cuml.fit(device_data) D_cuml, I_cuml knn_cuml.kneighbors(device_data[:n_query], n_neighbors)Notebook 明确指出一个精度差异根源cuML 当前使用 FAISS 进行精确最近邻搜索输入被限制为单精度float32当不同数量级的浮点数相加时可能出现舍入误差因此 cuML 结果很可能无法与 sklearn 的精确结果逐位一致。验证方式因此采用宽松比较距离用np.allclose(..., atol1e-3)索引按行排序后统计不一致比例 1e-9。实现层面封装在 python/cuml/cuml/neighbors/nearest_neighbors.pyx底层使用 FAISS见 cpp/src/knn/knn.cu相关测试见 python/cuml/tests/test_nearest_neighbors.py。4.5 随机森林训练、评估与 Pickle 序列化random_forest_demo.ipynbnotebooks/random_forest_demo.ipynb 的主题是随机森林 模型持久化随机森林通过构建多棵决策树并聚合输出来分类Notebook 特别提示cuML 的树节点分裂底层算法与 scikit-learn 不同因此两者结果会存在差异数据集make_classification生成n_samples2**12、n_features399、n_informative300的二分类数据注释中提示把n_samples调大如2**17可看到 cuML 更明显的加速cuML 的随机森林分类器要求标签为整数astype(np.int32)参数对齐两侧均使用n_estimators40, max_depth16, max_features1.0, random_state10Pickle 演示含安全警告只能反序列化可信来源的 pickle 数据filename cuml_random_forest_model.sav pickle.dump(cuml_model, open(filename, wb)) del cuml_model # 删除原模型避免指针泄漏仅为演示 pickled_cuml_model pickle.load(open(filename, rb)) pred_after_pickling pickled_cuml_model.predict(X_cudf_test)最后对比三个准确率sklearn、pickle 前的 cuML、pickle 后的 cuML。实现层面封装在 python/cuml/cuml/ensemble/randomforestclassifier.py与randomforest_common.pyx配合C 位于 cpp/src/randomforest/测试见 python/cuml/tests/test_random_forest.py 与 cpp/tests/sg/rf_test.cu。关于 cuML 模型持久化的更多细节文档树中还有专门的 docs/source/pickling_cuml_models.ipynb 可供延伸阅读。4.6 随机森林 MNMGDask 分布式训练random_forest_mnmg_demo.ipynbnotebooks/random_forest_mnmg_demo.ipynb 展示了实验性的多节点多 GPU 随机森林其原理是易并行embarrassingly parallel——若随机森林共有N棵树、由W个 worker 拟合则每个 worker 建N/W棵树推理时合并全部N棵树的预测。Notebook 强调调用方负责通过 Dask 高效分区数据确保每个 worker 拥有有代表性的数据分块可通过均匀分布数据实现。关键实践启动集群LocalCUDACluster(threads_per_worker1)Client(cluster)用c.has_what()查询 worker 数量与列表参数train_size100000、max_depth12、n_bins16、n_trees1000并提示n_streams8作为性能优化项Notebook 注释指出除样本数外列数与max_depth对拟合性能影响最大降低max_depth可大幅加速但可能损失精度数据分区将 cuDF DataFrame 通过dask_cudf.from_cudf(..., npartitionsn_workers)分给各 workerNotebook 同时提示也可用dask_cudf.read_csv()直接在 worker 上加载数据k-means MNMG notebook 则展示了在 worker 上生成数据的替代方式异步训练cuml_model.fit(X_train_dask, y_train_dask)后用wait(cuml_model.rfs)等待异步训练任务完成结果对比与 sklearnn_jobs-1多核对比准确率且提示由于算法随机性精度可能略有波动。实现层面MNMG 封装位于 python/cuml/cuml/dask/ensemble/相关测试见 python/cuml/tests/dask/ 下的随机森林测试。关于 MNMG 的更多通用知识可参考文档树中的 docs/source/dask_multigpu_guide.ipynb。4.7 目标编码Target Encoding 设计详解target_encoder_walkthrough.ipynbnotebooks/target_encoder_walkthrough.ipynb 是这批示例中篇幅最长672 行、概念最完整的一篇它从零推导目标编码的设计动机与优化路径并给出三个关键结论编码时使用 ground truth 列target作为输入训练数据与测试数据的变换方式不同支持多列联合变换。动机以 criteo 点击率CTR建模数据集为背景仅用 3 个类别特征。原始类别是字符串需要编码为什么不用 one-hot类别基数cardinality极高示例中cat_0/1/2的 unique 数量达到数十万量级one-hot 会导致巨大内存消耗或极高稀疏度在 GPU 上优化不佳为什么纯 label encoding 不够字符串到整数的映射是任意的编码后数值的接近程度不代表类别语义相似性。文中以cat_2前三行9218, 5875, 5199为例说明5875虽比9218更接近5199但并不能保证对应字符串更相似树模型需要多次分裂才能学习这种编码中的模式用 label encoding 特征训练 XGBoostmax_depth6, learning_rate0.1, eval_metricauc, tree_methodhist, devicecuda验证 AUC 约 0.60为后续目标编码提供基线。目标编码的核心思想将类别列按每个取值分组的target均值编码即 pandas 语义下的df.groupby(fea)[target].transform(mean)。三个递进实现朴素实现naive直接对全量训练数据groupby-agg-merge求label均值。结果验证 AUC 反而未提升且训练 AUC0.84与验证 AUC0.63差距悬殊——原因是训练特征直接使用了 ground truth严重过拟合无法泛化K 折交叉验证实现FOLDS10将训练数据分折用排除当前折的其余数据计算均值来编码当前折样本使样本自身的 ground truth 不参与其编码特征生成而验证数据仍使用全量训练数据的组均值。Notebook 强调训练/验证数据的编码方式不同因此不能像LabelEncoder那样对两类数据使用完全相同的transform调用。此实现将验证 AUC 提升到约 0.70优化实现TargetEncoder针对 for 循环版本的两处不足做优化——①一次性计算编码而非逐折 for 循环②支持单列或多列联合编码③引入平滑smoothing避免低频取值使编码失真④同时支持单 GPU 与多 GPU。Notebook 的基准显示优化实现比 for 循环版本约快 6 倍且可能快至 10 倍精度也略有提升验证 AUC 约 0.704。多列联合编码除逐列编码外还可以把多列组合成一个新特征例如[cat_0,cat_1]、[cat_0,cat_1,cat_2]这对某些数据集可能带来增益。核心用法from cuml.preprocessing.TargetEncoder import TargetEncoder encoder TargetEncoder(n_foldsFOLDS, smooth0.001, split_methodinterleaved) train[out_col] encoder.fit_transform(train[cols], train[label]) valid[out_col] encoder.transform(valid[cols])实现层面TargetEncoder的源码位于 python/cuml/cuml/preprocessing/_target_encoder.pyLabelEncoder则在label.py测试见 python/cuml/tests/test_target_encoder.py。五、仓库中的其他相关 Notebook 与工具除notebooks/目录外仓库还在其他位置提供了互补的 Notebook 资源文档树中的示例除了入门用的 docs/source/estimator_intro.ipynb 外还有 docs/source/dask_multigpu_guide.ipynb多 GPU 使用指南与 docs/source/pickling_cuml_models.ipynb模型持久化专题基准测试工具notebooks/tools/cuml_benchmarks.ipynb 提供算法基准测试入口notebooks/tools/hdbscan_soft_clustering_benchmark.ipynb 则聚焦 HDBSCAN 软聚类CI 用示例ci/notebooks/XGboost_Demo.ipynb 展示了在 RAPIDS 环境下用xgb.QuantileDMatrix直方图树方法专用的内存高效数据结构在 GPU 上训练 XGBoost 的完整流程与target_encoder_walkthrough中的 XGBoost 用法可互相印证数据资产notebooks/data/time_series/、notebooks/data/weather/、notebooks/data/fashion/ 与notebooks/data/mortgage.npy.gz共同构成这些自包含 Notebook 的离线数据基础。六、质量保障Notebook 的可复现测试机制notebooks/README.md将各示例标注为 Working 状态这一状态由 CI 持续保障。仓库中的相关脚本包括ci/test_notebooks.shNotebook 测试的顶层入口ci/utils/nbtest.sh执行单个 Notebook 的测试脚本ci/utils/nbtestlog2junitxml.py将测试日志转换为 JUnit XML便于集成到 CI 报告体系。这意味着如果你想在自己环境中复现某个示例直接按 Notebook 的 Cell 顺序执行即可而官方示例可用这一承诺是有自动化测试背书的这也正是以notebooks/README.md为入口、按图索骥学习 cuML 的可靠性所在。七、总结与延伸阅读notebooks/目录及其 README 构成了 cuML 的官方示例地图从单 GPU 的 ARIMA、K-Means、线性回归、最近邻、随机森林到基于 Dask 的 MNMG 版本再到概念深入的目标编码专题覆盖了 cuML 最常用的监督学习、无监督学习与时间序列能力。建议的学习路径是先运行入门 Notebook docs/source/estimator_intro.ipynb 建立整体认知再按业务需求挑选对应专题深入对比 sklearn 的 CPU 结果与 cuML 的 GPU 结果注意 FAISS 单精度、初始化策略差异等已知差异点是理解两者行为差异的高效方式。需要进一步深入时可回到各节列出的 Python 封装python/cuml/cuml/下的*.pyx/*.py与 C 内核cpp/src/源码并参考 python/cuml/tests/ 与 cpp/tests/ 中的测试用例验证行为社区维护的更多扩展示例也可在 RAPIDS 的 notebooks-contrib 仓库中找到该仓库由社区维护未包含在当前仓库中。【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cuml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考