4. El código fuente completo y los modelos utilizados

Objetivo de esta entrada

Publico todo el código fuente usado en los experimentos de IA para el puzzle deslizante. El código solo se carga cuando abres un archivo.

Modelos utilizados

• DQN: Stable-Baselines3. La observación son los números de las fichas en 4×4, las acciones son los cuatro movimientos de la casilla vacía (arriba, abajo, izquierda, derecha) y la recompensa es el negativo de la suma de la distancia Manhattan que le queda a cada ficha hasta su sitio. La repetición infinita de la entrada 1 salió de esta recompensa.
• Aprendizaje por imitación (BC): primero se entrenó la política de DQN con registros resueltos por una persona y con soluciones generadas por un profesor en C++ (A*)
• Planner y Executor: dos CNN de PyTorch (convoluciones de 32→64 canales). El Planner elige la siguiente ficha que hay que colocar y el Executor elige el movimiento que desplaza esa ficha. Los datos se reforzaron con DAgger, que vuelve a etiquetar con la respuesta del profesor las posiciones en las que la política se equivocó.
• Modelo del mundo: simula las jugadas siguientes con el motor de C++ y elige el movimiento según la puntuación de un ValueNet que predice el progreso del tablero (de 0 a 1).
• VLM: Qwen2.5-VL-3B-Instruct de Hugging Face. Le dábamos la imagen del tablero del puzzle y la lista de movimientos posibles, y recibíamos el siguiente movimiento en JSON.

Piezas de apoyo

• Profesor en C++ (PuzzleTeacher, Planner, Executor): generación de demostraciones y referencia de puntuación. En modo de investigación no sobrescribe los movimientos que hace el agente.
• agent_loop_guard: una protección que, cuando DQN o el VLM repiten el mismo tablero, los saca de ahí con un movimiento que reduce la distancia Manhattan
• Solucionador de IA del juego web: no es un modelo entrenado, sino una búsqueda A* ponderada que se ejecuta en el navegador (distancia Manhattan + conflicto lineal)

Resultados al volver a ejecutarlos

Incluso tras 40 iteraciones, el aprendizaje por imitación se estancó en un 71,1% de movimientos iguales a los del profesor.

Volvimos a ejecutar en las mismas condiciones tableros mezclados con 80 movimientos. Ninguno de los modelos entrenados terminó ni un tablero; solo el Executor en C++, que tiene la regla del bucle escrita en código, los resolvió todos.

Las redes Planner/Executor coincidieron con el profesor un 83% al elegir la siguiente ficha y un 40% al elegir un movimiento, y ni siquiera completaron la primera fila. El modelo del mundo resolvió los 10 tableros, pero la secuencia de movimientos era idéntica incluso con el ValueNet desactivado. Lo que resolvió los tableros no fue el ValueNet, sino el Executor en C++ que se ejecuta dentro.

A Qwen2.5-VL-3B le dimos la imagen del tablero y los movimientos posibles y le preguntamos directamente en cada movimiento. No pudo resolver ni siquiera tableros mezclados con solo 4 movimientos. En las 20 partidas, o iba y venía entre dos casillas o giraba sin fin un bloque de 2×2 de cuatro casillas. Sabe girar un bucle, pero no sabe cuándo parar.

Estructura de carpetas

• src: motor del puzzle en Qt6/C++, API en C para Python, Planner/Executor/Teacher, pantalla Qt y servidor de entrenamiento TCP
• Archivos .py de la raíz: entorno de Gymnasium, generación de demostraciones, entrenamiento de DQN/BC/Planner-Executor/modelo del mundo, cliente de conexión con Qt, simulaciones de evaluación
• web: pantalla web del puzzle en Next.js

La configuración de despliegue del servidor, los scripts de monitorización y automatización, los datos de entrenamiento y los pesos de los modelos, y los archivos de imagen del puzzle quedan fuera de lo publicado. También se han omitido el código y los archivos de configuración de operación web como los anuncios, y las herramientas de depuración, por lo que algunos import y las rutas de scripts del README apuntan a archivos no publicados.

Código fuente completo