4. 전체 소스 코드와 사용한 모델

이 글의 목적

타일 슬라이딩 퍼즐 AI 실험에 쓴 소스 코드 전체를 공개합니다. 파일을 펼칠 때만 코드를 불러옵니다.

사용한 모델

• DQN: Stable-Baselines3. 관측은 4×4 타일 번호, 행동은 빈칸의 상하좌우 4가지, 보상은 타일마다 제자리까지 남은 맨해튼 거리를 더한 값의 음수입니다. 1편의 무한 반복은 이 보상에서 나왔습니다.
• 모방 학습(BC): 사람이 직접 푼 기록과 C++ 교사(A*)가 만든 풀이를 DQN 정책에 먼저 학습
• Planner·Executor: PyTorch CNN 두 개(합성곱 32→64 채널). Planner는 다음에 맞출 타일을, Executor는 그 타일을 옮길 한 수를 고릅니다. 정책이 틀린 국면을 교사 답으로 다시 라벨링하는 DAgger로 데이터를 보강했습니다.
• 월드 모델: C++ 엔진으로 앞 수를 시뮬레이션하고, 판의 진행도(0~1)를 예측하는 ValueNet 점수로 수를 고릅니다.
• VLM: Hugging Face의 Qwen2.5-VL-3B-Instruct. 퍼즐 판 이미지와 둘 수 있는 수 목록을 주고 다음 수를 JSON으로 받았습니다.

보조로 쓴 것

• C++ 교사(PuzzleTeacher·Planner·Executor): 데모 생성과 채점 기준. 연구 모드에서는 에이전트가 낸 수를 덮어쓰지 않습니다.
• agent_loop_guard: DQN·VLM이 같은 판을 되풀이하면 맨해튼 거리를 줄이는 수로 빠져나오게 하는 안전장치
• 웹 게임의 AI 풀이: 학습 모델이 아니라 브라우저 안에서 도는 가중 A* 탐색(맨해튼 거리 + 선형 충돌)

다시 돌려 본 결과

모방 학습은 40번 반복해도 교사와 같은 수를 고른 비율이 71.1%에서 멈췄습니다.

80수 섞은 판을 같은 조건으로 다시 돌렸습니다. 학습한 모델은 한 판도 끝내지 못했고, 루프 규칙을 코드로 넣은 C++ Executor만 모두 풀었습니다.

Planner·Executor 신경망은 다음 타일 고르기에서 교사와 83%, 한 수 고르기에서 40% 일치했고 첫 줄도 끝까지 맞추지 못했습니다. 월드 모델은 10판을 모두 풀었지만 ValueNet을 끄고 돌려도 수순이 똑같았습니다. 판을 푼 것은 ValueNet이 아니라 안에서 도는 C++ Executor입니다.

Qwen2.5-VL-3B에게는 판 그림과 둘 수 있는 수를 주고 매 수 직접 물었습니다. 4수만 섞은 판도 풀지 못했습니다. 20판 모두 두 칸을 왕복하거나 2×2 네 칸을 끝없이 돌렸습니다. 루프를 돌릴 줄은 알지만 언제 멈춰야 하는지는 모릅니다.

폴더 구성

• src: Qt6/C++ 퍼즐 엔진, Python용 C API, Planner·Executor·Teacher, Qt 화면과 TCP 학습 서버
• 루트의 .py: Gymnasium 환경, 데모 생성, DQN·BC·Planner/Executor·월드 모델 학습, Qt 연결 클라이언트, 평가 시뮬레이션
• web: Next.js 웹 퍼즐 화면

서버 배포 설정, 감시·자동화 스크립트, 학습 데이터와 모델 가중치, 퍼즐 그림 파일은 공개 범위에서 제외했습니다. 광고 같은 웹 운영 코드와 설정 파일, 디버그용 도구도 빼서 일부 import와 README의 scripts 경로는 공개하지 않은 파일을 가리킵니다.

전체 소스