Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

LeRobot SO-101: сборка, калибровка, запись, обучение и запуск

Это руководство следует официальной документации Hugging Face LeRobot для ведущей и ведомой рук SO-101, добавляет проверки, которые сборщики чаще всего упускают, и заканчивается мобильной базой LeKiwi и контрольным списком по устранению неполадок. Команды соответствуют LeRobot v0.7.0 (выпущена 5 ноября 2026 года). LeRobot быстро меняется, поэтому сверяйте флаги с документацией той версии, которую устанавливаете.

Что вы построите и что для этого нужно

LeRobot — библиотека для робототехники с открытым исходным кодом от Hugging Face. Один набор команд двигает робота, записывает демонстрации, обучает политику и запускает её. SO-101 — флагманская рука этого проекта: вы двигаете ведущую руку вручную, ведомая рука повторяет движение, а записанные движения и изображения с камер учат нейронную сеть самостоятельно повторять задачу.

Работа состоит из семи этапов: подобрать детали и установить программы, задать каждому мотору ID, собрать обе руки, откалибровать их, настроить телеуправление с камерами, записать датасет, а затем обучить политику и запустить её. В последнем разделе о сборке добавляется мобильная база LeKiwi, а за ним идёт контрольный список по устранению неполадок.

Прокрутите вбок, чтобы увидеть весь рисунок.

Семь этапов сборки и команда, которая выполняет каждый из нихНумерованный список из семи этапов сверху вниз. 1 Детали и программы: pip install lerobot. 2 Порты и ID моторов: lerobot-find-port и lerobot-setup-motors. 3 Сборка обеих рук, вручную. 4 Калибровка: lerobot-calibrate. 5 Телеуправление с камерами: lerobot-find-cameras и lerobot-teleoperate. 6 Запись датасета: lerobot-record, а для проверки — lerobot-replay. 7 Обучение и запуск политики: lerobot-train, затем lerobot-rollout.1Детали и программыЗакупка и установка LeRobotpip install lerobot2Порты и ID моторовПо одному сервоприводуlerobot-find-portlerobot-setup-motors3Сборка обеих рукСустав за суставом, обе рукиБез команды: собирается вручную4КалибровкаОдинаковые числа у обеих рукlerobot-calibrate5Телеуправление и камерыВедущая рука двигает ведомуюlerobot-find-cameraslerobot-teleoperate6Запись датасетаПоложения суставов и видеоlerobot-recordlerobot-replay7Обучение и запуск моделиПолитика ACT на ведомой рукеlerobot-trainlerobot-rollout
Семь этапов сборки и команда, которая выполняет каждый из них

Вам понадобятся две руки (детали — в следующем разделе), USB-плата управления сервоприводами на последовательной шине и блок питания для каждой руки, компьютер с Python 3.12 или новее, две USB-камеры (в командах этого руководства используются две), бесплатная учётная запись Hugging Face для датасетов и контрольных точек и GPU для обучения. Для политики ACT, которая используется здесь, достаточно GPU уровня ноутбука; подойдёт и арендованный GPU.

Мы составили это руководство по официальной документации и отчётам сообщества о сборке и не проверяли каждый шаг на стенде для каждой ревизии оборудования. Более старые руководства, в которых вызывается control_robot.py, не подходят для версии 0.7.0, где используются команды lerobot-*.

Детали, печать и питание

Проект SO-101 публикует спецификацию материалов и файлы для печати; ссылки на них есть на странице SO-101 в Hugging Face. Для полной пары из ведущей и ведомой руки нужны 12 сервоприводов Feetech STS3215, две платы управления, два блока питания, два кабеля USB-C и струбцины для стола. В сборке используются винты M2×6 и M3×6; в спецификации материалов проекта их нет, поэтому проверьте, что входит в комплект ваших сервоприводов или набора. Напечатанные детали и готовые комплекты тоже продаются.

Ведомая рука использует шесть сервоприводов с передаточным числом 1/345. В ведущей руке используются три разных передаточных числа, поэтому она удерживает собственный вес и при этом двигается с небольшим усилием.

Подберите блок питания под сервоприводы. Сервопривод STS3215 на 7,4 В имеет стопорный момент 16,5 кг·см при 6 В (при питании 5 В немного меньше) и обычно работает от блока питания на 5 В. Ведомая рука может использовать сервоприводы на 12 В (30 кг·см) для большей мощности, но тогда ей нужен блок питания на 12 В, рассчитанный на ток 5 А или больше; ведущая рука всегда использует сервоприводы на 7,4 В. Никогда не подключайте блок питания на 12 В к плате, на которой стоят сервоприводы на 7,4 В; подпишите каждый блок питания, указав его напряжение и руку, к которой он относится.

Прокрутите вбок, чтобы увидеть весь рисунок.

