Booster K1 в браузере на MuJoCo: локальное развёртывание и опыт обучения AMP

Дата обновления: 2026-09-29

Сначала опробуйте онлайн-демо из upstream, затем разверните статический сайт upstream и модельные ресурсы из репозитория локально в браузере Windows; также описано, как опубликовать сайт на собственном GitHub Pages после получения разрешения. Инференс в браузере не требует установки Python-проекта MuJoCo или обучения модели. Локальный хостинг статического сайта требует HTTP-сервер на Python, а переобучение — Linux и NVIDIA GPU.

1. Как работает демо в браузере

Upstream-проект booster_mjlab предоставляет модель MuJoCo робота Booster K1, задачи управления скоростью и отслеживания движения, а также процесс обучения на основе состязательных априорных данных о движении (Adversarial Motion Priors, AMP). Сайт демо статический: браузер загружает страницу, JavaScript и политику с моделью из static/demo/ в каталоге сайта, а MuJoCo WebAssembly, Three.js и декодер Draco подключаются с jsDelivr. Симуляция и инференс политики выполняются в браузере; на официальной странице указана частота политики 50 Гц. Это не удалённый рабочий стол и не видеопоток.

Поэтому различайте три вещи:

Локальное развёртывание этого шага использует исходный код сайта upstream и предварительно экспортированные ресурсы политики, а не переписанный здесь фронтенд MuJoCo и не модель, обученная на вашей машине. На официальной странице проекта показан результат работы политики на реальном роботе, но в репозитории upstream пока сказано, что код развёртывания на реальном роботе ещё не опубликован; эта глава не утверждает, что воспроизводит эксперименты на реальном роботе.

2. Сначала онлайн-демо upstream

2.1 Открыть интерактивную страницу

Откройте в свежих Microsoft Edge или Google Chrome официальную страницу проекта Booster K1, прокрутите до In your browser и нажмите Load interactive demo ≈14 MB. Это страница, размещённая upstream; при первой загрузке нужна сеть, чтобы скачать WebAssembly, библиотеки рендеринга и политику.

2.2 Управление роботом

1. Дождитесь появления холста симуляции и показания скорости в левом верхнем углу.
2. Щёлкните по сцене симуляции, чтобы она получила фокус клавиатуры.
3. Клавиши W — вперёд, S — назад, A / D — боковое движение, Q / E — поворот. Можно также перетащить джойстик в левом нижнем углу или использовать геймпад.
4. Нажмите кнопку Reset на экране, чтобы вернуть начальное состояние. Перетаскивание мышью по сцене меняет ракурс наблюдения.

2.3 Как проверить, что всё работает

• Страница показывает модель K1 в симуляции, землю и джойстик управления.
• После нажатия клавиш направления показание скорости меняется, и робот движется; после отпускания клавиши соответствующая команда скорости возвращается к нулю.
• После Reset симуляция возвращается в начальное состояние.

При написании этой главы онлайн-страница upstream была открыта в Microsoft Edge на Windows: холст отрисовывался, после нажатия W значение vx менялось с 0.00 на ненулевое и возвращалось к 0.00 m/s после отпускания. Это подтверждает, что онлайн-демо upstream в данном браузере работает интерактивно, но не является проверкой локального хостинга.

2.4 Частые проблемы

• После нажатия кнопки нет изображения: проверьте, что сеть может открыть официальную страницу, и дождитесь завершения первой загрузки ресурсов; затем обновите страницу. При необходимости обновите браузер и драйвер видеокарты и включите аппаратное ускорение графики в настройках браузера.
• Клавиши не реагируют: сначала щёлкните по холсту симуляции, затем нажимайте клавиши направления; убедитесь, что фокус не остался в адресной строке или на других элементах страницы.
• Картинка тормозит или загружается долго: при первом запуске нужно скачать около 14 МБ; закройте программы, которые сильно нагружают систему, перезагрузите страницу и проверьте, что в браузере не отключены WebAssembly и WebGL.
• Хочу запускать файлы сайта на своём компьютере: переходите к следующему разделу. Локальный статический хостинг сайта и установка Python-окружения симуляции или обучения — это разные задачи.
• Хочу запускать обучение на Python в Windows: upstream сейчас требует NVIDIA GPU, но не даёт пошаговых инструкций для нативного Windows; обучение выполняйте в Linux с NVIDIA.

