多智能体网格世界环境 MultiGrid：MiniGrid 多代理扩展的使用与源码解析-开发者社区

人工智能
深度学习
NLP
计算机视觉
强化学习

【免费下载链接】google-research

Google Research

项目地址：https://gitcode.com/gh_mirrors/go/google-research

本指南以 Google Research 仓库social_rl/gym_multigrid模块为核心，讲解 MultiGrid 多智能体网格世界环境的背景、与 MiniGrid 的 API 差异、文本化人工控制工具的使用方法，以及MultiGridEnv的核心参数、观测/动作空间与已注册环境。读完本文，你将能够手动运行并调试任意 MultiGrid 环境，理解多代理并行交互的实现原理，并据此接入自己的多智能体强化学习训练流程。

什么是 MultiGrid

MultiGrid（Multi-agent Minimalistic Gridworld Environment）是 MiniGrid 的继承与扩展。MiniGrid 是一个基于 OpenAI Gym API 的轻量级快速网格世界环境，而 MultiGrid 在其基础上引入了多代理同时行动的能力：多个代理可以同时在环境中行动，每个代理拥有自己独立的部分可观测视图（partially observable view），代理之间可能为资源相互竞争。

模块的核心代码位于 social_rl/gym_multigrid/multigrid.py，其中MultiGridEnv直接继承自 MiniGrid 的MiniGridEnv，并通过重写step、reset、gen_obs、render等方法将单代理环境推广到多代理场景。MultiGrid 保持了对 MiniGrid 的向后兼容，也支持单代理训练，因此原有的 MiniGrid 用法可以平滑迁移。

与 MiniGrid 的核心差异

从 API 层面看，MultiGrid 与 MiniGrid 的关键区别在于step()的输入输出形态：

输入：不再传入单个动作，而是传入一个动作数组（array of actions），数组长度等于代理数量，每个元素对应一个代理的动作。
输出：返回一个观测数组，数组中每个元素是形如 dict 的观测（与 MiniGrid 一致）。

这一设计的实现位于 multigrid.py 的step()方法。需要注意两个细节：

公平性处理：每一步中，代理以随机顺序依次行动（np.random.shuffle(agent_ordering)），避免固定的行动先后顺序给某些代理带来不公平优势。
观测结构：与 MiniGrid 不同，MultiGrid 在观测中不包含'mission'的字符串文本，观测 dict 主要包含image与direction两个字段（详见下文“观测空间”一节）。

此外，MultiGrid 在非竞争模式下，所有 episode 都运行固定的最大步数：如果某个代理提前完成任务，它会在网格中的新位置重生（respawn），以便在步数预算内尽可能多地重复完成任务；即使只有一个代理，也应设计为固定步数并允许代理在步数内多次寻找目标，才能与该设计公平比较。

基本用法：文本化人工控制

MultiGrid 提供了一种基于文本的 UI 应用，允许你手动控制每个代理来测试环境功能。该脚本位于 social_rl/gym_multigrid/manual_control_multiagent.py，其设计初衷是环境以字符串形式渲染，因此可以透过 SSH 在无图形界面的服务器上使用。

默认运行方式：

python -m manual_control_multiagent.py

指定环境运行，通过--env_name选项选择环境，例如：

python -m manual_control_multiagent.py --env_name MultiGrid-DoorKey-16x16-v0

脚本默认环境为MultiGrid-DoorKey-8x8-v0（见 manual_control_multiagent.py 的参数解析），并要求环境名以MultiGrid开头。

交互方式如下：

启动后会打印当前环境的字符串渲染结果，以及所有可用动作及其整数编号。
每次需要为所有代理同时输入动作，以逗号分隔，例如0,1,2表示三个代理分别执行动作 0、1、2；输入的动作数量必须与代理数量一致。
输入r重置环境，输入q退出。
每步执行后会打印各代理的奖励、累计奖励历史与累计奖励总和，并通过 matplotlib 渲染 RGB 图像；当done为真时打印 "Game over"。

注意：脚本内通过from social_rl import gym_multigrid的导入副作用触发环境注册（见 manual_control_multiagent.py），因此运行前需确保social_rl包位于 Python 路径中，且已安装依赖（gym、gym-minigrid、numpy、matplotlib）。

