Microduck Robot●microduck-robot.com

Microduck Robot / RL

Aprendizaje por refuerzo en robótica: enseña a andar a un pato bípedo

Esta guía explica el aprendizaje por refuerzo en robótica con un bípedo real y de código abierto: el pato robot Microduck. Sigue los proyectos de entrenamiento publicados por Pollen Robotics (el Microduck original) y Luwu Dynamics (la versión con Arduino UNO Q), desde la instalación del entorno de entrenamiento hasta la exportación de una política y su prueba en el robot.

Qué significa el aprendizaje por refuerzo para un bípedo pequeño

El aprendizaje por refuerzo (RL, por sus siglas en inglés) entrena una política de control mediante prueba y error. La política es una pequeña red neuronal que lee las posiciones y velocidades de las articulaciones y la orientación del cuerpo del robot, y devuelve un objetivo para cada servo. Una función de recompensa puntúa cada paso (seguir la velocidad indicada, mantenerse erguido, no dar pisotones) y el algoritmo de entrenamiento ajusta la red para obtener más recompensa. En los robots con patas esto ocurre en un simulador físico, donde miles de copias del robot pueden caerse a la vez sin ningún riesgo.

Microduck es un buen robot para aprender aprendizaje por refuerzo porque toda la receta es abierta. Pollen Robotics publica el robot y sus entornos de entrenamiento de RL, y Luwu Dynamics publica una versión derivada para la variante con Arduino UNO Q. Ambos entrenan con PPO la marcha, levantarse, sentarse y algunos trucos, y después exportan la política a ONNX para que el robot pueda ejecutarla.

El RL no es lo mismo que el aprendizaje por imitación de nuestra guía de LeRobot. Allí una persona demuestra la tarea y la red copia las demostraciones. Aquí nadie demuestra cómo caminar: la recompensa define qué es caminar bien y el simulador pone la práctica.

Hemos escrito esta guía a partir de la documentación publicada por ambos proyectos y de nuestras propias notas técnicas. No hemos entrenado ni desplegado ninguna política mientras la escribíamos, y los dos proyectos siguen cambiando. Toma los comandos como el punto de partida documentado y compruébalos con la versión del código que descargues.

Elige el proyecto de entrenamiento que corresponde a tu robot

Hay dos proyectos de entrenamiento relacionados, y el modelo del robot importa más que el código. Una política aprende la masa, la geometría y el comportamiento de los servos del robot con el que se entrenó, así que una política de marcha entrenada para un pato puede caerse al instante en el otro.

microduck_rl, de Pollen Robotics, entrena el Microduck original, un bípedo de unos 800 g y 25 cm con 14 servos Dynamixel XL330. xgoduck_rl, de Luwu Dynamics, sigue las mismas recetas de tareas para la adaptación al Arduino UNO Q, cuya geometría e inercia son distintas y cuyo simulador modela servos de la familia 1910 en lugar del XL330. Los kits Microduck Robot de este sitio se basan en el UNO Q, así que empieza con xgoduck_rl y confirma el modelo de servo de tu montaje.

Desplázate horizontalmente para comparar todas las columnas.

microduck_rl (Pollen Robotics)xgoduck_rl (Luwu Dynamics)
RobotMicroduck original, unos 800 g y 25 cm de altoLa adaptación al Arduino UNO Q
Modelo de servo en la simulaciónDynamixel XL330 (modelo BAM M6)Servo de la familia 1910 (modelo BAM HLS1910)
Los nombres de las tareas terminan en-MicroDuck-XgoDuck
Pila de entrenamientomjlab sobre MuJoCo Warp, PPOmjlab sobre MuJoCo Warp, PPO
LicenciaApache 2.0 para el código; los modelos 3D, CC BY-NC-SA 4.0Apache 2.0

Cómo funciona el bucle de entrenamiento