3. Локальный хостинг сайта в Windows

Сам сайт — это статические файлы, поэтому на Windows не нужно устанавливать пакет MuJoCo для Python и не нужен GPU для обучения. Браузер всё равно загружает WebAssembly MuJoCo, Three.js и Draco с jsDelivr, поэтому при первом открытии нужна сеть. Не открывайте index.html двойным щелчком через file://: модули браузера и fetch() работают только по HTTP.

3.1 Получение сайта и файлов модели upstream

В корне репозитория учебника откройте PowerShell и клонируйте upstream:

$BoosterRoot = Join-Path $env:USERPROFILE 'src\booster_mjlab'
git clone --depth 1 https://github.com/IntelligentRoboticsLab/booster_mjlab.git $BoosterRoot

Если соединение с GitHub не работает, откройте репозиторий upstream, нажмите **Code → Download ZIP», распакуйте архив и замените $BoosterRoot на путь к распакованному каталогу. Убедитесь, что страница и файлы политики есть на диске:

Test-Path "$BoosterRoot\website\index.html"
Test-Path "$BoosterRoot\website\static\demo\scene.json"
Test-Path "$BoosterRoot\website\static\demo\policy.bin"

Все три проверки должны вернуть True. Демо опирается на набор файлов, которые ссылаются друг на друга, поэтому при загрузке сохраняйте всю структуру каталогов website/.

3.2 Запуск локального HTTP-сервера

Прилагаемый serve_demo.py — это простой статический сервер на стандартной библиотеке. В Python 3.11 для Windows таблица MIME по умолчанию отдаёт .js как text/plain, и браузер отказывается выполнять ES-модули страницы; скрипт явно задаёт MIME-типы для .js, .mjs и .wasm.

Команда выполняется из корня репозитория учебника:

