📚 课程目录第2章环境搭建

2. 环境搭建：CUDA、cuDF、cuML安装归纳总结

环境搭建这步，说白了就是给你的机器装上RAPIDS的“心脏”和“手脚”。

很多人在这卡住，不是因为代码难，而是版本没对齐。我当初刚接触cuML时，也栽过跟头——明明按教程装了，跑起来就是报错“driver version mismatch”。后来才明白，CUDA、cuDF、cuML这三个东西，版本得严格配对。

2.1 环境总览：先搞清楚谁依赖谁

RAPIDS 全家桶的安装顺序，你想想看，就跟盖楼一样——地基没打好，二楼就盖不上去。

最底层：NVIDIA GPU —— 你家显卡至少得是 Kepler 架构（GTX 600 系列以后），否则洗洗睡吧。
第二层：NVIDIA 驱动 —— 必须安装，而且版本不能太老。我建议直接用最新稳定版。
第三层：CUDA Toolkit —— 这是 RAPIDS 的运行基石。cuDF、cuML 都依赖它做底层计算。
第四层：cuDF + cuML —— 这才是我们的主角。它们俩版本必须严格对齐。

嗯，这里要特别强调：你不要用 pip 强行装一个 cuML 24.06 然后配一个 CUDA 11.0 的环境。我试过，报错能让你怀疑人生。

2.2 第一步：NVIDIA 驱动与 CUDA Toolkit 安装

我个人习惯先在终端里跑一下 nvidia-smi，看看驱动版本和 CUDA 版本。

# 查看当前驱动信息
nvidia-smi

# 输出示例 (关键行)
# NVIDIA-SMI 545.23.08   Driver Version: 545.23.08   CUDA Version: 12.3

如果驱动版本太低，去 NVIDIA 官网下对应显卡驱动。Ubuntu 系还可以用 apt：

# Ubuntu 20.04 / 22.04 安装驱动 (推荐使用显卡驱动PPA)
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt update
sudo apt install nvidia-driver-550 -y   # 或 nvidia-driver-545

# 重启后验证
nvidia-smi

我踩过的一个坑： 千万别把 CUDA Toolkit 和驱动版本搞混。驱动是驱动，Toolkit 是 Toolkit。我曾经图省事，用系统包管理器装了 CUDA Toolkit，结果驱动被降级了，cuML 直接罢工。后来学到了最稳妥的方式——用 NVIDIA 官方提供的 cuda-toolkit-12-0 版本锁。

CUDA Toolkit 安装，我一般用 NVIDIA 的 runfile 或者 deb 包，这样能精准控制版本。

# 使用 runfile 安装 CUDA 12.0 (推荐，灵活度高)
wget https://developer.download.nvidia.com/compute/cuda/12.0.0/local_installers/cuda_12.0.0_525.60.13_linux.run
sudo sh cuda_12.0.0_525.60.13_linux.run --toolkit --silent --override

# 配置环境变量 (写到 ~/.bashrc 或 ~/.zshrc)
export PATH=/usr/local/cuda-12.0/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.0/lib64:$LD_LIBRARY_PATH

2.3 第二步：cuDF 安装——数据准备的基础

cuDF 的概念很简单——就是 GPU 上的 pandas。但它对版本极度敏感。你想想看，cuDF 的某个版本只支持某一小段 CUDA 版本。

安装前，先确定你的 CUDA 版本。我假设你装了 CUDA 12.0。

官方推荐用 conda 安装（省心，不会搞乱系统 Python）：

# 创建新环境 (Python 3.10 比较稳)
conda create -n rapids-24.06 python=3.10
conda activate rapids-24.06

# 安装 cuDF (通过 rapidsai 官方 channel)
conda install -c rapidsai -c conda-forge -c nvidia \
    cudf=24.06 python=3.10 cuda-version=12.0

# 如果你用 pip，也可以 (但 conda 更推荐)
# pip install cudf-cu12==24.06

小经验： conda 的速度时快时慢。国内用户建议配置清华源或阿里云的 conda 镜像。我一般会先加 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/rapidsai/，会快很多。但注意——一定要同时保留 conda-forge 和 nvidia channel，不然依赖容易缺失。

验证 cuDF 是否装好：

python -c "import cudf; print(cudf.__version__)"
# 应该输出类似 24.06.00 的版本号

如果这里报错，比如提示找不到 libcudf 或者 CUDA driver 版本不对。嗯，先回去检查第一步的驱动和 CUDA Toolkit 版本吧。

2.4 第三步：cuML 安装——机器学习引擎就位