Питание и USB для ведущей и ведомой рукиВверху компьютер, подключённый кабелем USB-C к плате управления ведущей руки и к плате управления ведомой руки. У каждой платы управления свой блок питания. От каждой платы цепочкой соединены шесть сервоприводов, начиная с сервопривода 1, 3-контактными кабелями. Ведущая рука всегда использует сервоприводы 7,4 В с блоком питания 5 В. Ведомая рука использует сервоприводы 7,4 В с блоком питания 5 В либо сервоприводы 12 В с блоком питания 12 В, рассчитанным на 5 А или больше. На плате Waveshare обе перемычки стоят на канале B — канале USB.КомпьютерВедущая рукаПитание 5 ВКонтроллерПлата Waveshare:обе перемычки наканале B (USB).1234566 сервоприводов7,4 В на 5 В.Ведомая рукаПитание: 5 Вили 12 В, 5 А+КонтроллерПлата Waveshare:обе перемычки наканале B (USB).123456Сервоприводы7,4 В на 5 Вили 12 В на 12 В.ПитаниеUSB-C3-контактный кабельНикогда не подключайте питание 12 В к плате с сервоприводами 7,4 В.
Питание и USB для ведущей и ведомой руки

Печатайте из PLA+ соплом 0,4 мм со слоем 0,2 мм (или соплом 0,6 мм со слоем 0,4 мм) и заполнением 15%. Детали каждой руки поставляются одним файлом с ориентацией, при которой нужно мало поддержек; не ставьте поддержки в горизонтальные отверстия под винты. Сначала напечатайте тестовые детали Gauge Zero и Gauge Tight и примерьте их к сервоприводу; если Gauge Zero не встаёт так, как показано в видео проекта, подстройте параметры принтера и напечатайте её заново, прежде чем печатать руки.

Подготовьте крестовые отвёртки Phillips #0 и #1 и до проверки закрепите каждое основание на столе струбциной. Ссылки на детали, которые мы поставляем для этой сборки, приведены ниже.

Прокрутите таблицу вбок, чтобы сравнить все столбцы.

СуставID мотораПередаточное число ведущей рукиПередаточное число ведомой руки
Поворот плеча11/1911/345
Подъём плеча21/3451/345
Сгиб локтя31/1911/345
Сгиб запястья41/1471/345
Вращение запястья51/1471/345
Захват61/1471/345

Установка LeRobot и поддержки моторов

LeRobot 0.7.0 требует Python 3.12 или новее. Создайте изолированное окружение с помощью conda (из miniforge) или uv и активируйте его в каждом новом терминале. Для видео на большинстве платформ нужен ffmpeg (на macOS Intel и на 32-разрядном ARM Linux LeRobot переключается на PyAV, и ffmpeg можно пропустить); пакет conda подходит для любой версии PyTorch.

Создать окружение
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

Установите LeRobot из PyPI с нужными дополнениями (extras). core_scripts добавляет то, что используют запись, воспроизведение и калибровка, feetech добавляет поддержку сервоприводов STS3215, а training — инструменты обучения.

Установить LeRobot с дополнениями
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'

Особенности платформ: на Apple silicon PyTorch требует macOS 14 или новее, а для ускорения на GPU (MPS) — macOS 15 или новее. Чтобы использовать GPU NVIDIA в Linux, стандартные сборки PyTorch требуют драйвер 580.65 или новее; при более старом драйвере сначала установите подходящую сборку PyTorch с CUDA и возьмите torchcodec из индекса для CPU (см. страницу установки в Hugging Face). В WSL дополнительно установите evdev (conda install evdev -c conda-forge или, при работе с uv, sudo apt install libevdev-dev, а затем uv pip install evdev). С PyTorch 2.10 или новее можно использовать системный ffmpeg вместо ffmpeg из conda.

Поиск портов и назначение ID моторов

Новые сервоприводы STS3215 обычно поставляются с ID 1, а контроллер и каждый сервопривод должны использовать одну скорость обмена (baud rate). LeRobot один раз записывает оба значения в память каждого сервопривода, поэтому сделайте это до сборки и подключайте по одному сервоприводу. Сервоприводы, снятые с другого робота, вероятно, тоже нужно настроить.

Прокрутите вбок, чтобы увидеть весь рисунок.

Шесть суставов руки SO-101 и ID мотора каждого из нихВид сбоку на руку робота. Сустав 1, поворот плеча, поворачивает всю руку вокруг вертикальной оси в основании. Суставы 2, 3 и 4 — подъём плеча, сгиб локтя и сгиб запястья — сгибают руку в одной плоскости. Сустав 5, вращение запястья, поворачивает захват вокруг оси предплечья. Сустав 6 — захват. ID мотора каждого сустава равен его номеру. Длины звеньев и оси соответствуют официальной модели SO-101.1234561Поворот плеча2Подъём плеча3Сгиб локтя4Сгиб запястья5Вращение запястья6ЗахватID = номер сустава.Настраивайте от 6 до 1.Ведомая рука, вид сбоку, пропорции по официальноймодели SO-101.На ведущей руке сустав 6 — курок.
Шесть суставов руки SO-101 и ID мотора каждого из них

