# Value-based 实践 · Q-Learning（FrozenLake-v1 + Taxi-v3）

> 《第3周-深度强化学习原理实践》PPT 第 27–40 页 value-based 实践产物：**从零手写 Q-Learning**（Q 表 + epsilon-greedy + Bellman 更新），训练好的智能体 + 训练代码 + 回放视频 + 评估分数。

## 1. 评估分数

| 智能体 | 环境 | 平均回报（100 局） | 成功率 | 平均步数 | 训练回合 |
|---|---|---|---|---|---|
| FrozenLake-v1 · 4x4 不滑 | `FrozenLake-v1` | **1.00 ± 0.00** | 100% | 6.0 | 10000 |
| FrozenLake-v1 · 4x4 滑冰版 | `FrozenLake-v1` | **0.74 ± 0.44** | 74% | 39.4 | 20000 |
| FrozenLake-v1 · 8x8 | `FrozenLake-v1` | **1.00 ± 0.00** | 100% | 14.0 | 60000 |
| Taxi-v3 | `Taxi-v3` | **7.56 ± 2.71** | 100% | 13.4 | 25000 |

> 评估方式：独立环境、贪心策略 `argmax_a Q(s,a)`、每局最多 99 步，跑 100 局；FrozenLake 的回报是「是否到达目标」（0/1），Taxi 的回报是「每步 −1，成功送达 +20」。

## 2. 回放视频

**总回放（三个智能体合集）**

<video controls width="100%" src="videos/replay_value_based_all.mp4"></video>

**FrozenLake-v1 · 4x4 不滑**

<video controls width="100%" src="videos/replay_frozenlake4x4.mp4"></video>

**FrozenLake-v1 · 4x4 滑冰版**

<video controls width="100%" src="videos/replay_frozenlake4x4_slippery.mp4"></video>

**FrozenLake-v1 · 8x8**

<video controls width="100%" src="videos/replay_frozenlake8x8.mp4"></video>

**Taxi-v3**

<video controls width="100%" src="videos/replay_taxi.mp4"></video>

## 3. 学到的策略（Q 表可视化）

## 4. 训练曲线

![FrozenLake-v1 · 4x4 不滑 训练曲线](logs/frozenlake4x4/train_curve.png)

![FrozenLake-v1 · 4x4 滑冰版 训练曲线](logs/frozenlake4x4_slippery/train_curve.png)

![FrozenLake-v1 · 8x8 训练曲线](logs/frozenlake8x8/train_curve.png)

![Taxi-v3 训练曲线](logs/taxi/train_curve.png)

## 5. 怎么复现

```powershell
# 环境（本机已有）：conda activate DRL
conda activate DRL

# 训练（每个实验 1~30 秒）
python train_qlearning.py --env frozenlake4x4
python train_qlearning.py --env frozenlake4x4_slippery
python train_qlearning.py --env frozenlake8x8
python train_qlearning.py --env taxi

# 评估 + 录视频（生成 eval_results/*.json 和 videos/*.mp4）
python evaluate_and_record.py --model models/qtable_frozenlake4x4.pkl
python evaluate_and_record.py --model models/qtable_frozenlake4x4_slippery.pkl --video-episodes 5 --slowmo 4
python evaluate_and_record.py --model models/qtable_frozenlake8x8.pkl
python evaluate_and_record.py --model models/qtable_taxi.pkl

# Q 表可视化 + 总回放 + 打包
python visualize_qtable.py --all
python make_combined_video.py
python build_hub_package.py
```

## 6. 文件说明

- `models/qtable_*.pkl`：模型文件。pickle 格式，内含 Q 表、超参数、训练种子和评估指标；
  `evaluate_and_record.py` 可以直接加载（不需要重新训练）。
- `videos/*.mp4`：回放，每帧标注步数/动作/奖励/Q 值条形图，片头片尾是标题卡和分数卡。
- `eval_results/*.json`：评估分数 + 逐局明细（起点种子、回报、步数、是否成功）。
- `logs/<run>/train_console.log`：完整训练日志（环境自检、超参数、每 N 回合进度、每次评估）。
- `code/`：全部代码（训练 / 评估录像 / 可视化 / 打包 / 上传 / 一键脚本）。

## 7. 对应 PPT 页码

| PPT 页 | 内容 | 对应实现 |
|---|---|---|
| 29 | Q 表 / Q 函数 / 最优策略 | `train_qlearning.py` 的 `initialize_q_table` / `greedy_policy` |
| 31–32 | FrozenLake 观测/动作/奖励 | 训练日志里的「环境自检」 |
| 33 | Q 表初始化 + 贪心策略 | `initialize_q_table` / `greedy_policy` |
| 34 | epsilon-greedy + 超参数 | `epsilon_greedy_policy` + `EXPERIMENTS` 配置 |
| 35 | 训练循环（Bellman 更新） | `train_qlearning.py::train` 里的 `Q[s][a] += lr*(...)` |
| 36–37 | 训练、Q 表可视化、评估、保存模型 | 训练日志 / `visualize_qtable.py` / `evaluate_and_record.py` / `models/*.pkl` |
| 38–40 | Taxi-v3（500 状态 × 6 动作） | `--env taxi`（含 PPT 的 100 个官方评估种子） |
| 28 | 上传 Hub + 视频 + 分数 | `build_hub_package.py` + `upload_to_hub.py` + README |

- 生成时间：2026-10-30 23:05