cuML 的安装逻辑和 cuDF 几乎一样，版本也必须一一对应。

我建议在同一个 conda 环境里同时装 cuDF 和 cuML：

# conda 安装 cuML (与 cuDF 同一版本)
conda install -c rapidsai -c conda-forge -c nvidia \
    cuml=24.06 python=3.10 cuda-version=12.0

# 或者 pip 方式
# pip install cuml-cu12==24.06

安装完成后，跑个简单的测试，确认它能调用 GPU：

python -c "
from cuml import LogisticRegression
import numpy as np
import cudf

# 造点假数据
X = cudf.DataFrame(np.random.rand(100, 4))
y = cudf.Series(np.random.randint(0, 2, 100))

model = LogisticRegression()
model.fit(X, y)
print('cuML 模型训练成功！')
print('系数:', model.coef_)
"

避坑总结

版本对齐表：别乱搭。下面是 RAPIDS 24.06 与 CUDA 的对应关系（来自官方）：

RAPIDS 版本	支持 CUDA 版本	建议 Python 版本	备注
24.06	11.8 / 12.0	3.10 / 3.11	推荐 12.0
24.02	11.8 / 12.0	3.10	稳定版
23.12	11.8	3.9 / 3.10	旧版，仍可用
23.08	11.8	3.9	不再推荐

你看这个表，说白了就是：你选定了 RAPIDS 24.06，就得配 CUDA 12.0 或 11.8。不要玩跨版本混搭。

2.5 环境验证清单：装完不是终点

好，装完了。但你怎么知道环境真的能用？我建议你做一套完整的“体检”流程。记住，别只看 import 不报错就以为万事大吉。

# 完整的验证脚本
import os
import sys

def check_rapids_environment():
    print("=== 环境检查开始 ===")
    
    # 1. 检查 CUDA 驱动
    print(f"CUDA_VISIBLE_DEVICES: {os.environ.get('CUDA_VISIBLE_DEVICES', '未设置')}")
    
    # 2. 检查 cuDF
    try:
        import cudf
        print(f"cuDF 版本: {cudf.__version__}")
    except ImportError:
        print("❌ cuDF 未安装")
    
    # 3. 检查 cuML
    try:
        import cuml
        print(f"cuML 版本: {cuml.__version__}")
    except ImportError:
        print("❌ cuML 未安装")
    
    # 4. 简单性能测试（可选）
    from cuml import KMeans
    import cudf
    import cupy as cp
    X = cudf.DataFrame(cp.random.rand(10000, 10))
    model = KMeans(n_clusters=5)
    model.fit(X)
    print(f"✅ KMeans 训练成功，耗时: {model.score(X):.4f}")
    print("=== 环境检查通过 ===")

if __name__ == "__main__":
    check_rapids_environment()

再次提醒： 如果检查时出现 CUDA driver version is insufficient 之类的错误，别慌。那通常是因为你的显卡驱动版本太低，或者 CUDA Toolkit 版本和驱动不匹配。我遇到过最离奇的一次是系统里装了多个版本的 CUDA，环境变量 PATH 指向错了。解决方案是 export CUDA_HOME=/usr/local/cuda-12.0 并确保 ldconfig 能看到正确的 libcudart。

2.6 容器化方案：一条命令搞定一切

如果觉得手动安装太麻烦，我特别推荐用 Docker 容器。RAPIDS 官方提供了现成的镜像，版本完全对齐，拉下来就能用。

# 拉取 RAPIDS 24.06 完整镜像 (包含 cuDF, cuML, cuGraph)
docker pull rapidsai/rapidsai:24.06-cuda12.0-runtime-ubuntu22.04-py3.10

# 运行容器，挂载你的代码目录
docker run --gpus all -it --rm \
    -v $(pwd):/workspace \
    rapidsai/rapidsai:24.06-cuda12.0-runtime-ubuntu22.04-py3.10

容器里，所有依赖都预装好了。你直接 python your_script.py 就能跑。个人来说，我经常在本机开发环境折腾半天，最后发现还是容器最快。尤其是团队协作时，发给同事一个 Dockerfile，比让他们从头装环境省心一百倍。

2.7 小结：稳住这一步，后面不踩坑

环境搭建听起来繁琐，但它决定了你后面所有内容能不能跑起来。很多初学者一上来就想跑算法，结果环境没配好，浪费大量时间在调试“import 报错”上。

我的建议是：先花半小时把本节内容走一遍，确保验证脚本无报错。然后，你就可以安心进入下一阶段的特征工程了。