HiVT：用于多智能体运动预测的层次化向量Transformer

本仓库包含发表于CVPR 2022的论文HiVT：用于多智能体运动预测的层次化向量Transformer的官方实现。

快速入门

1. 克隆本仓库：

git clone https://github.com/ZikangZhou/HiVT.git
cd HiVT

2. 创建Conda环境并安装依赖：

conda create -n HiVT python=3.8
conda activate HiVT
conda install pytorch==1.8.0 cudatoolkit=11.1 -c pytorch -c conda-forge
conda install pytorch-geometric==1.7.2 -c rusty1s -c conda-forge
conda install pytorch-lightning==1.5.2 -c conda-forge

3. 下载Argoverse运动预测数据集v1.1。下载并解压tar.gz文件后，数据集目录应按如下方式组织：

/path/to/dataset_root/
├── train/
|   └── data/
|       ├── 1.csv
|       ├── 2.csv
|       ├── ...
└── val/
    └── data/
        ├── 1.csv
        ├── 2.csv
        ├── ...

4. 安装Argoverse 1 API。

训练

训练HiVT-64：

python train.py --root /path/to/dataset_root/ --embed_dim 64

训练HiVT-128：

python train.py --root /path/to/dataset_root/ --embed_dim 128

注意：首次运行训练脚本时，数据预处理需要数小时（在我的机器上约为3.5小时）。在RTX 2080 Ti GPU上，每轮训练大约需要35–40分钟。

训练过程中，检查点会自动保存到lightning_logs/目录下。要监控训练过程：

tensorboard --logdir lightning_logs/

评估

评估预测性能：

python eval.py --root /path/to/dataset_root/ --batch_size 32 --ckpt_path /path/to/your_checkpoint.ckpt

预训练模型

我们在checkpoints/目录中提供了预训练的HiVT-64和HiVT-128模型。您可以使用上述评估命令对预训练模型进行评估，或通过TensorBoard查看训练过程：

tensorboard --logdir checkpoints/

结果

定量结果

对于本仓库，在Argoverse 1.1验证集上的预期性能如下：

模型	minADE	minFDE	MR
HiVT-64	0.69	1.03	0.10
HiVT-128	0.66	0.97	0.09

定性结果

引用

如果您觉得本仓库有用，请考虑引用我们的工作：

@inproceedings{zhou2022hivt,
  title={HiVT: Hierarchical Vector Transformer for Multi-Agent Motion Prediction},
  author={Zhou, Zikang and Ye, Luyao and Wang, Jianping and Wu, Kui and Lu, Kejie},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
  year={2022}
}

许可证

本仓库采用Apache 2.0许可证。

HiVT 快速上手指南

HiVT (Hierarchical Vector Transformer) 是发表于 CVPR 2022 的多智能体运动预测模型。本指南将帮助开发者快速在本地搭建环境并运行模型。

环境准备

• 操作系统: Linux (推荐 Ubuntu 18.04+)
• Python: 3.8
• GPU: 支持 CUDA 的 NVIDIA 显卡 (官方测试环境为 CUDA 11.1)
• 前置依赖:
  • Conda (用于管理虚拟环境)
  • Git

安装步骤

1. 克隆代码库

git clone https://github.com/ZikangZhou/HiVT.git
cd HiVT

2. 创建并激活 Conda 环境

建议使用国内镜像源（如清华源）加速包下载：

conda create -n HiVT python=3.8
conda activate HiVT

3. 安装核心依赖

依次安装 PyTorch、PyTorch Geometric 和 PyTorch Lightning。 (注：以下命令基于官方指定的 CUDA 11.1 版本，若需使用国内源，可在命令后添加 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch 等参数)

conda install pytorch==1.8.0 cudatoolkit=11.1 -c pytorch -c conda-forge
conda install pytorch-geometric==1.7.2 -c rusty1s -c conda-forge
conda install pytorch-lightning==1.5.2 -c conda-forge

4. 准备数据集

下载 Argoverse Motion Forecasting Dataset v1.1。解压后，请确保目录结构如下：

/path/to/dataset_root/
├── train/
|   └── data/
|       ├── 1.csv
|       ├── 2.csv
|       └── ...
└── val/
    └── data/
        ├── 1.csv
        ├── 2.csv
        └── ...

5. 安装 Argoverse API

pip install argoverse
# 或者从源码安装：
# git clone https://github.com/argoai/argoverse-api.git
# cd argoverse-api && pip install .

基本使用

训练模型

首次运行会自动预处理数据（耗时约 3.5 小时），之后开始训练。以下以训练 HiVT-64 为例：

python train.py --root /path/to/dataset_root/ --embed_dim 64

• 监控训练: 在新终端运行 tensorboard --logdir lightning_logs/ 查看损失曲线。
• 显存参考: 在 RTX 2080 Ti 上，每 epoch 约需 35-40 分钟。

评估模型

使用预训练权重或自己训练的 checkpoint 进行评估：

python eval.py --root /path/to/dataset_root/ --batch_size 32 --ckpt_path /path/to/your_checkpoint.ckpt

使用预训练模型

项目已提供 HiVT-64 和 HiVT-128 的预训练权重（位于 checkpoints/ 目录）。直接替换上述评估命令中的 --ckpt_path 路径即可快速验证效果。

预期在 Argoverse 1.1 验证集上的性能指标：

模型	minADE	minFDE	MR
HiVT-64	0.69	1.03	0.10
HiVT-128	0.66	0.97	0.09