跳到主要内容

Spirit-v1.5 模型微调

Spirit-v1.5 是 Spirit AI 开源的 VLA 模型。官方源码在 Spirit-AI-Team/spirit-v1.5，模型卡在 Spirit-AI-robotics/Spirit-v1.5。

艾欧智能已经基于官方源码构建并发布 ioaitech/train_spirit:1.5 Docker 镜像。该镜像包含 Spirit-v1.5 训练环境、Hugging Face 基座权重、微调入口，以及 LeRobot 到 RoboChallenge 数据布局的转换逻辑。满足数据要求后，可以直接挂载 RoboChallenge 数据集或兼容的 LeRobot 数据集进行微调。

Spirit-v1.5 的模型卡说明其骨干为 Qwen/Qwen3-VL-4B-Instruct，动作头为 DiT（Diffusion Transformer）。官方 README 已包含 train.py 与 scripts/run_finetune.sh，并标注 2026-04 已发布微调代码。

国内镜像

镜像默认发布在 Docker Hub：ioaitech/train_spirit:1.5。中国大陆环境可改为 swr.cn-east-3.myhuaweicloud.com/ioaitech/train_spirit:1.5。

适用边界​

Spirit-v1.5 是前沿模型，不应当作为第一个训练基线。建议先用 ACT 或 SmolVLA 确认数据质量，再训练 Spirit-v1.5。

适合使用 Spirit-v1.5 的情况：

  • 你希望在较大 VLA 基座上微调，并具备多卡 GPU 环境。
  • 数据接近 RoboChallenge 的机器人状态与相机布局。
  • 数据中包含清晰的任务文本与连续动作。
  • 能接受严格的数据 schema 要求和较高训练成本。

官方 README 推荐多 GPU，并写明训练测试环境为 NVIDIA A100 80GB。消费级单卡可用于阅读源码和小规模排错，但不应承诺可完成正式训练。

数据要求​

Spirit 官方训练数据采用 RoboChallenge 布局：

dataset/
├── meta/
│   └── task_info.json
└── data/
    └── episode_000000/
        ├── states/
        │   └── states.jsonl
        └── videos/
            ├── handeye_realsense_rgb.mp4
            ├── main_realsense_rgb.mp4
            └── side_realsense_rgb.mp4

ioaitech/train_spirit:1.5 支持两类输入：

  • 原生 RoboChallenge 数据集：直接用于训练。
  • 兼容的 LeRobot 数据集：入口脚本会先转换到 RoboChallenge 布局。

LeRobot 转换是严格的。数据必须提供：

  • observation.state：至少 8 维，前 7 维作为末端位姿，第 8 维作为 gripper width。
  • 三路 RGB 视频：映射到 main_realsense_rgb、handeye_realsense_rgb、side_realsense_rgb。
  • meta/tasks.jsonl 或命令行任务文本，用于生成 task_info.json。

如果你的 LeRobot 数据是关节角状态而不是末端位姿，不应直接训练 Spirit-v1.5；需要先完成状态空间适配。

使用镜像训练​

最小验证​

docker run --rm --gpus all \
  -v /path/to/lerobot_dataset:/data/input:rw \
  -v /path/to/output:/data/output:rw \
  ioaitech/train_spirit:1.5 \
  --batch_size 1 \
  --max_train_steps 1 \
  --num_gpus 1 \
  --wandb_mode disabled

这条命令用于确认基座权重、数据转换和训练入口是否可用，不代表有效训练。

指定相机映射​

如果 LeRobot 相机字段不符合内置别名，必须传 --camera_map：

docker run --rm --gpus all \
  -v /path/to/lerobot_dataset:/data/input:rw \
  -v /path/to/output:/data/output:rw \
  ioaitech/train_spirit:1.5 \
  --camera_map '{"main_realsense_rgb":"observation.images.front","handeye_realsense_rgb":"observation.images.left_wrist","side_realsense_rgb":"observation.images.right_wrist"}' \
  --task_name pick_block \
  --task_prompt "pick up the block and place it into the box" \
  --batch_size 1 \
  --max_train_steps 1000 \
  --num_gpus 1 \
  --wandb_mode disabled

多卡训练模板​

docker run --rm --gpus all \
  -v /path/to/robochallenge_or_lerobot_dataset:/data/input:rw \
  -v /path/to/output:/data/output:rw \
  ioaitech/train_spirit:1.5 \
  --batch_size 2 \
  --max_train_steps 40000 \
  --save_steps 2500 \
  --log_interval 25 \
  --num_workers 2 \
  --prefetch_factor 2 \
  --num_gpus 8 \
  --wandb_mode disabled

默认输出目录为：

/path/to/output/spirit_train/latest/

镜像构建时默认将 Hugging Face 基座权重 Spirit-AI-robotics/Spirit-v1.5 下载到 /models/spirit-v1.5-base。如需使用其他权重，可通过 --pretrained_path 指向包含 model.safetensors 和 config.json 的目录。

常用参数​

参数默认值说明
--data_root/data/input输入数据目录。
--pretrained_path/models/spirit-v1.5-base基座权重目录。
--output_dir/data/output/spirit_train/latest输出目录。
--num_gpus自动检测torchrun 进程数。
--batch_size上游默认 32，镜像示例建议从小值开始每卡 batch size。
--max_train_steps40000最大训练步数。
--save_steps2500checkpoint 保存间隔。
--log_interval25日志间隔。
--num_workers2DataLoader worker 数。
--prefetch_factor2DataLoader 预取因子。
--wandb_modedisableddisabled、offline 或 online。
--task_namemove_objects_into_boxLeRobot 转换时的任务名。
--task_prompt数据集 task 或任务名LeRobot 转换时的语言提示。
--camera_map自动推断LeRobot 相机字段到 Spirit 三相机的 JSON 映射。

从官方源码复现​

如果要直接使用官方源码：

git clone https://github.com/Spirit-AI-Team/spirit-v1.5.git
cd spirit-v1.5

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txt
pip install -r requirements-train.txt

官方训练入口是 scripts/run_finetune.sh，通过环境变量配置：

export DATA_ROOT=/path/to/robochallenge_dataset
export PRETRAINED_PATH=/path/to/Spirit-v1.5
export OUTPUT_DIR=./outputs/my_finetuned_model
export NUM_GPUS=8
export BATCH_SIZE=32
export MAX_TRAIN_STEPS=40000
export WANDB_MODE=disabled

./scripts/run_finetune.sh

也可以直接查看 train.py 的参数：

python train.py --help

官方源码不负责把任意 LeRobot 数据自动转换为 RoboChallenge 布局。ioaitech/train_spirit:1.5 提供了该转换入口，但前提仍是数据满足末端状态和三相机要求。

排错​

转换时报缺少三路相机​

检查 meta/info.json 的 video features。若字段名不包含 front、wrist、side 等可推断别名，使用 --camera_map 显式映射。

转换时报 observation.state 维度不足​

Spirit 转换要求至少 8 维：7 维末端位姿加 1 维夹爪宽度。关节角数据不能直接替代末端位姿。

权重目录错误​

--pretrained_path 必须包含 model.safetensors 和 config.json。镜像默认已烘焙基座权重；源码运行时需要手动下载 Hugging Face 权重。

显存不足​

先降低 --batch_size 和 --num_workers，并用较小 --max_train_steps 做链路验证。正式训练建议使用多张大显存 GPU。

参考链接​