通用导航模型：GNM、ViNT 和 NoMaD

贡献者: Dhruv Shah, Ajay Sridhar, Nitish Dashora, Catherine Glossop, Kyle Stachowicz, Arjun Bhorkar, Kevin Black, Noriaki Hirose, Sergey Levine

伯克利人工智能研究组

项目页面 | 引用 | 预训练模型

---

通用导航模型是一类通用的目标条件视觉导航策略，它们基于多样化的跨机器人平台训练数据进行训练，能够在零样本条件下控制多种不同的机器人。此外，这些模型还可以高效地进行微调或适配，以应对新的机器人和下游任务。我们的一系列模型已在以下研究论文中有所介绍（且仍在不断扩展）：

1. GNM：一种可驱动任意机器人的通用导航模型（2022年10月，于ICRA 2023会议上发表）
2. ViNT：用于视觉导航的基础模型（2023年6月，于CoRL 2023会议上发表）
3. NoMaD：用于导航与探索的目标掩码扩散策略（2023年10月）

概述

本仓库包含使用您自己的数据训练我们系列模型的代码、预训练模型检查点，以及在TurtleBot2/LoCoBot机器人上部署这些模型的示例代码。该仓库的组织结构沿用了GNM的设计。

• ./train/train.py：用于在您的自定义数据上训练或微调ViNT模型的训练脚本。
• ./train/vint_train/models/：包含GNM、ViNT及一些基线模型的文件。
• ./train/process_*.py：用于将rosbag或其他格式的机器人轨迹处理为训练数据的脚本。
• ./deployment/src/record_bag.sh：用于在目标环境中收集演示轨迹并将其保存为ROS bag文件的脚本。该轨迹会被下采样以生成环境的拓扑图。
• ./deployment/src/create_topomap.sh：用于将演示轨迹的ROS bag文件转换为机器人可用于导航的拓扑图的脚本。
• ./deployment/src/navigate.sh：用于在机器人上部署训练好的GNM/ViNT/NoMaD模型，使其根据生成的拓扑图导航到指定目标的脚本。请参阅下方的相关部分以了解配置设置。
• ./deployment/src/explore.sh：用于在机器人上部署训练好的NoMaD模型，使其随机探索周围环境的脚本。请参阅下方的相关部分以了解配置设置。

训练

此子文件夹包含处理数据集以及使用您自己的数据训练模型的代码。

前置条件

该代码库假设您拥有一台运行Ubuntu系统的工作站（已测试过18.04和20.04版本），Python 3.7及以上版本，以及配备CUDA 10+的GPU。此外，还假设有conda环境，但您可以对其进行修改以适应其他虚拟环境工具或原生安装方式。

设置

请在vint_release/（最顶层）目录下执行以下命令：

1. 创建conda环境：

   conda env create -f train/train_environment.yml
   

2. 激活conda环境：

   conda activate vint_train
   

3. 安装vint_train相关包：

   pip install -e train/
   

4. 从这个仓库安装diffusion_policy包：

   git clone git@github.com:real-stanford/diffusion_policy.git
   pip install -e diffusion_policy/
   

数据处理

在我们的论文中，我们结合了公开可用和未公开的数据集进行训练。以下是用于训练的公开数据集列表；如需访问未公开的数据，请联系相应作者。

• RECON
• TartanDrive
• SCAND
• GoStanford2（修改版）
• SACSoN/HuRoN

我们建议您下载这些（以及您可能希望用于训练的其他数据集）并按照以下步骤进行数据处理。

数据处理

我们提供了一些示例脚本，用于直接从rosbag或自定义格式（如HDF5）处理这些数据集：

1. 使用相关参数运行process_bags.py，或运行process_recon.py来处理RECON的HDF5文件。您也可以按照我们下面的结构手动添加自己的数据集（如果您要添加自定义数据集，请参阅自定义数据集部分）。
2. 在您的数据集文件夹中使用相关参数运行data_split.py。

完成第一步数据处理后，处理后的数据集应具有如下结构：

├── <dataset_name>
│   ├── <name_of_traj1>
│   │   ├── 0.jpg
│   │   ├── 1.jpg
│   │   ├── ...
│   │   ├── T_1.jpg
│   │   └── traj_data.pkl
│   ├── <name_of_traj2>
│   │   ├── 0.jpg
│   │   ├── 1.jpg
│   │   ├── ...
│   │   ├── T_2.jpg
│   │   └── traj_data.pkl
│   ...
└── └── <name_of_trajN>
    	├── 0.jpg
    	├── 1.jpg
    	├── ...
        ├── T_N.jpg
        └── traj_data.pkl

