cuml-machine-learning

cuML 机器学习技能

使用 NVIDIA RAPIDS cuML 进行 GPU 加速的机器学习。cuML 提供了与 scikit-learn 兼容的 API，可在 NVIDIA GPU 上运行，从而在大规模数据集上实现显著的加速。

何时使用此技能

在以下情况使用此技能：

• 训练分类模型（预测类别、检测欺诈、对文本进行分类）
• 训练回归模型（预测数值、预测价格、估计数量）
• 对数据进行聚类（客户分群、文档分组、发现模式）
• 降维（可视化高维数据、压缩特征）
• 对大型数据集进行预处理和特征工程
• 任何涉及 10K 行以上数据集的机器学习任务，其中 GPU 加速有益

初始化（必需）

始终在每个脚本的开头使用以下样板代码。它会测试实际的 GPU 机器学习操作。

import pandas as pd
import numpy as np

try:
    import cudf
    import cuml
    # 冒烟测试：验证端到端的 GPU 机器学习功能
    _test_data = cudf.DataFrame({'a': [1.0, 2.0, 3.0, 4.0], 'b': [5.0, 6.0, 7.0, 8.0]})
    _km = cuml.cluster.KMeans(n_clusters=2, n_init=1, random_state=42)
    _km.fit(_test_data)
    assert len(_km.labels_) == 4
    GPU = True
except Exception as e:
    print(f"[GPU] cuml 不可用，回退到 scikit-learn：{e}")
    GPU = False

def read_csv(path):
    return cudf.read_csv(path) if GPU else pd.read_csv(path)

def to_pd(df):
    """将 cuML/cuDF 输出转换为 pandas。使用此函数代替直接调用 .to_pandas()。"""
    if not GPU:
        return df
    try:
        return df.to_pandas()
    except Exception as e:
        print(f"[GPU] .to_pandas() 失败，使用 Arrow 回退：{e}")
        return df.to_arrow().to_pandas()

导入模式

# GPU 模式
if GPU:
    from cuml.cluster import KMeans, DBSCAN, HDBSCAN
    from cuml.ensemble import RandomForestClassifier, RandomForestRegressor
    from cuml.linear_model import LinearRegression, Ridge, Lasso, LogisticRegression
    from cuml.neighbors import KNeighborsClassifier, KNeighborsRegressor
    from cuml.svm import SVC, SVR
    from cuml.decomposition import PCA, TruncatedSVD
    from cuml.manifold import UMAP, TSNE
    from cuml.preprocessing import StandardScaler, MinMaxScaler, LabelEncoder
    from cuml.model_selection import train_test_split
    from cuml.metrics import accuracy_score, r2_score, mean_squared_error
# CPU 回退
else:
    from sklearn.cluster import KMeans, DBSCAN, HDBSCAN
    from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
    from sklearn.linear_model import LinearRegression, Ridge, Lasso, LogisticRegression
    from sklearn.neighbors import KNeighborsClassifier, KNeighborsRegressor
    from sklearn.svm import SVC, SVR
    from sklearn.decomposition import PCA, TruncatedSVD
    from sklearn.manifold import TSNE
    from sklearn.preprocessing import StandardScaler, MinMaxScaler, LabelEncoder
    from sklearn.model_selection import train_test_split
    from sklearn.metrics import accuracy_score, r2_score, mean_squared_error
    # UMAP 不在 sklearn 中 — 跳过或使用 pip install umap-learn

快速参考

训练/测试集划分（从这里开始）

X = df[["feature1", "feature2", "feature3"]].astype("float32")
y = df["target"]

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

分类

model = RandomForestClassifier(n_estimators=100, max_depth=10, random_state=42)
model.fit(X_train, y_train)

predictions = model.predict(X_test)
accuracy = float(accuracy_score(to_pd(y_test), to_pd(predictions)))
print(f"准确率：{accuracy:.4f}")

# 特征重要性（仅适用于树模型）
importances = to_pd(model.feature_importances_)
for name, imp in zip(feature_names, importances):
    print(f"  {name}：{imp:.4f}")

回归

model = Ridge(alpha=1.0)
model.fit(X_train, y_train)

predictions = model.predict(X_test)
r2 = float(r2_score(to_pd(y_test), to_pd(predictions)))
mse = float(mean_squared_error(to_pd(y_test), to_pd(predictions)))
print(f"R² 分数：{r2:.4f}")
print(f"MSE：{mse:.4f}")

# 系数
coeffs = to_pd(model.coef_)
print(f"截距：{float(model.intercept_):.4f}")

聚类（KMeans）

X = df[["feature1", "feature2"]].astype("float32")

model = KMeans(n_clusters=4, n_init=10, random_state=42)
model.fit(X)

labels = to_pd(model.labels_)
centroids = to_pd(model.cluster_centers_)
inertia = float(model.inertia_)

print(f"惯性：{inertia:.2f}")
print(f"簇大小：{labels.value_counts().sort_index().to_dict()}")
print(f"质心：\n{centroids}")

降维（PCA）

scaler = StandardScaler()
X_scaled = scaler.fit_transform(X.astype("float32"))

pca = PCA(n_components=3)
X_reduced = pca.fit_transform(X_scaled)

variance_ratio = to_pd(pca.explained_variance_ratio_)
print(f"解释方差：{[f'{v:.4f}' for v in variance_ratio]}")
print(f"总解释方差：{float(sum(variance_ratio)):.4f}")

降维（UMAP — 仅 GPU）

if GPU:
    reducer = UMAP(n_components=2, n_neighbors=15, min_dist=0.1, random_state=42)
    embedding = to_pd(reducer.fit_transform(X_scaled))
    print(f"UMAP 嵌入形状：{embedding.shape}")

预处理

# 缩放数值特征
scaler = StandardScaler()
X_scaled = scaler.fit_transform(X.astype("float32"))

# 编码分类列
le = LabelEncoder()
df["category_encoded"] = le.fit_transform(df["category"])

数据类型要求

• cuML 要求特征为 float32 或 float64。始终进行强制类型转换：X.astype("float32")
• 整数目标（分类标签）可直接使用
• 分类列必须先进行编码（LabelEncoder 或 OneHotEncoder）
• cuML 不支持稀疏矩阵 — 始终使用稠密数据

常见问题

问题	解决方法
TypeError: sparse input	转换为稠密矩阵：X.toarray() 或避免使用稀疏数据
PCA solver='randomized' 失败	使用 solver='full' 或省略（cuML 会自动选择）
UMAP 在 CPU 上不可用	在 CPU 模式下跳过 UMAP，或使用 pip install umap-learn
Float64 比 float32 慢	转换为 float32：X.astype("float32")
大型数据集内存不足	减少特征数量或在拟合前对数据进行采样

输出指南

报告机器学习结果时：

• 包含数据集形状（行数 × 特征数）和目标分布
• 显示训练/测试集划分大小
• 以格式化表格报告关键指标（准确率、R²、MSE 等）
• 对于分类任务：如果是多分类，显示每个类别的指标
• 对于聚类任务：显示簇大小和质心摘要
• 对于降维任务：显示解释方差比
• 按重要性排序列出特征重要性
• 注意任何数据质量问题（类别不平衡、缺失值、异常值）