MultiGridEnv 核心参数

MultiGridEnv的构造函数（见 multigrid.py）提供了以下关键参数，用于控制环境规模、代理数量与观测形态：

参数	默认值	说明
`grid_size`	`None`	正方形网格的边长（瓦片数）；设置后不能再同时指定`width`/`height`
`width`/`height`	`None`	网格的宽、高（瓦片数）
`max_steps`	`100`	一个 episode 的最大步数
`see_through_walls`	`False`	代理能否看穿墙壁
`seed`	`52`	生成环境使用的随机种子
`agent_view_size`	`7`	代理方形部分可观测视图的边长
`n_agents`	`3`	环境中代理的数量
`competitive`	`False`	若为`True`，任一代理到达目标即结束全部代理的 episode；若为`False`，代理到达目标后在其他位置重生，episode 持续到`max_steps`
`fixed_environment`	`False`	若为`True`，每次生成环境时使用相同的随机种子，环境保持不变
`minigrid_mode`	`False`	若为`True`，保持与 MiniGrid 的单代理向后兼容（此时强制要求`n_agents == 1`）
`fully_observed`	`False`	若为`True`，每个代理获得完整环境状态的观测，而非以自我为中心的部分观测

实现中的几个关键行为：

当n_agents == 1时，competitive会被强制置为True（见 multigrid.py）。
当fully_observed为True时，agent_view_size被自动设置为max(width, height)，使观测覆盖整个网格。
若设置了grid_size，则断言width与height均为None并把二者同时赋值为grid_size。
minigrid_mode下观测与动作空间退化为 MiniGrid 的单代理形态（离散动作空间、三维图像观测）；否则动作空间为(n_agents,)的 Box，图像观测多出代理维度(n_agents, agent_view_size, agent_view_size, 3)（见 multigrid.py）。

动作与观测空间

动作空间

多代理模式下，动作空间是gym.spaces.Box(low=0, high=len(Actions)-1, shape=(n_agents,), dtype='int64')，即需要为每个代理提供一个动作索引。可用动作继承自 MiniGrid 的枚举（left、right、forward、pickup、drop、toggle、done），其中done默认作为空操作处理。在step_one_agent（见 multigrid.py）中，每个动作对应的世界变更如下：

left/right：原地左转/右转，更新方向并同步网格中的代理对象；
forward：尝试前移一格；若前方是goal或lava，代理完成任务并进入重生流程，若前方为空或可重叠则移动；代理不能互相穿过（前移时检查其他代理是否占据目标格）；
pickup/drop：拾取/放下前方物体；
toggle：切换/激活前方物体，对门（door）而言会尝试用手中同色钥匙开锁或开关门。

观测空间

observation_space是一个gym.spaces.Dict，包含：

image：(n_agents, agent_view_size, agent_view_size, 3)的 uint8 数组，每个代理的部分可观测视图（以自我为中心的视角，已按朝向旋转）；
direction：(n_agents,)的 uint8 数组，记录每个代理的朝向（保留额外维度以兼容 TF-Agents）；
当fully_observed=True时，额外包含position：(n_agents, 2)的 uint8 数组，记录每个代理的全局坐标（见 multigrid.py）。

部分可观测视图的生成流程是：先通过get_view_exts计算视野范围，用Grid.slice截取子网格，再按代理朝向旋转，最后通过process_vis计算可见性掩码（see_through_walls=False时墙壁会遮挡视线）。代理携带的物体会被放到视野底部中央的自身位置，以便代理看到自己拿了什么。

竞争模式与非竞争模式

competitive参数决定多代理场景的终局语义：

竞争模式（competitive=True）：只要有一个代理找到目标，整个 episode 对所有代理立即结束（collective_done = np.sum(self.done) >= 1）。这适用于竞速或对抗类任务。
非竞争模式（competitive=False）：episode 固定持续到max_steps；某个代理到达目标后会被重生到新位置继续探索，其他代理不受影响（见agent_is_done方法，multigrid.py）。若该代理正携带物体，物体也会被随机重新放置到网格中，以满足关卡依赖。

step()返回的done是所有代理共享的collective_done布尔值，而rewards仍是长度n_agents的数组，按代理分别统计。

