目录

• 🛠️ 安装
• 📦 数据准备
• 🚀 训练
• 🎯 推理
• 📈 评估
• 👀 可视化
• 📜 引用
• 🙏 致谢

🛠️ 安装

通过以下步骤创建所需环境：

git clone https://github.com/MIV-XJTU/FSDrive.git && cd FSDrive

conda create -n FSDrive python=3.10 -y && conda activate FSDrive

# CUDA 12.4
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

cd LLaMA-Factory && pip install -e ".[metrics,deepspeed,liger-kernel,bitsandbytes]" --no-build-isolation

cd .. && pip install -r requirements.txt

📦 数据准备

1、下载 nuScenes

从 nuScenes 下载完整数据集并解压到 ./LLaMA-Factory/data/nuscenes

或者建立软连接：

ln -s /path/to/your/nuscenes LLaMA-Factory/data

我们使用了来自 nuScenes 数据集的预缓存数据。数据可在 Google Drive 下载。cached_nuscenes_info.pkl 文件位于 ./create_data 目录下。metrics 文件夹放置在 ./tools/data 目录下。

2、提取视觉 token

分别从头数据和微调数据中提取前视图的视觉 token，以方便监督多模态大语言模型（Multimodal Large Language Model, MLLM）：

python MoVQGAN/pretrain_data.py
python MoVQGAN/sft_data.py

3、构建数据

分别构建符合 LLaMA-Factory 格式的预训练和微调数据：

python create_data/pretrain_data.py
python create_data/sft_data.py --split train # 改为 "val" 以构建验证集

遵循 LLaMA-Factory 教程，并在 ./LLaMA-Factory/data/dataset_info.json 文件中添加数据集信息。

🚀 训练

进入 LLaMA-Factory 的工作目录：

cd LLaMA-Factory

1、预训练

首先，预训练视觉语言模型（Vision-Language Model, VLM）以激活其视觉生成能力：

llamafactory-cli train ../configs/pretrain.yaml

2、监督微调（SFT）

然后，基于预训练参数，微调 VLM 使其能够就轨迹规划进行视觉思考：

llamafactory-cli train ../configs/sft.yaml

🎯 推理

在 LLaMA-Factory 目录下运行以下命令以推理测试数据集：

python scripts/vllm_infer.py \ 
--model_name_or_path saves/qwen2_vl-2b/sft \
--dataset val_cot_motion \
--template qwen2_vl \
--cutoff_len 32768 \
--max_new_tokens 2048 \
--max_samples 100000 \
--image_resolution 524288 \
--save_name results.jsonl \
--temperature 0.1 \
--top_p 0.1 \
--top_k 10

📈 评估

首先，在 FSDrive 目录下，将预测结果与 token 匹配以便于评估：

cd ..

python tools/match.py \
--pred_trajs_path ./LLaMA-Factory/results.jsonl \
--token_traj_path ./LLaMA-Factory/data/val_cot_motion.json

然后评估端到端轨迹规划的 L2 和碰撞率指标：

python tools/evaluation/evaluation.py \
# 改为 "stp3" 并使用 ST-P3 计算方法
--metric uniad \  
--result_file ./LLaMA-Factory/eval_traj.json

👀 可视化

在 FSDrive 目录下使用以下命令可视化轨迹：

python tools/visualization/visualize_planning.py \
--pred-trajs-path ./LLaMA-Factory/results.jsonl \
--tokens-path ./LLaMA-Factory/eval_traj.json \  
--output-path ./vis_traj

在 FSDrive 目录下使用以下命令将视觉 token 还原到像素空间并可视化思维链（CoT）：

python ./MoVQGAN/vis.py \
--input_json ./LLaMA-Factory/eval_traj.json \
--output_dir ./vis_cot

📜 引用

如果您认为 FSDrive 对您的研究或应用有用，请考虑给我们点个星 🌟 并通过以下 BibTeX 条目引用它：

