ETPNav 完整复现指南：从零搭建连续环境视觉语言导航基线

Lin_Aries_0421

507人浏览 · 2026-06-01 18:24:13

Lin_Aries_0421 · 2026-06-01 18:24:13 发布

一份面向研究者的详细踩坑笔记与可执行操作手册 | 基于 TPAMI 2024 论文 ETPNav

📌 摘要

ETPNav 是连续环境视觉语言导航（VLN‑CE）领域的强力基线模型，其核心贡献在于在线拓扑建图与试错式避障控制器。本文基于官方开源代码，提供了一套完整的复现流程：从 Python 3.8 环境配置、PyTorch 1.9.1+cu111 安装、Habitat 仿真器部署，到 Matterport3D 场景数据、R2R/RxR 任务数据及预训练权重的获取，再到预训练、微调、评估与可视化的具体命令。此外，针对云服务器常见的 OpenGL/EGL 缺失与 C++ ABI 冲突问题给出了即用修复方案。本文旨在帮助研究者快速上手 ETPNav，并避免环境与依赖上的常见陷阱。

🌟 项目简介

ETPNav（Evolving Topological Planning） 由 Dong An 等人提出，论文发表于 IEEE TPAMI 2024。
官方开源仓库：MarSaKi/ETPNav

该算法突破了传统 VLN 方法在长距离规划和避障控制上的局限，两大核心创新：

✅ 在线拓扑建图与长距离规划
无需预先探索环境，通过自组织预测的路点动态构建拓扑地图，将导航任务解耦为高层规划与底层控制。跨模态 Transformer 规划器能够理解自然语言指令并生成全局路径。
✅ 连续环境下的避障控制
提出基于试错启发式的鲁棒避障控制器（Tryout），有效避免智能体因碰撞障碍物而陷入死锁，显著提升连续环境下的导航成功率。

📌 本文是作者在复现过程中的完整踩坑笔记，所有步骤均在真实服务器上验证通过，希望能为后续研究者提供一份清晰、闭环的参考教程。

🛠️ 1. 环境配置

本次复现统一使用 Python 3.8，强烈推荐使用 Conda 管理环境。

1.1 创建虚拟环境与安装 PyTorch

conda create -n vlnce38 python=3.8
conda activate vlnce38

安装 PyTorch 1.9.1 + cu111（两种方式任选）：

方式一：直接 pip 安装（国内镜像加速）

pip install torch==1.9.1+cu111 torchvision==0.10.1+cu111 \
    -f https://download.pytorch.org/whl/torch_stable.html \
    -i https://mirrors.cloud.tencent.com/pypi/simple

方式二：下载 whl 本地安装（推荐，避免网络超时）

wget https://mirrors.aliyun.com/pytorch-wheels/cu111/torch-1.9.1%2Bcu111-cp38-cp38-linux_x86_64.whl
wget https://mirrors.aliyun.com/pytorch-wheels/cu111/torchvision-0.10.1%2Bcu111-cp38-cp38-linux_x86_64.whl
pip install torch-1.9.1+cu111-cp38-cp38-linux_x86_64.whl torchvision-0.10.1+cu111-cp38-cp38-linux_x86_64.whl

⚠️ 版本锁定警告：必须使用 PyTorch 1.9.1+cu111，更高版本会导致 Habitat 仿真器不兼容。

1.2 安装项目依赖

pip install "pip<24.1" setuptools==65.5.0 wheel==0.38.4
pip install -r requirements.txt   # requirements.txt 下载链接：百度网盘 提取码: 8je8

1.3 安装 Habitat 仿真器

Habitat 是 VLN‑CE 任务的底层仿真平台，需安装特定版本：

habitat-sim v0.1.7 无头版：下载链接
habitat-lab v0.1.7：GitHub Release

# 安装 habitat-sim
conda install habitat-sim-0.1.7-py3.8_headless_linux_856d4b08c1a2632626bf0d205bf46471a99502b7.tar.bz2

# 安装 habitat-lab
cd habitat-lab-0.1.7
pip install -e .

1.4 云服务器环境依赖修复（选做）

在精简版 Linux（容器、云主机）中运行 Habitat 时常遇到 OpenGL/EGL 缺失 或 C++ ABI 版本冲突。执行以下命令一次性解决：

# 安装图形渲染依赖
apt-get update
apt-get install -y libopengl0 libgl1-mesa-glx libglib2.0-0 libegl1

# 升级 C++ 标准库
apt-get install -y software-properties-common
add-apt-repository ppa:ubuntu-toolchain-r/test -y
apt-get update
apt-get install --only-upgrade libstdc++6 -y

1.5 下载 ETPNav 源码

git clone https://gh-proxy.org/https://github.com/MarSaKi/ETPNav.git
cd ETPNav

