minigrid_basics 实战指南：基于 Gym-Minigrid 的轻量级强化学习实验库

minigrid_basics 实战指南：基于 Gym-Minigrid 的轻量级强化学习实验库

【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research

导读

minigrid_basics是 Google Research 仓库中一个面向 Gym-Minigrid 的轻量级实验库，核心目标是把 MiniGrid 默认的"旋转 + 前进"动作空间改造成强化学习研究中更标准的四方向动作空间，并提供表格化（tabular）观测、MDP 动力学提取与可视化渲染等配套工具。读完本文，你将掌握该库的安装方式、五个开箱即用的示例脚本、Gin 配置文件驱动的自定义环境机制，以及如何基于仓库源码扩展自己的实验。

一、minigrid_basics 是什么

Gym-Minigrid 本身是经典的网格世界（GridWorld）环境套件，但其默认动作空间包含{rotate left, rotate right, forward, pick up object, drop object, toggle/activate object, done}等一整套动作，这与标准强化学习（RL）研究中常见的四方向离散动作并不一致。

minigrid_basics/README.md 将本库定位为 "A lightweight library for experiments using Gym-Minigrid"，其核心设计体现在 MonMiniGridEnv 的注释中：继承并覆写 MiniGridEnv，得到标准的四个方向动作{left, right, up, down}，同时移除捡拾（pick up）、开关（toggle）等非必要动作，使环境适配表格化 RL 与 MDP 求解等研究场景。

从仓库结构看，整个库由四部分组成：

• envs/：自定义环境mon_minigrid.py及其 8 个.gin环境配置；
• custom_wrappers/：三个自定义 Gym Wrapper（tabular、mdp、coloring）及对应测试；
• examples/：5 个可直接运行的示例脚本；
• requirements.txt 与 run.sh：依赖清单与一键运行脚本。

二、安装与运行

2.1 环境依赖

按照 README 的安装说明，需要依次执行：

git clone https://github.com/google-research/google-research cd google_research pip install -r minigrid_basics/requirements.txt

minigrid_basics/requirements.txt 中锁定了完整依赖版本，核心组件包括：

依赖	版本	作用
gym	0.23.1	强化学习环境标准接口
gym-minigrid	1.0.3	底层 MiniGrid 环境
gin-config	0.5.0	参数配置系统（环境定义依赖它）
absl-py	1.0.0	命令行参数解析与日志
tensorflow	2.9.1	文件系统 IO（tf.io.gfile）
matplotlib	3.5.2	观测图像渲染与保存
numpy	1.22.4	数值计算

此外仓库还提供了 run.sh，可一键创建虚拟环境、安装依赖并运行示例：

python3 -m venv .venv source .venv/bin/activate pip install -r minigrid_basics/requirements.txt python -m minigrid_basics.examples.mdp_four_directions

2.2 运行示例

README 给出的示例启动方式为：

python -m minigrid_basics.examples.interactive_example

由于所有脚本都基于 absl flags 与 gin-config，运行时可以随时通过--gin_bindings覆写环境参数，例如 interactive_example.py 文档字符串中展示的随机性设置：

python -m minigrid_basics.examples.interactive_example \ --gin_bindings="MonMiniGridEnv.stochasticity=0.1"

三、核心环境：MonMiniGridEnv 与四方向动作

3.1 为什么需要覆写动作空间

mon_minigrid.py 的模块文档解释了这一设计动机：Gym-Minigrid 假定智能体始终朝向某个方向，因此默认动作是"旋转/前进"。MonMiniGridEnv则把智能体先转向目标方向再尝试前进，从而以标准四方向动作运行。一个需要注意的细节是：在查看原始像素（raw pixels）时，智能体的朝向编码了它上一次执行的动作——这在使用像素观测时需要留意。

同时，环境刻意移除了pick up、toggle等动作，保持研究场景的标准性；如果未来需要加入可交互物体，需要在 step 实现 中做额外处理（如自动触发拾取）。

3.2 方向动作枚举与 step 逻辑

DirectionalActions以IntEnum定义了四方向动作（见 mon_minigrid.py）：

class DirectionalActions(enum.IntEnum): # Right, down, left, up. right = 0 down = 1 left = 2 up = 3

在step中，动作值直接写入agent_dir作为朝向，然后读取前方格子（front_pos）决定是否移动。奖励与终止逻辑遵循 MiniGrid 惯例：走到goal得 1 分（episodic 模式下结束回合），踏上lava立即结束。

3.3 随机性（stochasticity）的滑移模型