每个*.jpg文件都包含机器人前方的RGB观测图像，并按时间顺序进行了标记。traj_data.pkl文件则存储了该轨迹的里程计数据，它是一个包含以下键的pickle字典：

• "position"：一个形状为[T, 2]的np.ndarray，记录了机器人在每张图像观测时刻的xy坐标。
• "yaw"：一个形状为[T,]的np.ndarray，记录了机器人在每张图像观测时刻的偏航角。

完成第二步数据处理后，处理后的数据分割应在vint_release/train/vint_train/data/data_splits/目录下呈现如下结构：

├── <dataset_name>
│   ├── train
|   |   └── traj_names.txt
└── └── test
        └── traj_names.txt 

训练你的通用导航模型

在 vint_release/train 目录下运行以下命令：

python train.py -c <训练配置文件路径>

预先准备好的配置 YAML 文件位于 train/config 目录中。

自定义配置文件

你可以以其中一个预设的 YAML 文件为起点，根据需要修改其中的参数。config/vint.yaml 是一个不错的选择，因为它包含了注释说明。而 config/defaults.yaml 则包含了默认的配置值（请勿直接使用此配置文件进行训练，因为它未指定任何用于训练的数据集）。

自定义数据集

确保你的数据集和数据划分目录遵循【数据处理】部分中提供的结构。找到 train/vint_train/data/data_config.yaml 文件，并添加以下内容：

<数据集名称>:
    metric_waypoints_distance: <该数据集中航点之间的平均距离（米）>

然后找到你的训练配置文件，在 datasets 参数下添加以下内容（你可以根据需要调整 end_slack、goals_per_obs 和 negative_mining 的值）：

<数据集名称>:
    data_folder: <数据集路径>
    train: data/data_splits/<数据集名称>/train/ 
    test: data/data_splits/<数据集名称>/test/ 
    end_slack: 0 # 从每条轨迹末尾截取的时间步数（以防许多轨迹因碰撞而终止）
    goals_per_obs: 1 # 每次观测采样的目标数量
    negative_mining: True # 来自 ViNG 论文中的负样本挖掘方法（Shah 等人）

从检查点继续训练模型

你也可以不从头开始训练，而是加载已发布的成果中的现有检查点。在 vint_release/train/config/ 目录下的 YAML 配置文件中添加 load_run: <项目名称>/<日志运行名称>。要加载的 .pth 文件应保存在以下目录结构中，并重命名为“latest”：vint_release/train/logs/<项目名称>/<日志运行名称>/latest.pth。这样可以方便地从先前运行的检查点继续训练，因为日志默认就是按这种方式保存的。注意：如果你是从之前的运行中加载检查点，请先在 vint_release/train/logs/<项目名称>/ 中确认运行名称，因为代码会在每个运行的配置 YAML 文件中指定的运行名称后附加日期字符串，以避免运行名称重复。

如果你想使用我们的检查点，可以从这个链接下载 .pth 文件。

部署

本子文件夹包含用于加载预训练的 ViNT 并将其部署到开源 LoCoBot 室内机器人平台上的代码，该平台搭载了 NVIDIA Jetson Orin Nano。该软件可以轻松适配到其他机器人上，研究人员已成功将其独立部署到以下机器人及仿真环境中：Clearpath Jackal、DJI Tello、Unitree A1、TurtleBot2、Vizbot，以及 CARLA 等仿真环境。

LoCoBot 设置

本软件已在运行 Ubuntu 20.04 的 LoCoBot 上进行了测试。

软件安装（按顺序）

1. ROS：ros-noetic
2. ROS 软件包：

   sudo apt-get install ros-noetic-usb-cam ros-noetic-joy
   

3. kobuki
4. Conda
   • 安装 Anaconda、Miniconda 等工具来管理环境
   • 使用 environment.yml 创建 Conda 环境（在 vint_release/ 目录下执行）

     conda env create -f deployment/deployment_environment.yaml
     

   • 激活环境

     conda activate vint_deployment
     

   • （推荐）将以下内容添加到 ~/.bashrc：

     echo “conda activate vint_deployment” >> ~/.bashrc 
     

5. 安装 vint_train 软件包（在 vint_release/ 目录下执行）：

   pip install -e train/
   