@article{zeng2025futuresightdrive,
  title={FutureSightDrive: Thinking Visually with Spatio-Temporal CoT for Autonomous Driving},
  author={Zeng, Shuang and Chang, Xinyuan and Xie, Mengwei and Liu, Xinran and Bai, Yifan and Pan, Zheng and Xu, Mu and Wei, Xing},
  journal={arXiv preprint arXiv:2505.17685},
  year={2025}
}

🙏 致谢

我们的工作主要基于以下代码库：LLaMA-Factory, MoVQGAN, GPT-Driver, Agent-Driver。我们衷心感谢他们的工作。

FSDrive 快速上手指南

FSDrive (FutureSightDrive) 是一个基于时空思维链（Spatio-Temporal CoT）的端到端自动驾驶视觉语言动作（VLA）模型。它使自动驾驶系统能够进行“视觉思考”，统一视觉生成与理解，实现轨迹规划。

环境准备

• 操作系统: Linux (推荐)
• Python 版本: 3.10
• GPU 环境: CUDA 12.4
• 依赖工具: Conda, Git

安装步骤

1. 克隆代码仓库

   git clone https://github.com/MIV-XJTU/FSDrive.git && cd FSDrive
   

2. 创建并激活 Conda 环境

   conda create -n FSDrive python=3.10 -y && conda activate FSDrive
   

3. 安装 PyTorch (CUDA 12.4)

   pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
   

4. 安装 LLaMA-Factory 依赖

   cd LLaMA-Factory && pip install -e ".[metrics,deepspeed,liger-kernel,bitsandbytes]" --no-build-isolation
   

5. 安装项目其他依赖

   cd .. && pip install -r requirements.txt
   

基本使用

1. 数据准备

下载 nuScenes 数据集并提取视觉 Token，构建符合 LLaMA-Factory 格式的数据。

# 下载数据集到 ./LLaMA-Factory/data/nuscenes 或建立软连接
ln -s /path/to/your/nuscenes LLaMA-Factory/data

# 提取视觉 Token
python MoVQGAN/pretrain_data.py
python MoVQGAN/sft_data.py

# 构建预训练和微调数据
python create_data/pretrain_data.py
python create_data/sft_data.py --split train

注意：需在 ./LLaMA-Factory/data/dataset_info.json 中添加数据集信息。

2. 模型训练

进入 LLaMA-Factory 目录执行训练。

cd LLaMA-Factory

# 1. 预训练 (激活视觉生成能力)
llamafactory-cli train ../configs/pretrain.yaml

# 2. 微调 (学习轨迹规划的视觉思考)
llamafactory-cli train ../configs/sft.yaml

3. 推理与评估

在 LLaMA-Factory 目录下运行推理脚本，并在根目录下进行评估和可视化。

# 推理测试集
python scripts/vllm_infer.py \ 
--model_name_or_path saves/qwen2_vl-2b/sft \
--dataset val_cot_motion \
--template qwen2_vl \
--cutoff_len 32768 \
--max_new_tokens 2048 \
--max_samples 100000 \
--image_resolution 524288 \
--save_name results.jsonl \
--temperature 0.1 \
--top_p 0.1 \
--top_k 10

# 返回根目录进行结果匹配与评估
cd ..
python tools/match.py \
--pred_trajs_path ./LLaMA-Factory/results.jsonl \
--token_traj_path ./LLaMA-Factory/data/val_cot_motion.json

python tools/evaluation/evaluation.py \
--metric uniad \  
--result_file ./LLaMA-Factory/eval_traj.json

# 可视化轨迹与 CoT
python tools/visualization/visualize_planning.py \
--pred-trajs-path ./LLaMA-Factory/results.jsonl \
--tokens-path ./LLaMA-Factory/eval_traj.json \  
--output-path ./vis_traj

python ./MoVQGAN/vis.py \
--input_json ./LLaMA-Factory/eval_traj.json \
--output_dir ./vis_cot