跳到主要内容

SmolVLA 模型微调

SmolVLA（Small Vision-Language-Action）是 Hugging Face 推出的轻量级 VLA 模型（约 450M 参数）。如果你想在单卡/消费级 GPU 上先把“数据 → 训练 → 推理”跑通，SmolVLA 通常是最省心的起点。

本文会带你完成三件事：

  • 准备 LeRobot 格式数据（本地或 Hub）
  • 启动微调训练（单卡/多卡/省显存）
  • 用训练产物做一个最小推理验证

先决条件​

系统要求​

  • 操作系统：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
    └── ...

数据质量要求​

根据 HuggingFace 的建议，SmolVLA 需要：

  • 最少 25 个高质量 episode 才能获得良好性能
  • 推荐 100+ episode 以获得最佳效果
  • 每个 episode 应包含完整的任务执行过程
  • 图像分辨率推荐 224x224 或 256x256

微调训练​

基本训练命令​

# 建议先把数据集“标识”和“路径”写清楚，后面命令就不容易写错
# - 本地数据集：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策略类型smolvlaSmolVLA 模型类型
--policy.pretrained_path预训练模型路径lerobot/smolvla_baseHuggingFace 上的官方预训练模型
--dataset.repo_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推送到Hubfalse是否上传模型到HuggingFace（需要repo_id）
--save_checkpoint保存检查点true是否保存训练检查点
--save_freq保存频率5000检查点保存间隔步数

模型特定参数​

参数含义推荐值说明
--policy.vlm_model_nameVLM骨干模型HuggingFaceTB/SmolVLM2-500M-Video-InstructSmolVLA 使用的视觉语言模型
--policy.chunk_size动作块大小50预测的动作序列长度
--policy.n_action_steps执行动作步数50每次实际执行的动作数
--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：是否接近上限（便于决定要不要降 batch / 开 amp）

快速验证（比“写评估脚本”更靠谱）​

很多时候你不需要先写一套完整评估：先用一帧真实输入跑通推理，就能快速排掉 80% 的坑（字段 key、维度、dtype、归一化等）。

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

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

# 下面两项建议直接从你的数据集中取“一帧真实值”
# 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，优先检查两件事：数据集字段名（如 cam_high 是否一致）和 state/action 维度（是否缺/多了 gripper、关节数是否一致）。

最佳实践（精简版）​

  • 数据：宁可少一点，但要“稳定且一致”（同一套相机命名/同一套 state/action 定义）。
  • 起步超参：先用能跑通的配置（比如 batch_size=16/32），确认 loss 正常再往上加。
  • 省显存三件套：--policy.use_amp true、减小 --batch_size、减小 --num_workers（先保稳定）。
  • 检查点：建议保留 checkpoints/last，这样推理和回归测试都更方便。

常见问题（FAQ）​

  • Q：训练能跑，但推理时报字段 key 不匹配？
    • A：先对齐数据集里的相机 key（比如 cam_high）以及 observation.state 的维度；这类问题通常不是“模型坏了”，而是输入映射不一致。
  • Q：一上来就 OOM？
    • A：先把 --batch_size 降到 16/8，再打开 --policy.use_amp true；同时把 --num_workers 降到 2 或 1。
  • Q：Loss 不怎么下降？
    • A：先确认数据是否“真对齐”（state/action 维度、时间对齐、动作是否平滑），再考虑调学习率和训练步数。

相关资源​