6. 从该 仓库 安装 diffusion_policy 包：

   git clone git@github.com:real-stanford/diffusion_policy.git
   pip install -e diffusion_policy/
   

7. （推荐）如果尚未安装，可安装 tmux。许多 Bash 脚本依赖 tmux 启动多个终端窗口并分别运行不同命令。这将有助于调试，因为你可以在每个窗口中查看输出。

硬件要求

• LoCoBot：http://locobot.org（仅导航栈）
• 广角 RGB 摄像头：示例。vint_locobot.launch 文件使用的摄像头参数适用于类似 ELP 广角鱼眼镜头的设备，你可以根据自己的摄像头进行相应调整。请根据你的摄像头情况，在 vint_release/deployment/config/camera.yaml 中调整摄像头参数（用于可视化）。
• 可与 Linux 兼容的 操纵杆/键盘遥控。将操纵杆上的“死人开关”按键映射添加到 vint_release/deployment/config/joystick.yaml 文件中。常见操纵杆的按键与索引对应关系可在 ROS 维基 中找到。

加载模型权重

将模型权重 .pth 文件保存到 vint_release/deployment/model_weights 文件夹中。我们模型的权重可在此链接获取。

收集拓扑地图

请确保在 vint_release/deployment/src/ 目录下运行这些脚本。

本节介绍一种简单的方法，用于为目标部署环境创建拓扑地图。为简化起见，我们将机器人置于“路径跟踪”模式：即给定环境中的一条轨迹，任务是沿着该轨迹到达目标。环境可能会出现新的或动态变化的障碍物、光照条件变化等情况。

录制 rosbag：

./record_bag.sh <bag_name>

运行此命令以使用操纵杆和摄像头遥控机器人。该命令会打开三个窗口：

1. roslaunch vint_locobot.launch：此启动文件会启动摄像头的 usb_cam 节点、操纵杆的 joy 节点以及机器人移动基座的相关节点。
2. python joy_teleop.py：此 Python 脚本会启动一个节点，从 joy 主题读取输入，并将其输出到用于遥控机器人基座的主题上。
3. rosbag record /usb_cam/image_raw -o <bag_name>：此命令不会立即执行（需要按 Enter 键）。它将在 vint_release/deployment/topomaps/bags 目录中运行，我们建议将 rosbag 文件存储在此目录中。

准备好录制 bag 后，运行 rosbag record 命令，并在希望机器人遵循的地图上遥控机器人。完成路径录制后，终止 rosbag record 命令，然后关闭 tmux 会话。

生成拓扑地图：

./create_topomap.sh <topomap_name> <bag_filename>

此命令会打开 3 个窗口：

1. roscore
2. python create_topomap.py —dt 1 —dir <topomap_dir>：此命令会在 /vint_release/deployment/topomaps/images 中创建一个目录，并在播放 bag 的每一秒保存一张图像作为地图中的一个节点。
3. rosbag play -r 1.5 <bag_filename>：此命令以 5 倍速播放 rosbag，因此 Python 脚本实际上是以 1.5 秒的间隔记录节点。<bag_filename> 应该是包含 .bag 扩展名的完整 bag 文件名。您可以在 make_topomap.sh 文件中更改此值。该命令不会运行，直到您按下 Enter 键，而您应该仅在 Python 脚本发出等待消息后才按下 Enter 键。开始播放 bag 后，请切换到运行 Python 脚本的屏幕，以便在 rosbag 播放结束后终止该脚本。

当 bag 播放结束时，终止 tmux 会话。

运行模型

导航

请确保在 vint_release/deployment/src/ 目录下运行此脚本。

./navigate.sh “--model <model_name> --dir <topomap_dir>”

为了部署已发表结果中的模型，我们发布了模型检查点，您可以从此链接下载。

<model_name> 是 vint_release/deployment/config/models.yaml 文件中模型的名称。在此文件中，您需要为每个模型指定以下参数（默认值）：

• config_path（str）：用于训练模型的位于 vint_release/train/config/ 中的 *.yaml 文件路径。
• ckpt_path（str）：位于 vint_release/deployment/model_weights/ 中的 *.pth 文件路径。

请确保这些配置与您训练模型时使用的配置一致。我们提供的权重对应的模型配置已在 yaml 文件中列出，供您参考。

<topomap_dir> 是 vint_release/deployment/topomaps/images 中的目录名称，其中包含与拓扑地图节点相对应的图像。这些图像按名称从 0 到 N 排序。

此命令会打开 4 个窗口：