Подключите плату управления к компьютеру по USB, подайте питание и запустите утилиту поиска портов. Когда скрипт попросит, отсоедините USB-кабель только этой платы и нажмите Enter; скрипт выведет порт, например /dev/ttyACM0 в Linux, /dev/tty.usbmodem… в macOS или COM3 в Windows. Подключите кабель обратно и повторите то же для второй платы. В Linux может понадобиться разрешить доступ командой sudo chmod 666 для каждого порта (например, /dev/ttyACM0 и /dev/ttyACM1).

Найти порт платы управления
lerobot-find-port

Запустите скрипт настройки для ведомой руки, затем для ведущей, каждый раз с её собственным портом. Скрипт называет моторы по одному, поэтому прочитайте шаги ниже, прежде чем его запускать.

Задать ID моторов ведомой руки
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

Для ведущей руки используются параметры телеоператора вместо параметров робота. На каждом запросе берите мотор с тем передаточным числом, которое указано для этого сустава в таблице в разделе о деталях (на ведущей руке 1/191 для поворота плеча и сгиба локтя, 1/345 для подъёма плеча и 1/147 для сгиба запястья, вращения запястья и захвата), и подписывайте каждый мотор его ID, как только скрипт сообщит, что ID задан.

Задать ID моторов ведущей руки
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. Скрипт называет моторы по одному, начиная с захвата (ID 6) и заканчивая поворотом плеча (ID 1). Подключите к плате управления только этот мотор; он не должен быть соединён цепочкой ни с каким другим мотором.
  2. Нажмите Enter. Когда скрипт сообщит, что ID задан, отсоедините кабель этого мотора от платы, подключите следующий мотор, который назовёт скрипт, и снова нажмите Enter.
  3. Перед каждым нажатием Enter проверяйте питание, USB и 3-контактные кабели. Если скрипт сообщает об ошибке, сначала проверьте эти кабели; на плате Waveshare обе перемычки должны стоять на канале B (USB).
  4. Когда скрипт завершится, соедините моторы в цепочку по порядку и подключите мотор поворота плеча (ID 1) к плате управления.

    Прокрутите вбок, чтобы увидеть весь рисунок.

    Назначение ID по одному сервоприводу, затем соединение сервоприводов цепочкой по порядкуВерхняя панель: при назначении ID к плате управления подключён только один сервопривод. Скрипт настройки называет сервоприводы в порядке 6, 5, 4, 3, 2, 1. Нижняя панель: после настройки сервоприводы соединены цепочкой по порядку. Сервопривод 1 подключается к плате управления, а каждый следующий — к предыдущему, вплоть до сервопривода 6.При назначении IDПодключён только настраиваемый сервопривод. Отсоедините его, затемподключите следующий, который назовёт скрипт.Контроллер?Порядок по запросу скрипта654321После настройкиСоедините сервоприводы цепочкой по порядку. Сервопривод 1 идёт к платеуправления.Контроллер123456
    Назначение ID по одному сервоприводу, затем соединение сервоприводов цепочкой по порядку

Сборка ведущей и ведомой рук

Обе руки используют в основном одинаковые напечатанные детали и собираются в одном порядке (деталь вращения запястья отличается, а на ведущей руке рукоятка и курок стоят там, где у ведомой подвижная губка): основание и плечо, верхнее звено руки, предплечье, запястье, затем захват на ведомой руке или рукоятка и курок на ведущей. Hugging Face публикует короткое видео для каждого сустава на своей странице SO-101; смотрите его вместе с этими заметками. Сначала удалите весь поддерживающий материал с напечатанных деталей и вставьте 3-контактный кабель в каждый сервопривод до того, как закроете его корпусом.

  1. Сустав 1, поворот плеча: наденьте обе качалки на мотор и закрепите верхнюю винтом M3×6 (для нижней винт не нужен). Установите мотор в основание четырьмя винтами M2×6, наденьте первый держатель мотора и закрепите двумя M2×6, прикрепите плечо четырьмя M3×6 сверху и четырьмя снизу, затем добавьте держатель мотора плеча.
  2. Сустав 2, подъём плеча: наденьте обе качалки и закрепите верхнюю винтом M3×6 (для нижней винт не нужен), вставьте мотор сверху, закрепите его четырьмя M2×6, затем прикрепите верхнее звено руки четырьмя M3×6 с каждой стороны.
  3. Сустав 3, локоть: наденьте обе качалки и закрепите верхнюю винтом M3×6 (для нижней винт не нужен), вставьте мотор 3 и закрепите его четырьмя M2×6, затем соедините с ним предплечье четырьмя M3×6 с каждой стороны.
  4. Сустав 4, сгиб запястья: наденьте обе качалки и закрепите верхнюю винтом M3×6 (для нижней винт не нужен), надвиньте держатель мотора 4, вставьте мотор 4 и закрепите его четырьмя M2×6.
  5. Сустав 5, вращение запястья: установите мотор 5 в держатель запястья двумя M2×6 спереди, наденьте одну качалку и закрепите её винтом M3×6, затем прикрепите запястье к мотору 4 винтами M3×6, как показано в официальном видео по суставу 5 (в письменной инструкции сказано: по четыре с обеих сторон).
  6. Захват ведомой руки: прикрепите захват к качалке мотора запястья четырьмя M3×6, установите мотор захвата по две M2×6 с каждой стороны, наденьте обе качалки и закрепите верхнюю винтом M3×6 (для нижней винт не нужен), а подвижную губку закрепите винтами M3×6, как показано в официальном видео по захвату (в письменной инструкции сказано: по четыре с обеих сторон).
  7. Рукоятка ведущей руки: установите держатель ведущей руки на запястье четырьмя M3×6, прикрепите к нему рукоятку одним M2×6, установите мотор 6 — мотор курка (в официальной инструкции он назван мотором захвата) — по две M2×6 с каждой стороны, наденьте качалку и закрепите её винтом M3×6, затем прикрепите курок четырьмя M3×6.
  8. Прежде чем подавать питание, медленно проверните каждый сустав вручную по всему диапазону и никогда не проворачивайте его силой за упор; он должен двигаться без задеваний. Подпишите каждый мотор его ID до того, как закроете его корпусом, и закрепите оба основания на столе струбцинами.

