From 3a8db20cd3e092920ee2bc772489e6f6be1e585f Mon Sep 17 00:00:00 2001 From: webbrain-one <295484252+webbrain-one@users.noreply.github.com> Date: Wed, 5 Aug 2026 18:25:03 +0300 Subject: [PATCH] docs: add Spanish README --- README.es-ES.md | 203 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 README.es-ES.md diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..ba2b958 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,203 @@ + + +# ROCm_Robotics_RL_Lab + +Un laboratorio de aprendizaje por refuerzo para simulación robótica en GPUs de AMD, actualmente centrado en la línea base de **robosuite Panda + Lift**. + +> Este proyecto fue desarrollado, entrenado y validado de extremo a extremo en un portátil **AMD Ryzen AI Max+ 395**, aprovechando completamente su GPU integrada **Radeon 8060S** tanto para el renderizado de simulación OpenGL como para el cómputo de IA con ROCm / PyTorch. Ha demostrado ser una plataforma de desarrollo portátil muy capaz para trabajos de RL robótico. + +> Las instrucciones en chino están disponibles en [README_zh.md](README_zh.md) + +## 📁 Estructura del Proyecto + +```text +ROCm_Robotics_RL_Lab/ +├── docs/ # Publicaciones del blog y activos de publicación +├── environments/ +│ ├── gym_wrapper.py # Adaptadores robosuite -> Gymnasium +│ └── pick_cube_place_cup.py # Prototipo de entorno personalizado de agarre y colocación +├── scripts/ +│ ├── quickstart.py # Ejemplo de inicio rápido +│ ├── train_sac.py # Script de entrenamiento SAC para Panda Lift +│ ├── train_ppo.py # Script de entrenamiento PPO para Panda Lift +│ ├── evaluate.py # Script de evaluación y grabación de video +│ ├── seed_sweep.py # Ejecutor con múltiples semillas +│ └── param_sweep.py # Ejecutor de barrido de parámetros +├── model_loading.py # Ayudas para cargar modelos de SB3 +├── requirements.txt +├── README.md +└── README_zh.md +``` + +## 🚀 Inicio Rápido + +### 1. Configuración del Entorno (GPU AMD / ROCm) + +```bash +# Crear entorno virtual +uv venv .venv --python 3.12 +source .venv/bin/activate + +# Instalar PyTorch compilado para ROCm (GPU AMD) +uv pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.1 +``` + +Verifique que la GPU sea visible: + +```bash +python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))" +``` + +Instale las dependencias: + +```bash +uv pip install -r requirements.txt +uv pip install stable-baselines3[extra] + +# Inicialización única de robosuite +python .venv/lib/python3.12/site-packages/robosuite/scripts/setup_macros.py +``` + +### 2. Ejecutar el ejemplo rápido + +```bash +cd ROCm_Robotics_RL_Lab +python scripts/quickstart.py +``` + +Esto entrena una pequeña política SAC en la tarea `Lift` de robosuite con el robot Panda. + +### 3. Entrenamiento completo + +```bash +# Entrenamiento SAC +python scripts/train_sac.py --total-timesteps 500000 --n-envs 4 + +# Entrenamiento PPO +python scripts/train_ppo.py --total-timesteps 1000000 --n-envs 8 + +# Observar las acciones en vivo durante el entrenamiento (entorno único) +python scripts/train_sac.py --total-timesteps 500000 --n-envs 1 --render + +# Habilitar la barra de progreso de Stable-Baselines3 explícitamente si se desea +python scripts/train_sac.py --total-timesteps 500000 --n-envs 4 --progress-bar +``` + +`train_sac.py` ahora incluye valores predeterminados más robustos para entornos paralelos: + +- `--save-freq` y `--eval-freq` se escalan automáticamente mediante `n_envs` en frecuencias de devolución de llamada de SB3, evitando puntos de control y evaluaciones excesivamente dispersos en el entrenamiento vectorizado +- Los hiperparámetros predeterminados están sesgados hacia un éxito estable en la tarea en lugar de explotar rápidamente recompensas de moldeo densas: `learning_rate=1e-4`, `batch_size=512`, `learning_starts=20000`, `tau=0.002` y `gradient_steps=1` +- Estos valores predeterminados reducen la oscilación del crítico / actor y hacen menos probable que la política se sobreajuste a las recompensas de moldeo antes de resolver realmente Lift +- Los episodios de entrenamiento terminan inmediatamente al tener éxito, mientras que los límites de tiempo se tratan como `truncated`, reduciendo el sesgo de aprendizaje de valor causado por confundir los tiempos de espera con estados terminales reales +- Basándose en la primera ronda de barridos de parámetros, el valor predeterminado actual orientado al éxito agrega una recompensa terminal de `+100` en los episodios exitosos (`--success-bonus`) y no aplica una penalización extra por tiempo de espera (`--timeout-penalty 0`); esta configuración obtuvo el mejor rendimiento en promedio en múltiples semillas +- `best_success` ahora utiliza `20` episodios de evaluación y un umbral de éxito del `20%` de manera predeterminada (`--n-eval-episodes 20 --min-best-success-rate 0.20`), equilibrando fiabilidad y velocidad de entrenamiento +- `best_success/best_metrics.json` registra el `timestep`, `success_rate` y `mean_reward` del checkpoint, y la misma información se imprime al final del entrenamiento + +Si desea un umbral más estricto, configúrelo explícitamente: + +```bash +python scripts/train_sac.py --total-timesteps 500000 --n-envs 4 --n-eval-episodes 20 --min-best-success-rate 0.20 +``` + +Si la política aún prefiere la recompensa de moldeo densa en lugar de completar realmente la tarea, puede reforzar aún más la señal de éxito: + +```bash +python scripts/train_sac.py --total-timesteps 500000 --n-envs 4 --n-eval-episodes 20 --min-best-success-rate 0.20 --success-bonus 100 --timeout-penalty 0 +``` + +Si desea detallar explícitamente la configuración de entrenamiento estable actualmente recomendada, utilice: + +```bash +python scripts/train_sac.py --total-timesteps 500000 --n-envs 4 --learning-rate 1e-4 --batch-size 512 --learning-starts 20000 --gradient-steps 1 --tau 0.002 --n-eval-episodes 20 --min-best-success-rate 0.20 --success-bonus 100 --timeout-penalty 0 +``` + +Si sospecha de una alta sensibilidad a la semilla, puede ejecutar varias semillas en lote directamente: + +```bash +python scripts/seed_sweep.py --seeds 42 123 456 --total-timesteps 500000 --n-envs 4 +``` + +Este script hará lo siguiente: + +- llamará al script existente `scripts/train_sac.py` para cada semilla +- evaluará primero el checkpoint `best_success` de cada ejecución, recurriendo al modelo final si es necesario +- resumirá los resultados de entrenamiento y evaluación por semilla en `models/seed_sweeps//summary.json` + +Si desea inspeccionar los comandos sin ejecutar realmente las tareas, utilice: + +```bash +python scripts/seed_sweep.py --seeds 42 123 456 --dry-run +``` + +### 4. Evaluar un modelo + +```bash +python scripts/evaluate.py --model models/sac_lift_final.zip --algo sac --n-episodes 10 +python scripts/evaluate.py --model models/best/best_model.zip --algo sac --no-render +python scripts/evaluate.py --model --algo ppo --record-video --video-dir videos/ +``` + +El script de evaluación cuenta el `success` a lo largo de todo el episodio: si la tarea se completa en cualquier paso, el episodio se marca como exitoso en lugar de verificar solo el fotograma final. + +## 🎯 Enfoque Actual + +El flujo de trabajo activo y validado en este repositorio es: + +- Tarea Lift de `robosuite` +- Robot Panda +- Stable-Baselines3 SAC / PPO +- Entrenamiento con GPU AMD + ROCm + PyTorch +- Renderizado, evaluación y captura de video basados en OpenGL + +El entorno personalizado `pick_cube_place_cup.py` permanece en el repositorio como un prototipo para futuros trabajos, pero la línea base documentada y probada actualmente es Panda Lift. + +## 📊 Parámetros de Entrenamiento Recomendados + +### Parámetros de SAC + +| Parámetro | Valor recomendado | Descripción | +|------|--------|------| +| learning_rate | 1e-4 | Tasa de aprendizaje | +| buffer_size | 1,000,000 | Tamaño del buffer de reproducción | +| batch_size | 512 | Tamaño del lote | +| learning_starts | 20,000 | Pasos de muestreo aleatorio antes de iniciar el aprendizaje | +| gradient_steps | 1 | Frecuencia de actualización conservadora | +| gamma | 0.99 | Factor de descuento | +| tau | 0.002 | Coeficiente de actualización suave | + +### Parámetros de PPO + +| Parámetro | Predeterminado | Descripción | +|------|--------|------| +| learning_rate | 3e-4 | Tasa de aprendizaje | +| n_steps | 2048 | Pasos por actualización | +| batch_size | 64 | Tamaño del lote | +| n_epochs | 10 | Épocas de entrenamiento | +| clip_range | 0.2 | Rango de recorte (clipping) | + +## 📈 Monitoreo del Entrenamiento + +Utilice TensorBoard para inspeccionar las curvas de entrenamiento: + +```bash +tensorboard --logdir logs/ +``` + +## 🔗 Recursos Relacionados + +- [Sitio web de robosuite](https://robosuite.ai/) +- [GitHub de robosuite](https://github.com/ARISE-Initiative/robosuite) +- [Stable-Baselines3](https://github.com/DLR-RM/stable-baselines3) +- [Documentación de ROCm](https://rocm.docs.amd.com/) +- [Ruedas de PyTorch ROCm](https://pytorch.org/get-started/locally/) + +## 📝 Notas + +1. La línea base validada del repositorio es Panda + Lift en robosuite. +2. Para renderizado en vivo durante el entrenamiento, utilice `--render` junto con `--n-envs 1`. +3. Para evaluación sin interfaz gráfica (headless), prefiera `--no-render` para evitar problemas con GLFW / DISPLAY. +4. Los scripts de entrenamiento desactivan la barra de progreso de `rich` de SB3 de manera predeterminada para evitar rastros de error durante la limpieza (tracebacks) de `tqdm` / `rich` en algunos entornos; agregue `--progress-bar` si desea habilitarla. + +## 📜 Licencia + +Licencia MIT