Hana-ame/maze-transformer

🧭 MazeGPT：基于纯强化学习（零预训练）的反应式 2D 迷宫导航

反应式迷宫导航 Agent 的训练、评估与量化全流程工具箱

---

📖 任务规格与核心形式化

MazeGPT 旨在探究微型自回归 Transformer 在零预训练、纯强化学习（Pure RL）引导下，如何在部分可观测 2D 迷宫网格环境（POMDP）中自发掌握反应式空间导航与避障能力。

环境设定与观测模型：

• **观测空间 (Observation)**：每个时间步，环境向智能体提供四周局部视野的 4 格切片 U, D, L, R（其中 . 表示可通行的道路，# 表示墙壁，越界自动视为墙壁）。
• **动作空间 (Action Space)**：离散动作集合 U, D, L, R 及相应分隔符。
• 转移转移机制 (Dynamics)：若智能体尝试撞墙或越界，则当前步被判定为非法位移，智能体原地停留。
• *稀疏奖励 (Sparse Reward)：仅当智能体到达终点目标 G 时获得稀疏奖励 (+1.0)，其余所有转移奖励均为 0。训练全程不提供任何最短路径 BFS/A* 监督*。

---

🧭 DIY 快速导航

• DIY 第一步：Google Colab 零配置极速上手
• DIY 第二步：本地安装与环境准备
• DIY 第三步：运行交互式迷宫模拟器
• DIY 第四步：使用 maze_config.json 训练模型
• DIY 第五步：多尺寸迷宫泛化导航评测（5x5 – 9x9）
• DIY 第六步：训练后动态 INT8 量化评测
• 预训练权重 Checkpoint 清单
• 迷宫专项实验 Excel 工作簿

---

🚀 DIY 第一步：Google Colab 零配置极速上手

直接在 Google Colab 上使用免费 GPU/CPU 启动纯 RL 训练与评测：

1. 下载 Colab_Run_Maze_Transformer.ipynb。
2. 打开 Google Colab -> 点击 上传 (Upload) -> 选择该 .ipynb 文件。
3. 点击 代码执行程序 (Runtime) -> **全部运行 (Run All)**。

---

💻 DIY 第二步：本地安装与环境准备

# 1. 克隆本仓库
git clone https://huggingface.co/Hana-ame/maze-transformer
cd maze-transformer

# 2. 安装依赖（Python >= 3.8, PyTorch >= 2.0）
pip install torch openpyxl huggingface_hub matplotlib pandas
pip install -e .

---

🎮 DIY 第三步：运行交互式迷宫模拟器

# 在随机生成的 5x7 迷宫上测试智能体动态求解过程
./use_model.sh --checkpoint checkpoints/l2_d64_maze_forced_obs_rl_final.pt

---

🏋️ DIY 第四步：使用 maze_config.json 训练模型

1. 编写配置文件 maze_config.json

{
  "layers": 2,
  "d": 64,
  "heads": 4,
  "steps": 120,
  "batch_size": 6,
  "lr": 3e-4,
  "min_size": 5,
  "max_size": 9,
  "single": true,
  "datasource": {
    "type": "random_perfect_maze",
    "observation": "forced_obs_4cell",
    "reward": "sparse_goal_reach"
  }
}

2. 启动训练

# 纯 RL (GRPO) 训练
python -m maze_transformer.train --config maze_config.json

# 50 步快速冒烟测试验证环境
python -m maze_transformer.train --quick

---

📊 DIY 第五步：多尺寸迷宫泛化导航评测（5x5 – 9x9）

在跨尺寸随机迷宫中评测到达成功率与平均撞墙步数：

python -m maze_transformer.evaluate \
    --checkpoint checkpoints/l2_d64_maze_forced_obs_rl_final.pt \
    --sizes 5x5,5x7,6x6,6x9 \
    --n_trials 24

---

⚡ DIY 第六步：训练后动态 INT8 量化评测

测量 PyTorch 动态 INT8 量化在压缩权重体积的同时对策略稳定性的影响：

python -m maze_transformer.quantize --checkpoint checkpoints/l2_d64_maze_forced_obs_rl_final.pt

---

📦 预训练权重 Checkpoint 清单

Checkpoint 名称	架构参数	训练协议	说明与评测表现
l2_d64_maze_forced_obs_rl_final.pt	2L · 64d · 4 头	纯 RL (GRPO 120 步)	主力交付模型（5x7 迷宫到达率突破 **83.3%**）
l2_d64_maze_rnn_rl_ref.pt	1L · 128d · GRU-RNN	纯 RL (120 步)	循环神经网络 Baseline 对照模型
l2_d64_maze_sft_ref.pt	2L · 64d · Transformer	SFT (BFS 最短路径监督)	有监督学习导航能力上限对照参考

---

📊 迷宫专项实验 Excel 工作簿

全部 13 项迷宫专项实验（GRPO vs. REINFORCE vs. RNN 60/120/300 步、上下文压缩与 INT8 量化）完整归档在： 👉 EXPERIMENTS_ALL.xlsx

核心工作表说明：

1. **迷宫纯RL与导航实验全景表**：38 列全景矩阵，记录 5x5 至 9x9 各尺寸到达率、撞墙步数及样本吞吐效率。
2. **算法对照_GRPO_vs_REINFORCE_vs_RNN**：直观对比不同架构在 POMDP 局部观测迷宫中的引导成功率差异。

---

📄 开源协议

本项目采用 MIT 协议 开源。