stochasticity是环境最常用的调参项。其语义在 MDPWrapper 文档 中有明确说明：随机性概率质量会被均匀分配到"另外三个方向动作 + 原地停留"四种结果上。在 step 中，若随机数小于stochasticity，则随机换一个动作执行；若换到的动作恰好与原始动作相同，则表现为"打滑、原地不动"。

3.4 完整构造参数

MonMiniGridEnv.__init__（见 mon_minigrid.py）提供的可配置参数全部可通过 gin bindings 覆写：

参数	默认值	说明
ascii_grid	（必填）	用 ASCII 字符描述的网格布局
directional	False	是否使用四方向动作
agent_pos	None	指定智能体起始坐标，None 则随机放置
goal_pos	None	指定目标坐标，None 则随机放置
mission	'Reach the goal'	任务描述
custom_rewards	None	(x, y, r)三元组列表，自定义奖励；None 时到达 goal 得 1
max_steps	100	每回合最大步数
see_through_walls	True	智能体是否可透视墙体
seed	1337	随机种子
agent_view_size	7	智能体视野范围
stochasticity	0.0	环境随机性（滑移概率）
episodic	True	是否为回合制（False 时到达 goal 不结束）

四、用 Gin 文件定义自定义网格世界

4.1 环境注册与加载流程

每个示例脚本的标准加载流程（以 interactive_example.py 为例）是：

gin.parse_config_files_and_bindings( [os.path.join(mon_minigrid.GIN_FILES_PREFIX, '{}.gin'.format(FLAGS.env_name))], bindings=FLAGS.gin_bindings, skip_unknown=False) env_id = mon_minigrid.register_environment() env = gym.make(env_id)

其中register_environment（见 mon_minigrid.py）通过gym.register将env_id绑定到入口点minigrid_basics.envs.mon_minigrid:MonMiniGridEnv，必须在gym.make之前调用。

4.2 ASCII 网格的编码约定

网格布局通过字符串定义，字符与物体的映射关系定义在 ASCII_TO_OBJECT：

字符	含义
*	墙体（Wall）
s	智能体起点
g	目标（Goal）
空格	可通行空地

网格在 parse_ascii_grid 中被解析为字符数组，并以其形状确定环境的width与height。若未指定起点/目标坐标，则按 _gen_grid 的逻辑随机放置。

4.3 仓库内置的 8 个环境

仓库在 minigrid_basics/envs/ 下预置了 8 个.gin环境配置：

Gin 文件	env_id	出处/用途
classic_fourrooms.gin	MiniGrid-ClassicFourRooms-v0	Sutton, Precup & Singh (1999) 的四房间经典布局
dayan_gridworld.gin	MiniGrid-DayanGridTask-v0	Dayan (1993) 的网格任务
four_state_grid.gin	MiniGrid-FourStateGrid-v0	仅 4 个状态的调试用 MDP
openroom.gin	MiniGrid-OpenRoom-v0	10x10 开阔网格，适合快速实验
separator.gin	MiniGrid-Separator-v0	被近乎完整的墙分隔的两个房间
mirrored_rooms.gin	MiniGrid-MirroredRooms-v0	Castro (2020) 的镜像房间
mirrored_rooms_separated.gin	MiniGrid-MirroredRoomsSeparated-v0	同上但隔墙闭合
zafs_gridworld.gin	MiniGrid-ZafGridworld-v0	Ahmed et al. (2019) 策略梯度方法中的网格世界

以 zafs_gridworld.gin 为例，它展示了custom_rewards的典型用法——为两个坐标配置非对称奖励：

MonMiniGridEnv.mission = 'Maximize the return across several episodes.' MonMiniGridEnv.custom_rewards = [(5, 1, 5.0), (1, 5, 4.5)]

自定义奖励的匹配逻辑在 _reward：遍历custom_rewards三元组，命中坐标即返回对应奖励；否则默认返回 1。若奖励配置在非g格子上，会打印警告日志。

五、三个自定义 Wrapper：表格化、MDP 与可视化

5.1 TabularWrapper：把网格变成状态编号

TabularWrapper 将 GridWorld 转为表格化（tabular）环境：给每个坐标分配一个状态 id，并维护pos_to_state/state_to_pos双向映射。实现上墙仍先被当作状态处理（id 为 -1），目标与空地才分配有效 id，最终观测为{'state': state_id}；开启get_rgb=True时还会附带渲染的 RGB 图像（见 observation）。

5.2 MDPWrapper：直接给出转移概率与奖励矩阵

MDPWrapper 继承自 TabularWrapper，遍历每个状态-动作对，构造出两个关键数组：