Ambos proyectos se basan en mjlab, que ejecuta la física de MuJoCo en la GPU mediante MuJoCo Warp y entrena con PPO (proximal policy optimization) de rsl_rl. Los comandos documentados ejecutan 4096 robots simulados en paralelo, de modo que una hora de entrenamiento acumula miles de horas de práctica simulada.

Cada habilidad es una tarea independiente con su propia política. Una tarea de velocidad aprende a caminar siguiendo órdenes de velocidad. Una tarea de levantarse aprende a ponerse de pie desde boca abajo, boca arriba o sentado. Otras tareas aprenden a sentarse y levantarse cuando se les ordena, agacharse y tocar el suelo, dar una patada a una pelota, hacer una voltereta hacia delante por encima de la cabeza o patinar sobre ruedas pasivas. El proyecto original entrena sus políticas a 50 Hz.

Las recompensas y la aleatorización están en la configuración de cada tarea. El proyecto original documenta sus reglas de diseño de recompensas y mantiene los interruptores de aleatorización de dominio como flags ENABLE_* al principio del archivo de configuración de cada tarea, así que puedes ver qué se aleatoriza antes de lanzar una ejecución.

Qué necesitas antes de empezar

No necesitas el robot para entrenar una política ni para comprobarla en simulación. Solo lo necesitas para la prueba final.

  1. Un ordenador con GPU NVIDIA compatible con CUDA. El entrenamiento se ejecuta en la GPU mediante MuJoCo Warp; el ordenador del robot no entrena.
  2. Python 3.12 y uv, el gestor de paquetes de Python que ambos proyectos usan para instalar sus dependencias fijadas.
  3. El código fuente de entrenamiento: xgoduck_rl de Luwu Dynamics para la versión UNO Q, o microduck_rl de Pollen Robotics para el Microduck original. Nuestra documentación técnica menciona ambos proyectos.
  4. Opcional: una cuenta de Weights & Biases o de Hugging Face. El proyecto original puede reproducir y exportar ejecuciones registradas en Weights & Biases, y documenta cómo entrenar en Hugging Face Jobs si no tienes GPU local.

Instala el entorno de entrenamiento

Desde la raíz del proyecto descargado, uv sync crea el entorno a partir del archivo de bloqueo del proyecto. Ejecútalo dentro de xgoduck_rl, o dentro de microduck_rl para el robot original.

Instala las dependencias fijadas
cd xgoduck_rl
uv sync

En máquinas ARM como DGX Spark (GB10) o Jetson, la primera sincronización descarga un wheel de CUDA de gran tamaño (unos 2 GB, según el proyecto original) y el tiempo de espera HTTP predeterminado de uv, de 30 segundos, puede interrumpirla. Aumenta ese tiempo de espera para la primera sincronización.

Primera sincronización en una máquina ARM
UV_HTTP_TIMEOUT=600 uv sync

Después, lista las tareas registradas. Usa una tarea cuyo nombre termine en -XgoDuck para la versión UNO Q y en -MicroDuck para el robot original.

Lista las tareas registradas
uv run list-envs

Entrena una política de marcha

Empieza con la tarea de velocidad en terreno plano. Es la tarea principal de ambos proyectos: el robot aprende a caminar siguiendo órdenes de velocidad.

Entrena la política de marcha (versión UNO Q)
uv run train Mjlab-Velocity-Flat-XgoDuck --env.scene.num-envs 4096

Para el Microduck original, el proyecto calcula entre una y dos horas hasta obtener una marcha utilizable con 4096 entornos. Luwu Dynamics no publica un tiempo para la versión UNO Q, y la duración real depende de tu GPU.

La misma tarea para el Microduck original
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096

Los checkpoints (model_*.pt) y los registros de TensorBoard se guardan en logs/rsl_rl/<experiment>/; la tarea de marcha usa logs/rsl_rl/xgoduck_velocity/. Entrena otras habilidades con el mismo comando y otro nombre de tarea, por ejemplo la tarea de levantarse. La tabla siguiente recoge las tareas de la versión UNO Q; las descripciones proceden de la lista de tareas del proyecto original, cuyas recetas siguen estas tareas.

