4. O código-fonte completo e os modelos usados

Objetivo deste post

Este post publica todo o código-fonte usado nos experimentos de IA no quebra-cabeça deslizante. O código só é carregado quando você abre um arquivo.

Modelos usados

• DQN: Stable-Baselines3. A observação são os números das peças 4×4, as ações são os quatro movimentos da casa vazia (cima, baixo, esquerda, direita), e a recompensa é o negativo da soma das distâncias de Manhattan que faltam para cada peça chegar ao seu lugar. A repetição infinita do post 1 veio dessa recompensa.
• Aprendizado por imitação (BC): a política da DQN foi treinada primeiro com registros resolvidos por uma pessoa e com soluções geradas por um professor em C++ (A*)
• Planner e Executor: duas CNNs em PyTorch (convoluções de 32→64 canais). O Planner escolhe a próxima peça a posicionar, e o Executor escolhe a jogada que move essa peça. Os dados foram reforçados com DAgger, que rotula de novo com a resposta do professor as posições em que a política errou.
• Modelo de mundo: simula as próximas jogadas com o motor em C++ e escolhe a jogada pela pontuação de uma ValueNet que prevê o progresso do tabuleiro (de 0 a 1).
• VLM: Qwen2.5-VL-3B-Instruct, do Hugging Face. Demos a ele a imagem do tabuleiro do quebra-cabeça e a lista de jogadas possíveis e recebemos a próxima jogada em JSON.

O que usamos como apoio

• Professor em C++ (PuzzleTeacher, Planner, Executor): geração de demonstrações e referência de avaliação. No modo de pesquisa, ele não sobrescreve as jogadas feitas pelo agente.
• agent_loop_guard: uma proteção que, quando a DQN ou o VLM repete o mesmo tabuleiro, sai do loop com uma jogada que reduz a distância de Manhattan
• Solução por IA no jogo da web: não é um modelo treinado, e sim uma busca A* ponderada que roda dentro do navegador (distância de Manhattan + conflito linear)

Resultados ao rodar de novo

Mesmo depois de 40 iterações, o aprendizado por imitação parou em 71,1% de jogadas iguais às do professor.

Rodamos de novo, nas mesmas condições, tabuleiros embaralhados com 80 jogadas. Nenhum dos modelos treinados terminou sequer um tabuleiro; só o Executor em C++, que tem a regra do loop escrita em código, resolveu todos.

As redes Planner/Executor concordaram com o professor em 83% das vezes ao escolher a próxima peça e em 40% ao escolher uma jogada, e não conseguiram completar nem a primeira linha. O modelo de mundo resolveu os 10 tabuleiros, mas a sequência de jogadas era idêntica mesmo com a ValueNet desligada. Quem resolveu os tabuleiros não foi a ValueNet, e sim o Executor em C++ que roda dentro dele.

Para o Qwen2.5-VL-3B, demos a imagem do tabuleiro e as jogadas possíveis e perguntamos diretamente a cada jogada. Ele não conseguiu resolver nem tabuleiros embaralhados com apenas 4 jogadas. Nas 20 partidas, ele ficou indo e voltando entre duas casas ou girando sem parar um bloco 2×2 de quatro casas. Ele sabe girar um loop, mas não sabe quando parar.

Estrutura de pastas

• src: motor do quebra-cabeça em Qt6/C++, API em C para Python, Planner/Executor/Teacher, tela em Qt e servidor de treinamento TCP
• Arquivos .py na raiz: ambiente Gymnasium, geração de demonstrações, treinamento de DQN/BC/Planner-Executor/modelo de mundo, cliente de conexão com o Qt, simulações de avaliação
• web: tela do quebra-cabeça na web em Next.js

As configurações de implantação do servidor, os scripts de monitoramento e automação, os dados de treinamento e pesos dos modelos e os arquivos de imagem do quebra-cabeça ficaram de fora da publicação. O código de operação da web, como anúncios, os arquivos de configuração e as ferramentas de depuração também foram retirados, por isso alguns imports e os caminhos de scripts no README apontam para arquivos não publicados.

Código-fonte completo