跳到主要内容

SmolVLA 模型微调

SmolVLA 是 Hugging Face LeRobot 发布的轻量 VLA 基座模型。本文以 LeRobot v0.5.0 为准；官方文档 LeRobot v0.5.0 SmolVLA 说明，它使用 lerobot/smolvla_base 作为预训练权重，面向 LeRobot 数据集微调；官方模型卡 lerobot/smolvla_base 标注其输入为多视角图像、机器人状态和可选语言指令，输出为连续动作。

如果你的目标是先建立一个可靠的训练基线，SmolVLA 通常比 Pi0/Pi0.5 更容易起步：它仍然是 VLA 模型，但环境与训练命令都在 LeRobot 官方栈内完成。

艾欧智能已经构建并发布 ioaitech/lerobot-gpu:v0.5.0 Docker 镜像。该镜像包含 LeRobot v0.5.0、GPU 训练依赖、视频解码依赖和 lerobot-train 命令，可直接用于 SmolVLA 微调。旧版本镜像用于复现历史实验，不建议作为新实验默认选择。

国内镜像

镜像默认发布在 Docker Hub：

  • ioaitech/lerobot-gpu:v0.5.0
  • ioaitech/lerobot-gpu:v0.4.4
  • ioaitech/lerobot-gpu:v0.3.3

中国大陆环境可加前缀，例如 swr.cn-east-3.myhuaweicloud.com/ioaitech/lerobot-gpu:v0.5.0。

版本选择​

LeRobot 数据格式版本与代码版本需要匹配。训练前先查看 meta/info.json 中的 codebase_version。

数据格式推荐镜像说明
v3.0ioaitech/lerobot-gpu:v0.5.0当前推荐路径，适合 SmolVLA 官方命令。
v3.0ioaitech/lerobot-gpu:v0.4.4用于复现较早的 v0.4 训练环境。
v2.1ioaitech/lerobot-gpu:v0.3.3用于旧数据格式或历史实验复现。

新实验建议统一导出或转换为 v3.0，减少版本兼容成本。

数据要求​

官方文档建议从约 50 个高质量 episode 起步，并保证每种任务变化有重复演示。官方示例中 50 个 episode 覆盖 5 个方块位置，每个位置 10 次；25 个 episode 的版本效果明显不足。这个结论不能机械套用到所有机器人，但它说明了数据覆盖比单纯增加训练步数更重要。

至少确认：

  • 图像字段在所有 episode 中一致。
  • observation.state 与 action 维度固定。
  • 任务文本与动作目标一致。
  • 训练集覆盖不同物体位置、光照和初始姿态。

使用镜像训练​

先检查 GPU 容器：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

最小验证​

docker run --rm --gpus all --shm-size 16g \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/outputs \
  ioaitech/lerobot-gpu:v0.5.0 \
  bash -lc 'lerobot-train \
    --policy.path=lerobot/smolvla_base \
    --dataset.repo_id=local/my_dataset \
    --dataset.root=/data/input \
    --batch_size=8 \
    --steps=1000 \
    --output_dir=/outputs/smolvla_smoke \
    --job_name=smolvla_smoke \
    --policy.device=cuda \
    --wandb.enable=false'

正式微调模板​

docker run --rm --gpus all --shm-size 16g \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/outputs \
  ioaitech/lerobot-gpu:v0.5.0 \
  bash -lc 'lerobot-train \
    --policy.path=lerobot/smolvla_base \
    --dataset.repo_id=local/my_dataset \
    --dataset.root=/data/input \
    --batch_size=64 \
    --steps=20000 \
    --output_dir=/outputs/smolvla_finetune \
    --job_name=smolvla_finetune \
    --policy.device=cuda \
    --wandb.enable=false'

官方文档给出的参考量级是：20k steps 在单张 A100 上约 4 小时。实际时间取决于图像分辨率、数据解码、batch size 与显卡型号。

如果使用 Hugging Face Hub 数据集，去掉 --dataset.root，并将 --dataset.repo_id 改为真实仓库名：

lerobot-train \
  --policy.path=lerobot/smolvla_base \
  --dataset.repo_id=your-name/your-dataset \
  --batch_size=64 \
  --steps=20000 \
  --output_dir=outputs/train/smolvla \
  --job_name=smolvla_finetune \
  --policy.device=cuda \
  --wandb.enable=true

安装 LeRobot 后训练​

本地安装请先阅读 安装 LeRobot。v0.5.0 要求 Python >=3.12，训练入口是安装后的 lerobot-train。

git clone https://github.com/huggingface/lerobot.git
cd lerobot
git checkout v0.5.0

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[smolvla]"

然后运行官方训练命令。下面保留本地数据路径写法：

lerobot-train \
  --policy.path=lerobot/smolvla_base \
  --dataset.repo_id=local/my_dataset \
  --dataset.root=/path/to/lerobot_dataset \
  --batch_size=64 \
  --steps=20000 \
  --output_dir=outputs/train/smolvla_finetune \
  --job_name=smolvla_finetune \
  --policy.device=cuda \
  --wandb.enable=false

如果需要完全对齐官方示例，可把数据上传到 Hugging Face Hub，仅保留 --dataset.repo_id=${HF_USER}/mydataset。

调参边界​

参数建议
--batch_size从显存能承受的较小值开始，再逐步增加。
--steps先用 1k steps 做 smoke test；正式训练从 20k 左右建立基线。
--policy.deviceNVIDIA GPU 使用 cuda；CPU 只适合功能验证。
--wandb.enable公开或长期实验建议开启；本地短测可关闭。
--output_dir每次实验使用独立目录，避免覆盖 checkpoint。

不要过早修改模型结构。先固定数据和训练命令，确认 loss、checkpoint 加载和最小推理都正常，再考虑 PEFT、学习率或动作 horizon 的变化。

快速推理检查​

训练完成后，至少加载一次 checkpoint，确认模型与输入字段匹配：

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

policy = SmolVLAPolicy.from_pretrained(
    "/path/to/output/smolvla_finetune/checkpoints/last",
    device="cuda",
)
policy.eval()

observation = {
    "observation.images.front": image_tensor,
    "observation.state": state_tensor,
}

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

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

如果这里报 key 或 shape 错误，优先检查数据集相机字段和 observation.state 维度，而不是先改训练超参。

排错​

命令中的 --policy.path 与旧文档不同​

LeRobot v0.5.0 官方 SmolVLA 文档使用 --policy.path=lerobot/smolvla_base。旧版文档中可能出现 --policy.type smolvla 或 --policy.pretrained_path，复现旧实验时要同时锁定 LeRobot 代码版本。

训练时视频解码失败​

LeRobot 新版本依赖视频解码组件，官方安装文档要求准备 ffmpeg。使用镜像时通常已内置；源码安装失败时先检查 ffmpeg 与 PyTorch/TorchCodec 版本。

Loss 下降但实机效果差​

先检查数据覆盖和任务文本一致性。SmolVLA 是基座模型微调，不会自动弥补数据中缺失的物体位置、相机角度或失败恢复样本。

参考链接​