内置环境一览

MultiGridEnv是一个可继承的基类，仓库在 social_rl/gym_multigrid/envs/ 下提供了 13 个具体环境模块，全部通过 envs/init.py 在导入时注册到 Gym：

模块	环境语义
`adversarial.py`	对抗式环境
`cluttered.py`	堆满障碍物的杂乱环境
`coingame.py`	硬币收集游戏
`doorkey.py`	门与钥匙任务（拿钥匙开锁到达目标）
`empty.py`	空房间，只有目标格，稀疏奖励
`fourrooms.py`	四房间布局
`gather.py`	收集物体任务（按颜色区分）
`lava_walls.py`	熔岩与墙壁障碍
`maze.py`	迷宫
`meetup.py`	会合/集合任务
`stag_hunt.py`	猎鹿博弈类协作/竞争任务
`tag.py`	追捕（tag）任务
`tasklist.py`	任务列表式多步骤任务

每个模块都定义了一组具体的环境子类并在文件末尾调用register()完成 Gym 注册。例如：

empty.py 注册了MultiGrid-Empty-5x5-v0、MultiGrid-Empty-8x8-v0、MultiGrid-Empty-16x16-v0、MultiGrid-Empty-5x5-Single-v0、MultiGrid-Empty-Random-6x6-Minigrid-v0等一系列环境。其中EmptyEnv本身支持n_agents、size、agent_start（fixed或random）、randomize_goal等参数，minigrid_mode=True的变体用于与 MiniGrid 单代理对齐。
doorkey.py 注册了MultiGrid-DoorKey-6x6-v0、MultiGrid-DoorKey-8x8-v0、MultiGrid-DoorKey-16x16-v0以及多个Single单代理变体。其place_one_agent被重写，确保代理总是被放置在门的一侧，且钥匙也在同侧，从而保证任务可解。
gather.py 注册了MultiGrid-Gather-v0、MultiGrid-Gather-Empty-6x6-v0、MultiGrid-Color-Gather-Empty-6x6-v0等收集类环境，支持n_goals（硬币数）、n_clutter（障碍物数）、n_colors（颜色种类）、random_colors等参数，并默认使用fully_observed=True与自定义的按颜色奖励逻辑。

README 中示例使用的MultiGrid-DoorKey-16x16-v0即来自 doorkey 模块：一个 16×16 网格、5 个代理、目标在右下角、中间有垂直分割墙与一把黄色钥匙门锁的环境。

Gym 注册机制

环境注册由 register.py 完成。其register(env_id, entry_point, reward_threshold=0.95)函数要求环境 ID 以MultiGrid-开头，将(id, entry_point)交给 Gym 的注册表，并默认设置reward_threshold=0.95（该阈值在 Gym 环境中用于判断任务是否被视为“已解决”）。

每个环境模块在文件末尾通过__loader__.name获取自身模块路径，并以module_path + ':EnvClassName'作为entry_point注册，例如：

register( env_id='MultiGrid-DoorKey-16x16-v0', entry_point=module_path + ':DoorKeyEnv16x16' )

因此，只要import social_rl.gym_multigrid（导入envs/__init__.py触发全部子模块），所有环境就会一次性注册到 Gym，之后即可通过gym.make('MultiGrid-...-v0')创建任意环境实例。

在强化学习训练中的应用

MultiGrid 的MultiGridEnv严格遵循 Gym API（reset/step/render），且观测空间为gym.spaces.Dict、动作空间为数组形态，天然适配多智能体 RL 框架。在本仓库的 social_rl/ 顶层还包含配套的训练组件：

social_rl/multiagent_tfagents/：基于 TF-Agents 的多代理训练实现，可与 MultiGrid 环境直接对接；
social_rl/adversarial_env/：对抗环境训练框架；
social_rl/self_tuning_follower/：自适应跟随者相关实验。

多代理训练的基本模式是：在每个 step 为全部代理各产生一个动作组成数组传入env.step(actions)，收取返回的观测数组、奖励数组与共享的done，从而并行优化每个代理的策略。观测中的direction字段专门保留了额外维度以兼容 TF-Agents 的观测格式，这也印证了该环境面向 TF-Agents 生态的设计取向。