Калибровка обеих рук

Калибровка записывает диапазон каждого сустава, чтобы ведущая и ведомая рука сообщали одинаковые числа в одинаковой физической позе. Она также позволяет политике, обученной на одном роботе, работать на другом. Выполняйте её один раз для каждой руки и повторно — после изменения в оборудовании или когда LeRobot сообщает об отсутствии калибровки. Записи и политики, сделанные до перекалибровки, использовали прежнюю калибровку.

Сначала откалибруйте ведомую руку. Скрипт просит установить каждый сустав в середину его диапазона и нажать Enter, а затем провести каждый сустав через весь диапазон движения и снова нажать Enter, когда каждый сустав его пройдёт. Дайте каждой руке уникальный id; по этому имени называется её файл калибровки. В командах этого руководства в качестве примеров используются /dev/ttyACM0 для ведомой руки и /dev/ttyACM1 для ведущей: замените их найденными вами портами и не путайте руки местами.

Прокрутите вбок, чтобы увидеть весь рисунок.

Калибровка: сначала середина диапазона каждого сустава, затем весь его диапазонДве панели рядом. Шаг 1: каждый из шести суставов удерживается в середине своего диапазона (на рисунке это точка в центре полосы), затем вы нажимаете Enter. Шаг 2: каждый из шести суставов проводится через весь свой диапазон (двойная стрелка от минимального до максимального конца полосы). Внизу: одна и та же физическая поза даёт одинаковые значения положения на ведущей и ведомой руке.Шаг 1: середина диапазонаУстановите каждый сустав в серединудиапазона и нажмите Enter.123456серединаШаг 2: весь диапазонПроведите каждый сустав через весьдиапазон и снова нажмите Enter.123456мин.макс.Та же поза — те же значения положения у ведущей и ведомой руки.
Калибровка: сначала середина диапазона каждого сустава, затем весь его диапазон
Откалибровать ведомую руку
lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm

Затем откалибруйте ведущую руку теми же движениями.

Откалибровать ведущую руку
lerobot-calibrate \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

Во всех следующих командах используйте тот же id: так LeRobot находит файл калибровки, который по умолчанию хранится в ~/.cache/huggingface/lerobot/calibration. Сделайте его резервную копию и не держите его во временных папках: один из участников сообщества потерял файлы калибровки при выключении и повторном включении питания и выполнил калибровку заново, не поставив каждый сустав в середину его диапазона, из-за чего у некоторых суставов оказались неверные смещения нуля (homing offsets).

Телеуправление ведомой рукой с помощью ведущей

Телеуправление соединяет две руки: ведомая рука копирует ведущую. Если калибровки нет, команда сначала запускает процедуру калибровки. Начинайте с небольших медленных движений, держитесь подальше от суставов ведомой руки и держите блок питания в пределах досягаемости.

Телеуправление
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

Далее добавьте камеры. Выведите их список утилитой поиска камер, которая печатает идентификатор каждой камеры и сохраняет из каждой тестовый кадр в outputs/captured_images; откройте кадры, чтобы понять, какой индекс какой камере соответствует. Индексы могут измениться после перезагрузки или при повторном подключении камеры.

Показать список камер
lerobot-find-cameras opencv

Снова запустите телеуправление с подключёнными камерами и просмотром в реальном времени в Rerun. Имена камер, которые вы выберете здесь, например top и wrist, позже станут ключами датасета, поэтому с этого момента используйте те же имена и настройки.

Телеуправление с камерами и просмотром в реальном времени
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm \
    --display_data=true

Расстановка камер, чтобы политика могла учиться

Политика видит только изображения с камер и положения суставов, поэтому хорошая установка камер важнее высокого разрешения. Для большинства задач достаточно 640×480 при 30 кадрах/с — это ускоряет запись и обучение.

Прокрутите вбок, чтобы увидеть весь рисунок.