1. roslaunch vint_locobot.launch：此启动文件会开启摄像头的 usb_cam 节点、操纵杆的 joy 节点以及机器人移动基座的多个节点。
2. python navigate.py --model <model_name> -—dir <topomap_dir>：此 Python 脚本会启动一个节点，从 /usb_cam/image_raw 主题读取图像观测，将观测和地图输入模型，并发布动作到 /waypoint 主题。
3. python joy_teleop.py：此 Python 脚本会启动一个节点，从 joy 主题读取输入，并将其输出到用于遥控机器人基座的主题上。
4. python pd_controller.py：此 Python 脚本会启动一个节点，从 /waypoint 主题读取消息（来自模型的航路点），并输出速度指令以控制机器人基座的运动。

当机器人完成导航时，终止 pd_controller.py 脚本，然后终止 tmux 会话。如果您想在机器人导航过程中接管控制，可以使用 joy_teleop.py 脚本通过操纵杆进行操作。

探索

请确保在 vint_release/deployment/src/ 目录下运行此脚本。

./exploration.sh “--model <model_name>”

为了部署已发表结果中的模型，我们发布了模型检查点，您可以从此链接下载。

<model_name> 是 vint_release/deployment/config/models.yaml 文件中模型的名称（请注意，只有 NoMaD 可用于探索）。在此文件中，您需要为每个模型指定以下参数（默认值）：

• config_path（str）：用于训练模型的位于 vint_release/train/config/ 中的 *.yaml 文件路径。
• ckpt_path（str）：位于 vint_release/deployment/model_weights/ 中的 *.pth 文件路径。

请确保这些配置与您训练模型时使用的配置一致。我们提供的权重对应的模型配置已在 yaml 文件中列出，供您参考。

<topomap_dir> 是 vint_release/deployment/topomaps/images 中的目录名称，其中包含与拓扑地图节点相对应的图像。这些图像按名称从 0 到 N 排序。

此命令会打开 4 个窗口：

1. roslaunch vint_locobot.launch：此启动文件会开启摄像头的 usb_cam 节点、操纵杆的 joy 节点以及机器人移动基座的多个节点。
2. python explore.py --model <model_name>：此 Python 脚本会启动一个节点，从 /usb_cam/image_raw 主题读取图像观测，将观测和地图输入模型，并发布探索行动到 /waypoint 主题。
3. python joy_teleop.py：此 Python 脚本会启动一个节点，从 joy 主题读取输入，并将其输出到用于遥控机器人基座的主题上。
4. python pd_controller.py：此 Python 脚本会启动一个节点，从 /waypoint 主题读取消息（来自模型的航路点），并输出速度指令以控制机器人基座的运动。

当机器人完成导航时，终止 pd_controller.py 脚本，然后终止 tmux 会话。如果您想在机器人导航过程中接管控制，可以使用 joy_teleop.py 脚本通过操纵杆进行操作。

将此代码适配到不同机器人

我们希望这个代码库足够通用，以便您可以将其部署到您喜爱的基于 ROS 的机器人上。您可以在 vint_release/deployment/config/robot.yaml 中修改机器人配置参数，例如机器人的最大角速度和线速度，以及用于遥控和控制机器人的发布话题。如果您有任何问题或建议，欢迎随时创建 GitHub 问题，或通过 shah@cs.berkeley.edu 联系作者。

引用

