📚 课程目录第2章环境搭建与工具链

2、环境搭建与工具链：Python、PyTorch、CUDA、Docker、自动驾驶仿真平台（如CARLA、SUMO）的安装与配置，以及常用开发工具（Jupyter、VS Code）的使用

Transformer端到端自动驾驶模型的开发，本质上是一个“数据—模型—部署”闭环的工程实践。与纯算法研究不同，端到端自动驾驶涉及多传感器数据流（相机、LiDAR、毫米波雷达）、高精地图、车辆动力学仿真以及实时推理引擎，任何一个环节的工具链缺失或版本错配，都会导致实验无法复现、训练效率低下甚至仿真环境崩溃。本章将围绕“从零搭建一套可复现、可扩展、可调试的Transformer自动驾驶开发环境”这一目标，系统讲解Python虚拟环境、PyTorch与CUDA的版本匹配、Docker容器化封装、CARLA与SUMO联合仿真，以及Jupyter和VS Code的高效使用。下图展示了本章工具链的整体架构与数据流向关系。

上图清晰地展示了从底层硬件驱动到上层应用工具的完整依赖链。在实际项目落地中，我们通常将“物理层”和“容器化层”视为基础设施，由DevOps或算法工程师一次性配置；而“开发框架层”和“仿真平台层”则是日常算法迭代的主战场。下面我们将按照“先基础、后仿真、再工具”的顺序，逐步拆解每个环节的安装配置要点与实战经验。

2.1 Python虚拟环境与依赖管理：从混乱到有序

核心原理：Python虚拟环境的核心价值在于依赖隔离。Transformer自动驾驶项目通常依赖数十个第三方库，且不同库对Python版本、NumPy版本、CUDA绑定版本有严格约束。例如，PyTorch 2.1要求Python≥3.8，而某些旧版mmcv可能不兼容Python 3.10。若直接在系统全局环境安装，极易出现“A库升级导致B库崩溃”的依赖地狱。虚拟环境通过创建独立的site-packages目录和Python解释器副本，确保每个项目拥有完全独立的依赖空间。

操作流程（推荐使用Miniconda）：

安装Miniconda（Python 3.10内置），下载地址选择Linux x86_64版本。

创建专用环境并激活：

conda create -n trans_av python=3.10
conda activate trans_av

配置国内镜像源（清华源）以加速下载：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes

安装核心依赖：

pip install numpy==1.24.4 opencv-python==4.8.1.78 einops==0.7.0
pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu121

经验提醒：不要使用pip install torch直接安装CPU版本。务必通过PyTorch官网的--index-url指定CUDA版本（cu118/cu121/cu124）。安装完成后，在Python中执行import torch; print(torch.cuda.is_available())验证GPU可用性。

案例拆解：某项目组在复现BEVFormer时，发现模型训练速度极慢且报错CUDA error: no kernel image is available for execution on the device。排查过程如下：nvidia-smi显示驱动版本为535.104，支持CUDA 12.2；但PyTorch安装的是cu118版本，其编译时的PTX代码与驱动不兼容。解决方法是卸载重装为cu121版本，并同步更新torchvision。此案例说明，驱动版本、CUDA Toolkit版本、PyTorch编译版本三者必须形成兼容链，不能只看单一指标。

常见误区：误区一：认为conda和pip可以混用所有包。实际上，对于包含CUDA扩展的包（如mmcv-full），建议使用pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.1/index.html指定编译版本。误区二：忽略requirements.txt的版本锁定。建议使用pip freeze > requirements.txt生成精确版本列表，并在Docker镜像中固化。

2.2 CUDA与PyTorch的版本匹配：性能与兼容性的平衡

核心原理：CUDA是NVIDIA GPU的并行计算平台，PyTorch通过预编译的二进制文件调用CUDA库。版本匹配的核心在于：PyTorch的CUDA运行时版本 ≤ 驱动支持的CUDA版本。驱动是向后兼容的，即新驱动可以运行旧CUDA编译的程序，反之则不行。例如，驱动535.104支持CUDA 12.2，那么PyTorch cu121、cu118均可运行，但cu124可能无法运行。

判断方法：使用nvidia-smi查看右上角“CUDA Version”即为驱动支持的最高版本。然后访问PyTorch官网（pytorch.org/get-started/previous-versions/）选择对应版本。下表总结了常见组合的推荐配置：

GPU型号	推荐驱动	CUDA Toolkit	PyTorch版本	适用场景
RTX 3090/4090	≥535.104	12.1	2.1.0+cu121	主流训练/微调
A100/H100	≥525.85	12.0	2.0.1+cu118	大规模预训练
RTX 2080Ti	≥470.82	11.8	1.13.1+cu117	旧卡兼容/推理
Jetson Orin	JetPack 5.1	11.4	1.12.0+cu113	车规级部署

