先说个真实经历。上个月我在一台跑着 Ubuntu 22.04 的服务器上配 Habitat-baselines v0.1.7原以为照着 README 半小时搞定结果从早上十点折腾到下午五点中途一度怀疑是自己太菜。装完后回头看问题全集中在版本对应关系、habitat-sim 安装方式、数据路径三块。今天这篇就按我实际踩坑的顺序把整个流程重新走一遍。标题里写“全网唯一”确实有点标题党但这个 v0.1.7 是官方比较早的 tag网上能搜到的教程要么年代久远、要么只讲主流程不讲坑如果你也是做具身智能、想在老版本上复现论文基线或者纯粹想搞清楚 Habitat 三件套怎么协同工作这篇文章应该能帮你省下我那一整天。我尽量把每一步的命令、为什么这么做、报错怎么定位都写清楚。下面开始。1. 跑通之前先弄清楚 Habitat 三件套的版本血缘关系很多人装 Habitat-baselines 失败第一原因不是操作问题而是根本没搞明白这个仓库和 habitat-lab、habitat-sim 之间的关系。1.1 谁依赖谁sim、lab、baselines 的三角关系这三个项目是分开维护、分开发布的但它们在实际运行时必须是一套互相匹配的组合。habitat-sim底层仿真器负责加载 3D 场景、做物理碰撞检测、渲染视觉观测。它是 C 写的Python 层只是封装。habitat-lab中间层 API定义了环境接口、传感器、任务逻辑比如 PointNav、ObjectNav 的 reward 计算、碰撞判定、成功指标。habitat-baselines最上层的算法库基于 habitat-lab 提供的接口实现 PPO、DQN、DD-PPO 等训练算法。baselines 并不会自己实现仿真逻辑它训练智能体时要调用 lab 的HabitatEnvlab 又调用 sim 去渲染场景、控制智能体位置。所以安装顺序必须是 sim 在最底层、lab 在中间、baselines 在最上面。如果你只装了 baselines运行时会直接报ModuleNotFoundError: No module named habitat因为habitat这个 Python 包其实是 habitat-lab 提供的。1.2 v0.1.7 的配套版本和典型运行环境Habitat-baselines v0.1.7 是 2021 年的版本当时官方发布时还是以 Ubuntu 18.04/20.04 为主力测试环境Python 官方推荐 3.8但我实测 Python 3.9 也可以3.10 及以上就不要尝试了habitat-lab 里的很多第三方依赖在 3.10 上会出现兼容性问题属于给自己找麻烦。配套版本方面v0.1.7 对应 habitat-lab 的 v0.2.2 tag。这个对应关系很重要如果你直接拉 habitat-lab 的 master接口大概率变了baselines 跑不起来。我当时用的是这样一套组合组件版本备注Ubuntu22.04 / 20.0422.04 需要额外装系统依赖Python3.93.8 也可以CUDA11.3配合 PyTorch 1.10PyTorch1.10.0cu113官方要求 1.8 以上1.10 实测最稳habitat-simconda-forge 最新版不需要指定太细的版本号habitat-labv0.2.2必须切 taghabitat-baselinesv0.1.7必须切 tag1.3 为什么坚持用 conda二进制依赖的锅habitat-sim 是一个大型 C 项目如果你自己从源码编译需要配 CMake、Bullet、Magnum、OpenGL 头文件等一系列依赖即使编译成功后续更新系统库还可能导致动态链接库重新冲突。官方推荐、社区实际使用也最稳的方式是用 conda 安装预编译好的二进制包。所以我的第一个建议是不要尝试从源码编译 habitat-sim除非你实验环境特殊到必须自己改仿真器源码。直接用 conda 从 conda-forge 渠道拉包省下大量时间。提示如果你用无显示器服务器一定要装 headless 版本否则运行时初始化渲染上下文会失败。这个我后面会单独讲。2. 源码获取和环境准备每条命令背后的实际原因这个阶段看着简单但很多人就是在这里开始踩坑。我把关键命令拆开说。2.1 克隆仓库与切换 tag先创建并激活 conda 环境conda create -n habitat python3.9 conda activate habitat然后克隆两个仓库git clone https://github.com/facebookresearch/habitat-lab.git git clone https://github.com/facebookresearch/habitat-baselines.git克隆完成后不要急着安装先切到对应 tagcd habitat-lab git checkout v0.2.2 cd ../habitat-baselines git checkout v0.1.7这一步特别容易忽略。如果你直接装默认分支baselines 的run.py调用的接口和最新版 lab 不一定对得上轻则命令跑不通重则连导入都报错。2.2 安装底层的 habitat-sim我实测下来最稳定的安装方式conda install -c conda-forge habitat-sim如果你的服务器没有显示器安装 headless 版本conda install -c conda-forge habitat-sim headless这里有个细节需要注意headless在这里相当于一个额外的 feature 标签并不是一个独立的包名。加了它之后仿真器会忽略本机显卡显示输出只做离屏渲染这对 SSH 远程训练非常关键。如果你在安装时 conda 解析依赖很慢可以给 conda 配上国内镜像源把~/.condarc换成清华源或者中科大源都行。这和你网络环境有关不是必选项但能节省很多等待时间。2.3 PyTorch 与 CUDA 版本匹配的实测建议habitat-baselines v0.1.7 官方要求 PyTorch 1.8 以上但我实测下来最省心的是 PyTorch 1.10.0 配 CUDA 11.3pip install torch1.10.0cu113 torchvision0.11.0cu113 \ -f https://download.pytorch.org/whl/torch_stable.html安装之后先验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())只要输出1.10.0cu113 True就说明 GPU 环境是通的。这里必须提醒一句不要图新装 PyTorch 2.x。我试过一次虽然import torch没问题但 habitat-baselines 里的utils模块调用了torch.distributed的一些旧接口2.x 里已经调整了默认初始化方式导致多卡训练直接起不来。如果你想省时间就按老版本环境来。3. 编译安装阶段最容易翻车的三个环节PyTorch 装好之后接下来是让 Python 能识别 habitat-lab 和 habitat-baselines。这个阶段有三个高频坑。3.1 安装 habitat-lab 时的顺序问题很多人先装 baselines再装 lab结果 pip 会尝试从 PyPI 拉一个老旧的 habitat 包或者干脆报错。正确顺序是先 lab 后 baselinescd habitat-lab pip install -e .-e表示 editable 模式会创建一个软链接到你的源码目录后续你改了 lab 的 Python 文件不需要重新安装。而且它会在当前 Python 环境里注册habitat这个包。注意安装前确认当前 conda 环境是habitat很多人因为忘记激活环境把包装到了 base 环境里后面import habitat却永远找不到模块。如果这里有编译报错通常和缺少系统依赖有关。Ubuntu 22.04 上我遇到过error: command gcc failed这时候先安装sudo apt update sudo apt install build-essential cmake libgl1 mesa-utils libglu1-mesa-dev装完再重新执行pip install -e .就可以了。3.2 habitat-baselines 安装时的依赖冲突cd ../habitat-baselines pip install -e .这个步骤本身没什么复杂操作真正麻烦的是它会把gym、numpy、scipy、opencv-python等一大堆依赖拉到你的环境里。如果你之前装过其他 RL 库很容易出现numpy版本回退或者gym版本冲突。我遇到最典型的问题安装之后import gym报AttributeError: module numpy has no attribute bool。这是因为 numpy 1.24 移除了np.bool而老版本 gym 还在用。解决办法是降级 numpypip install numpy1.23.5装完之后先跑一遍自检python -c import habitat_sim; print(habitat_sim.__file__) python -c import habitat; print(habitat.__file__) python -c import habitat_baselines; print(habitat_baselines.__file__)这三条命令只要各自输出了路径说明三件套都已经就位。如果第一条就报错回头看 habitat-sim 是否装到了这个环境里。3.3 libGL 相关报错Ubuntu 22.04 新增的坑import habitat_sim时如果报错libGL.so.1: cannot open shared object file说明当前系统缺少 OpenGL 运行库。这是 Ubuntu 22.04 上很常见的问题因为默认安装的 Python 环境不会自动带上 libGL。解决方式sudo apt install libgl1 libglib2.0-0或者从 conda 侧补conda install -c conda-forge libgl这个问题在 20.04 上不太明显在 22.04 上几乎必踩。4. 数据集准备不弄好路径训练根本起不来代码环境配好之后下一步是准备数据。这里的水比想象中深我见过很多人环境没问题卡在数据上半天。4.1 Scene 数据和 Episode 数据到底有什么区别一个完整的导航任务数据由两部分组成Scene 数据3D 场景本身通常是.glb格式的文件比如 Gibson 数据集的各房间模型。仿真器加载这个场景才能渲染出画面、计算碰撞。Episode 数据一系列任务的描述文件通常是.json.gz里面每条 episode 包含智能体的初始位置、目标位置、场景名称等。两者是配套关系。你下载了一个 Gibson 场景对应的 episode 文件里会引用这个场景的名字如果场景文件不存在训练启动时就会报错或者直接创建一个空数据集。4.2 数据下载与目录摆放规范在 habitat-baselines 项目根目录下默认约定的数据结构是这样的habitat-baselines/ └── data/ ├── datasets/ │ └── pointnav/ │ └── gibson/ │ └── v1/ │ ├── train/ │ │ └── train.json.gz │ └── val/ │ └── val.json.gz └── scene_datasets/ └── gibson/ └── (一堆 .glb 文件)下载数据集时不要自己手动去网上乱搜。老版本 habitat-sim 提供了一键下载脚本python -m habitat_sim.utils.datasets_download --uids gibson_habitat这个命令会自动创建data/scene_datasets和data/datasets目录。如果你需要使用 HM3D 数据集命令是python -m habitat_sim.utils.datasets_download --uids hm3d但要注意有些数据集需要额外申请权限尤其 Matterport3D。下载下来之后一定要对着目录结构检查一遍我见过太多人把.json.gz放错位置训练时报路径错误折腾半天才发现是目录层级多了或者少了一层。4.3 修改配置文件的正确姿势v0.1.7 的 PointNav PPO 示例配置在configs/ppo/ppo_pointnav.yaml。打开之后重点检查几项TASK_CONFIG: DATASET: TYPE: PointNav-v1 SPLIT: train DATA_PATH: data/datasets/pointnav/gibson/v1/{split}/{split}.json.gz SIMULATOR: SCENE: data/scene_datasets/gibson/Allensville.glb其中{split}是运行时动态替换的占位符会根据run.py传入的--run-type或者配置里的训练验证 split 换成train或val。很多人不知道这个占位符机制把路径写死了结果训练和验证时加载同一批数据。还有一点SIMULATOR.SCENE在旧配置里不是必填项但如果你的 episode 里引用的场景名与实际文件名不一致仿真器加载会失败。这时候可以临时在配置里指定一个场景文件但更好的做法是保证数据集目录完整性。提示千万不要把数据集放到中文路径或者带空格的路径下Git 项目和 conda 环境对这类路径处理得很不稳定我遇到过莫名其妙的报错最后发现是路径问题。5. 启动 PPO 单智能体训练从命令到日志到这里前面所有坑都绕过之后真正的训练才刚开始。这个阶段也有自己的问题。5.1 训练命令逐参数拆解在项目根目录执行python habitat_baselines/run.py \ --exp-config configs/ppo/ppo_pointnav.yaml \ --run-type train--exp-config指定的是实验配置文件--run-type有三个选择train、eval、inference。直接跑训练时用train。如果你的机器只有一张显卡可能还需要在配置里检查TORCH_GPU_ID: 0或者在命令行指定CUDA_VISIBLE_DEVICES0 python habitat_baselines/run.py ...我遇到过不少新手明明机器上有多张卡但 PyTorch 默认只在 0 号卡上占显存其他卡空着还以为是程序不支持多卡。v0.1.7 的 PPO 单卡实现本身也没做多卡数据并行想多卡训练得换 DD-PPO 配置或者自己改代码。这个版本不是开箱即用的多卡框架预期要放平。5.2 启动失败排查清单训练启动阶段碰到的问题大多是环境或者配置导致我整理了一个排查清单现象可能原因处理方式启动后立刻报FileNotFoundError数据集路径不对检查data_path和scene_datasets目录报AssertionError: Dataset is emptyepisode 文件与场景不匹配或 json.gz 未正确加载单独写脚本打印数据集长度确认有内容报CUDA out of memorybatch size 太大调小RL.PPO.batch_size或降低分辨率启动后卡住不打印日志数据集加载过程中没有使用进度条等几分钟或者先检查数据量大小报NameError: name habitat_sim is not defined环境混用sim 装到别的环境确认conda activate habitat生效有一次我启动后一直停在initializing environment等了十分钟还没反应最后发现是网络驱动器上的数据集读取太慢。如果数据放在 NFS 挂载盘上建议先拷到本地 SSD 再训练不然每个 episode 加载都要卡顿很久fps 会低到让人怀疑人生。5.3 训练日志怎么看loss、reward、fps训练启动后终端会打印类似这样的日志[INFO] Training: num_updates1560 [INFO] update: 1, mean reward: 0.1234, num_episodes: 64, fps: 45 [INFO] update: 2, mean reward: 0.1456, num_episodes: 128, fps: 49这里几个关键指标mean reward最近一批 episode 的平均奖励PointNav 任务早期分数很低很正常不代表训练失败。num_episodes累计完成的 episode 数量用来判断数据采样是否正常。fps每秒执行帧数反映仿真器运行速度。Gibson 场景在单张 3090 上跑到 40-50 fps 是正常的如果你只有个位数 fps先检查是不是 CPU 算碰撞、GPU 利用率上不去再检查数据集是否在慢速存储上。TensorBoard 日志会输出到tb/目录如果你想实时看曲线tensorboard --logdir tb打开浏览器访问http://服务器IP:6006就能看到 reward、loss 曲线。这里有个老版本的小问题v0.1.7 默认可能只记录部分 scalar如果你看不到 policy loss可能是配置文件里TENSORBOARD这个 feature 没开。检查RL.TENSORBOARD是否为True。6. 评估与可视化隐藏的雷区训练完模型之后第一件事自然是评估效果但这里还有几个容易忽略的点。6.1 评估命令与常见误区评估时使用python habitat_baselines/run.py \ --exp-config configs/ppo/ppo_pointnav.yaml \ --run-type eval但直接跑大概率报错找不到 checkpoint。因为评估需要你明确指定模型权重路径在配置文件里有这样一个字段EVAL_CKPT_PATH_DIR: data/checkpoints/ppo_pointnav/它要求目录下存在.pth文件。训练默认会把模型保存到data/checkpoints/下但训练和评估如果在不同时间跑一定要确认目录名是否一致。另一个常见误区是直接复制训练配置跑评估没有修改SPLIT。训练用的是trainsplit评估应该用valsplit否则你评估的是智能体在训练集上的表现指标虚高没有参考价值。修改配置时把TASK_CONFIG.DATASET.SPLIT改成val。6.2 渲染视频时容易忽略的条件v0.1.7 支持评估时输出智能体视角视频。相关配置一般长这样VIDEO_OPTION: [disk, tensorboard] TENSORBOARD_DIR: tb VIDEO_DIR: video_dir如果你在 headless 服务器上跑即使装了 headless 版本视频渲染也可能出现黑屏。这个问题不是模型问题而是离屏渲染上下文没有正确初始化。一种解决方式是给运行命令加上虚拟显示xvfb-run -a python habitat_baselines/run.py ...在 Ubuntu 上先安装sudo apt install xvfb跑完之后到video_dir下看看有没有 mp4。如果没有检查ffmpeg是否安装。老版本依赖外部ffmpeg命令很多容器镜像里默认没有sudo apt install ffmpeg这个坑我印象非常深因为当时模型 checkpoint 一切正常就是视频没生成查了半天最后发现是 ffmpeg 缺失。6.3 我踩完坑之后留下的经验清单最后分享几条实操经验不是文档里会写的但能救命第一整个安装过程最好全程记录下来包括每一个pip install和conda install。因为环境挂掉后重建很痛苦记录下来了可以直接复制执行。我甚至会把conda env export environment.txt存一份虽然这个文件不能完全复现 conda-forge 的源但至少能看清大版本。第二遇到报错不要急着重新安装整个环境先看报错栈里最后一行是哪个模块抛出的。绝大多数问题都是单个依赖版本问题升级或降级一个包就能解决我踩过的坑中有近一半是 numpy、scipy、gym 之间的兼容性问题。第三v0.1.7 是 2021 年的版本如果你不需要复现特定论文的基线可以优先考虑直接用新版 habitat-lab 和 habitat-baselines 的 master 分支新版的 API 更规范、支持的数据集更多。但如果你因为论文代码锁定在这个版本那本文前面这些坑就是你绕不过去的路。我个人的建议是在一个独立的 conda 环境里跑这套老版本别跟其他项目混在一起这样哪天不想要了直接删环境不牵连其他工作。这次复现虽然折腾但跑通之后我对 Habitat 三件套的边界理解比看文档清楚得多sim 管渲染和物理lab 管任务定义baselines 管算法参数。希望这篇文章能帮你少走点弯路一次性把环境配好跑起来。