Spirit-v1.5 のファインチューニング
Spirit-v1.5 は Spirit AI のオープン VLA モデルです。公式コードは Spirit-AI-Team/spirit-v1.5、モデルカードは Spirit-AI-robotics/Spirit-v1.5 です。
IO-AI は公式ツリーを基に ioaitech/train_spirit:1.5 を公開しています。Spirit-v1.5 の学習環境・Hugging Face 基盤重み・ファインチューニング入口・LeRobot → RoboChallenge レイアウト変換が含まれます。データ制約を満たせば、ネイティブの RoboChallenge ツリーまたは互換 LeRobot をマウントしてファインチューニングできます。
モデルカードではバックボーンに Qwen/Qwen3-VL-4B-Instruct、アクション頭に DiT（Diffusion Transformer）が記載されています。公式 README には train.py と scripts/run_finetune.sh があり、2026-04 にファインチューニングコードが公開された旨が記されています。
Docker Hub の既定イメージ名：ioaitech/train_spirit:1.5。
適用範囲
Spirit-v1.5 は最先端寄りのモデルで、最初のベースラインには向きません。データ品質は ACT や SmolVLA で先に確認してください。
向いている場合：
- 大きな VLA 基盤とマルチ GPU がある
- データが RoboChallenge 風の状態・カメラ構成に近い
- タスク文と連続動作が明瞭
- 厳しいスキーマと高コストを受け入れられる
公式はマルチ GPU を推奨し、検証環境として NVIDIA A100 80GB を挙げています。消費級単 GPU はコード読解や極小スモーク向けであり、本番ファインチューニングを保証するものではありません。
データ要件
公式学習データは 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 番目＝グリッパ幅）- 3 系統の RGB 動画を
main_realsense_rgb/handeye_realsense_rgb/side_realsense_rgbにマッピング meta/tasks.jsonlまたは CLI のタスク文でtask_info.jsonを生成
関節角だけの状態を末端姿勢の代わりに使わないでください。変換が必要です。
イメージで学習
スモーク
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
品質評価ではなく、重み・変換・入口の確認用です。
カメラマップ指定
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
マルチ GPU テンプレート
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/
基盤重み 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（例は小さめから） | GPU あたりバッチ |
--max_train_steps | 40000 | 最大ステップ |
--save_steps | 2500 | 保存間隔 |
--wandb_mode | disabled | disabled / offline / online |
--camera_map | 自動 | 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
python train.py --help も参照。
公式ソースは任意の LeRobot を自動で RoboChallenge にしませ ん。ioaitech/train_spirit:1.5 に変換入口はありますが、末端姿勢＋三カメラの前提は変わりません。
トラブルシューティング
三カメラ不足
meta/info.json の動画 feature を確認。別名なら --camera_map。
observation.state 次元不足
7+1（グリッパ）の 8 次元が必要。関節ベクトルは代替になりません。
--pretrained_path 不正
model.safetensors と config.json が必要。イメージは既定を焼き込み済み。
メモリ不足
バッチとワーカーを下げ、短い max_train_steps でスモーク。本番は大容量 GPU 複数台を想定。