Entrena la política para levantarse
uv run train Mjlab-StandUp-Flat-XgoDuck --env.scene.num-envs 4096

El proyecto original documenta cómo continuar una ejecución desde un checkpoint guardado con los flags del agente que se muestran a continuación.

Reanuda una ejecución (proyecto Microduck original)
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096 \
    --agent.run-name resume --agent.load-checkpoint model_29999.pt --agent.resume True

Desplázate horizontalmente para comparar todas las columnas.

Tarea (versión UNO Q)TerrenoQué aprende
Mjlab-Velocity-Flat-XgoDuckPlanoCaminar siguiendo órdenes de velocidad
Mjlab-Velocity-Rough-XgoDuckIrregularLa misma tarea de marcha sobre terreno irregular
Mjlab-StandUp-Flat-XgoDuckPlanoLevantarse desde tumbado o sentado y mantenerse de pie
Mjlab-SitStand-Flat-XgoDuckPlanoSentarse y levantarse cuando se le ordena
Mjlab-GroundPick-Flat-XgoDuckPlanoAgacharse, tocar el suelo con el pico y volver a levantarse
Mjlab-BallKick-Flat-XgoDuckPlanoDar una patada a una pelota con el pie derecho; también existe una tarea para el pie izquierdo
Mjlab-Roulade-Flat-XgoDuckPlanoDar una voltereta hacia delante por encima de la cabeza y caer de pie
Mjlab-RollerStandUp-Flat-XgoDuckPlanoLevantarse desde el suelo sobre ruedas pasivas
Mjlab-Velocity-Swizzle-XgoDuckPlanoPatinaje swizzle simétrico sobre ruedas

Comprueba la política en simulación

play abre el visor de una tarea. Sin el flag de checkpoint, carga el model_*.pt más reciente del directorio de experimento de esa tarea.

Reproduce el checkpoint más reciente
uv run play Mjlab-Velocity-Flat-XgoDuck

Para revisar una ejecución concreta, pásale su archivo de checkpoint. Reproduce exactamente el checkpoint que piensas exportar, no solo el más reciente.

Reproduce un checkpoint concreto
uv run play Mjlab-Velocity-Flat-XgoDuck \
    --checkpoint-file logs/rsl_rl/xgoduck_velocity/<run>/model_XXXX.pt

Fíjate en lo que la recompensa puede no detectar: pies que rozan el suelo, un tirón cada pocos pasos, una inclinación que aumenta con la velocidad o una caída cuando cambia la orden. Una política que parece inestable en simulación no va a mejorar en el robot real.

Reduce la brecha entre simulación y realidad

Con servos pequeños moviendo un bípedo ligero, los autores del proyecto original afirman que la fidelidad de los actuadores explica la mayor parte de la brecha entre simulación y realidad. Por eso ambos proyectos modelan el servo con BAM (Better Actuator Models, de Rhoban) hasta su ley de control de tensión, la fuerza contraelectromotriz y la fricción dependiente de la carga, en lugar de usar un controlador PD ideal.

Después, la aleatorización de dominio varía la tensión de la batería, la caída de tensión bajo carga, el retardo de las órdenes y la fricción entre los entornos paralelos, para que la política no dependa de un servo exacto. En el proyecto original, cada tarea principal tiene además una variante Backlash que añade ±1° de holgura de engranajes en serie con cada articulación de servo: inserta -Backlash antes del nombre del robot, por ejemplo Mjlab-Velocity-Flat-Backlash-MicroDuck.

Por eso también el modelo de servo decide qué proyecto usar. Entrenar la versión UNO Q con el modelo del XL330, o al revés, entrena la política para unos servos que no lleva tu robot.

Exporta la política a ONNX

