MicroDuck: ходьба с сохранением равновесия на свободно катящемся баскетбольном мяче

В этом разделе Every Embodied собрана экспериментальная задача, которая хорошо подходит как пример управления движением с обучением с подкреплением: MicroDuck стоит на свободно катящемся баскетбольном мяче, сохраняет корпус вертикально и касание поверхности мяча ступнями, а по командам скорости активно катит мяч вперёд.

Видео GPU-повтора стратегии балансировки на мяче (5 секунд, без звука). Превью на главной странице — GIF того же повтора с сохранённой временной шкалой действий; видео кодируется H.264 с флагом faststart. Источник — уже имеющийся GPU-повтор для Notebook 01 этой темы, а не фрагмент многороботной балансировки на сфере из MotrixLab.

1. Главный вывод

Эта задача не сводится к тому, чтобы наложить действия стратегии ходьбы по земле на задачу с мячом. Прямое наложение обычно даёт две проблемы:

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

Публичная реализация использует более осторожный подход: сохраняется соглашение о наблюдениях и действиях задачи управления скоростью MicroDuck, применяется актор LSTM с памятью, а PPO напрямую обучает новую динамику «под ногами свободный мяч». Актор не читает положение и скорость мяча: он оценивает движение мяча по гироскопу, проекции гравитации, состоянию суставов, предыдущему действию и скрытому состоянию истории. Во время обучения привилегированный критик видит состояние мяча; при развёртывании остаётся только актор.

Поэтому точнее сказать так:

Используем интерфейс управления и определение команд скорости из исходной задачи ходьбы, чтобы заново обучить стратегию ходьбы по сферической поверхности с памятью собственного состояния (проприоцепции).

Это не просто «заморозить ONNX ходьбы по земле и добавить к действиям небольшую поправку». Но итоговое поведение соответствует задуманному: утёнок переносит опору с ноги на ногу, мяч катится, а корпус по возможности остаётся над верхушкой мяча.

1.1. Что в этом повторе принадлежит вышестоящему проекту, а что сделано нами

Видя демонстрационное видео, легко подумать, что мы обучили новую модель «утёнок ходит по баскетбольному мячу». На самом деле в этой версии публичный подход полностью прогнан локально. Он служит базой для дальнейших изменений среды, наград и адаптации к реальному роботу.

Вышестоящий проект уже предоставляет основные части:

• microduck-playground содержит сцену с мячом, модель столкновений, функцию награды и скрипты обучения PPO; идентификатор задачи — Mjlab-Basketball-MicroDuck;
• размер, масса, параметры контакта и способ сброса мяча взяты из публичной конфигурации;
• репозиторий модели на Hugging Face содержит обученные checkpoint.pt и policy.onnx;
• официальный репозиторий содержит инструкции по обучению и референсные видео.

Наша работа в этом повторе — поднять цепочку локально: получить исходный код и модель, настроить среду выполнения, выполнить вывод по checkpoint, отрендерить локальное видео, провести smoke-тест продолжения обучения и сравнить пошаговый вывод PyTorch и ONNX.

Поэтому на вопрос «не перенесли ли вы готовую чужую модель?» ответ такой: текущая версия по сути воспроизводит публичную модель в публичной сцене. Сцена не создана нами, модель не обучена с нуля нами. Основная ценность работы — проверка, что исходный код, модель, физическая сцена и интерфейс вывода на устройстве действительно соединяются, и оформление процесса так, чтобы его могли повторить другие.

Цифра 98.83%, которую мы измерили, — это проверка публичного checkpoint в нашей среде на 256 средах по 30 секунд. Она показывает, что модель работает в нашем окружении; она не означает, что мы обучили новую стратегию, и её нельзя напрямую сравнивать с официальными полными результатами.

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

2. Публичный проект и код

Текущий публичный checkpoint — b11, примерно на 6 999 итерации обучения. Авторы проекта прямо указывают, что проверки симуляции и экспорта пройдены, но временные характеристики на реальном роботе и его фактическое поведение ещё не проверены. Поэтому модель подходит как база для учебника, симуляции и проверки цепочки вывода на устройстве, но её нельзя сразу использовать как рабочую стратегию для моторов.

3. Сцена и физическая модель

3.1. Свободный мяч, а не фиксированная опора

В симуляции баскетбольный мяч — это свободное твёрдое тело с free joint:

• диаметр около 0.24 м, радиус около 0.12 м;
• масса около 0.62 кг;
• контакт с землёй и подошвами — настоящий контакт MuJoCo;
• мяч не закреплён на месте через weld или фиксирующее ограничение;
• поступательное и вращательное движение мяча и трение контакта влияют на следующий шаг утёнка.

При сбросе мяч помещается в начало координат среды, утёнок начинает из вертикальной позы около верхушки мяча. На раннем этапе обучения используется постепенно ослабляемый учебный план hold, чтобы стратегия сначала научилась удерживать равновесие в более простых условиях, а затем перешла к полностью свободному мячу. Этот hold — только учебный приём, а не постоянная сила, которую мы прикладываем к мячу в финальной демонстрации.

3.2. Зачем нужна полная модель столкновений

Если у робота только подошвы имеют коллизии, при падении корпус может пройти сквозь мяч или «повиснуть» непредусмотренным образом. В задаче с мячом используется полная модель столкновений, а падение фиксируется по трём условиям:

• корень утёнка слишком низко относительно центра мяча;
• корень слишком далеко отклонился от центра мяча;
• угол наклона корпуса превысил порог.

Эти три условия вместе ограничивают понятие «стоит на мяче» и не дают засчитать эффектную картинку как успех.

4. Структура сети и входы-выходы

4.1. Вход актора: 61 измерение

Опубликованный актор без зрения (blind) не читает состояние мяча; вход сохраняет 61-мерный интерфейс управления, обычный для MicroDuck:

Термин «blind» здесь не означает отсутствие памяти. Актор не видит мяч напрямую, но скрытое состояние LSTM сжимает информацию за несколько прошедших управляющих циклов и используется для оценки контакта подошв и тенденции качения по сфере.

4.2. LSTM и голова действий

Структуру можно описать так:

61D проприоцепция
        |
   LSTM(256)
        |
   ELU MLP: 512 -> 256 -> 128
        |
    14 действий суставов

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

4.3. Контракт вывода ONNX

ONNX-модель — не одношаговый MLP, а рекуррентная модель: входы и выходы включают состояние рекуррентного слоя:

inputs:
  obs  [1, 61]
  h_in [1, 1, 256]
  c_in [1, 1, 256]

outputs:
  actions [1, 14]
  h_out   [1, 1, 256]
  c_out   [1, 1, 256]

Частота работы — 50 Гц. На каждом шаге h_out/c_out передаются в следующий вызов; при первом запуске, переключении стратегии, восстановлении после падения и сбросе эпизода они обнуляются. Обычное изменение команды скорости не должно очищать память, иначе стратегия внезапно потеряет оценку того, как катится мяч.

5. Как награда описывает «ходьбу с мячом под ногами»

Основная награда — не просто поощрение за то, что мяч неподвижен. Если считать скорость мяча отрицательным членом, стратегия охотнее научится стоять на месте, а не катить мяч по команде. Поэтому публичная реализация использует сочетание:

1. Отслеживание скорости: поощряется движение системы «утёнок и мяч» в соответствии с командами скорости вперёд, вбок и рыскания;
2. Награда за вертикальность: проекция гравитации на корпус близка к вертикальному направлению;
3. Награда за центровку: корень утёнка остаётся вблизи центра мяча;
4. Награда за контакт ступней: подошвы касаются поверхности мяча на подходящей высоте;
5. Награда за высоту корня: корпус остаётся над верхушкой мяча, а не постепенно приседает или уходит внутрь;
6. Регуляризация скорости мяча: небольшой вес подавляет неуправляемое катание при отсутствии команды;
7. Штраф за изменение действия: снижает высокочастотную дрожь, но не добавляет низкочастотный фильтр действий на стороне развёртывания.

Ключевой баланс здесь такой: член скорости мяча — только слабая регуляризация, а отслеживание скорости превращает «качение» в целенаправленное поведение. Именно так получается физическая замкнутая петля: шаг переносит опору, мяч катится вслед за корпусом.

6. Обучение и воспроизведение

Ниже приведён путь воспроизведения, опубликованный проектом. Здесь показаны точки входа, а не требование пройти полное длительное обучение с нуля.

6.1. Получение исходного кода и модели

git clone https://github.com/Vottivott/microduck-playground
cd microduck-playground
uv sync --locked

Загрузите из репозитория модели на Hugging Face checkpoint.pt, policy.onnx, параметры и файлы проверки. Если для репозитория модели нужен вход, используйте собственный аккаунт Hugging Face; не записывайте токен в Notebook, историю командной строки или Git-репозиторий:

from huggingface_hub import snapshot_download

snapshot_download(
    "HannesVonEssen/microduck-basketball",
    local_dir="artifacts/basketball",
)

6.2. Сначала smoke-тест обучения

Перед обучением проверьте на небольшом числе сред и итераций MuJoCo-Warp, актуатор BAM, восстановление checkpoint и расчёт награды:

WANDB_MODE=disabled uv run python scripts/finetune_basketball.py \
  artifacts/basketball/checkpoint.pt \
  --run-name basketball-resume-smoke \
  --num-envs 64 \
  --iterations 5 \
  --learning-rate 2e-5 \
  --push-interval-s 1.5 3 \
  --save-interval 5

Официальная длительная конфигурация выглядит так. Число 4096 — это количество параллельных сред, а не обязательное значение; при нехватке видеопамяти сначала уменьшите его до 256 или 512, но в отчёте обязательно укажите число сред, итераций и random seed:

uv run python scripts/finetune_basketball.py \
  artifacts/basketball/checkpoint.pt \
  --run-name basketball-resume \
  --num-envs 4096 \
  --iterations 500 \
  --learning-rate 2e-5 \
  --action-rate-weight -0.2 \
  --command-scale 1 \
  --episode-seconds 10 \
  --seed 42 \
  --push-interval-s 1.5 3 \
  --save-interval 125

6.3. Оценка и экспорт

Оценку нельзя строить по одному красивому видео. Сохраняйте по меньшей мере:

• долю выживших эпизодов и время первого падения;
• ошибку отслеживания скорости вперёд, вбок и рыскания;
• RMS изменения действий;
• видео и JSON-результаты для разных seed;
• пошаговую ошибку паритета ONNX и PyTorch.

Проект предоставляет стандартный сценарий экспорта и проверки паритета:

MICRODUCK_BB_BLIND=1 MICRODUCK_BB_HISTORY=1 \
uv run python scripts/export.py \
  Mjlab-Basketball-MicroDuck \
  --checkpoint-file PATH/TO/model_XXXX.pt \
  --onnx-file output.onnx

uv run python scripts/verify_basketball_onnx_parity.py \
  PATH/TO/model_XXXX.pt output.onnx

7. Локальные результаты проверки

Публичный checkpoint был проверен на локальной машине с CUDA и GPU-средой MuJoCo-Warp:

Эти результаты — локальная проверка публичного checkpoint. Они не равны нашему переобучению и не совпадают с полной официальной оценкой. Более крупную статистику и граничные условия эксперимента ищите в официальном README.

8. Связь с исходной стратегией ходьбы

Этот эксперимент полезен как пример неудачного переноса навыка и его улучшения:

• Не рекомендуется: подставлять 14-мерные действия ONNX ходьбы по земле в актор балансировки на мяче кадр за кадром. Две стратегии работают с разной контактной динамикой, поэтому момент подъёма ноги, направление качения мяча и положение корпуса легко начинают конфликтовать.
• Рекомендуется: повторно использовать порядок суставов задачи ходьбы, масштабирование действий, команды скорости и 50-герцовый интерфейс управления, а сферическую балансировку рассматривать как новую задачу динамики и переобучать с LSTM и привилегированным критиком.
• Направление исследований: стратегию ходьбы по земле можно использовать для инициализации поведения, регуляризации учителем или тёплого старта по учебному плану; но итоговый актор должен научиться постановке ног и коррекции качения на данных контакта со свободным мячом.

9. Границы для реального робота и правила безопасности

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

1. Проверить на компьютере Ubuntu с ONNX Runtime бюджет вывода 50 Гц.
2. Корректно вести рекуррентное состояние h/c и проверить поведение при сбросе.
3. Ограничить углы суставов, скорости, ток и скорость изменения действий.
4. Использовать страховочный трос, мягкий коврик и кнопку аварийной остановки; сначала проверять с закреплённым или низкой сложностью hold мячом и затем постепенно усложнять.
5. Сначала проверить удержание на мяче, затем низкоскоростное качение и только потом свободный мяч на роботе.
6. Не выдавать 98,83% выживаемости в симуляции за показатель успеха на реальном роботе.

10. Источники

• MicroDuck Playground
• Описание эксперимента с балансировкой на мяче (blind)
• Hugging Face: модель и checkpoint
• Pollen Robotics MicroDuck
• LSTM runtime support PR #231