SmolVLA モデルのファインチューニング

SmolVLA（Small Vision-Language-Action）は、Hugging Face がリリースした軽量な VLA モデル（約 450M パラメータ）です。「データ → トレーニング → 推論」のプロセスをシングル GPU やコンシューマー向け GPU で迅速に試したい場合、SmolVLA は通常、最も手軽なスタート地点となります。

この記事では、以下の3つのステップについて説明します：

• LeRobot 形式データの準備（ローカルまたは Hub）
• ファインチューニングの開始（シングル GPU/マルチ GPU/メモリ最適化）
• トレーニング済みモデルによる最小限の推論検証

先決条件

システム要件

• OS：Linux（Ubuntu 20.04+ 推奨）または macOS
• Python バージョン：3.10+ 推奨（LeRobot の一般的な依存関係とより適合します）
• GPU：NVIDIA GPU（RTX 3080 以上推奨）、少なくとも 8GB のビデオメモリ
• メモリ：少なくとも 16GB の RAM
• ストレージ：少なくとも 50GB の空き容量

环境準備

1. LeRobot のインストール

# LeRobot リポジトリをクローン
git clone https://github.com/huggingface/lerobot.git
cd lerobot

# 仮想環境の作成（venv 推奨、conda でも可）
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

# 依存関係のインストール（SmolVLA 関連の依存関係は通常 extras に含まれます）
pip install -e ".[smolvla]"

2. 追加の依存関係のインストール

# Flash Attention のインストール（任意：通常 Linux + NVIDIA CUDA 環境のみ、macOS/CPU 環境は対象外）
pip install flash-attn --no-build-isolation

# Weights & Biases のインストール（実験追跡用、任意）
pip install wandb

ヒント

現時点で W&B を使用したくない場合は、wandb login をスキップして構いません。トレーニングに影響はありません（後で --wandb.enable をオフにするだけです）。

データ準備

LeRobot 形式データ

SmolVLA は LeRobot データセット形式を使用します。少なくとも以下のファイル/ディレクトリを準備する必要があります（名前はエクスポート方法によって若干異なる場合がありますが、コアとなるのは meta.json + data/ です）：

your_dataset/
├── data/
│   ├── chunk-001/
│   │   ├── observation.images.cam_high.png
│   │   ├── observation.images.cam_low.png
│   │   └── ...
│   └── chunk-002/
│       └── ...
├── meta.json
├── stats.safetensors
└── videos/
    ├── episode_000000.mp4
    └── ...

データ品質要件

Hugging Face の推奨事項によると、SmolVLA には以下が必要です：

• 良好なパフォーマンスを得るために、最低 25 個の高品質なエピソード
• 最適な効果を得るために、100 エピソード以上を推奨
• 各エピソードには完全なタスク実行プロセスが含まれている必要があります
• 画像解像度は 224x224 または 256x256 を推奨

ファインチューニングのトレーニング

基本トレーニングコマンド

# データセットの「ID」と「パス」を明確に定義して、コマンドの入力を簡略化します
# - ローカルデータセット：DATASET_ID は local/xxx とし、DATASET_ROOT を指定
# - Hub データセット：DATASET_ID は your-name/your-repo とし、--dataset.root を削除
DATASET_ID=local/mylerobot3
DATASET_ROOT=~/Downloads/mylerobot3

export CUDA_VISIBLE_DEVICES=0

# SmolVLA ファインチューニングの開始
lerobot-train \
  --policy.type smolvla \
  --policy.pretrained_path lerobot/smolvla_base \
  --dataset.repo_id ${DATASET_ID} \
  --dataset.root ${DATASET_ROOT} \
  --batch_size 64 \
  --steps 20000 \
  --output_dir outputs/train/smolvla_finetuned \
  --job_name smolvla_finetuning \
  --policy.device cuda \
  --policy.optimizer_lr 1e-4 \
  --policy.scheduler_warmup_steps 1000 \
  --policy.push_to_hub false \
  --save_checkpoint true \
  --save_freq 5000 \
  --wandb.enable true \
  --wandb.project smolvla_finetuning

注記

Hub データセット（例：your-name/your-repo）を使用する場合は、DATASET_ID をその値に変更し、--dataset.root ... の行を削除してください。

高度なトレーニング設定

マルチ GPU トレーニング

# torchrun を使用したマルチ GPU トレーニング
torchrun --nproc_per_node=2 --master_port=29500 \
  $(which lerobot-train) \
  --policy.type smolvla \
  --policy.pretrained_path lerobot/smolvla_base \
  --dataset.repo_id ${DATASET_ID} \
  --dataset.root ${DATASET_ROOT} \
  --batch_size 32 \
  --steps 20000 \
  --output_dir outputs/train/smolvla_finetuned \
  --job_name smolvla_multi_gpu \
  --policy.device cuda \
  --policy.optimizer_lr 1e-4 \
  --policy.push_to_hub false \
  --save_checkpoint true \
  --wandb.enable true

メモリ最適化設定

# ビデオメモリの小さい GPU 向け
lerobot-train \
  --policy.type smolvla \
  --policy.pretrained_path lerobot/smolvla_base \
  --dataset.repo_id ${DATASET_ID} \
  --dataset.root ${DATASET_ROOT} \
  --batch_size 16 \
  --steps 30000 \
  --output_dir outputs/train/smolvla_finetuned \
  --job_name smolvla_memory_optimized \
  --policy.device cuda \
  --policy.optimizer_lr 5e-5 \
  --policy.use_amp true \
  --num_workers 2 \
  --policy.push_to_hub false \
  --save_checkpoint true \
  --wandb.enable true

パラメータ詳細説明