El script de exportación convierte un checkpoint en un archivo ONNX e integra la normalización de las observaciones en el grafo. Despliega siempre un archivo generado por scripts/export.py; un checkpoint convertido a mano recibiría observaciones sin normalizar en el robot.

Exporta un checkpoint a ONNX
uv run python scripts/export.py Mjlab-Velocity-Flat-XgoDuck \
    --checkpoint-file logs/rsl_rl/xgoduck_velocity/<run>/model_XXXX.pt \
    --onnx-file logs/rsl_rl/xgoduck_velocity/<run>/<run>.onnx

Sin --onnx-file, la salida se escribe en output.onnx en el directorio actual. Guarda el archivo exportado junto a la ejecución que lo generó y anota la revisión del proyecto de entrenamiento, el checkpoint y la suma de verificación del archivo.

Anota la suma de verificación del archivo
sha256sum logs/rsl_rl/xgoduck_velocity/<run>/<run>.onnx

El proyecto original también permite controlar una política exportada con el teclado en MuJoCo sobre CPU con scripts/infer_policy.py. Simula los servos con el mismo modelo BAM usado en el entrenamiento, lo que lo convierte en una última comprobación útil antes de pasar al robot.

Controla la política exportada en MuJoCo sobre CPU (proyecto original)
uv run scripts/infer_policy.py --walking output.onnx

Ejecuta la política en el robot

En el Microduck original, el runtime embarcado de Pollen Robotics carga las políticas exportadas y alterna entre ellas (caminar, recuperarse, truco) con una única observación compartida de 61 valores: 48 valores de propiocepción más órdenes de velocidad del cuerpo, postura de la cabeza y postura del cuerpo. Su herramienta de publicación rechaza cualquier grafo que no sea [1,61] → [1,14], una salida por cada uno de los 14 servos.

Para la versión UNO Q, carga la política con el runtime que corresponda a tu rama de firmware; nuestra documentación técnica describe los runtimes. Antes de la primera ejecución, comprueba que el orden de articulaciones, los campos de observación y la normalización del runtime coinciden con la tarea de entrenamiento. Una discrepancia suele notarse en que el robot lanza una pata o se dobla en lugar de quedarse de pie.

  1. Carga la batería y realiza la calibración de la guía de montaje, para que la postura cero del robot coincida con la postura cero del modelo.
  2. En el primer arranque, sujeta el robot o colócalo sobre un soporte, con el interruptor de encendido al alcance de la mano.
  3. Carga primero una política de estar de pie o de levantarse, y después la política de marcha con una velocidad indicada baja.
  4. Anota el checkpoint, la suma de verificación del ONNX y la revisión del runtime, para que una reparación posterior pueda volver a una combinación que funcionaba.

Solución de problemas

Si un problema persiste, envíanos la versión de tu kit, el proyecto de entrenamiento, el nombre de la tarea y un vídeo corto del robot, y lo compararemos con los problemas de montaje que conocemos.

  1. uv sync se detiene a medias en una máquina ARM: define UV_HTTP_TIMEOUT=600 para la primera sincronización.
  2. list-envs no muestra tu tarea: revisa el sufijo (-XgoDuck o -MicroDuck) y que estés en el proyecto correcto.
  3. play muestra una ejecución inesperada: elige el checkpoint más reciente del directorio de experimento, así que pasa --checkpoint-file.
  4. El robot tiembla o reacciona tarde aunque la simulación se vea bien: revisa primero el modelo de servo, la tensión de la batería y la holgura de los engranajes. Es justo lo que la aleatorización de dominio pretende cubrir.
  5. El robot mueve la articulación equivocada o se cae al instante: compara el orden de articulaciones y la estructura de observaciones del runtime con la tarea de entrenamiento, y confirma que el archivo se exportó con scripts/export.py.
  6. El robot se queda torcido: vuelve a calibrar antes de reentrenar. Una política no puede corregir un servo cuyo cero está desplazado respecto al modelo.

Fuentes del proyecto

Contacto