2. 环境搭建
Occupancy 网络训练与部署工程对运行环境有较强的版本耦合要求：PyTorch 版本必须与 CUDA 驱动、cuDNN、Python 解释器以及显卡算力匹配，否则会出现“能 import 但无法训练”“训练中途显存报错”“推理结果与训练不一致”等隐蔽问题。本节从依赖关系出发，给出可复现的环境搭建路径，并说明 Docker 与工具链的配置要点。
一、核心原理：版本依赖链与匹配规则
环境搭建的本质是构建一条自洽的版本依赖链。自底向上依次是：GPU 硬件算力（Compute Capability）→ NVIDIA 驱动 → CUDA Runtime → cuDNN → PyTorch 编译版本 → Python 解释器 → 上层工具链（NumPy、OpenCV、mmcv、TensorRT 等）。链条中任意一环不匹配，都会在编译算子或调用内核时失败。
关键匹配规则有三条：第一，驱动版本决定可支持的最高 CUDA 版本，驱动向下兼容，但 CUDA 不向上兼容；第二，PyTorch 官方 wheel 包内置了特定 CUDA Runtime，因此安装 PyTorch 时通常无需单独安装完整 CUDA Toolkit，只需驱动满足最低要求；第三，若需自行编译自定义算子（如 Occupancy 中的体素化、可变形采样），则必须安装与 PyTorch 编译版本一致的 CUDA Toolkit 与 nvcc。
二、方法流程：从裸机到可训练环境
推荐采用“先验证驱动、再装 Python、后装 PyTorch、最后补工具链”的顺序，每一步都做一次最小验证，避免问题堆积。
- 验证驱动与 GPU：执行
nvidia-smi，确认驱动版本、CUDA 版本上限与显存容量。 - 安装 Python 环境：使用 conda 或 venv 创建独立环境，避免污染系统解释器。
- 安装 PyTorch：按官网生成的命令安装，指定 CUDA 版本。
- 验证 PyTorch 与 CUDA：检查
torch.cuda.is_available()与张量运算。 - 安装工具链：按需安装 OpenCV、mmcv、TensorRT 等，并验证导入。
- 容器化固化：用 Dockerfile 固化上述步骤，保证多机一致。
# 1. 验证驱动
nvidia-smi
# 2. 创建 Python 环境
conda create -n occ python=3.10 -y
conda activate occ
# 3. 安装 PyTorch（以 CUDA 12.1 为例）
pip install torch==2.2.0 torchvision==0.17.0 --index-url https://download.pytorch.org/whl/cu121
# 4. 验证
python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
# 5. 常用工具链
pip install numpy opencv-python open3d tensorboard
三、案例/场景：Docker 固化 Occupancy 训练镜像
Occupancy 训练常涉及多机多卡与长期复现，Docker 是最稳妥的固化手段。基础镜像应选择与驱动兼容的 CUDA 镜像，再在其上安装 Python 与 PyTorch，避免在容器内重复安装驱动。
FROM nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y \
python3.10 python3-pip git libgl1 libglib2.0-0 && \
rm -rf /var/lib/apt/lists/*
RUN pip3 install --no-cache-dir \
torch==2.2.0 torchvision==0.17.0 \
--index-url https://download.pytorch.org/whl/cu121
RUN pip3 install --no-cache-dir numpy opencv-python tensorboard
WORKDIR /workspace
启动容器时使用 --gpus all 暴露 GPU，并挂载数据与代码目录：
docker build -t occ-train:cu121 .
docker run -it --gpus all --shm-size=16g \
-v /data/occupancy:/data \
-v $(pwd):/workspace \
occ-train:cu121 bash
DataLoader worker killed，优先检查 --shm-size，默认 64MB 往往不足，建议设为 8GB 以上。四、误区与复盘：常见环境问题清单
| 现象 | 根因 | 排查与修复 |
|---|---|---|
| torch.cuda.is_available() 为 False | 驱动过低或安装了 CPU 版 PyTorch | 升级驱动；重装 cu 版本 wheel |
| ImportError: libcudart.so.12 | CUDA Runtime 与 PyTorch 编译版本不一致 | 统一为 cu121 或 cu118 |
| 自定义算子编译失败 | nvcc 版本与 torch 编译 CUDA 不一致 | 安装匹配的 CUDA Toolkit 并设置 CUDA_HOME |
| mmcv 导入报错 | mmcv 与 torch / CUDA 版本不匹配 | 按官方矩阵选择 mmcv 版本或源码编译 |
| 多卡训练卡死 | NCCL 版本或共享内存不足 | 升级 NCCL；增大 shm-size |
pip install --upgrade torch，这会破坏已验证的版本链。环境变更后必须重新执行一次最小验证脚本。复盘建议：将 nvidia-smi、python -c "import torch; ..."、pip list 三条输出保存为环境快照，随实验记录归档。这样在复现失败时，可以快速定位是代码问题还是环境漂移。