操作流程：首先安装NVIDIA驱动（推荐使用sudo ubuntu-drivers autoinstall或官网.run文件），然后安装CUDA Toolkit（仅需cuda-toolkit-12-1子包），最后安装PyTorch。验证命令：python -c "import torch; print(torch.version.cuda); print(torch.backends.cudnn.version())"。

风险提示：切勿在已有PyTorch的环境中直接运行pip install -U torch，这可能导致CUDA版本漂移。若需升级，先卸载旧版本：pip uninstall torch torchvision，再重新安装指定版本。另外，cuDNN的版本不匹配通常表现为训练时出现cudnn error: CUDNN_STATUS_EXECUTION_FAILED，此时需检查libcudnn.so的软链接是否正确。

案例拆解：在配置多卡训练环境时，我们遇到NCCL error: unhandled cuda error。通过export NCCL_DEBUG=INFO查看日志，发现是不同GPU的驱动版本不一致（一张卡驱动为535，另一张为470）。统一驱动版本后问题解决。这提醒我们，多卡环境的驱动和CUDA版本必须完全一致，否则NCCL通信会异常。

2.3 Docker容器化：让环境“一次构建，处处运行”

核心原理：Docker通过Linux内核的namespace和cgroup技术实现进程隔离，将Python环境、CUDA依赖、系统库打包成镜像。对于自动驾驶项目，Docker的价值在于：① 消除“在我机器上能跑”的尴尬；② 快速切换不同版本的PyTorch/CUDA；③ 与CI/CD流水线无缝集成。NVIDIA Container Toolkit（nvidia-docker2）允许容器内直接访问GPU资源。

操作流程：

安装Docker Engine和NVIDIA Container Toolkit：

curl -fsSL https://get.docker.com | sh
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-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

拉取基础镜像并创建容器：

docker pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel
docker run -it --gpus all --shm-size=16g \
  -v /home/user/datasets:/workspace/datasets \
  -v /home/user/code:/workspace/code \
  -p 8888:8888 -p 2000-2002:2000-2002 \
  --name trans_av_container pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel bash

在容器内安装项目依赖，并提交为新镜像：
```
docker commit trans_av_container trans_av:latest
```

关键参数说明：--shm-size=16g用于增加共享内存，避免DataLoader多进程崩溃；-v挂载数据卷实现宿主机与容器数据共享；-p映射端口，其中2000-2002是CARLA仿真器的默认端口范围。

案例拆解：某团队需要同时测试PyTorch 1.13和2.1两个版本的模型。他们创建了两个容器：trans_av_old（挂载同一数据卷）和trans_av_new，通过docker exec -it trans_av_old bash进入不同环境。由于数据卷共享，两个容器可以访问同一份数据集，但模型代码和依赖完全隔离。最终通过对比两个版本的训练速度和精度，决定迁移到2.1版本。此案例展示了Docker在多版本并行实验中的巨大优势。

常见误区：误区一：在容器内使用pip install安装包后不提交镜像，导致容器删除后环境丢失。误区二：忽略.dockerignore文件，将大型数据集或.git目录打入镜像，导致镜像体积膨胀至数十GB。建议在项目根目录创建.dockerignore，排除datasets/、.git/、__pycache__/等目录。

2.4 自动驾驶仿真平台：CARLA与SUMO的安装与联合仿真

核心原理：CARLA是一款基于Unreal Engine的开源仿真器，提供高保真度的传感器渲染（相机、LiDAR、毫米波雷达）和车辆动力学模型，适合端到端模型的感知与规划训练。SUMO是一款微观交通流仿真工具，擅长模拟大规模路网中的车辆行为、信号灯控制和交通流统计。两者通过CARLA-SUMO协同仿真接口连接：SUMO负责生成全局交通流和路网逻辑，CARLA负责渲染高精度传感器数据和车辆物理反馈。

安装流程（以Ubuntu 20.04 + CARLA 0.9.15为例）：

安装CARLA：

# 下载CARLA压缩包（约20GB）
wget https://carla-releases.s3.us-east-005.backblazeb2.com/Linux/CARLA_0.9.15.tar.gz
tar -xzf CARLA_0.9.15.tar.gz -C ~/carla
cd ~/carla
# 安装Python API
pip install -r PythonAPI/carla/dist/carla-0.9.15-py3.7-linux-x86_64.egg

