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]"

1.1 数据版本与 tag 对应（务必一致）

数据集 codebase_version	推荐 LeRobot 代码版本
v2.1	v0.3.x
v3.0	v0.4+（含 v0.5.x）

# 训练 v2.1 数据集前
git checkout v0.3.3
pip install -e ".[all]"

# 训练 v3.0 数据集前
git checkout v0.5.0
pip install -e ".[all]"

这里要注意：v2.1 / v3.0 是 LeRobotDataset 格式版本，v0.4.0 / v0.5.0 是 lerobot 代码库版本。截至 lerobot v0.5.0，新版数据格式仍然是 v3.0。

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/info.json、data/、videos/ 以及对应版本的 episode 元数据：

your_dataset/
├── meta/
│   ├── info.json
│   ├── tasks.jsonl
│   ├── episodes.jsonl          # v2.1
│   └── episodes/               # v3.0
├── data/
│   └── chunk-000/
│       ├── episode_000000.parquet   # v2.1
│       └── file-000.parquet         # v3.0
└── videos/
    └── ...

数据质量要求

根据 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	策略类型	smolvla	SmolVLA 模型类型
--policy.pretrained_path	预训练模型路径	lerobot/smolvla_base	HuggingFace 上的官方预训练模型
--dataset.repo_id	数据集标识	local/mylerobot3	推荐本地训练用 local/xxx；也可以填 your-name/your-repo（Hub）
--dataset.root	数据集本地路径	~/Downloads/mylerobot3	仅当你使用本地数据集时需要（目录包含 meta/info.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	每次实际执行的动作数
--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 不匹配？
  先对齐数据集中的相机 key（如 cam_high）和 observation.state 维度；多为输入映射不一致，而非模型问题。
• Q：一上来就 OOM？
  先把 --batch_size 降到 16/8，并开启 --policy.use_amp true，--num_workers 降到 2 或 1。
• Q：Loss 几乎不降？
  先确认数据是否对齐（state/action 维度、时间对齐、动作平滑），再考虑调学习率和步数。

相关资源

• SmolVLA 官方博客
• LeRobot 官方文档
• SmolVLA 模型页面
• LeRobot GitHub 仓库