Eval 系统功能与配置

为什么需要 Eval？

训练曲线（TensorBoard） vs Eval 结果 reward/episode 上升固定种子 32 scenario ↓ success / reward / length 无法判断泛化能力判断真实测试集表现 ↓ 检测训练后期退化不知道哪个 checkpoint 最好自动保存 best / latest

训练曲线只反映当前 policy 在训练环境上的表现，可能过拟合到特定地图。
Eval 用固定种子在独立测试集上跑，结果可复现。
通过 eval 可以选择历史最佳 checkpoint，避免"训练后期退化"。

Eval 核心功能

1. 训练内定期 Eval

train 过程中按 eval_interval 触发 eval。
eval 使用独立环境 eval_envs，不污染训练状态。
支持贪婪策略（eval_deterministic=True）或随机策略。

2. 独立 Reset 模式

训练用 env_reset_mode，eval 用 eval_reset_mode。
例如：训练用 jitter，eval 用 full_random 测试泛化。

3. 自动保存 Best / Latest Checkpoint

每次 eval 后保存 actor_eval_latest.pt。
按字典序评分保存 actor_eval_best.pt：
success → task_completion_ratio → episode_reward → -successful_episode_length

4. 全 Checkpoint 评估（eval_sweep.py）

枚举所有中间 checkpoint（actor_ep*.pt）。
多 GPU 并行评估，输出每模型的最佳结果。

5. 跨实验汇总（aggregate_runs.py）

把多个 run 的 per-checkpoint 结果 join 成一张大表。
自动生成 Markdown 报告，包含 best/final/latest 对比。

Eval 指标

指标	含义
`success`	任务全部完成且没有死亡 agent 的 episode 比例
`episode_reward`	每 episode 平均总奖励
`episode_length`	每 episode 平均步数
`task_completion_ratio`	完成任务数 / 总任务数
`sent_percentage`	实际送达物资 / 目标物资量
`dead_agents`	每 episode 死亡 agent 数
`coalition_changes`	联盟切换次数
`premature_no_explorer_ratio`	过早失去探索者的比例

此外还记录 9 个奖励分量（reward_switch_coalition、reward_dead、reward_discover 等）用于诊断。

Eval 相关配置参数

参数	说明	典型值
`use_eval`	是否开启训练内 eval	True
`eval_interval`	每隔多少 env episode 触发一次 eval	25 / 50 / 100
`eval_episodes`	每次 eval 跑多少个 episode	32 / 64
`eval_seed`	eval 环境固定种子，保证可复现	10000
`eval_deterministic`	eval 时是否用贪婪策略	True
`env_reset_mode`	训练环境重置模式	jitter / full_random
`eval_reset_mode`	eval 环境重置模式，可与训练不同	full_random

Eval 流程示意

训练循环： for episode: collect → insert → train if episode % eval_interval == 0: ├─ 创建 eval_envs（固定 seed） ├─ 跑 eval_episodes 个 scenario ├─ 记录 success / reward / length / 奖励分量 ├─ 保存 actor_eval_latest.pt └─ 如果评分更高：保存 actor_eval_best.pt + eval_best.json

关键文件：

runs/.../eval/step_*.csv：每次 eval 的 per-scenario 结果
runs/.../eval/step_*.json：每次 eval 的汇总统计
runs/.../models/actor_eval_best.pt：历史最佳模型
runs/.../models/eval_best.json：最佳模型元数据