@inproceedings{shah2022gnm,
  author    = {Dhruv Shah 和 Ajay Sridhar 和 Arjun Bhorkar 和 Noriaki Hirose 和 Sergey Levine},
  title     = {{GNM：一种可驱动任意机器人的通用导航模型}},
  booktitle = {国际机器人与自动化会议（ICRA）},
  year      = {2023},
  url       = {https://arxiv.org/abs/2210.03370}
}

@inproceedings{shah2023vint,
  title     = {Vi{NT}：视觉导航的基础模型},
  author    = {Dhruv Shah 和 Ajay Sridhar 和 Nitish Dashora 和 Kyle Stachowicz 和 Kevin Black 和 Noriaki Hirose 和 Sergey Levine},
  booktitle = {第七届机器人学习年度会议},
  year      = {2023},
  url       = {https://arxiv.org/abs/2306.14846}
}

@article{sridhar2023nomad,
  author  = {Ajay Sridhar 和 Dhruv Shah 和 Catherine Glossop 和 Sergey Levine},
  title   = {{NoMaD：用于导航与探索的目标掩码扩散策略}},
  journal = {arXiv 预印本},
  year    = {2023},
  url     = {https://arxiv.org/abs/2310.xxxx}
}

visualnav-transformer 快速上手指南

visualnav-transformer 是一个通用的目标条件视觉导航模型库（包含 GNM、ViNT 和 NoMaD），支持在多种机器人上进行零样本导航或微调适配。

环境准备

系统要求

• 操作系统: Ubuntu 18.04 或 20.04（推荐 20.04）
• Python: 3.7+
• GPU: 支持 CUDA 10+ 的 NVIDIA 显卡
• 包管理器: Conda (Anaconda 或 Miniconda)

硬件依赖（部署阶段）

• 机器人平台：LoCoBot, TurtleBot2, Clearpath Jackal 等（或仿真环境如 CARLA）
• 摄像头：广角 RGB 摄像头（如 ELP Fisheye）
• 控制设备：兼容 Linux 的游戏手柄或键盘

安装步骤

以下命令请在项目根目录 vint_release/ 下执行。

1. 创建并激活 Conda 环境

conda env create -f train/train_environment.yml
conda activate vint_train

2. 安装核心训练包

pip install -e train/

3. 安装扩散策略依赖

需要克隆并安装 diffusion_policy 仓库：

git clone git@github.com:real-stanford/diffusion_policy.git
pip install -e diffusion_policy/

提示：如果国内网络克隆缓慢，可尝试使用 Gitee 镜像或配置 Git 代理。

4. 部署环境安装（仅在机器人端需要）

若在机器人（如 LoCoBot）上部署，还需安装 ROS Noetic 及相关驱动：

# 安装 ROS Noetic (参考官方文档)
# 安装 ROS 组件
sudo apt-get install ros-noetic-usb-cam ros-noetic-joy

# 创建部署专用环境
conda env create -f deployment/deployment_environment.yaml
conda activate vint_deployment

# 重复安装上述 python 包
pip install -e train/
pip install -e diffusion_policy/

基本使用

1. 数据准备与处理

模型训练需要特定的数据格式。你可以使用公开数据集（如 RECON, TartanDrive 等）或自定义数据。

处理 Rosbag 或自定义数据：

# 处理 rosbag 文件
python train/process_bags.py --input_path <path_to_bag> --output_path <output_dir>

# 或者处理 RECON 格式的 HDF5 数据
python train/process_recon.py --input_path <path_to_hdf5> --output_path <output_dir>

划分训练集/测试集：

python train/data_split.py --data_dir <path_to_processed_dataset>

处理后数据结构应包含按时间序列命名的图片 (0.jpg, 1.jpg...) 和里程计文件 (traj_data.pkl)。

2. 配置训练

修改配置文件 train/config/vint.yaml（推荐以此为基础修改），指定数据集路径和参数。

若添加自定义数据集，需编辑 train/vint_train/data/data_config.yaml 添加数据集元数据，并在训练配置文件的 datasets 字段中引用：

<dataset_name>:
    data_folder: <path_to_the_dataset>
    train: data/data_splits/<dataset_name>/train/ 
    test: data/data_splits/<dataset_name>/test/ 
    end_slack: 0
    goals_per_obs: 1
    negative_mining: True

3. 开始训练

使用配置文件启动训练或微调：

cd train
python train.py -c config/vint.yaml

若要加载预训练权重进行微调，请在配置文件中添加 load_run: <project_name>/<log_run_name>，并将下载的 .pth 文件重命名为 latest.pth 放入对应的 logs 目录中。

4. 机器人部署示例

部署流程分为三步：采集演示、构建拓扑地图、导航。

步骤 A: 采集演示轨迹 (生成 Rosbag) 在机器人终端运行：

./deployment/src/record_bag.sh

手动遥控机器人走一遍环境，脚本将保存为 Rosbag 文件。

步骤 B: 构建拓扑地图 将采集的 Rosbag 转换为导航用的拓扑图：

./deployment/src/create_topomap.sh <path_to_bag_file>

步骤 C: 执行导航 加载训练好的模型进行导航：

./deployment/src/navigate.sh --model_path <path_to_model_weights> --topomap_path <path_to_generated_map>

对于 NoMaD 模型的随机探索任务，可使用：

./deployment/src/explore.sh --model_path <path_to_model_weights>

注意：使用前请确保已将预训练权重文件 (*.pth) 下载至 vint_release/deployment/model_weights 目录，并根据实际摄像头和手柄型号调整 deployment/config/ 下的 YAML 配置文件。