TVT 项目的 Pycolab 任务详解:两个三阶段长时程记忆环境的实现、原理与上手玩法
TVT 项目的 Pycolab 任务详解:两个三阶段长时程记忆环境的实现、原理与上手玩法
本文围绕 tvt/pycolab 目录中的 Pycolab 任务文档展开,深入讲解 TVT(Temporal Value Transport,时间价值传输)项目所提供的两个二维网格世界任务——key_to_door 与 active_visual_match 的三阶段结构、关键精灵(Sprite)实现细节、奖励机制,以及如何从命令行人工试玩这两个任务、以及它们如何被接入训练流程。读完后,你能够完整理解这两类“先获取信息、后被干扰、再兑现奖励”的长时程环境的内部实现,并掌握运行、调参与观测训练指标的具体方法。
背景:为什么 TVT 需要 Pycolab 版本的二维任务
TVT 项目(对应论文《Optimizing Agent Behavior over Long Time Scales by Transporting Value》的开源实现)的核心目标是让智能体学会利用“很久以前获取的信息或采取的行动”来在很久以后兑现奖励。根据 tvt/README.md 的说明,论文原版任务运行在 DeepMind Lab 的三维环境中,使用 384 个 actor 的分布式 A3C 架构训练;为了让单台机器能在合理时间内完成训练,仓库专门提供了基于 Pycolab 的二维网格世界版本任务来替代原三维任务,本目录下的 Pycolab 任务文档 就是对这两个任务的官方说明。原始的 DeepMind Lab 三维版本任务同样保留在 tvt/dmlab 目录中,其任务划分逻辑与 Pycolab 版本一致(explore / distractor / exploit 三阶段)。
从源码结构看,两个 Pycolab 任务都以 Pycolab 的 storytelling.Story 机制组织:一个 episode 由三个“章节”(chapter)按顺序串成,前一章节结束后自动切换到下一章节的地图与对象,这正是三阶段结构在框架层面的落地方式。
三阶段结构与通用规则
tvt/pycolab/README.md 明确指出:这里提供 2 个 Pycolab 任务,每个关卡由 3 个不同阶段组成:
- explore 阶段(第一阶段):智能体应学会获取一条信息或完成某个动作;
- distractor 阶段(第二阶段):两个任务均为“收苹果”阶段,智能体收集苹果获得奖励;
- exploit 阶段(第三阶段):智能体根据第一阶段获取的知识或执行的动作获得奖励。
这一结构在 common.py 中通过每阶段的最大帧数常量具体化:
DEFAULT_MAX_FRAMES_PER_PHASE = {
'explore': 15,
'distractor': 90,
'reward': 15
}
即 explore 阶段最多 15 帧、distractor 阶段 90 帧、reward(exploit)阶段 15 帧,整个 episode 固定 120 帧(Game.episode_length 属性返回三个阶段帧数之和,见 key_to_door.py 与 active_visual_match.py)。每个阶段内部由 TimerSprite 负责计时:当 the_plot.frame >= max_frames 时强制结束当前章节(the_plot.terminate_episode() 在 Story 语境下意味着进入下一章)。update_schedule 中 TIMER 一律排最后,确保本章所有对象先更新、计时器最后判定。
动作空间在 common.py 中统一定义:
| 动作 | 数值 | 说明 |
|---|---|---|
ACTION_NORTH |
0 | 向上移动 |
ACTION_SOUTH |
1 | 向下移动 |
ACTION_WEST |
2 | 向左移动 |
ACTION_EAST |
3 | 向右移动 |
ACTION_DELAY |
-1 | 停留(负 ID,不对智能体开放) |
ACTION_QUIT |
-2 | 终止 episode(负 ID,不对智能体开放) |
NUM_ACTIONS = 4,即训练时智能体只有 4 个可用离散动作。地图符号同样在此集中声明:玩家 +、边界 #、背景空格、钥匙 k、门 d、苹果 a、计时器 t、指示器 i;FIXED_COLOURS 为这些符号提供了 0–1000 区间的固定 RGB 颜色映射,供渲染与人类玩家界面共用。
Key To Door:先找钥匙、再收苹果、后开门取奖
文档中对 Key To Door 任务的描述是:
- 阶段 1:一把钥匙随机放置在两连通房间里;
- 阶段 2:收集苹果;
- 阶段 3:一个带门的小房间。如果智能体持有钥匙,就可以开门,穿过门去拿到门后的目标奖励。
KeySprite 所在文件 的 docstring 与之完全一致。结合源码可以看到各阶段的具体实现:
Explore 阶段:墙形钥匙区中随机保留一把钥匙
探索阶段的地图 EXPLORE_GRID 是一个 7×11 的网格:
#######
#kkkkk#
#kkkkk#
## ##
#+++++#
#+++++#
#######
上方两行的 10 个 k 单元格与下方两行的 6 个 + 单元格由中间一行的 3 个缺口连通,正对应文档中“两连通房间”的设定。Game._make_explore_phase 调用 keep_n_characters_in_grid 从 10 个 k 中随机保留 1 个作为真正的钥匙、从 6 个 + 中随机保留 1 个作为玩家出生点(见 key_to_door.py)。
拾取逻辑在 KeySprite.update 中:玩家坐标与钥匙坐标重合时,把全局标志 the_plot<a href="https://link.gitcode.com/i/baa1f633da7dce58b0dae910faa29271" target="_blank">'has_key'] = True 并隐藏钥匙。这个标志写在 Pycolab 的 the_plot 命名空间里,因此可以跨章节保留——这是“第一阶段的信息能影响到第三阶段”的底层机制。此外探索阶段还挂载了一个 [IndicatorObjectSprite(符号 i,固定在位置 (0, 5)):当玩家拾取被跟踪对象(这里是钥匙)时,它会在单帧内点亮一次,给智能体一个视觉确认。
Exploit 阶段:开门与一次性奖励
奖励阶段的地图 REWARD_GRID 是:
###
##d##
# #
# + #
# #
#####
门 d 位于小房间顶部。DoorSprite 的逻辑是:玩家触碰门的位置且 the_plot.get('has_key') 为真时,发放 pickup_reward(即 final_reward,默认 10),并立刻把 has_key 置回 False——注释说明这是为了确保每 episode 只能拿到一次该奖励。移动方面,key_to_door.PlayerSprite 默认把 BORDER + INDICATOR + DOOR 都设为不可通行;一旦持有钥匙,就从 impassable 中移除 DOOR,玩家由此可以穿过门格。
key_to_door.Game 的构造参数及默认值为:num_apples=10、apple_reward=(1, 10)、fix_apple_reward_in_episode=True、final_reward=10.、crop=True(见 key_to_door.py)。注意该游戏构造函数中直接 del rng,注释说明“每个 episode 布局相同且颜色不做随机化”——颜色来自固定映射 FIXED_COLOURS 加白色的 i,随机性只体现在钥匙与玩家的随机落点。
Active Visual Match:随机位置、随机颜色的视觉匹配
文档中对 Active Visual Match 任务的描述是:
- 阶段 1:一个颜色方块随机放置在两连通房间里;
- 阶段 2:收集苹果;
- 阶段 3:从若干选项中选出与阶段 1 颜色相一致的方块。
active_visual_match.py 的实现细节如下:
- 候选符号:模块级常量
SYMBOLS_TO_SHUFFLE = <a href="https://link.gitcode.com/i/8db2845bbf5e1dc6a40a688b01e3e8f9" target="_blank">'b', 'c', 'e']([L37),即三个候选颜色方块符号。 - 探索阶段:EXPLORE_GRID 中一整片
p构成墙形区域(pp pp一行的缺口形成两连通结构)。每个 episode 通过keep_n_characters_in_grid先只保留 1 个p并将其改写为目标符号(如b),其余p全部变为边界#,再从 6 个+中随机保留 1 个作为玩家位置。于是“随机放置的颜色方块”就是墙中那唯一一格,且目标符号target_char在每个make_episode()时由self._rng.choice(SYMBOLS_TO_SHUFFLE)重新抽取(L154-L161)。 - 颜色随机化:与 Key To Door 的固定配色不同,AVM 在构造时调用 get_shuffled_symbol_colour_map 为
b/c/e三个符号从 HSV 均匀色相盘中无放回地抽取 3 个颜色并映射到 0–1000 区间,因此每个 episode 连颜色本身都会变化,智能体无法靠“记住固定颜色—符号对应”取巧。 - 奖励阶段:REWARD_GRID 顶行并排放置
b、c、e三个颜色方块,玩家从底部小房间进入。三个阶段中只有与target_char对应的方块通过ascii_art.Partial(objects.ObjectSprite, reward=self._final_reward)挂上了final_reward(默认 10),其余两个符号的 ObjectSprite 拾取奖励为 0 且不可再次拾取;也就是说选错颜色只能拿到 0。
共享的 Distractor 阶段:收苹果引擎
两个任务的第二阶段都由 common.distractor_phase 工厂函数生成,共享同一套机制:
- 苹果网格:11×7 的 APPLE_DISTRACTOR_GRID 中预设 11 个苹果位置,
keep_n_characters_in_grid随机保留num_apples(默认 10)个:
###########
#a a a a a#
# a a a a #
#a a a a a#
# a a a a #
#a a + a a#
###########
- 奖励采样:
apple_reward支持标量或区间<a href="https://link.gitcode.com/i/70ff9c1d69f2546a7b7734bd5be1fb99" target="_blank">min, max)(默认(1, 10),由pycolab_apple_reward_min/pycolab_apple_reward_max两个 flag 传入)。若fix_apple_reward_in_episode=True(默认),[AppleDrape.update 会在该 episode 首次更新时从区间两个端点中np.random.choice采样一次并缓存到the_plot['sampled_apple_reward'],之后每个苹果都发放这个固定值;若为 False,则每次拾取独立地从区间均匀采样。 - 苹果重生:默认
respawn_every=20帧(DEFAULT_APPLE_RESPAWN_TIME),被拾取的苹果在 20 帧后于原位重新出现。 - 计时:同样由
TimerSprite(max_frames=90)控制阶段时长。
这一阶段的设计目的(文档中称为 distractor 阶段)是让 episode 的大部分奖励来自“收苹果”这种与长时程决策无关的局部行为,从而拉开 reward(整局总奖励)与 last phase reward(第三阶段奖励)之间的差距,迫使算法必须专门处理远期奖励信号。
命令行人工试玩任务
tvt/pycolab/README.md 提供了让人类玩家上手试玩的脚本。原文给出的命令为:
python3 pycolab/human_player.py -- --game=key_to_door
要玩 active_visual_match,把参数换成 --game=active_visual_match 即可。
从 human_player.py 源码看,该脚本的关键实现是:
- 通过 absl 的
DEFINE_enum('game', 'key_to_door', ['key_to_door', 'active_visual_match'], ...)定义游戏选择,默认游戏为key_to_door; - 根据参数实例化
key_to_door.Game(rng)或active_visual_match.Game(rng),然后game.make_episode()生成 episode; - 使用 Pycolab 自带的
human_ui.CursesUi(基于终端 curses 的界面)进行渲染,并把game.colours作为前景色映射传入,因此终端里看到的颜色与训练时智能体观察到的颜色体系一致。
键盘到动作的映射关系(human_player.py)为:
| 按键 | 动作 |
|---|---|
| 上方向键 | ACTION_NORTH |
| 下方向键 | ACTION_SOUTH |
| 左方向键 | ACTION_WEST |
| 右方向键 | ACTION_EAST |
-1(延迟键) |
ACTION_DELAY |
q / Q |
ACTION_QUIT(退出) |
需要注意的运行前提:
- 脚本位于仓库顶层
tvt包内部,导入路径是from tvt.pycolab import key_to_door等(见 human_player.py),因此应在仓库根目录下运行,例如python3 tvt/pycolab/human_player.py -- --game=key_to_door或等价地用模块形式python3 -m tvt.pycolab.human_player -- --game=key_to_door,以保证tvt包可被正确导入; - 界面依赖终端 curses,因此必须在交互式终端中运行;
- 依赖来自 tvt/requirements.txt:
absl-py、dm-sonnet==1.34、numpy、pycolab、six、trfl、tensorflow==1.13.2、tensorflow-probability==0.6.0。整套代码基于 TensorFlow 1.13 生态,需要在相应版本的 Python 2/3 环境中安装。仓库提供的 tvt/run.sh 脚本会创建/tmp/tvt_venv虚拟环境、安装依赖,并以--num_episodes=1冒烟运行一次python3 -m tvt.main,可作为安装自检流程。
试玩时你会直观体会到三阶段的衔接:探索阶段 15 帧内必须在随机位置找到钥匙(或看到那面墙中唯一的颜色方块),随后被强制“传送”到苹果房间收 90 帧苹果,最后进入 15 帧的兑现阶段——此时是否还“记得”钥匙/颜色,直接决定能否拿到 final_reward=10。
任务如何接入训练流程
人类试玩与智能体训练共用同一套 Game 类,区别只在适配层 env.py:
- PycolabEnvironment 根据
game名称(key_to_door/active_visual_match)构造对应Game,并暴露num_actions(4)、observation_shape、episode_length(120); - 观察转换:Pycolab 输出 CHW 浮点观察,
rendering.ObservationToArray按game.colours把符号颜色从 0–1000 缩放到 0–255(float(c) * 255 / 1000),并permute=(1, 2, 0)转为智能体期望的 HWC uint8 图像; crop=True时观察经过 get_cropper 生成的 5×5ScrollingCropper(以玩家为中心、边距 2),因此智能体每帧只看到 5×5×3 的局部视野,任务难度由此而来——探索阶段的信息必须在视野之外被记忆系统留住;last_phase_reward()直接读取the_plot<a href="https://link.gitcode.com/i/a8e4dc3bef36a850a4969230553d1cea" target="_blank">'chapter_reward'],该值由奖励阶段TimerSprite(track_chapter_reward=True)在本章内累计(见 [key_to_door.py)。
main.py 中与 Pycolab 任务直接相关的 flag 及默认值如下(python3 -m tvt.main 启动,默认在 RMA 智能体上跑 key_to_door):
| Flag | 默认值 | 作用 |
|---|---|---|
pycolab_game |
key_to_door |
选择任务,可选 key_to_door 或 active_visual_match |
pycolab_num_apples |
10 |
干扰阶段苹果数 |
pycolab_apple_reward_min |
1. |
苹果奖励区间下限 |
pycolab_apple_reward_max |
10. |
苹果奖励区间上限 |
pycolab_fix_apple_reward_in_episode |
True |
在 episode 内固定采样出的苹果奖励 |
pycolab_final_reward |
10. |
第三阶段兑现奖励 |
pycolab_crop |
True |
是否裁剪观察 |
这些 flag 经 env_kwargs 传入 PycolabEnvironment,再由 batch_env.BatchEnv 用线程池锁步地包装成 batch_size(默认 16)个并行环境供批量 A2C 训练使用。main.py 中 do_tvt=True 时会调用 tvt_rewards.compute_tvt_rewards,基于记忆读头的 read_weights / read_strengths / read_times 与 baseline,把“后验价值”回传到早期记忆读取时刻,生成虚拟奖励加入策略梯度——这正是这两个任务要考察的算法能力。
训练指标与示例结果
tvt/README.md 强调:TVT 关注的是与早期行为/信息在时间上距离很远的奖励,因此追踪 TVT 是否起效的最佳指标是 last phase reward(第三阶段奖励)而非整局 reward。main.py 每 logging_frequency(默认 1)个 episode 打印并写入 TensorBoard 的日志包括:reward(整局总奖励)、Last phase reward(即上文 last_phase_reward() 的批量均值)、tvt reward(TVT 虚拟奖励总和)与 Loss / 各项分项损失。
使用默认超参训练 TVT 智能体与关闭 TVT 的最优对照 RMA(do_tvt=False, gamma=1)的示例结果如下(引自 tvt/README.md,10 次重复):
Key To Door 任务中,TVT 智能体稳定达到第三阶段奖励满分 10(即可靠地在探索阶段拿到钥匙并在兑现阶段开门),而无 TVT 的同超参对照表现持续偏低:
Active Visual Match 任务中,TVT 智能体同样达到 10 分,意味着它能在探索阶段主动搜寻墙中唯一的颜色方块、记住其颜色,并在兑现阶段触碰对应颜色方块:
对照曲线(无 TVT、同超参与无 TVT + gamma=1)分别存放在 tvt/images/ktd_notvt.png、tvt/images/ktd_notvt_gamma1.png、tvt/images/avm_notvt.png、tvt/images/avm_notvt_gamma1.png,可用于对比不同设置下探索阶段主动信息获取行为的学习效果。
小结
tvt/pycolab 目录用不到千行代码实现了两个结构对称的三阶段长时程任务:key_to_door 考察“记住物理事实(是否拿到钥匙)”,active_visual_match 考察“记住感知细节(唯一颜色方块的颜色与位置)”,两者都以收苹果的干扰阶段把兑现奖励与早期行为在时间上拉开 90 帧以上。核心实现分布在 common.py(阶段常量、苹果引擎、计时器、裁剪)、key_to_door.py、active_visual_match.py(阶段地图与任务精灵)、objects.py(可拾取对象与指示器)与 env.py(训练适配层),而 human_player.py 提供了零训练成本的命令行体验入口——先人工玩几局,再跑 python3 -m tvt.main 观察 last phase reward 的变化,是理解 TVT 算法动机最直接的路径。文档原文特别致谢了撰写这两个任务脚本的 Hamza Merzic,这里一并保留该致谢。