Расстановка камер: неподвижные виды задачи, ровный свет и имена, которые становятся ключами датасетаВид сбоку на рабочую зону. Ведомая рука тянется к предмету рядом с целевым контейнером. Верхняя камера на стойке над столом смотрит вниз на всю рабочую зону; её поле зрения показано затенённой областью, охватывающей руку, предмет и цель. Камера на запястье закреплена на захвате и смотрит вдоль губок. Мягкая световая панель вверху слева равномерно освещает сцену. Камеры остаются неподвижными между записью и запуском. Имена камер становятся ключами датасета, observation.images.top и observation.images.wrist.Рассеянный светПредметЦельверхняя камеракамера на запястьеЖёстко закреплены: не двигайте камеры между записью и запуском.Имена камер — ключи датасета:observation.images.topobservation.images.wrist
Расстановка камер: неподвижные виды задачи, ровный свет и имена, которые становятся ключами датасета
  1. Освещайте сцену равномерным рассеянным светом. Избегайте прямого солнечного света, сильных бликов и движущихся теней: различия в освещении между записью и запуском могут привести к сбоям политики.
  2. Жёстко закрепите камеры и не двигайте их между записью и запуском. Первая политика одного из участников сообщества лишь клевала стол, и одной из нескольких причин было то, что камеры слегка сместились между записью и проверкой.
  3. Выберите кадр под задачу: объект, захват и цель должны быть видны хотя бы в одной камере. Хорошая проверка — смогли бы вы сами выполнить задачу только по изображениям с камер. Тот же участник сообщества показывал демонстрации, глядя только на изображение с камер; если попробуете так делать, держите блок питания в пределах досягаемости.
  4. Тот же участник заменил боковую камеру, у которой в момент схватывания плохо были видны кончики захвата, верхней камерой рядом с фронтальной, и это уменьшило перекрытие обзора; камера на запястье упоминается в той публикации только как следующий шаг. Если вы записываете в течение дня, зафиксируйте экспозицию и баланс белого в собственных настройках веб-камеры; конфигурация камеры RealSense в LeRobot также принимает exposure, gain и white_balance.
  5. С двумя одинаковыми веб-камерами в Ubuntu USB-адреса могут поменяться местами, и запись может остановиться с ошибкой камеры. Тот же участник решил это правилами udev, которые определяют каждую камеру по её физическому USB-порту, поэтому держите каждую камеру в одном и том же порту; иначе после каждой перезагрузки снова запускайте утилиту поиска камер.

Запись датасета

Датасеты используют формат LeRobotDataset и загружаются в Hugging Face Hub. Создайте бесплатную учётную запись, выпустите в настройках Hugging Face токен с правом записи, затем войдите в систему и сохраните своё имя пользователя в переменной. Сначала задайте переменную HUGGINGFACE_TOKEN со своим токеном или выполните hf auth login отдельно и вставьте токен, когда его запросят.

Войти в Hugging Face
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

Сначала запишите пять эпизодов, чтобы проверить настройку. Используйте тот же id робота, те же порты и настройки камер, что и при телеуправлении, и опишите задачу простыми словами.

Записать датасет
lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube" \
    --dataset.streaming_encoding=true

LeRobot добавляет к имени датасета дату и время, поэтому ${HF_USER}/record-test сохраняется как ${HF_USER}/record-test_YYYYMMDD_HHMMSS. Используйте это полное имя в следующих командах; найти его можно командой ls ~/.cache/huggingface/lerobot/${HF_USER}, а чтобы оставить переданное вами имя, добавьте --dataset.no_stamp=true. Датасет хранится в ~/.cache/huggingface/lerobot и по окончании записи отправляется в Hub. Датасет, отправленный из личной учётной записи, может быть общедоступным, поэтому проверьте его видимость в Hub и добавьте --dataset.private=true, если он должен быть приватным; добавьте --dataset.push_to_hub=False, чтобы оставить его только на компьютере. Чтобы продолжить прерванный сеанс, повторите команду с --resume=true, полным --dataset.repo_id с меткой времени, --dataset.root, указывающим на локальную папку датасета, и --dataset.num_episodes, равным числу дополнительных эпизодов, а не общему числу.

Длительность эпизода и время сброса по умолчанию равны 60 секундам (--dataset.episode_time_s и --dataset.reset_time_s), а число эпизодов по умолчанию — 50. Во время записи ходом управляет клавиатура, как показано в таблице ниже.

Для первого полезного датасета выберите простую задачу, например взять предмет из нескольких положений и положить его в корзину. Запишите не менее 50 эпизодов, примерно по 10 на каждое положение, сохраняйте единообразие камер и способа захвата и добавляйте разнообразие постепенно. Перезаписывайте неудачные эпизоды. Пятьдесят эпизодов в фиксированных положениях — это отправная точка; ожидайте, что политика будет работать в основном вблизи записанных вами положений. LeRobot печатает строку с частотой после каждого сохранённого эпизода и сводку по окончании записи. Если частота значительно ниже целевых 30 Гц, датасет всё равно заявляет 30 Гц, поэтому движение выглядит быстрее, чем было. Найдите, что замедляет цикл (в примере из документации это было чтение с камер), и перезапишите затронутые эпизоды вместо того, чтобы обучаться на них.