python ".\07-robot-operation-and-motion-control\Locomotion\02-BoosterK1-mjlab-AMP\serve_demo.py" `
  --directory "$BoosterRoot\website" `
  --host 127.0.0.1 `
  --port 8765

Когда в терминале появится Serving ... at http://127.0.0.1:8765, оставьте окно открытым и откройте в Edge или Chrome адрес http://127.0.0.1:8765/. Нажмите Load interactive demo, дождитесь появления модели и нажмите W: показание скорости должно стать ненулевым и плавно вернуться к нулю после отпускания. Чтобы остановить сервер, нажмите Ctrl+C.

127.0.0.1 доступен только с этого же компьютера. Этот сервер на Python подходит для локальной проверки, но не для публичного продакшена; чтобы временно открыть доступ из локальной сети, можно заменить --host на 0.0.0.0, но тогда сами настройте брандмауэр и круг доступа.

При написании этой главы путь локального хостинга был проверен на Windows 11, Python 3.11 и Microsoft Edge: модули страницы отдавались как text/javascript, интерактивный холст и политика загрузились; при удержании W скорость становилась ненулевой и возвращалась к 0.00 m/s после отпускания. Видео-вступление на странице при автоматической проверке отменял браузер, но это не влияет на демо симуляции.

4. Откуда берутся файлы модели и политики

Upstream-репозиторий уже содержит предварительно экспортированные ресурсы, которые использует текущее демо; для инференса в браузере не нужно скачивать веса с Hugging Face. Они лежат в website/static/demo/:

Самый простой и надёжный способ повторно использовать официальное демо — скачать или клонировать репозиторий upstream и полностью сохранить website/static/demo/. Набор данных lafan_locomotion_k1 на Hugging Face — это справочные данные о движении для обучения AMP, а не policy.bin для демо в браузере.

Скрипт экспорта upstream export-web-demo принимает ONNX-политику скорости с метаданными mjlab и генерирует policy.bin, XML, сетки и метаданные сцены. Пример использования:

uv run --with fast-simplification export-web-demo path/to/policy.onnx

По умолчанию выходной каталог — website/static/demo/ в репозитории. Upstream пока не описывает, как превратить обученный файл .pt в ONNX-вход для этого экспорта, поэтому не переименовывайте .pt в policy.bin напрямую. Чтобы подставить собственную политику, сначала подготовьте модель по процедуре экспорта ONNX из upstream.

5. Публикация на собственном GitHub Pages после получения разрешения

На дату обновления этой главы в репозитории upstream нет файла LICENSE на уровне проекта; файл BULMA-LICENSE.txt описывает лицензию библиотеки стилей Bulma и не заменяет лицензию на сайт, модели роботов и веса политики. Перед тем как публично размещать или распространять код сайта, модели или политику, получите разрешение у сопровождающих upstream или дождитесь, когда в репозитории появится лицензия. Инструкция ниже применима только в том случае, если у вас есть право публично размещать эти файлы. На GitHub Pages policy.bin, модели и файлы сайта доступны всем посетителям.

Файл .github/workflows/docs.yml в upstream уже показывает способ публикации: сайт — статические файлы без шага сборки, а GitHub Actions загружает каталог website/ на Pages. Проще всего после получения разрешения сделать fork upstream-репозитория; если вы используете собственный репозиторий, по лицензии скопируйте файлы сайта и этот workflow, сохранив исходную структуру каталогов.

1. Сделайте fork IntelligentRoboticsLab/booster_mjlab или, получив разрешение, поместите website/ и .github/workflows/docs.yml из upstream в свой репозиторий. Workflow по умолчанию работает с веткой main; если у вас другое имя основной ветки, поменяйте его в workflow.
2. Откройте Settings → Pages → Build and deployment и в поле Source выберите GitHub Actions. Убедитесь, что Actions включены; если на странице workflow предлагается включить Docs, нажмите на эту кнопку.
3. Откройте Actions → Docs → Run workflow, чтобы опубликовать вручную. Дальше публикация будет запускаться автоматически при отправке изменений в website/ или в файл workflow в ветке main. После успешного выполнения адрес сайта можно найти в деталях развёртывания в Actions или в Settings → Pages. Для репозитория проекта обычно адрес имеет вид https://<имя-пользователя>.github.io/booster_mjlab/.
4. Откройте страницу по публичному адресу и нажмите Load interactive demo. Проверьте, что холст робота загружается, клавиатура отзывается, а файлы scene.json, policy.bin, XML, сетки и GLB доступны.

Зависимости MuJoCo и рендеринга сайт по-прежнему загружает с jsDelivr, поэтому посетителям нужен доступ к CDN. Если среда развёртывания не может обращаться к CDN, нужно разрешённым способом разместить эти зависимости самостоятельно и поменять import map и пути к WASM в странице; в этой главе такой офлайн-вариант не проверялся. GitHub Pages поддерживает публикацию статических сайтов через GitHub Actions; подробнее см. документацию GitHub Pages о пользовательских workflow и инструкцию по выбору источника публикации.

6. Необязательно: обучение AMP-политики скорости

Этот раздел для тех, кто хочет попробовать обучение с подкреплением. Для знакомства с демо в браузере выполнять его не нужно. Команды основаны на README upstream-репозитория; проект может меняться, поэтому имена задач и параметры перед запуском сверяйте с последней версией его документации.

6.1 Требования к окружению

• Linux с работающим NVIDIA GPU. Upstream говорит, что обучению нужен NVIDIA GPU, но не указывает минимальный объём видеопамяти и рекомендуемую модель видеокарты; не выводите из этого, что любая видеокарта для ноутбука справится с настройками по умолчанию.
• Git, доступ в интернет и менеджер пакетов uv. Проект сам синхронизирует Python и зависимости проекта через uv.
• Учётная запись Weights & Biases (W&B) для записи запусков обучения и загрузки контрольных точек по пути запуска. При первом использовании войдите по официальной инструкции W&B; API-ключ не записывайте в код и не отправляйте в репозиторий.
• Стабильная сеть и несколько гигабайт свободного места на диске. При первом uv run синхронизируются PyTorch, MuJoCo и другие зависимости; реальный объём загрузки зависит от платформы и результата разрешения зависимостей. Upstream не публикует точного минимума по диску.

Upstream не описывает нативную поддержку обучения в Windows. Если нужно обучение на Windows, используйте Linux-станцию с NVIDIA GPU или облачную Linux-среду. Проверка инференса в браузере не означает, что обучение на Python под Windows проверено. Параметр по умолчанию в 4096 параллельных сред может потребовать много видеопамяти; если её не хватает, сначала уменьшите число параллельных сред. Скорость и потребление памяти зависят от GPU, драйвера и версий зависимостей.

6.2 Установка и проверка задач

В терминале Linux выполните:

git clone https://github.com/IntelligentRoboticsLab/booster-mjlab.git
cd booster-mjlab
uv run list_envs

Команда uv run list_envs подготовит окружение по конфигурации проекта и выведет список зарегистрированных задач. Убедитесь, что она завершилась и в списке есть Mjlab-Velocity-Flat-Amp-DA-Muon-Booster-K1, только потом начинайте обучение. Если uv ещё не установлен, сначала следуйте его официальной инструкции, откройте терминал заново и проверьте uv --version.

6.3 Запуск обучения управлению скоростью

Команда по умолчанию из README upstream использует 4096 параллельных сред:

uv run train Mjlab-Velocity-Flat-Amp-DA-Muon-Booster-K1 \
  --env.scene.num-envs 4096

Если видеопамяти не хватает, попробуйте меньшее число параллельных сред, например:

uv run train Mjlab-Velocity-Flat-Amp-DA-Muon-Booster-K1 \
  --env.scene.num-envs 512

Во время обучения следите за терминалом и страницей запуска в W&B: должны обновляться число шагов симуляции и метрики обучения; запомните путь к этому запуску. Значение 512 — лишь начальная попытка с меньшим числом сред, а не минимальная конфигурация или гарантия производительности от upstream. Если при инициализации не хватает памяти, уменьшите число сред или возьмите GPU с большей памятью.

По умолчанию задача скорости использует небольшой набор фрагментов ходьбы из LAFAN1 как априорные данные о движении AMP. Чтобы заменить данные движения, upstream поддерживает идентификатор набора данных на Hugging Face или локальный файл / каталог, которые передаются через --agent.dataset-root. Сначала подготовьте данные по формату upstream и проверьте их.

6.4 Оценка контрольной точки в симуляции

Скопируйте из страницы запуска W&B путь к запуску в виде организация-или-пользователь/mjlab/run-id и выполните:

uv run play Mjlab-Velocity-Flat-Amp-DA-Muon-Booster-K1 \
  --wandb-run-path организация-или-пользователь/mjlab/run-id

Замените пример пути на собственный путь запуска W&B. Upstream указывает, что команда получает последнюю контрольную точку из W&B и запускает оценку политики в симуляции. Проверьте, реагирует ли политика на команды скорости и может ли робот непрерывно идти в симуляции. Это по-прежнему оценка в симуляции, а не отправка команд управления на реального робота.

7. Результаты и важные замечания

• На официальной странице проекта показана демонстрация реального Booster K1, который работает с политикой скорости AMP после 30 тыс. шагов обучения. Это результат, который показал upstream, а не гарантия того, что вы получите такой же эффект на своём оборудовании; одно лишь число шагов тоже не гарантирует того же результата.
• В README upstream сказано, что код развёртывания политики на реальном роботе «скоро будет доступен». Эта глава охватывает только инференс в браузере, команды обучения и оценку в симуляции из upstream; развёртывание на реальном роботе и инструкции по безопасной работе здесь не рассматриваются.
• Веб-версия использует опубликованную экспортированную политику; обучение же выполняется заново на вашей машине или на Linux-GPU. У них разные зависимости, среда запуска и результаты.
• В этой главе приведены только ссылки на upstream-репозиторий, сайт и набор данных; код, веса моделей и ресурсы сайта не скопированы. На дату обновления в репозитории upstream не найден файл LICENSE. Чтобы повторно распространять его код, веса или данные, сначала уточните лицензию и условия использования данных у сопровождающих.

8. Справочные материалы

• Официальная страница проекта Booster K1 и браузерное демо
• Репозиторий booster_mjlab upstream и инструкция по обучению
• Набор данных LAFAN1 K1 из upstream
• Документация по установке uv
• Быстрый старт Weights & Biases