コアパラメータ

パラメータ	意味	推奨値	説明
--policy.type	ポリシータイプ	smolvla	SmolVLA モデルタイプ
--policy.pretrained_path	事前学習済みモデルパス	lerobot/smolvla_base	HuggingFace 上の公式事前学習済みモデル
--dataset.repo_id	データセット ID	local/mylerobot3	ローカルでのトレーニングは local/xxx、または your-name/your-repo (Hub) を使用
--dataset.root	データセットローカルパス	~/Downloads/mylerobot3	ローカルデータセットを使用する場合のみ必要（meta.json や data/ などを含むディレクトリ）
--batch_size	バッチサイズ	64	ビデオメモリに応じて調整。RTX 3080 なら 32-64 推奨
--steps	トレーニングステップ数	20000	小規模データセットなら 10000 まで削減可能
--output_dir	出力ディレクトリ	outputs/train/smolvla_finetuned	モデル保存パス
--job_name	ジョブ名	smolvla_finetuning	ログおよび実験追跡用（任意）

トレーニングパラメータ

パラメータ	意味	推奨値	説明
--policy.optimizer_lr	学習率	1e-4	ファインチューニング時は適宜下げることが可能
--policy.scheduler_warmup_steps	ウォームアップステップ数	1000	学習率のウォームアップ、トレーニングの安定化
--policy.use_amp	混合精度	true	ビデオメモリの節約、トレーニングの加速
--policy.optimizer_grad_clip_norm	勾配クリッピング	1.0	勾配爆発の防止
--num_workers	データロードスレッド数	4	CPU コア数に応じて調整
--policy.push_to_hub	Hub へのプッシュ	false	HuggingFace へのアップロード（repo_id が必要）
--save_checkpoint	チェックポイント保存	true	トレーニングチェックポイントの保存
--save_freq	保存頻度	5000	チェックポイントの保存間隔ステップ数

モデル固有パラメータ

パラメータ	意味	推奨値	説明
--policy.vlm_model_name	VLM バックボーン	HuggingFaceTB/SmolVLM2-500M-Video-Instruct	SmolVLA が使用する視覚言語モデル
--policy.chunk_size	アクションブロックサイズ	50	予測するアクションシーケンスの長さ
--policy.n_action_steps	実行アクションステップ数	50	1回に実際に実行するアクション数
--policy.n_obs_steps	観測履歴ステップ数	1	使用する履歴観測フレーム数

トレーニングの監視

グラフを見る習慣があるなら W&B は非常に便利ですが、まずはフローを通すだけなら、必ずしも使用する必要はありません。

• W&B の有効化（任意）：トレーニングコマンドに以下を追加します：
  • --wandb.enable true
  • --wandb.project smolvla_experiments
  • （任意）--wandb.notes "your note"
• 推奨される監視指標：
  • Loss / Action Loss：継続的に下降しているか、発散していないか
  • Learning Rate：ウォームアップ終了後に期待通りか
  • GPU Memory：上限に達していないか（バッチサイズを下げるか、AMP を有効にするかの判断材料）

迅速な検証（「評価スクリプト作成」より確実な方法）

多くの場合、最初から完全な評価セットを作成する必要はありません。実際の入力フレームを使用して推論を実行するだけで、落とし穴（フィールドキー、次元、dtype、正規化など）の 80% を迅速に排除できます。

import torch
from lerobot.policies.smolvla.modeling_smolvla import SmolVLAPolicy

policy = SmolVLAPolicy.from_pretrained(
    "outputs/train/smolvla_finetuned/checkpoints/last",
    device="cuda",
)
policy.eval()

# 以下の2つはデータセットから「実際のフレームの値」を取得することを推奨します
# image_tensor: [1, 3, H, W] float32（通常 0~1）
# state_tensor: [1, state_dim] float32
observation = {
    "observation.images.cam_high": image_tensor,
    "observation.state": state_tensor,
}

with torch.no_grad():
    action = policy.select_action(observation)

print("action shape:", getattr(action, "shape", None))

ヒント

ここで key error/shape error が発生した場合は、まず2つのことを確認してください：データセットのフィールド名（cam_high などが一致しているか）と state/action の次元（グリッパーの有無や関節数が一致しているか）。

ベストプラクティス（簡易版）

• データ：量は少なくとも「安定しており一貫している」もの（同じカメラ命名規則、同じ state/action 定義）を優先してください。
• 開始時のハイパーパラメータ：まずは実行可能な設定（例：batch_size=16/32）から始め、loss が正常であることを確認してから上げてください。
• メモリ節約の三種の神器：--policy.use_amp true、--batch_size の削減、--num_workers の削減（まずは安定性を優先）。
• チェックポイント：checkpoints/last を保持しておくと、推論や回帰テストがより便利になります。

よくある質問 (FAQ)

• Q：トレーニングは動くが、推論時にフィールドキー不一致のエラーが出る。
  • A：まずデータセット内のカメラキー（例：cam_high）と observation.state の次元を一致させてください。この種の問題は通常「モデルの故障」ではなく、入力マッピングの一貫性がないことが原因です。
• Q：最初から OOM（メモリ不足）になる。
  • A：まず --batch_size を 16 または 8 に下げ、--policy.use_amp true を有効にしてください。また --num_workers を 2 または 1 に下げてください。
• Q：Loss があまり下がらない。
  • A：学習率やステップ数を調整する前に、データが「本当に一致しているか」（state/action の次元、時間の整合性、アクションの滑らかさ）をまず確認してください。

関連リソース

• SmolVLA 公式ブログ
• LeRobot 公式ドキュメント
• SmolVLA モデルページ
• LeRobot GitHub リポジトリ