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) | |
|---|---|---|
| Robot | Microduck original, unos 800 g y 25 cm de alto | La adaptación al Arduino UNO Q |
| Modelo de servo en la simulación | Dynamixel XL330 (modelo BAM M6) | Servo de la familia 1910 (modelo BAM HLS1910) |
| Los nombres de las tareas terminan en | -MicroDuck | -XgoDuck |
| Pila de entrenamiento | mjlab sobre MuJoCo Warp, PPO | mjlab sobre MuJoCo Warp, PPO |
| Licencia | Apache 2.0 para el código; los modelos 3D, CC BY-NC-SA 4.0 | Apache 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.
- Un ordenador con GPU NVIDIA compatible con CUDA. El entrenamiento se ejecuta en la GPU mediante MuJoCo Warp; el ordenador del robot no entrena.
- Python 3.12 y uv, el gestor de paquetes de Python que ambos proyectos usan para instalar sus dependencias fijadas.
- 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.
- 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.
cd xgoduck_rl
uv syncEn 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.
UV_HTTP_TIMEOUT=600 uv syncDespué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.
uv run list-envsEntrena 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.
uv run train Mjlab-Velocity-Flat-XgoDuck --env.scene.num-envs 4096Para 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.
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096Los 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.
uv run train Mjlab-StandUp-Flat-XgoDuck --env.scene.num-envs 4096El proyecto original documenta cómo continuar una ejecución desde un checkpoint guardado con los flags del agente que se muestran a continuación.
uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096 \
--agent.run-name resume --agent.load-checkpoint model_29999.pt --agent.resume TrueDesplázate horizontalmente para comparar todas las columnas.
| Tarea (versión UNO Q) | Terreno | Qué aprende |
|---|---|---|
Mjlab-Velocity-Flat-XgoDuck | Plano | Caminar siguiendo órdenes de velocidad |
Mjlab-Velocity-Rough-XgoDuck | Irregular | La misma tarea de marcha sobre terreno irregular |
Mjlab-StandUp-Flat-XgoDuck | Plano | Levantarse desde tumbado o sentado y mantenerse de pie |
Mjlab-SitStand-Flat-XgoDuck | Plano | Sentarse y levantarse cuando se le ordena |
Mjlab-GroundPick-Flat-XgoDuck | Plano | Agacharse, tocar el suelo con el pico y volver a levantarse |
Mjlab-BallKick-Flat-XgoDuck | Plano | Dar una patada a una pelota con el pie derecho; también existe una tarea para el pie izquierdo |
Mjlab-Roulade-Flat-XgoDuck | Plano | Dar una voltereta hacia delante por encima de la cabeza y caer de pie |
Mjlab-RollerStandUp-Flat-XgoDuck | Plano | Levantarse desde el suelo sobre ruedas pasivas |
Mjlab-Velocity-Swizzle-XgoDuck | Plano | Patinaje 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.
uv run play Mjlab-Velocity-Flat-XgoDuckPara revisar una ejecución concreta, pásale su archivo de checkpoint. Reproduce exactamente el checkpoint que piensas exportar, no solo el más reciente.
uv run play Mjlab-Velocity-Flat-XgoDuck \
--checkpoint-file logs/rsl_rl/xgoduck_velocity/<run>/model_XXXX.ptFí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.
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>.onnxSin --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.
sha256sum logs/rsl_rl/xgoduck_velocity/<run>/<run>.onnxEl 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.
uv run scripts/infer_policy.py --walking output.onnxEjecuta 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.
- 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.
- En el primer arranque, sujeta el robot o colócalo sobre un soporte, con el interruptor de encendido al alcance de la mano.
- 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.
- 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.
uv syncse detiene a medias en una máquina ARM: defineUV_HTTP_TIMEOUT=600para la primera sincronización.list-envsno muestra tu tarea: revisa el sufijo (-XgoDucko-MicroDuck) y que estés en el proyecto correcto.playmuestra una ejecución inesperada: elige el checkpoint más reciente del directorio de experimento, así que pasa--checkpoint-file.- 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.
- 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. - 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.