• transition_probs：形状(num_states, num_actions, num_states)的转移概率张量；
• rewards：形状(num_states, num_actions)的奖励矩阵。

其滑移概率建模与环境的stochasticity保持一致：以1 - stochasticity的概率执行所选动作，剩余概率质量按stochasticity / 4分摊到另外三个方向与原地停留（见 mdp_wrapper.py）。拿到这两个对象，就可以直接做值迭代、策略迭代等经典 MDP 求解。

5.3 ColoringWrapper：把数值渲染到网格上

ColoringWrapper 用于把长度为num_states的数值向量（如价值函数）按 matplotlib 色图着色到网格图像上。通过render_custom_observation(obs, values, cmap, boundary_values, boundary_colors)实现：值落在边界内时按色图取色，越界时使用boundary_colors兜底。该包装器直接服务于下面的mdp_four_directions示例的价值函数可视化。

六、五个示例脚本详解

examples/ 下的示例从简到繁覆盖了库的主要用法：

6.1 interactive_example：键盘交互

interactive_example.py 允许用户用键盘（w/s/a/d对应 up/down/left/right，映射见 ACTION_MAPPINGS）手动操控智能体。每步会在终端打印 ASCII 视图（*表示墙、g表示目标、%表示熔岩、箭头表示朝向，见 draw_ascii_view），同时把 RGB 帧保存到--file_path（默认/tmp/minigrid/interactive）。命令行参数包括--file_path、--env_name（默认classic_fourrooms）和--gin_bindings。

6.2 rw_standard：随机智能体 + 像素观测

rw_standard.py 是"最简示例"：随机智能体在 classic_fourrooms 中与环境交互，观测经RGBImgObsWrapper+ImgObsWrapper处理后保存为 PNG 帧，最多运行 500 步并输出累计回报。

6.3 rw_four_directions 与 rw_tabular：随机智能体 + 自定义环境/包装器

rw_four_directions.py 展示"自定义环境 + 自定义动作"的组合，每步打印t（时间步）与s（表格化状态编号）；rw_tabular.py 与之几乎相同，进一步强调 TabularWrapper 带来的状态观测。两者都通过--gin_bindings控制环境参数。

6.4 mdp_four_directions：值迭代求解并可视化

mdp_four_directions.py 是内容最完整的研究型示例，完整演示了"自定义环境 → MDPWrapper 提取动力学 → 值迭代 → ColoringWrapper 可视化"的链路：

python -m minigrid_basics.examples.mdp_four_directions \ --gin_bindings="MonMiniGridEnv.stochasticity=0.1"

其值迭代循环（见 mdp_four_directions.py）利用env.transition_probs与env.rewards计算 Bellman 更新，直到误差小于--tolerance（默认 0.001）；求解出的V*会打印到终端，并在指定--values_image_file时通过ColoringWrapper渲染成带色条的热力图保存。可用参数汇总如下：

参数	默认值	说明
--values_image_file	None	价值热力图保存路径前缀
--env	classic_fourrooms	使用的环境（对应 .gin 文件名）
--tolerance	0.001	值迭代收敛误差
--gamma	0.9	折扣因子
--gin_bindings	[]	覆写环境参数

七、测试与扩展建议

仓库在 custom_wrappers/tabular_wrapper_test.py 与 envs/mon_minigrid_test.py 中提供了对应模块的单元测试，验证状态映射与环境的注册、动作行为，可作为二次开发时的回归基准。

基于以上源码结构，扩展自己的实验通常只需三步：

1. 在 minigrid_basics/envs/ 下新建一个.gin文件，用 ASCII 网格描述布局并指定env_id（参考 separator.gin 这类最小配置）；
2. 在示例脚本中通过--env（或env_name）指向新配置，或用--gin_bindings覆盖agent_pos、goal_pos、stochasticity、custom_rewards等参数；
3. 按需组合TabularWrapper/MDPWrapper/ColoringWrapper，实现从"随机交互"到"MDP 精确求解"再到"可视化分析"的完整实验流程。

八、小结

minigrid_basics以极轻的代码量解决了 Gym-Minigrid 在研究场景中的三个关键痛点：四方向标准动作空间（MonMiniGridEnv）、表格化/MDP 动力学接口（TabularWrapper/MDPWrapper）与结果可视化（ColoringWrapper），并以 Gin 文件把环境定义与算法代码解耦。无论是快速验证一个 RL 算法、复现经典网格世界论文，还是调试 MDP 求解器，都可以从 minigrid_basics/README.md 出发，按本文介绍的五个示例与 8 个预置环境快速上手。

【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research