安装SUMO：

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc
echo 'export SUMO_HOME=/usr/share/sumo' >> ~/.bashrc

启动CARLA服务器（终端1）：

cd ~/carla
./CarlaUE4.sh -quality-level=Low -carla-rpc-port=2000

启动SUMO协同仿真（终端2）：

cd ~/carla/Co-Simulation/Sumo
python3 run_synchronization.py --sumo-home /usr/share/sumo --carla-host 127.0.0.1 --carla-port 2000 --sumo-port 8813 --sync-vehicle-lights

案例拆解：在构建一个包含200辆社会车辆的城区交通流场景时，我们使用SUMO生成路网文件（osm.net.xml），并通过sumo-gui检查路网拓扑。然后启动CARLA服务器，通过run_synchronization.py实现时间步同步（CARLA的tick与SUMO的step一一对应）。在Python脚本中，我们通过carla.Client获取世界对象，并注册传感器：

world = client.get_world()
bp = world.get_blueprint_library().find('sensor.camera.rgb')
sensor = world.spawn_actor(bp, carla.Transform(carla.Location(x=1.5, z=1.8)), attach_to=vehicle)

最终成功采集了RGB图像和LiDAR点云，用于训练一个基于Transformer的鸟瞰图（BEV）感知模型。此案例说明，仿真环境的稳定运行依赖于CARLA与SUMO的版本兼容性，建议使用CARLA官方文档中指定的SUMO版本（通常为1.14-1.18）。

风险提示：CARLA对GPU显存要求较高（建议≥8GB），若显存不足，可在启动时添加-quality-level=Low降低渲染质量。另外，CARLA与SUMO的坐标系需要对齐，通常通过--sync-vehicle-lights参数同步信号灯状态，否则会出现车辆闯红灯的仿真失真。

常见误区：误区一：直接使用pip install carla安装PyPI上的旧版本（0.9.11），导致与CARLA服务器版本不匹配。正确做法是从CARLA安装目录下的PythonAPI/carla/dist/安装egg文件。误区二：忽略CARLA_SERVER环境变量设置，导致Python脚本无法找到CARLA服务器路径。

2.5 开发工具链：Jupyter与VS Code的高效协同

核心原理：Jupyter Lab适合数据探索、可视化分析和模型调试，其交互式单元格可以逐行执行代码并即时查看结果。VS Code则是一个轻量级IDE，通过Remote-SSH和Dev Containers插件，可以无缝连接远程服务器或Docker容器，提供代码补全、断点调试、Git集成等完整功能。两者结合，形成“Jupyter做实验、VS Code写工程”的互补工作流。

配置方法：

Jupyter Lab远程访问：在服务器上执行jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root，然后在本地浏览器访问http://服务器IP:8888。建议设置密码：jupyter server password。
VS Code Remote-SSH：安装“Remote-SSH”扩展，配置~/.ssh/config文件，实现免密登录。连接后，可直接编辑服务器上的代码，并在集成终端中运行。
VS Code Dev Containers：在项目根目录创建.devcontainer/devcontainer.json，指定Docker镜像和挂载卷，VS Code会自动在容器内重新打开项目。

案例拆解：在调试Transformer模型时，我们使用Jupyter Lab进行单步可视化：在forward()函数中插入breakpoint()，然后通过Jupyter的%debug魔术命令进入调试模式，检查中间张量的shape和数值分布。同时，在VS Code中打开同一项目，使用“Python Debugger”配置launch.json，设置"justMyCode": false以进入PyTorch源码断点。这种双工具协同，使得我们能够快速定位到nn.MultiheadAttention中的维度不匹配问题。

常见误区：误区一：在Jupyter中直接修改sys.path导致环境混乱。建议在项目根目录创建.env文件，并通过python-dotenv加载环境变量。误区二：VS Code的Python解释器选择错误，导致无法导入已安装的PyTorch。务必通过Ctrl+Shift+P选择“Python: Select Interpreter”，指向conda环境中的python路径。

总结复盘：环境搭建是Transformer自动驾驶项目中最耗时但最关键的环节。本章的核心要点可归纳为：① 版本兼容是基石——驱动、CUDA、PyTorch三者必须形成闭环验证；② 容器化是保障——Docker确保环境可复现，建议从项目第一天就引入；③ 仿真平台是数据之源——CARLA与SUMO的联合仿真需要耐心调试，建议先跑通官方示例再修改；④ 工具链是效率倍增器——Jupyter与VS Code的配合能显著缩短调试周期。建议读者按照本章流程，从零开始搭建一套完整环境，并记录每一步的版本号和命令，形成自己的环境搭建手册。