Проверьте данные до обучения. Откройте датасет в визуализаторе датасетов LeRobot на Hugging Face и воспроизведите эпизод на роботе, чтобы убедиться, что движение повторяется. Воспроизведение двигает руку без вашего участия, поэтому освободите рабочую зону, приведите руку в положение, близкое к первой позе эпизода, и держите блок питания в пределах досягаемости.

Воспроизвести эпизод
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --dataset.episode=0

Прокрутите таблицу вбок, чтобы сравнить все столбцы.

КлавишаДействие
Стрелка вправо или nДосрочно закончить эпизод или период сброса и перейти дальше
Стрелка влево или rОтбросить текущий эпизод и записать его заново
Esc или qОстановить сеанс: текущий эпизод сохраняется, затем кодируются видео и загружается датасет (чтобы отбросить этот эпизод, сначала нажмите стрелку влево или r)

Обучение политики ACT

ACT (Action Chunking Transformer) — политика, которая используется в учебнике LeRobot: она подстраивается под моторы и камеры, сохранённые в вашем датасете. Руководство по оборудованию оценивает лёгкие политики (ACT, VQ-BeT, TD-MPC) примерно от 2 до 6 ГБ памяти GPU при размере батча 8 — как ориентировочную цифру. Обучайте на GPU NVIDIA (cuda); на Apple silicon измените команду, указав --policy.device=mps, для чего нужна macOS 15 или новее (в macOS 14 LeRobot переключается на CPU, который не подходит для обучения).

Запустите обучение с полным именем датасета.

Обучить политику ACT
lerobot-train \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --policy.type=act \
    --output_dir=outputs/train/act_so101_test \
    --job_name=act_so101_test \
    --policy.device=cuda \
    --trackio.enable=true \
    --policy.repo_id=${HF_USER}/my_policy \
    --steps=20000

Без --steps обучение идёт 100 000 шагов — обычно больше, чем нужно небольшому датасету: имитационное обучение, как правило, сходится за 5–10 проходов по данным. Датасет из 50 эпизодов по 30 секунд при 30 кадрах/с содержит около 45 000 кадров, что при размере батча 8 составляет около 5 600 шагов на проход, поэтому 5–10 проходов — это примерно от 28 000 до 56 000 шагов. Команда выше использует --steps=20000, около трёх с половиной проходов, как короткий первый запуск; увеличьте значение, если политика недообучена, а если уменьшите его сильно, задайте также --policy.scheduler_decay_steps близким к --steps. Руководство по оборудованию оценивает пять проходов ACT при размере батча 8 примерно в 30–60 минут на RTX 3090 или 4090 и 1–2 часа на L4 или A10G, а 6–14 часов при размере батча 4 — на M1, M2 или M3 Max; оно называет эти цифры ориентировочными и говорит, что реальные запуски могут отличаться примерно на 50%.

Если подходящего GPU нет, обучайте в Google Colab с ноутбуком для ACT или выполните hf auth login и добавьте к той же команде конфигурацию (flavor) Hugging Face Jobs, например --job.target=a10g-small. Поскольку эта команда включает Trackio, заданию также нужен --trackio.space_id=<user>/<space> (добавьте --trackio.private=true, чтобы Space был приватным) либо уберите --trackio.enable=true. Задания (jobs) тарифицируются посекундно и ограничены 48 часами, если вы не задали --job.timeout; кроме того, они сами загружают локальный датасет в приватный репозиторий и отправляют обученную модель по окончании; hf jobs hardware выводит список конфигураций.

Контрольные точки записываются в outputs/train/act_so101_test/checkpoints. Возобновите прерванный запуск с последней контрольной точки. Поскольку команда обучения задаёт --policy.repo_id=${HF_USER}/my_policy, готовая модель в конце отправляется в этот репозиторий (--policy.push_to_hub=false отключает это, --policy.private=true делает репозиторий приватным); чтобы загрузить контрольную точку самостоятельно, используйте то же имя репозитория, чтобы --policy.path=${HF_USER}/my_policy её нашёл.

Продолжить обучение и загрузить модель
lerobot-train \
    --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
    --resume=true

hf upload ${HF_USER}/my_policy \
    outputs/train/act_so101_test/checkpoints/last/pretrained_model

Скрипт обучения LeRobot не оценивает политики на реальных роботах, поэтому оставьте часть эпизодов вне обучения, включая начальные положения, которых вы не записывали, и проверьте политику на них. Один из участников сообщества обучил политику на 50 эпизодах (по 10 в каждой из пяти областей начальных положений) и получил 60% успеха на новых эпизодах из этих областей, но лишь 10% на эпизодах из области, исключённой из обучения. После увеличения данных до 25 эпизодов на область тот же участник достиг 90% и 75%. Это небольшие выборки, оценённые собственными скриптами участника.

