nuPlan环境搭建保姆级教程：Ubuntu 22.04 + Conda + Python 3.9 + PyTorch实战

刚开始接触nuPlan的时候我天真地以为这就是个普通的数据集加个pip install的事。结果从克隆代码到真正跑通第一个仿真脚本前后折腾了大半天踩了一堆官方文档里根本不会写的坑。如果你现在正卡在某一部或者正准备在Ubuntu 22.04上搭环境这篇保姆级实测记录应该能帮你省下不少时间。这篇文章我会完整复盘从系统准备、NVIDIA驱动检查、Conda安装、Python 3.9虚拟环境创建、PyTorch安装到nuPlan-devkit依赖处理和数据集落地的全过程。核心技术栈锁定在Ubuntu 22.04 Conda Python 3.9 PyTorch 1.13.1这也是我用下来最稳的组合。适合刚领到nuPlan数据集想做baseline的同学也适合想在服务器上快速复现实验的工程师。1. 动手之前为什么是Ubuntu 22.04 Conda Python 3.9 PyTorch这个组合选型这件事看着不起眼却决定了后面是一路绿灯还是步步红灯。先快速对齐一下nuPlan是什么它是Motional原nuTonomy主导推出的自动驾驶规划任务公开数据集和评测框架数据来自新加坡、拉斯维加斯、波士顿、匹兹堡等城市包含地图、场景标注、传感器数据等多个层次。和同门的nuScenes相比nuScenes主打感知任务而nuPlan主攻的是规划决策——也就是给车一个场景让模型决策怎么走然后评测路线质量和安全性。1.1 为什么不用Windows也不用Docker很多刚开始搞自动驾驶的同学习惯在Windows上做开发。nuPlan官网虽然支持跨平台但实际装下来Windows上做可视化渲染、处理shapely这类地理空间计算库的时候GCC编译链和各种.dll依赖会比Linux痛苦很多。Docker也是一种方案但如果你不熟悉Docker的图形界面转发和GPU透传配置光一个--gpus all参数就可能卡半天。Ubuntu 22.04是当前LTS版本社区资料多遇到问题容易搜到对新手最友好。1.2 为什么用Conda而不是直接pipnuPlan安装过程中最让人头疼的不是nuPlan本身而是它背后那一堆地理空间和可视化依赖。GDAL、Shapely、PyProj这些库用pip直接装经常要现场编译一旦系统里缺了对应的底层库比如libgdal、GEOS就会报各种莫名其妙的编译错误。Conda在这方面有着碾压性的优势conda-forge频道直接提供这些地理空间库的预编译二进制包依赖关系Conda自己处理能把“折腾半天终于编译完”变成“两分钟装好直接能用”。生活化类比pip像是让每个装修师傅自己带工具进毛坯房遇到没有的还得现买现造Conda则像个配备齐全的工具总仓你要什么它直接调给你。1.3 版本组合的兼容性对照这是全文最需要记牢的一张表。我实测的版本组合如下组件推荐版本备注操作系统Ubuntu 22.04 LTS内核版本5.15适配NVIDIA驱动更省心CondaMiniconda最新版不要装Anaconda全家桶太重Python3.9nuPlan官方文档支持范围3.8~3.103.9最保守PyTorch1.13.1搭配CUDA 11.7官方示例和第三方baseline大多用这个版本CUDA Toolkit11.7由PyTorch的conda包附带无需手动安装NVIDIA驱动530系列及以上取决于显卡兼容CUDA 11.7即可nuplan-devkitmain分支或release分支按官方README拉取说实话PyTorch装2.x也不是不能跑但如果你后面要复现一些老baseline很多开源项目的requirements.txt里写的就是1.13.x版本对齐能省去很多“诶为什么人家的demo我跑不出来”的烦恼。选择保守版本不是能力问题是在规避你无法预料的风险。2. 服务器底子NVIDIA驱动、CUDA检查与Miniconda安装避坑很多教程一上来就让你装驱动但如果你用的是实验室已经配好的服务器驱动可能早就装好了。先别急着动手按顺序做检查。2.1 先看硬件和驱动现状打开终端执行nvidia-smi如果能看到一张显卡信息表右上角显示CUDA版本号说明驱动正常、驱动支持的CUDA版本也足够高直接跳到Miniconda安装环节就行。如果提示NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver说明驱动没装好或内核模块没加载这个时候再处理驱动问题。ubuntu-drivers devices这个命令会列出当前机器推荐的驱动版本。推荐什么就装什么不需要追求最新版sudo ubuntu-drivers autoinstall sudo reboot提示千万别手动去NVIDIA官网下载.run格式的驱动来装一旦编译失败很容易把图形界面搞崩尤其在你装了桌面环境的时候。用系统源安装是最稳的有问题也方便卸载还原。这里插一句容易混淆的概念显卡驱动和CUDA Toolkit是两回事。显卡驱动是让系统认识并使用GPU的底层程序CUDA Toolkit是在驱动之上提供的开发库。PyTorch的conda包会把运行所需的CUDA运行库一起带过来所以你不需要单独装完整版CUDA Toolkit太重的开发工具反而容易引发动态库冲突。2.2 Miniconda安装与conda init驱动检查完毕后安装Miniconda。不推荐Anaconda是因为它自带的几百个预装包大部分你用不到还会拖慢conda的频道更新速度。安装命令wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程中会问是否执行conda init这里一定要选yes。如果选错了后面每次打开新终端都会提示CommandNotFoundError: Your shell has not been properly configured to use conda activate. To initialize your shell, run: $ conda init网上大量“conda activate失败”的问题基本都出在这一步。补救方式也很简单在bash下执行source ~/.bashrc或者直接conda init bash再重开终端。2.3 Conda换源预判你的下载会失败装好Conda后第一件事我建议先把软件源换到国内镜像。不做这一步的话后面conda create创建Python 3.9环境时依赖下载慢得像坐绿皮火车还经常断流。我现在的配置是这样的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也可以把默认的defaults频道removed掉只保留镜像源。另外pip源也建议换一下后面pip install -e .的时候会用到pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple如果你在境外服务器上跳过换源这步也没问题。但在国内环境这一步能让你少受很多“网络超时”的毒打。3. PyTorch与Conda虚拟环境地基建牢后面才不返工很多人拿到nuPlan代码后直接pip install -r requirements.txt结果装了一半发现Python版本不对或者PyTorch的版本对不上CUDA整个环境废掉重来。正确姿势是先把虚拟环境和PyTorch装好再碰nuPlan的依赖。3.1 创建并激活Python 3.9环境conda create -n nuplan python3.9 -y conda activate nuplan环境名字就叫nuplan后面所有操作都在这个环境里进行。用Conda隔离环境最大的好处就是你在nuPlan里装什么包都不会污染其他项目的环境。它相当于给每个项目单独开了一间干净房间你在这个房间里怎么折腾都可以。3.2 安装PyTorch 1.13.1 CUDA 11.7确认当前在nuplan环境里之后执行conda install pytorch1.13.1 torchvision0.14.1 torchaudio0.13.1 pytorch-cuda11.7 -c pytorch -c nvidia这个命令会把PyTorch本体和与CUDA 11.7匹配的运行库一起装好。安装包大约2~3GB视网速可能要等一段时间。装完后不要急着装别的先验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())如果输出1.13.1 True说明PyTorch装好且能识别GPU。如果你用的是纯CPU的云服务器输出会是1.13.1 False这也不影响跑nuPlan的基础流程只是跑大数据集会慢很多。提示如果你是NVIDIA新显卡比如Ada架构PyTorch 1.13.1 CUDA 11.7在个别老驱动下可能出现不支持的情况。遇到这种问题把驱动升到最新版就没有问题了。我这里以实验室常见的Ampere架构和RTX 4090为例实测都能正常识别。3.3 顺带装好后续必须的基础包进入nuPlan安装环节之前我习惯先把这个环境里必备的几件套装好避免后面混在一起难排查conda install -y numpy1.23.5 cython jupyter notebook tqdm pyyaml conda install -c conda-forge -y gdal shapely pyproj这里单独解释一下numpy。nuPlan的代码里有部分老写法还用到了np.bool、np.float这类旧API而numpy 1.24之后已经把它们删掉了如果直接装最新numpy后面运行可能会报AttributeError: module numpy has no attribute bool。把numpy锁到1.23.x是个非常聪明的规避手段。4. nuPlan-devkit安装依赖顺序比你想的重要接下来进入正题把nuPlan的开发套件装进这个环境。4.1 拉取代码仓库git clone https://github.com/motional/nuplan-devkit.git cd nuplan-devkit建议装之前先看一眼官方README确认当前推荐的分支。main分支更新快但偶尔会有依赖变动如果你想求稳可以Check Out到最新的release标签。实际操作中大部分示例和baseline都能跑在main分支上。4.2 系统级依赖别漏掉nuPlan依赖不少系统库很多人在这一步吃了亏。安装之前先把以下包装齐sudo apt-get update sudo apt-get install -y libboost-all-dev ffmpeg libsm6 libxext6 libxrender-dev libgomp1这几个包的作用拆开说libboost是C算法库需要ffmpeg负责视频渲染和传感器数据处理libgomp1是OpenMP运行时库缺了它你会在运行时报ImportError: libgomp.so.1: cannot open shared object file。后续如果还需要别的依赖报什么缺什么再补也来得及但提前装好能少很多回头路。4.3 安装GDALconda-forge是正解nuPlan做地图渲染和矢量数据处理时离不开GDAL。前面我让你用conda-forge装一次到这里再确认一下因为很多人单独在pip install -e .之后才发现缺这个库然后开始漫长的编译折腾。conda install -c conda-forge gdal shapely pyproj装完之后可以验证一下能否正常导入python -c from osgeo import gdal; print(gdal.__version__)如果这一步报错找不到libgdal.so多半是pip和conda混装导致的环境混乱。这时候用conda list gdal确认GDAL确实来自conda-forge频道再用ldd查一下依赖就知道了。4.4 核心安装pip install -e .所有前置依赖就绪后在nuplan-devkit根目录执行pip install -e .可编辑安装-e参数意味着你改代码之后不需要重新安装就能生效这对后续调试baseline特别有用。整个安装过程大概10到30分钟具体取决于网络和机器性能。中间如果弹出某个包的编译错误不要慌看错误信息缺什么系统库用apt补上再重新执行这一条命令。安装完成后最重要的一次验证python -c import nuplan; print(nuplan.__file__)能输出nuplan包路径就说明import正常。常见失败情况是报ModuleNotFoundError: No module named nuplan这通常是你没有执行pip install -e .或者换了一个终端窗口后没有激活conda环境。5. 数据集落地下载、目录结构与环境变量一次到位代码库装好了下一步是准备数据。nuPlan的数据集不像mnist那样一行命令就能下它需要去官网注册申请同意许可协议后官方会发下载链接到邮箱通过那个链接下载。5.1 先下载mini数据集第一次跑实验强烈建议只下mini数据集。mini的数据量大概在1GB左右包含了几条完整的路测场景轨迹足够你跑通整个流程和简单baseline。等后续研究真正深入了再考虑下载完整的trainval或neutron split。完整数据集动辄几百GB想清楚自己需要什么再下别把服务器硬盘撑爆了。5.2 目录结构与环境变量数据下载解压后建议放在这样一套结构里$HOME/data/nuplan/ ├── dataset/ │ ├── nuplan-v1.1/ │ │ ├── mini/ │ │ ├── mini14/ │ │ ├── maps/ │ │ ├── sensor_blobs/ │ │ └── splits.json └── exp/ └── logs/详细的关键环境变量需要手动配置。在~/.bashrc末尾追加export NUPLAN_DATA_ROOT$HOME/data/nuplan/dataset export NUPLAN_MAPS_ROOT$HOME/data/nuplan/dataset/maps export NUPLAN_EXP_ROOT$HOME/data/nuplan/exp export NUPLAN_LOG_ROOT$HOME/data/nuplan/exp/logs保存后执行source ~/.bashrc。这四行环境变量里的门道在于nuPlan的Hydra配置文件会依据这几个变量去定位数据集、地图和输出目录。如果你跳过了这步后面运行任何脚本都可能报“找不到scenario”或者把日志一股脑写进当前目录搞得到处都是文件。5.3 确认数据路径正确可以快速验证一下目录是否被正确识别ls $NUPLAN_DATA_ROOT/nuplan-v1.1/ cat $NUPLAN_DATA_ROOT/nuplan-v1.1/splits.json | headsplits.json文件是nuPlan用来索引每个split下有哪些log和scene的关键文件。如果你下载的数据里没有这个文件或者路径摆放不对不管代码怎么跑都会像找不到地址的快递员一样空转。5.4 磁盘空间规划这里列一个我建议的规划防止后面突然发现空间不够内容预估大小说明Conda环境含PyTorch等8~15GB具体取决于装的包数量nuplan-devkit代码 依赖2~5GB编译缓存和.egg-infomini数据集约1GB足够跑通全流程完整数据集500GB慎重下载实验输出与缓存10GB起仿真结果和metric缓存综合来看就算是只跑mini预留50GB空间会比较从容。如果是实验室的共享服务器加一个du -sh *到你经常用的目录看一眼心里会有数得多。6. 跑通官方示例验证环境的两个实用脚本到这里环境已经齐了但“装得起来”和“跑得起来”是两回事。下面两个验证方式强烈建议按顺序做完不要跳过。6.1 第一个脚本检查查找scenario是否正常在nuplan-devkit根目录执行python nuplan/planning/script/run_simulation.py \ simulationopen_loop_boxes \ plannersimple_planner \ scenario_buildernuplan_mini \ workersequentialopen_loop_boxes是官方自带的开环仿真配置simple_planner是最简单的占位规划器scenario_buildernuplan_mini告诉框架去mini数据集里找场景。整条命令的意义在于验证框架能否正确加载数据集、能否跑通最基本的仿真链路。如果数据路径、依赖版本有问题这条命令跑起来要么直接报错要么在加载某些scenario时卡住。实测正常跑完会在$NUPLAN_EXP_ROOT下生成结果目录并打印每个场景的仿真结果信息。你不需要看懂全部输出只看它有没有顺利完成、有没有抛出traceback。6.2 第二个脚本用jupyter notebook验证可视化和metricnuPlan仓库里自带了不少example_notebooks是理解框架非常好的入门材料。启动jupyterjupyter notebook example_notebooks/01_nuplan_compute_metrics.ipynb这个notebook会引导你计算一个场景的metric并画出路线图。如果在服务器上没有图形界面先执行一句export MPLBACKENDAgg否则matplotlib默认的后端会尝试打开图形窗口直接报错。用Agg后端图像会保存为png文件而不是弹窗展示这对SSH远程使用的人来说是标准操作。提示如果你发现notebook里某个cell运行报No matching scenarios十有八九不是代码问题是数据集路径没匹配上。回头检查一下环境变量和splits.json里的log名称是否对得上。7. 踩坑实录卡住我大半天的几个问题及排查链路这节是我最想分享的部分。下面每个问题都是我实际遇到过的按照“看到什么错 - 怎么排查 - 怎么解决”的链路来写你可以直接照着检查。7.1 CommandNotFoundError: Run conda init before conda activate现象新开一个终端输入conda activate nuplanShell直接报CommandNotFoundError。排查这是conda的初始化没生效。检查~/.bashrc里是否有conda初始化的代码块或者当前Shell是否把conda的路径加进了PATH。解决执行conda init bash然后source ~/.bashrc。如果还是不行可能是你的Shell不是bash比如是zsh改成conda init zsh再试。7.2 AttributeError: module numpy has no attribute bool现象运行nuPlan某个脚本时报numpy找不到bool属性。根因numpy 1.24及以上把np.bool、np.int这类旧别名全删了。nuPlan部分模块还没完全迁移。解决把numpy降级pip install numpy1.23.5这也解释了我在第3章为什么强调要把numpy版本锁在1.23.x。如果你已经在后续安装中把numpy升上去了现在降回来然后重新import一下nuplan确认没有其他连锁问题就行。7.3 ImportError: libGL.so.1: cannot open shared object file现象import相关可视化库时提示找不到libGL.so.1。场景这个报错在精简版服务器镜像和Docker容器里特别常见。系统缺少OpenGL/GL库和你的PyTorch、CUDA本身没任何关系。解决sudo apt-get install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev装完再跑一次import通常就好了。如果还有libgomp.so.1的报错就再补libgomp1。7.4 运行脚本后报Hydra配置找不到某个key现象运行run_simulation.py时Hydra抛错说某个配置项不存在比如KeyError: simulation或hydra.errors.ConfigCompositionException。排查链路第一步确认当前工作目录在nuplan-devkit根目录。Hydra的配置搜索路径是相对于仓库根目录的。第二步确认你用的终端在conda的nuplan环境里which python指向的是那个环境的解释器。第三步检查命令行参数顺序。Hydra对simulationopen_loop_boxes这种覆盖参数要求很严格如果简写拼错了系统不会自动提示你“用错了”而是让你找不到对应配置。解决重新对照README或文档里的命令抄一遍不要自己缩写。这类问题最气人但通常就是这么简单。7.5 加载scenario时提示数据集不全现象脚本能跑但加载到一半报错说某个log或某个scene数据不存在。根因或者mini数据集没下完整或者splits.json指向的日志名和mini目录下的文件对不上。解决重新解压数据集确认所有.db文件和sensor_blobs都在正确位置。然后检查NUPLAN_DATA_ROOT环境变量是否正确指向包含nuplan-v1.1的那一层目录而不是其父目录或子目录。7.6 如果你是在无显示器服务器上用jupyter远程跑notebook的时候除了设置MPLBACKENDAgg还要用jupyter notebook --no-browser --port8888启动然后在本地通过SSH端口转发访问。同时注意jupyter的kernel默认使用的是启动时那个Python环境如果你在jupyter里import不到nuplan八成是因为jupyter notebook是用系统Python启动的而不是nuplan conda环境里的。解决方式就是在nuplan环境里重新安装jupyter并启动或者给这个环境注册一个kernelpython -m ipykernel install --user --name nuplan --display-name Python (nuplan)这样在Jupyter界面里就能选到nuplan这个kernel环境永远不会搞混。最后分享一个我个人的习惯每部署一次nuPlan环境我都会把当前环境的版本号完整导出一份存成文件conda list --explicit nuplan_env_snapshot.txt这样万一环境被搞坏或者要在另一台机器上复现直接conda create --name nuplan --file nuplan_env_snapshot.txt就能恢复到几乎一模一样的环境。版本的折磨是环境搭建中最隐形也最耗时的一环多留一份快照总能在最关键的时候救你一命。祝顺利跑通。