SwiftVLN 评测
简体中文 | English
SwiftVLN 使用统一入口在 SatNav 和 Habitat 中执行在线评测。评测脚本从模型名称恢复训练 配置，加载对应 checkpoint，并将 Episode 分配到指定 GPU。
环境 |
默认 Split |
场景 |
最大步数 |
|---|---|---|---|
SatNav |
|
GeoTIFF |
500 |
Habitat |
|
MP3D |
500 |
动作队列为空时才触发模型查询；每次环境 step 执行队列中的一个动作。
Episode 开始时重置环境和推理 session；每一步采集 RGB 与当前位姿。动作队列为空时，session 初始化或推进窗口，准备记忆和上下文，再预测下一组动作。循环逐个执行动作，并记录动作引起的位姿变化。解析得到空动作序列时使用 STOP。环境报告结束或达到步数上限后，本轮评测完成。实现见 episode_loop.py，窗口和记忆更新见原理章节。
1. 准备评测环境
开始前完成：
安装：创建
swiftvln-eval环境；模型与 Checkpoint：下载模型或准备训练 checkpoint；
评测数据准备：配置 Episode 与场景路径。
进入仓库并激活评测环境：
cd /path/to/SwiftVLN
export SWIFTVLN_ROOT="${PWD}"
source .local/env.sh
source "${SWIFTVLN_CONDA_SH}"
conda activate swiftvln-eval
评测入口为：
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
2. 模型名称与 Checkpoint
模型名称同时记录环境、基础模型、轨迹窗口、memory、history processor、system prompt 和 embedding enhancement。评测时使用 checkpoint 对应的完整模型名称。
默认 SatNav 模型：
export MODEL_NAME=swiftvln-satnav-3b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
python -m swiftvln.experiment parse-name "${MODEL_NAME}" --format json
Habitat Qwen2.5-VL 3B 模型：
export MODEL_NAME=swiftvln-habitat-3b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
python -m swiftvln.experiment parse-name "${MODEL_NAME}" --format json
使用 Qwen3-VL 2B 时设置：
export MODEL_NAME=swiftvln-habitat-qwen3vl-2b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
eval_by_name.sh 按以下顺序查找模型：
优先级 |
模型位置 |
|---|---|
1 |
环境变量 |
2 |
|
3 |
|
按照 checkpoint 文档下载模型后，可以直接使用标准目录：
export MODEL_PATH="${SWIFTVLN_ROOT}/output/model_zoo/swiftvln/HF_model/${MODEL_NAME}"
评测本地训练结果时指定 checkpoint：
export MODEL_PATH=/path/to/checkpoint-step
3. 检查评测配置
CHECK_ONLY=true 解析模型名称，显示即将使用的模型路径与评测参数，不加载模型或启动
torchrun：
CHECK_ONLY=true \
EVAL_SPLIT=val_seen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
默认 SatNav checkpoint 名称为：
swiftvln-satnav-3b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
该名称的解析结果应包含：
环境类型: satnav
NUM_FRAMES: 32
NUM_FUTURE_STEPS: 4
NUM_OVERLAP: 0
MEMORY_METHOD: history
HISTORY_PROCESSOR_TYPE: per_frame
NUM_HISTORY: 8
COMPRESS_STRIDE: 2
EMBEDDING_MODE: none
配置检查不读取 Episode 和场景；实际评测命令会同时验证模型、数据、模拟器与推理链路。
5. Habitat 评测
5.1 评测配置
Habitat 评测配置分布在以下位置：
配置 |
位置 |
内容 |
|---|---|---|
任务配置 |
|
Habitat simulator、RGB sensor、动作、成功距离、指标与 R2R 数据集默认路径 |
本机路径 |
|
R2R Episode 与 MP3D 场景路径 |
模型配置 |
SwiftVLN 模型名称 |
模型族、轨迹窗口、memory、history processor、system prompt 和 embedding enhancement |
运行配置 |
启动命令的环境变量 |
split、GPU、输出目录和视频 |
默认任务配置由 eval_by_name.sh 自动选择。使用自定义 Habitat 配置时指定：
export EVAL_CONFIG_PATH=/path/to/habitat_r2r_eval.yaml
在 .local/env.sh 中设置 R2R 与 MP3D 路径：
export SWIFTVLN_HABITAT_DATA_ROOT="/path/to/streamvln_datasets"
export SWIFTVLN_HABITAT_SCENES_DIR="${SWIFTVLN_HABITAT_DATA_ROOT}/scene_datasets"
export SWIFTVLN_HABITAT_R2R_EVAL_DATA_PATH="${SWIFTVLN_HABITAT_DATA_ROOT}/datasets/r2r/{split}/{split}.json.gz"
Habitat 默认评测 val_unseen。评测 val_seen 时显式设置 EVAL_SPLIT=val_seen。
5.2 评测脚本
Habitat 与 SatNav 使用相同的评测入口：
脚本 |
用途 |
|---|---|
|
推荐入口；从模型名称恢复 Habitat、模型族与 Memory 配置并定位 checkpoint |
|
底层执行入口；使用显式提供的 Habitat 配置、模型路径与推理参数 |
|
将多个模型加入文件队列并串行评测 |
下载 Qwen2.5-VL 3B 模型后设置：
export MODEL_NAME=swiftvln-habitat-3b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
export MODEL_PATH="${SWIFTVLN_ROOT}/output/model_zoo/swiftvln/HF_model/${MODEL_NAME}"
使用 Qwen3-VL 2B 模型时只需替换模型名称；eval_by_name.sh 会自动设置
MODEL_FAMILY=qwen3_vl：
export MODEL_NAME=swiftvln-habitat-qwen3vl-2b-1ep-f32s4-overlap0-pf-h8-pool-s2-noembed
export MODEL_PATH="${SWIFTVLN_ROOT}/output/model_zoo/swiftvln/HF_model/${MODEL_NAME}"
运行配置检查：
CHECK_ONLY=true \
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
直接调用底层脚本时，需要显式传入 Habitat 环境和模型参数：
ENV_TYPE=habitat \
MODEL_NAME="${MODEL_NAME}" \
MODEL_PATH="${MODEL_PATH}" \
MODEL_FAMILY=qwen2_5_vl \
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_swiftvln_qwen_vl_distributed.sh
直接评测 Qwen3-VL 2B 模型时将 MODEL_FAMILY 设置为 qwen3_vl。
批量评测本地训练模型：
bash scripts/queue/enqueue_eval.sh "${MODEL_NAME}"
CUDA_DEVICES=0,1,2,3 bash scripts/queue/eval_queue.sh
5.3 单卡与多卡评测
单卡评测 val_unseen：
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
多卡评测 val_unseen：
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0,1,2,3,4,5,6,7 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
依次评测 val_seen 与 val_unseen：
for split in val_seen val_unseen; do
EVAL_SPLIT="${split}" \
CUDA_DEVICES=0,1,2,3,4,5,6,7 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
done
评测少量 Episode 时增加 MAX_EPISODES：
MAX_EPISODES=1 \
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
评测结果使用第 7 节所述的统一目录和指标格式。
6. SatNav 可视化与性能分析
可视化与性能分析目前仅用于 SatNav 评测。
保存 RGB、top-down map 与导航指令可视化视频：
SAVE_VIDEO=true \
MAX_EPISODES=10 \
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
评测结束后将视频按每 400 个 Episode 打包为 ZIP：
SAVE_VIDEO=true \
VIDEO_COMPRESSION=true \
MAX_EPISODES=10 \
EVAL_SPLIT=val_unseen \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
压缩完成后，videos/ 中对应的 MP4 会被 ZIP 文件替代。
评测默认将模型生成、环境 step、窗口更新与可视化的平均耗时写入
timing_summary.json。输出每个 Episode 的详细耗时：
DEBUG_TIMING=true \
MAX_EPISODES=10 \
CUDA_DEVICES=0 \
bash scripts/eval/eval_by_name.sh "${MODEL_NAME}"
7. 结果与指标
各 rank 追加同一份 Episode 日志；rank 0 等待完成标记后生成最终结果。
Runner 先按 scene 分组并排序 scene 名称，再将得到的全局序列轮转分配给各 rank。恢复时，每个 rank 读取 result.jsonl，跳过已记录的 scene_id::episode_id。每完成一个 Episode，就向这份共享日志追加一行。全部 rank 写入完成标记后，rank 0 按 Episode 键去重，生成完整结果和指标汇总。实现见 runner.py 与 results.py。
每个 split 生成独立目录：
results/eval/swiftvln/<model-name>/<split>/<timestamp>/
├── result.jsonl
├── all_results.jsonl
├── evaluation_summary.json
├── timing_summary.json
├── videos/ # SAVE_VIDEO=true
└── .dist_sync/
└── rank_<n>.done.json
文件 |
内容 |
|---|---|
|
逐 Episode 追加写入的恢复日志 |
|
评测完成后排序、去重的逐 Episode 结果 |
|
汇总指标、模型配置、split 与 GPU 数量 |
|
各推理阶段的平均耗时 |
|
多 GPU rank 完成标记 |
汇总指标包括：
字段 |
指标 |
|---|---|
|
Success Rate（SR） |
|
Success weighted by Path Length（SPL） |
|
Oracle Success（OS） |
|
平均终点导航误差（NE，米） |
|
平均执行步数 |
|
参与汇总的 Episode 数量 |
单条 Episode 发生运行错误时，结果保留在 JSONL 中，并包含 error 字段。