Запуск политики на ведомой руке

Запустите обученную политику командой lerobot-rollout. Используйте тот же id робота, имена камер, настройки камер и текст задачи, что и при записи, и снова запустите утилиту поиска портов, если после записи вы перезагружали компьютер или переподключали устройства. --duration задаётся в секундах; без него политика работает, пока вы её не остановите.

Запустить политику на роботе
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --task="Grab the black cube" \
    --duration=60

Стратегия определяет, что происходит во время запуска, как показано в таблице ниже. Стратегии, которая записывает датасет, нужно имя репозитория, начинающееся с rollout_ после вашего имени пользователя, например --dataset.repo_id=${HF_USER}/rollout_so101_test; к нему добавляется метка времени. Стратегии записи, такие как sentry, принимают --dataset.single_task вместо --task; флаги каждой стратегии смотрите в документации LeRobot.

В LeRobot v0.5.x и более ранних версиях команды lerobot-rollout нет; используйте lerobot-record, как описано в документации v0.5.1. Флаги обучения в этом руководстве рассчитаны на текущий выпуск.

В первый раз запускайте с короткой длительностью (например, 15 секунд), свободной рабочей зоной и продуманным планом, как вы остановите руку; отключение питания освобождает моторы, поэтому рука, которая ни на что не опирается, может упасть. Если рука клюёт стол или тянется слишком далеко, проверьте настройку, прежде чем винить модель: тот же id калибровки, камеры в тех же местах с теми же именами и разрешением, то же освещение и предметы в положениях, которые охватывает датасет.

Прокрутите таблицу вбок, чтобы сравнить все столбцы.

СтратегияЧто делает
baseРаботает автономно без записи, для быстрых проверок
sentryЗаписывает непрерывно и загружает данные автоматически
highlightХранит кольцевой буфер и сохраняет его по нажатию клавиши
daggerСбор данных с участием человека
episodicЗаписывает эпизод за эпизодом с фазами сброса между ними

Расширение сборки с LeKiwi

LeKiwi — трёхколёсная мобильная база, которая несёт ведомую руку SO-101. Роботом управляет Raspberry Pi или другой компьютер с питанием 5 В и достаточным числом USB-портов для камер и платы управления моторами (на странице LeKiwi сказано: два или больше), а вы управляете им с ноутбука при помощи ведущей руки и клавиатуры. В проводной версии всё работает на ноутбуке, и шаги с Pi можно пропустить. Список деталей, файлы для печати и инструкции по сборке базы берутся из проекта LeKiwi, ссылка на который есть на странице LeKiwi в Hugging Face.

Прокрутите вбок, чтобы увидеть весь рисунок.

LeKiwi: ноутбук управляет роботом по сети, а Raspberry Pi управляет моторамиСлева — ноутбук с ведущей рукой, клавиатурой и скриптом teleoperate.py. Справа — робот LeKiwi: Raspberry Pi с запущенным lekiwi_host, подключённый по USB к плате управления моторами и к камерам. Плата управления приводит в движение моторы руки (ID с 6 по 1) и моторы колёс (ID 9, 8 и 7). Ноутбук и Pi обмениваются данными по одной сети с помощью ZeroMQ: порт 5555 — для команд, порт 5556 — для наблюдений. В проводной версии всё работает на ноутбуке.НоутбукВедущая рука (USB)Клавиатураteleoperate.pyВ примере укажите адрес Piв remote_ip.Одна сетьZeroMQ5555, 5556Робот LeKiwiRaspberry Pi(хост)lekiwi_hostКонтроллерКамерыМоторы рукиID 6 – 1Моторы колёсID 9, 8, 7Проводная версия: Pi нет, всё работает на ноутбуке.
LeKiwi: ноутбук управляет роботом по сети, а Raspberry Pi управляет моторами

