3. 环境搭建：GPU驱动、CUDA Toolkit、cuDF、RAPIDS套件安装，Docker镜像配置与验证

说到单细胞多组学分析的加速，环境搭建是第一道坎。很多朋友买了 GPU 服务器，结果装完驱动发现 CUDA 版本对不上，或者 RAPIDS 跑起来报错，折腾一两天。我个人装机不下 20 次，踩过的坑足以写本小册子。今天咱们直奔主题，把这条链路理清楚。

3.1 整个环境长什么样？

先给个全景图，你心里有个谱。

GPU 加速单细胞分析环境栈 GPU 硬件（NVIDIA Tesla / GeForce / RTX） NVIDIA GPU Driver（~530 系列） CUDA Toolkit 11.8 / 12.x RAPIDS 套件（cuDF / cuML / cuGraph） Docker 容器（NGC / 自定义镜像） 依赖关系 只能从下往上 逐层安装
我的经验：很多人一上来就装 RAPIDS，结果驱动版本不够新，CUDA 不识别。记住一句话——驱动 → CUDA → RAPIDS → 容器，顺序反了必出妖。

3.2 GPU 驱动安装

驱动是地基。地基歪了，整栋楼都白搭。

3.2.1 确认你的 GPU

先查卡。在终端跑一句：

lspci | grep -i nvidia

如果输出里有 VGA/3D controller 字样，说明系统认到卡了。但这时驱动还没装，nvidia-smi 报错是正常的。我曾经遇到一台机器 lspci 能看到卡，但 nvidia-smi 死活不出，最后发现是 BIOS 里没开 Resizable BAR——折腾了我整整半天。

3.2.2 安装驱动（推荐 535 或 550 系列）

我一般直接用 NVIDIA 官方 .run 文件，干净利落。

# 1. 卸载旧驱动
sudo apt purge nvidia-* -y

# 2. 禁用 nouveau（开源驱动）
echo 'blacklist nouveau' | sudo tee /etc/modprobe.d/blacklist-nvidia-nouveau.conf
sudo update-initramfs -u

# 3. 重启后下载驱动
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/550.90.07/NVIDIA-Linux-x86_64-550.90.07.run
chmod +x NVIDIA-Linux-x86_64-550.90.07.run
sudo ./NVIDIA-Linux-x86_64-550.90.07.run

# 4. 验证
nvidia-smi

输出类似下面这样，说明驱动成功了：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.90.07    Driver Version: 550.90.07    CUDA Version: 12.4     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  Tesla T4            Off  | 00000000:00:04.0 Off |                  Off |
| 40%   54C    P0    27W /  70W |      0MiB / 15360MiB |      0%      Default |
+-----------------------------+----------------------+----------------------+
注意：CUDA Version 一栏显示的是驱动支持的最高 CUDA 版本，不是你已安装的 Toolkit 版本。这两者容易混淆，我早年就栽过这个跟头。

3.3 CUDA Toolkit 安装

RAPIDS 对 CUDA 版本有严格依赖。目前 cuDF 24.x 推荐 CUDA 11.8 或 12.0–12.4。我个人偏好 11.8，兼容性最稳。

# 下载 CUDA 11.8 runfile
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run --toolkit --silent --override

# 设置环境变量
echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version

看到 nvcc: NVIDIA (R) Cuda compiler driver 11.8 就对了。

一个小坑：如果你同时安装了 Anaconda，conda 里可能自带 cudatoolkit，那个是给 PyTorch 用的。系统级的 /usr/local/cuda 和 conda 里的别搞混。我建议把系统级 CUDA 作为默认，conda 环境里需要特殊版本时再指定。

3.4 RAPIDS 套件安装（cuDF + cuML + cuGraph）

RAPIDS 现在推荐用 conda 或 pip 安装。我测试下来，conda 的依赖解析更靠谱，尤其当你还要搭一个 scverse 环境的时候。

3.4.1 创建 conda 环境并安装

conda create -n rapids-24.06 python=3.10 -y
conda activate rapids-24.06

# 安装 RAPIDS（CUDA 11.8 版本）
conda install -c rapidsai -c conda-forge -c nvidia \
    rapids=24.06 python=3.10 cuda-version=11.8 \
    cudatoolkit=11.8 \
    cuvs=24.06 \
    -y

这个命令会把 cuDF、cuML、cuGraph 以及 cuVS 一键装好。装完之后，验证一下：

python -c "import cudf; print(cudf.__version__)"
python -c "import cuml; print(cuml.__version__)"

如果输出版本号 24.06（或 24.08），说明核心库正常。

