4. 完整源代码与使用的模型

本文的目的

公开滑块拼图AI实验中使用的全部源代码。只有展开文件时才会加载代码。

使用的模型

• DQN：Stable-Baselines3。观测是4×4的方块编号，动作是空格的上下左右4种移动，奖励是把每个方块到其正确位置剩余的曼哈顿距离相加后取负值。第1篇中的无限反复就是由这个奖励造成的。
• 模仿学习（BC）：先让DQN策略学习人亲手解出的记录和C++教师（A*）生成的解法
• 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路径指向的是未公开的文件。

完整源代码