📦 2. 数据集下载

2.1 场景数据：Matterport3D（MP3D）

共 90 个场景，大小约 22 GB。最终存放路径：data/scene_datasets/mp3d/{scene}/{scene}.glb

官方脚本下载（需 Python 2.7）
访问 Matterport3D 官网获取 download_mp.py，执行：
```
python download_mp.py --task habitat -o data/scene_datasets/mp3d/
```
网盘快捷下载（提取码: 4kz6）
百度网盘链接：见原项目文档。

2.2 任务数据：R2R 与 RxR

将下载的文件放置于 data/datasets/ 目录下。

数据集	下载链接	存放路径
R2R_VLNCE_v1-2_preprocessed	Google Drive	`data/datasets`
R2R_VLNCE_v1-2_preprocessed_BERTidx	百度网盘（提取码: `88yy`）	`data/datasets`
RxR	百度网盘（提取码: `g317`）	`data/datasets`

2.3 连通图文件（用于可视化）

下载：connectivity_graphs.pkl
存放路径：data/connectivity_graphs.pkl

🤖 3. 模型权重与预训练数据

3.1 编码器与组件权重

模型组件	下载方式	存放路径
Waypoint Predictor (R2R‑CE)	Google Drive	`data/wp_pred/check_cwp_bestdist_hfov90`
Waypoint Predictor (RxR‑CE)	Google Drive	`data/wp_pred/check_cwp_bestdist_hfov63`
BERT 权重	HuggingFace	`bert_config/bert-base-uncased`
RGB 编码器 (ViT‑B32)	HuggingFace	`.cache/clip/ViT-B-32.pt`
Depth 编码器 (ResNet50)	Facebook Link	`data/pretrained_models/ddppo-models/gibson-2plus-resnet50.pth`

3.2 预训练数据（可选）

R2R 预训练数据 → 存至 pretrain_src/datasets/R2R
预计算视觉特征 → 存至 pretrain_src/datasets/img_features
LXMERT 预训练权重 → 存至 pretrain_src/datasets/pretrained/LXMERT

具体下载链接请参考原项目文档。

3.3 最终预训练权重（跳过预训练直接微调）

下载链接：百度网盘提取码: vfsh
存放路径：pretrained/ETP/model_step_82500.pt

3.4 完整文件夹结构（参考）

ETPNav/
├── bert_config/bert-base-uncased/
├── data/
│   ├── datasets/{R2R_VLNCE_*, RxR_VLNCE_*}
│   ├── scene_datasets/mp3d/
│   ├── wp_pred/
│   ├── ddppo-models/gibson-2plus-resnet50.pth
│   └── connectivity_graphs.pkl
├── pretrain_src/
│   ├── datasets/{R2R, pretrained/LXMERT}
│   └── img_features/
├── pretrained/ETP/model_step_82500.pt
├── run_r2r/
├── habitat_extensions/
├── vlnce_baselines/
└── run.py

🚀 4. 代码运行

4.1 预训练（可跳过）

如果已下载最终预训练权重，可直接跳至微调。否则执行：

CUDA_VISIBLE_DEVICES=0 bash pretrain_src/run_pt/run_r2r.bash 233

训练日志保存在 pretrained/r2r_ce/mlm.sap_habitat_depth/logs/log.txt。

4.2 微调（Finetuning）

以单张 RTX 4090 (24GB) 为例，微调约需 1.5 天。

CUDA_VISIBLE_DEVICES=0 bash run_r2r/main.bash train 2333

可选：屏蔽 TensorFlow 无关警告

export TF_ENABLE_ONEDNN_OPTS=0
export TF_CPP_MIN_LOG_LEVEL=2

4.3 测试与评估

评估模式

CUDA_VISIBLE_DEVICES=0 bash run_r2r/main.bash eval 2333

输出指标：路径长度（TL）、导航误差（NE）、成功率（SR）、SPL 等。

可视化（可选）

修改配置中的视频保存模式为 disk，重新运行评估，导航视频将保存至：

data/logs/video/release_r2r/

推理模式（无 ground truth）

CUDA_VISIBLE_DEVICES=0 bash run_r2r/main.bash inference 2333

⚠️ 5. 常见问题与踩坑提示

问题现象	解决方案
`ImportError: libEGL.so.1` 等	执行第 1.4 节的系统依赖安装
`CXXABI_1.3.13 not found`	升级 libstdc++6（同 1.4 节）
PyTorch 版本冲突	必须使用 `1.9.1+cu111`，不可升级
数据集路径错误	严格按照第 2 章的存放路径放置文件
预训练权重下载极慢	使用百度网盘代理，或直接用作者提供的微调权重
`habitat-sim` 编译失败	直接使用提供的 `.tar.bz2` 二进制包，不要从源码编译