3.4.2 验证 GPU 加速是否生效

写个最小例子跑一下：

import cudf
import cupy as cp

# 创建 1000 万行数据，走 GPU
df = cudf.DataFrame({'a': cp.random.randn(10_000_000),
                     'b': cp.random.randn(10_000_000)})
df['c'] = df['a'] + df['b']
print(df.head())
print(f"DataFrame 在 GPU 上？ {df._column_names}")

应该 1 秒内跑完。如果用 pandas 跑同量级数据，怎么也得 3–5 秒。

核心指标：从 pandas 迁移到 cuDF，同样代码在单张 T4 上差不多有 5–20 倍加速。千万别在 CPU 上跑几百万细胞的高维矩阵，那是自己折磨自己。

3.5 Docker 镜像配置与验证

实话实说，生产环境里我强烈建议用 Docker。为什么呢？

  • 依赖隔离——你换项目不用重新装驱动。
  • 可复现——论文审稿人想复现，拉个镜像就行。
  • 团队协作——新人不用从头配环境。

3.5.1 安装 Docker + NVIDIA Container Toolkit

# 安装 Docker
sudo apt install docker.io -y
sudo systemctl enable docker

# 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update
sudo apt install nvidia-container-toolkit -y
sudo systemctl restart docker

3.5.2 拉取 RAPIDS 官方镜像并测试

NVIDIA NGC 上有现成的 RAPIDS 镜像，省去自己手配依赖的烦恼。

# 拉取 RAPIDS 24.06 镜像
docker pull nvcr.io/nvidia/rapidsai/rapidsai:24.06-cuda11.8-runtime-ubuntu22.04-py3.10

# 启动容器，挂载工作目录
docker run --gpus all -it --rm \
    -v /home/user/project:/workspace \
    nvcr.io/nvidia/rapidsai/rapidsai:24.06-cuda11.8-runtime-ubuntu22.04-py3.10 \
    bash

# 容器内验证
nvidia-smi
python -c "import cudf; print('cuDF 就绪:', cudf.__version__)"

3.5.3 验证 GPU 在容器内可用

有时候 nvidia-smi 在宿主机正常，到了容器里却报错。这是容器没挂载 GPU 设备。检查方法：

# 在容器内执行
python -c "import cupy; print(cupy.cuda.runtime.getDeviceCount(), '块 GPU 可用')"

如果返回 0，说明 --gpus all 没生效，或者 nvidia-container-toolkit 没装好。

我曾经踩过的坑：Ubuntu 22.04 上 nvidia-container-toolkit 新版本改了配置文件路径。旧教程里改 /etc/docker/daemon.json 的方法已经失效。现在老老实实用 apt 装 toolkit 并重启 docker daemon 就好，不用手动编辑配置文件。

3.6 环境验证清单

装完别急着跑分析。先过一遍这个清单，保证每层都没问题。

检查项 命令 期望输出
GPU 驱动 nvidia-smi 显示 GPU 型号、驱动版本、CUDA 版本
CUDA Toolkit nvcc --version Build cuda_11.8.r11.8/…
cuDF python -c "import cudf; print(cudf.__version__)" 24.06
cuML python -c "import cuml; print(cuml.__version__)" 24.06
GPU 可用性 python -c "import cupy; print(cupy.cuda.runtime.getDeviceCount())" ≥ 1
Docker GPU 访问 docker run --gpus all nvidia/cuda:11.8.0-base nvidia-smi 与宿主机一致
快速测试脚本：我习惯把这 6 个检查项写成一个 check_env.sh，新机器拿到手直接跑一遍。30 秒就知道环境搭没搭好，不用翻十几页日志。

3.7 常见问题与解决方案

  1. nvidia-smi 显示 "Failed to initialize NVML: Driver/library version mismatch"
    驱动版本和内核模块版本不一致。重启机器通常能解决。如果重启后依然报错，说明驱动没装全，重装驱动即可。
  2. nvcc 找不到
    没把 /usr/local/cuda/bin 加到 PATH。重新 source ~/.bashrc，或者直接在命令行 export 一下。
  3. cuDF import 报 "No module named 'cudf._lib'"
    大概率是 pip 安装的 cuDF 和系统 CUDA 不匹配。卸掉换 conda 安装，conda 会自动帮你处理 cudatoolkit 的版本。
  4. Docker 容器里跑 nvidia-smi 报 "could not select device driver"
    nvidia-container-toolkit 没装或没重启。执行 sudo apt install nvidia-container-toolkit && sudo systemctl restart docker。
← 上一章 📖 返回目录 下一章 →