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 Wrappertabular、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.txtminigrid_basics/requirements.txt 中锁定了完整依赖版本核心组件包括依赖版本作用gym0.23.1强化学习环境标准接口gym-minigrid1.0.3底层 MiniGrid 环境gin-config0.5.0参数配置系统环境定义依赖它absl-py1.0.0命令行参数解析与日志tensorflow2.9.1文件系统 IOtf.io.gfilematplotlib3.5.2观测图像渲染与保存numpy1.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_directions2.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_bindingsMonMiniGridEnv.stochasticity0.1三、核心环境MonMiniGridEnv 与四方向动作3.1 为什么需要覆写动作空间mon_minigrid.py 的模块文档解释了这一设计动机Gym-Minigrid 假定智能体始终朝向某个方向因此默认动作是旋转/前进。MonMiniGridEnv则把智能体先转向目标方向再尝试前进从而以标准四方向动作运行。一个需要注意的细节是在查看原始像素raw pixels时智能体的朝向编码了它上一次执行的动作——这在使用像素观测时需要留意。同时环境刻意移除了pick up、toggle等动作保持研究场景的标准性如果未来需要加入可交互物体需要在 step 实现 中做额外处理如自动触发拾取。3.2 方向动作枚举与 step 逻辑DirectionalActions以IntEnum定义了四方向动作见 mon_minigrid.pyclass 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 字符描述的网格布局directionalFalse是否使用四方向动作agent_posNone指定智能体起始坐标None 则随机放置goal_posNone指定目标坐标None 则随机放置missionReach the goal任务描述custom_rewardsNone(x, y, r)三元组列表自定义奖励None 时到达 goal 得 1max_steps100每回合最大步数see_through_wallsTrue智能体是否可透视墙体seed1337随机种子agent_view_size7智能体视野范围stochasticity0.0环境随机性滑移概率episodicTrue是否为回合制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))], bindingsFLAGS.gin_bindings, skip_unknownFalse) 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字符含义*墙体Walls智能体起点g目标Goal空格可通行空地网格在 parse_ascii_grid 中被解析为字符数组并以其形状确定环境的width与height。若未指定起点/目标坐标则按 _gen_grid 的逻辑随机放置。4.3 仓库内置的 8 个环境仓库在 minigrid_basics/envs/ 下预置了 8 个.gin环境配置Gin 文件env_id出处/用途classic_fourrooms.ginMiniGrid-ClassicFourRooms-v0Sutton, Precup Singh (1999) 的四房间经典布局dayan_gridworld.ginMiniGrid-DayanGridTask-v0Dayan (1993) 的网格任务four_state_grid.ginMiniGrid-FourStateGrid-v0仅 4 个状态的调试用 MDPopenroom.ginMiniGrid-OpenRoom-v010x10 开阔网格适合快速实验separator.ginMiniGrid-Separator-v0被近乎完整的墙分隔的两个房间mirrored_rooms.ginMiniGrid-MirroredRooms-v0Castro (2020) 的镜像房间mirrored_rooms_separated.ginMiniGrid-MirroredRoomsSeparated-v0同上但隔墙闭合zafs_gridworld.ginMiniGrid-ZafGridworld-v0Ahmed 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_rgbTrue时还会附带渲染的 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 中与环境交互观测经RGBImgObsWrapperImgObsWrapper处理后保存为 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_bindingsMonMiniGridEnv.stochasticity0.1其值迭代循环见 mdp_four_directions.py利用env.transition_probs与env.rewards计算 Bellman 更新直到误差小于--tolerance默认 0.001求解出的V*会打印到终端并在指定--values_image_file时通过ColoringWrapper渲染成带色条的热力图保存。可用参数汇总如下参数默认值说明--values_image_fileNone价值热力图保存路径前缀--envclassic_fourrooms使用的环境对应 .gin 文件名--tolerance0.001值迭代收敛误差--gamma0.9折扣因子--gin_bindings[]覆写环境参数七、测试与扩展建议仓库在 custom_wrappers/tabular_wrapper_test.py 与 envs/mon_minigrid_test.py 中提供了对应模块的单元测试验证状态映射与环境的注册、动作行为可作为二次开发时的回归基准。基于以上源码结构扩展自己的实验通常只需三步在 minigrid_basics/envs/ 下新建一个.gin文件用 ASCII 网格描述布局并指定env_id参考 separator.gin 这类最小配置在示例脚本中通过--env或env_name指向新配置或用--gin_bindings覆盖agent_pos、goal_pos、stochasticity、custom_rewards等参数按需组合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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 Wrappertabular、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.txtminigrid_basics/requirements.txt 中锁定了完整依赖版本核心组件包括依赖版本作用gym0.23.1强化学习环境标准接口gym-minigrid1.0.3底层 MiniGrid 环境gin-config0.5.0参数配置系统环境定义依赖它absl-py1.0.0命令行参数解析与日志tensorflow2.9.1文件系统 IOtf.io.gfilematplotlib3.5.2观测图像渲染与保存numpy1.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_directions2.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_bindingsMonMiniGridEnv.stochasticity0.1三、核心环境MonMiniGridEnv 与四方向动作3.1 为什么需要覆写动作空间mon_minigrid.py 的模块文档解释了这一设计动机Gym-Minigrid 假定智能体始终朝向某个方向因此默认动作是旋转/前进。MonMiniGridEnv则把智能体先转向目标方向再尝试前进从而以标准四方向动作运行。一个需要注意的细节是在查看原始像素raw pixels时智能体的朝向编码了它上一次执行的动作——这在使用像素观测时需要留意。同时环境刻意移除了pick up、toggle等动作保持研究场景的标准性如果未来需要加入可交互物体需要在 step 实现 中做额外处理如自动触发拾取。3.2 方向动作枚举与 step 逻辑DirectionalActions以IntEnum定义了四方向动作见 mon_minigrid.pyclass 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 字符描述的网格布局directionalFalse是否使用四方向动作agent_posNone指定智能体起始坐标None 则随机放置goal_posNone指定目标坐标None 则随机放置missionReach the goal任务描述custom_rewardsNone(x, y, r)三元组列表自定义奖励None 时到达 goal 得 1max_steps100每回合最大步数see_through_wallsTrue智能体是否可透视墙体seed1337随机种子agent_view_size7智能体视野范围stochasticity0.0环境随机性滑移概率episodicTrue是否为回合制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))], bindingsFLAGS.gin_bindings, skip_unknownFalse) 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字符含义*墙体Walls智能体起点g目标Goal空格可通行空地网格在 parse_ascii_grid 中被解析为字符数组并以其形状确定环境的width与height。若未指定起点/目标坐标则按 _gen_grid 的逻辑随机放置。4.3 仓库内置的 8 个环境仓库在 minigrid_basics/envs/ 下预置了 8 个.gin环境配置Gin 文件env_id出处/用途classic_fourrooms.ginMiniGrid-ClassicFourRooms-v0Sutton, Precup Singh (1999) 的四房间经典布局dayan_gridworld.ginMiniGrid-DayanGridTask-v0Dayan (1993) 的网格任务four_state_grid.ginMiniGrid-FourStateGrid-v0仅 4 个状态的调试用 MDPopenroom.ginMiniGrid-OpenRoom-v010x10 开阔网格适合快速实验separator.ginMiniGrid-Separator-v0被近乎完整的墙分隔的两个房间mirrored_rooms.ginMiniGrid-MirroredRooms-v0Castro (2020) 的镜像房间mirrored_rooms_separated.ginMiniGrid-MirroredRoomsSeparated-v0同上但隔墙闭合zafs_gridworld.ginMiniGrid-ZafGridworld-v0Ahmed 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_rgbTrue时还会附带渲染的 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 中与环境交互观测经RGBImgObsWrapperImgObsWrapper处理后保存为 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_bindingsMonMiniGridEnv.stochasticity0.1其值迭代循环见 mdp_four_directions.py利用env.transition_probs与env.rewards计算 Bellman 更新直到误差小于--tolerance默认 0.001求解出的V*会打印到终端并在指定--values_image_file时通过ColoringWrapper渲染成带色条的热力图保存。可用参数汇总如下参数默认值说明--values_image_fileNone价值热力图保存路径前缀--envclassic_fourrooms使用的环境对应 .gin 文件名--tolerance0.001值迭代收敛误差--gamma0.9折扣因子--gin_bindings[]覆写环境参数七、测试与扩展建议仓库在 custom_wrappers/tabular_wrapper_test.py 与 envs/mon_minigrid_test.py 中提供了对应模块的单元测试验证状态映射与环境的注册、动作行为可作为二次开发时的回归基准。基于以上源码结构扩展自己的实验通常只需三步在 minigrid_basics/envs/ 下新建一个.gin文件用 ASCII 网格描述布局并指定env_id参考 separator.gin 这类最小配置在示例脚本中通过--env或env_name指向新配置或用--gin_bindings覆盖agent_pos、goal_pos、stochasticity、custom_rewards等参数按需组合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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考