Для управления базой с клавиатуры нужен глобальный бэкенд клавиш, поэтому оно работает в X11, на рабочем столе Windows или в macOS при выданном терминалу разрешении Input Monitoring, но не работает в Wayland и на машинах без дисплея.

  1. Соберите две руки SO-101 по предыдущим разделам: одну для установки на базу, другую как ведущую. Затем соберите базу.
  2. Установите Raspberry Pi OS, включите SSH и убедитесь, что можете войти командой ssh <user>@<pi-ip>. Установите LeRobot на Pi и на ноутбук, как в разделе об установке, а затем добавьте дополнение LeKiwi, которое устанавливает драйвер сервоприводов и ZeroMQ.
    Установить дополнение LeKiwi
    pip install 'lerobot[lekiwi]'
  3. Настройте все моторы одной командой. Она задаёт моторам руки ID от 6 до 1, а колёсам — 9, 8 и 7; ID колёс должны соответствовать положениям крепления, показанным в документации LeKiwi. У LeKiwi одна плата управления.
    Задать ID моторов LeKiwi
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. Откалибруйте ведомую руку на Pi, а ведущую руку — на ноутбуке. На странице LeKiwi для ведущей руки показан --teleop.type=so100_leader; проверьте, какой класс ведущей руки создаёт examples/lekiwi/teleoperate.py, и калибруйте с тем же типом и тем же --teleop.id. Колёсным моторам калибровка не нужна.
    Откалибровать руку LeKiwi
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. На Pi активируйте окружение LeRobot и запустите хост. Через 30 секунд он останавливается, если не увеличить --host.connection_time_s (например, до 600); это нужно для более долгих сеансов, таких как запись.
    Запустить хост LeKiwi на Raspberry Pi
    python -m lerobot.robots.lekiwi.lekiwi_host \
        --robot.id=my_awesome_kiwi \
        --host.connection_time_s=600
  6. На ноутбуке отредактируйте examples/lekiwi/teleoperate.py в репозитории исходного кода LeRobot: задайте remote_ip равным адресу Pi, а port и id ведущей руки — своими значениями, затем запустите его. В record.py задайте ещё HF_REPO_ID и TASK_DESCRIPTION; в replay.py задайте remote_ip, port, id датасета и индекс эпизода. Для запуска обученной политики на странице LeKiwi используется examples/lekiwi/evaluate.py (задайте remote_ip, port и модель); команда lerobot-rollout из предыдущего раздела рассчитана на отдельную руку SO-101. Скорость имеет три режима, которые переключаются клавишами R и F: быстрый 0,3 м/с и 90°/с, средний 0,2 м/с и 60°/с, медленный 0,1 м/с и 30°/с.

Прокрутите таблицу вбок, чтобы сравнить все столбцы.

КлавишаДействие
WДвигаться вперёд
AДвигаться влево
SДвигаться назад
DДвигаться вправо
ZПовернуть налево
XПовернуть направо
RУвеличить скорость
FУменьшить скорость

Контрольный список по устранению неполадок

Многие проблемы связаны с питанием, кабелями, портами или настройкой, которая изменилась между записью и запуском. Прежде чем менять код, пройдите по этой таблице.

С вопросами о самом LeRobot обращайтесь в сообщество Discord, ссылку на которое даёт документация Hugging Face. По вопросам о деталях из нашего магазина используйте кнопку WhatsApp или форму поддержки.

Прокрутите таблицу вбок, чтобы сравнить все столбцы.

СимптомЧто проверить
Последовательный порт не найден или доступ запрещёнСнова запустите утилиту поиска портов при поданном питании платы и подключённом USB-кабеле. В Linux разрешите доступ командой sudo chmod 666 для этого порта. После перезагрузки или повторного подключения порты могут измениться, поэтому снова запустите утилиту поиска портов.
Скрипт назначения ID не находит моторПроверьте блок питания, USB-кабель и 3-контактный кабель. Подключён должен быть только настраиваемый мотор. На плате Waveshare обе перемычки должны стоять на канале B (USB).
Ранее использованные сервоприводы не находятся или не отвечаютСкорее всего, их ID и скорость обмена не совпадают с новым роботом, как отмечено в руководстве по SO-101. Снова запустите настройку моторов, по одному сервоприводу.
Калибровка завершается ошибкой, или после калибровки рука движется неправильноОткалибруйте заново: сначала установите каждый сустав в середину его диапазона и нажмите Enter, затем проведите каждый сустав через весь диапазон. Один из участников сообщества, который не поставил каждый сустав в середину, получил неверные смещения нуля (homing offsets). После этого используйте тот же id робота.
Камера отключается или меняется её индексЗапускайте утилиту поиска камер после каждой перезагрузки или повторного подключения. Две одинаковые веб-камеры в Linux могут поменяться USB-адресами; один из участников сообщества решил это правилами udev, привязанными к физическому USB-порту.
Клавиши записи ничего не делаютЗапускайте команду из интерактивного терминала и держите его в фокусе; клавиши n, r и q работают так же, как клавиши со стрелками и Esc. Только для управления роботом с клавиатуры, как на LeKiwi, нужны X11, рабочий стол Windows или разрешение в macOS.
Обучение не находит датасетИспользуйте полное имя датасета, включая суффикс с датой и временем.
Записанная частота намного ниже 30 ГцПосмотрите строки с частотой, которые печатает запись. Если основную долю времени занимает чтение с камер, уменьшите разрешение или используйте меньше камер, а затем запишите заново: политика ожидает такой же набор камер при запуске, а эпизоды, записанные заметно ниже 30 Гц, сохраняются так, будто шли на 30 Гц.
Политика клюёт стол или тянется слишком далекоСравните id калибровки, положения и имена камер и освещение с сеансом записи и проверьте, что предметы стартуют там, где в датасете есть примеры.
LeKiwi не подключается, или хост останавливается через 30 секундУзнайте адрес Pi командой hostname -I, пропингуйте его с ноутбука и проверьте ssh <user>@<pi-ip>; при необходимости включите SSH в sudo raspi-config. Хост останавливается через 30 секунд, если не задать --host.connection_time_s.

Источники проекта

Связаться с нами