TVT 项目的 Pycolab 任务详解:两个三阶段长时程记忆环境的实现、原理与上手玩法

原创2026-10-13 14:20:541,977 阅读
文章标签:人工智能深度学习机器学习计算机视觉NLP强化学习

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 个不同阶段组成:

  1. explore 阶段(第一阶段):智能体应学会获取一条信息或完成某个动作;
  2. distractor 阶段(第二阶段):两个任务均为“收苹果”阶段,智能体收集苹果获得奖励;
  3. 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×5 ScrollingCropper(以玩家为中心、边距 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 的同超参对照表现持续偏低:

TVT 智能体在 key_to_door 任务上的 last phase reward 训练曲线

Active Visual Match 任务中,TVT 智能体同样达到 10 分,意味着它能在探索阶段主动搜寻墙中唯一的颜色方块、记住其颜色,并在兑现阶段触碰对应颜色方块:

TVT 智能体在 active_visual_match 任务上的 last phase reward 训练曲线

对照曲线(无 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,这里一并保留该致谢。

登录后查看全文
deepmind-research