alexhegit · webbrain-one · Aug 5, 2026
diff --git a/README.es-ES.md 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/<timestamp>/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 <path> --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