Дообучение модели SmolVLA

SmolVLA (Small Vision-Language-Action) — это легковесная модель VLA (около 450 млн параметров), выпущенная Hugging Face. Если вы хотите быстро пройти путь от «данных к обучению и инференсу» на одной видеокарте или даже на потребительском GPU, SmolVLA обычно является самой простой отправной точкой.

В этой статье мы разберем три этапа:

Подготовка данных в формате LeRobot (локально или на Hub).
Запуск дообучения (одна карта / несколько карт / оптимизация памяти).
Минимальная проверка инференса на обученной модели.

Предварительные требования

Системные требования

ОС: Linux (рекомендуется Ubuntu 20.04+) или macOS.
Версия Python: рекомендуется 3.10+ (лучше соответствует зависимостям LeRobot).
GPU: NVIDIA GPU (рекомендуется RTX 3080 или выше) с минимум 8 ГБ видеопамяти.
ОЗУ: минимум 16 ГБ.
Место на диске: минимум 50 ГБ свободного пространства.

Подготовка окружения

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.

Обучение (Fine-tuning)

Базовая команда обучения

# Четко определите 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`	Официальная предобученная модель на Hub
`--dataset.repo_id`	ID датасета	`local/mylerobot3`	`local/xxx` для локальных данных; или `your-name/your-repo` (Hub)
`--dataset.root`	Локальный путь	`~/Downloads/mylerobot3`	Только для локальных данных (каталог с `meta.json`, `data/` и т.д.)
`--batch_size`	Размер батча	`64`	Зависит от VRAM, 32-64 для RTX 3080
`--steps`	Шаги обучения	`20000`	Можно уменьшить до 10000 для малых данных
`--output_dir`	Директория вывода	`outputs/train/smolvla_finetuned`	Путь сохранения модели
`--job_name`	Имя задачи	`smolvla_finetuning`	Для логов и отслеживания (опционально)

Параметры обучения

Параметр	Значение	Рекомендуемое	Описание
`--policy.optimizer_lr`	Скорость обучения	`1e-4`	Можно немного снизить при дообучении
`--policy.scheduler_warmup_steps`	Шаги прогрева	`1000`	Прогрев LR для стабильности обучения
`--policy.use_amp`	Использование 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`	VLM модель, используемая в 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 "ваше примечание"
Рекомендуемые метрики:
- Loss / Action Loss: должен стабильно снижаться без резких скачков.
- Learning Rate: проверка корректности после этапа прогрева.
- GPU Memory: контроль заполнения памяти (для решения об изменении батча или включении AMP).

Быстрая проверка (надежнее, чем написание скриптов оценки)

Часто не нужно сразу писать полноценную систему оценки: запустите инференс на одном реальном кадре, чтобы быстро отсечь 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()

# Рекомендуется взять реальные данные из вашего датасета для проверки:
# 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 (наличие захвата, количество суставов).

Лучшие практики (кратко)

Данные: лучше меньше, но «стабильнее и единообразнее» (одинаковые имена камер, одинаковые определения state/action).
Начальные параметры: начните с работающей конфигурации (например, batch_size=16/32), убедитесь, что лосс в норме, и только потом повышайте значения.
Трио экономии памяти: --policy.use_amp true, уменьшение --batch_size, уменьшение --num_workers.
Чекпоинты: сохраняйте checkpoints/last для удобства тестирования и инференса.

Часто задаваемые вопросы (FAQ)

В: Обучение идет, но при инференсе ошибка несовпадения ключей?
- О: Сначала сопоставьте ключи камер (например, cam_high) и размерность observation.state в датасете. Обычно проблема в несовпадении маппинга, а не в самой модели.
В: OOM сразу при запуске?
- О: Снизьте --batch_size до 16/8, включите --policy.use_amp true, а также снизьте --num_workers до 2 или 1.
В: Лосс почти не снижается?
- О: Проверьте «реальную состыковку» данных (размерности state/action, синхронизация по времени, плавность движений), прежде чем менять скорость обучения или количество шагов.

Предварительные требования​

Системные требования​

Подготовка окружения​

1. Установка LeRobot​

2. Установка дополнительных зависимостей​

Подготовка данных​

Данные в формате LeRobot​

Требования к качеству данных​

Обучение (Fine-tuning)​

Базовая команда обучения​

Расширенные настройки обучения​

Обучение на нескольких GPU​

Настройка для оптимизации памяти​

Детальное описание параметров​

Основные параметры​

Параметры обучения​

Специфические параметры модели​

Мониторинг обучения​

Быстрая проверка (надежнее, чем написание скриптов оценки)​

Лучшие практики (кратко)​

Часто задаваемые вопросы (FAQ)​

Дополнительные ресурсы​