MARLlib：多智能体强化学习库

多智能体强化学习库（MARLlib） 是一个基于 Ray 及其工具包之一 RLlib 的 多智能体强化学习库。它提供了一个全面的平台，用于开发、训练和测试各种任务及环境下的多智能体强化学习算法。

以下是 MARLlib 的使用示例：

from marllib import marl

# 准备环境
env = marl.make_env(environment_name="mpe", map_name="simple_spread", force_coop=True)

# 使用指定超参数初始化算法
mappo = marl.algos.mappo(hyperparam_source='mpe')

# 基于环境、算法和用户偏好构建智能体模型
model = marl.build_model(env, mappo, {"core_arch": "mlp", "encode_layer": "128-256"})

# 开始训练
mappo.fit(env, model, stop={'timesteps_total': 1000000}, share_policy='group')

为什么选择 MARLlib？

下面我们提供一张表格，用于比较 MARLlib 与现有工作。

库名	支持环境	算法数量	参数共享方式	模型架构	文档状态
PyMARL	1 个合作环境	5	共享	GRU	:x:
PyMARL2	2 个合作环境	11	共享	MLP + GRU	:x:
MAPPO Benchmark	4 个合作环境	1	共享 + 分离	MLP + GRU	:x:
MAlib	4 种自对战场景	10	共享 + 分组 + 分离	MLP + LSTM
EPyMARL	4 个合作环境	9	共享 + 分离	GRU	:x:
HARL	8 个合作环境	9	共享 + 分离	MLP + CNN + GRU	:x:
MARLlib	17 种环境（无任务模式限制）	18	共享 + 分组 + 分离 + 可定制	MLP + CNN + GRU + LSTM

库名	GitHub 星数	文档	开放问题数	活跃度	最后更新时间
PyMARL		:x:
PyMARL2		:x:
MAPPO Benchmark		:x:
MAlib
EPyMARL		:x:
HARL*		:x:
MARLlib

* HARL 是最近发布的最新 MARL 库：fire:。如果你的目标是前沿的、性能最先进的 MARL 算法，那么 HARL 绝对值得你 一看！

主要特性

:beginner: MARLlib 提供了多项关键特性，使其脱颖而出：

• MARLlib 通过代理级别的分布式数据流统一了多样化的算法流程，使研究人员能够在不同的任务和环境中开发、测试和评估多智能体强化学习算法。
• MARLlib 支持所有任务模式，包括合作、协作、竞争和混合模式。这使得研究人员能够更轻松地在各种任务中训练和评估多智能体强化学习算法。
• MARLlib 提供了一个遵循 Gym 结构的新接口，使研究人员更容易处理多智能体环境。
• MARLlib 提供灵活且可定制的参数共享策略，允许研究人员针对不同任务和环境优化其算法。

:rocket: 使用 MARLlib，您可以享受多种优势，例如：

• 无需多智能体强化学习知识：MARLlib 提供了 18 种预构建的算法，并配有直观的 API，使研究人员无需事先了解该领域即可开始实验多智能体强化学习。
• 支持所有任务模式：MARLlib 几乎支持所有的多智能体环境，使研究人员能够更轻松地尝试不同的任务模式。
• 可定制的模型架构：研究人员可以从模型库中选择自己喜欢的模型架构，也可以自行构建。
• 可定制的策略共享：MARLlib 提供了策略共享的分组选项，或者研究人员也可以自定义自己的策略共享方式。
• 访问上千个已发布的实验：研究人员可以访问上千个已发布的实验，了解其他研究人员是如何使用 MARLlib 的。

安装

注意： 请注意，目前 MARLlib 仅兼容 Linux 操作系统。

分步安装（推荐）

• 安装依赖项
• 安装环境
• 安装补丁

1. 安装依赖项（基础）

首先，安装 MARLlib 的依赖项以确保基本使用。 按照 此指南，最后为 RLlib 安装补丁。

$ conda create -n marllib python=3.8 # 或 3.9
$ conda activate marllib
$ git clone https://github.com/Replicable-MARL/MARLlib.git && cd MARLlib
$ pip install -r requirements.txt

2. 安装环境（可选）

请按照 此指南 进行操作。

注意： 我们建议使用大约 0.20.0 版本的 gym。

pip install "gym==0.20.0"

3. 安装补丁（基础）

使用补丁修复 RLlib 的错误，运行以下命令：

$ cd /Path/To/MARLlib/marllib/patch
$ python add_patch.py -y

PyPI

$ pip install --upgrade pip
$ pip install marllib

基于 Docker 的使用

我们在 MARLlib/docker/Dockerfile 中提供了用于构建 MARLlib Docker 镜像的 Dockerfile，并在 MARLlib/.devcontainer 文件夹中提供了 devcontainer 设置。如果您使用 devcontainer，请注意，您可能需要根据您的硬件设备自定义 devcontainer.json 中的 runArgs 参数，例如 --shm-size 参数。

开始使用

准备配置

整个训练过程由四个部分的配置负责。

• 场景：指定环境/任务设置
• 算法：选择算法的超参数
• 模型：自定义模型架构
• ray/rllib：更改基本训练设置

在开始训练之前，请确保所有参数都已正确设置，尤其是那些您不希望更改的参数。

注意： 您也可以通过 MARLLib API 修改所有预设参数。*

from marllib import marl



# 准备环境
env = marl.make_env(environment_name="smac", map_name="5m_vs_6m")
# 使用指定超参数初始化算法
mappo = marl.algos.mappo(hyperparam_source="smac")
# 根据环境、算法和用户偏好构建智能体模型
model = marl.build_model(env, mappo, {"core_arch": "gru", "encode_layer": "128-256"})
# 开始训练
mappo.fit(
  env, model, 
  stop={"timesteps_total": 1000000}, 
  checkpoint_freq=100, 
  share_policy="group"
)
# 渲染
mappo.render(
  env, model, 
  local_mode=True, 
  restore_path={'params_path': "checkpoint/params.json",
                'model_path': "checkpoint/checkpoint-10"}
)

结果

在当前工作目录下，您可以找到所有的训练数据（日志文件和 TensorFlow 文件）以及保存的模型。要可视化学习曲线，您可以使用 TensorBoard。请按照以下步骤操作：

1. 通过运行以下命令安装 TensorBoard：

pip install tensorboard

2. 使用以下命令启动 TensorBoard 并可视化结果：

tensorboard --logdir .

您也可以参考这篇教程，获取更详细的说明。

有关所有现有结果的列表，请访问此链接。请注意，这些结果来自 MARLlib 的旧版本，因此可能与当前结果存在不一致之处。

快速示例

MARLlib 提供了一些实用示例供您参考。

• 详细 API 使用：展示如何详细使用 MARLlib API，例如结合命令行和 API 运行。
• 自定义策略共享：根据当前任务自定义您的组策略共享策略。
• 加载模型：加载预训练模型并继续训练。
• 加载模型并渲染：基于预训练模型渲染环境。
• 集成新环境：按照 MARLlib 的环境-智能体交互接口添加您的新环境。
• 集成新算法：按照 MARLlib 的学习流程添加您的新算法。
• 并行微调：使用 ray.tune 微调您的策略/模型性能。

教程

在 Google Colaboratory 上尝试 MPE + MAPPO 示例！ 更多教程文档可在这里找到。

精选列表

收集了多智能体强化学习（MARL）的研究和综述论文。这些论文已按发表日期及其对相应环境的评估进行整理。

算法： 环境：

社区

路线图

未来版本的路线图可在ROADMAP.md中查看。

贡献

我们是一个专注于多智能体强化学习的小团队，非常欢迎任何帮助！ 如果您想参与其中，以下是关于贡献指南及如何在本地测试代码的信息。

您可以通过多种方式做出贡献，例如报告 bug、撰写或翻译文档、审查或重构代码、请求或实现新功能等。

引用

如果您在研究中使用 MARLlib，请引用MARLlib 论文。

@article{hu2022marllib,
  author  = {Siyi Hu and Yifan Zhong and Minquan Gao and Weixun Wang and Hao Dong and Xiaodan Liang and Zhihui Li and Xiaojun Chang and Yaodong Yang},
  title   = {MARLlib: 一个可扩展且高效的多智能体强化学习库},
  journal = {机器学习研究期刊},
  year    = {2023},
}

基于或密切合作于 MARLlib 的作品 <链接>

@InProceedings{hu2022policy,
      title={通过测量角色多样性进行合作式多智能体 RL 中的策略诊断},
      author={Hu, Siyi 和 Xie, Chuanlong 和 Liang, Xiaodan 和 Chang, Xiaojun},
      booktitle={第 39 届国际机器学习大会论文集},
      year={2022},
}
@misc{zhong2023heterogeneousagent,
      title={异构智能体强化学习}, 
      author={Yifan Zhong 和 Jakub Grudzien Kuba 和 Siyi Hu 和 Jiaming Ji 和 Yaodong Yang},
      archivePrefix={arXiv},
      year={2023},
}

MARLlib 快速上手指南

MARLlib 是一个基于 Ray 和 RLlib 构建的多智能体强化学习（MARL）库。它支持协作、竞争及混合等多种任务模式，提供 18 种预置算法和灵活的模型架构，旨在降低 MARL 研究门槛，让开发者无需深厚的领域知识即可快速开展实验。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：目前仅支持 Linux 系统。
• Python 版本：推荐 Python 3.8 或 3.9。
• 包管理工具：建议使用 conda 进行环境管理。
• 网络环境：由于需要克隆仓库和安装依赖，请确保网络连接畅通（国内用户可配置 pip 国内镜像源加速下载）。

安装步骤

推荐按照以下步骤进行分步安装，以确保基础依赖和环境补丁正确配置。

1. 创建并激活虚拟环境

conda create -n marllib python=3.8
conda activate marllib

2. 克隆代码库并安装基础依赖

git clone https://github.com/Replicable-MARL/MARLlib.git
cd MARLlib
pip install -r requirements.txt

提示：国内用户可使用清华或阿里镜像源加速安装，例如： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装特定环境与补丁（可选但推荐）

MARLlib 支持多种环境（如 MPE, StarCraft II, Google Research Football 等）。如需使用特定环境，请参考官方文档中的 环境安装指南 进行额外安装。

重要：安装完依赖后，务必安装针对 RLlib 的补丁以保证兼容性：

# 具体补丁安装命令请参考项目根目录或文档说明，通常在安装依赖后自动处理或需手动运行特定脚本

基本使用

MARLlib 提供了直观的 API，只需几行代码即可启动训练。以下是一个在 MPE (Multi-Agent Particle Environment) 的 simple_spread 地图上训练 MAPPO 算法的最小示例：

from marllib import marl

# 1. 准备环境
# environment_name: 环境名称
# map_name: 具体地图/场景名称
# force_coop: 是否强制协作模式
env = marl.make_env(environment_name="mpe", map_name="simple_spread", force_coop=True)

# 2. 初始化算法
# hyperparam_source: 加载预设的超参数配置（对应环境名）
mappo = marl.algos.mappo(hyperparam_source='mpe')

# 3. 构建模型
# core_arch: 核心网络架构 (mlp, cnn, gru 等)
# encode_layer: 隐藏层结构
model = marl.build_model(env, mappo, {"core_arch": "mlp", "encode_layer": "128-256"})

# 4. 开始训练
# stop: 停止条件 (如总步数)
# share_policy: 策略共享方式 ('group', 'all', 'separate' 等)
mappo.fit(env, model, stop={'timesteps_total': 1000000}, share_policy='group')

运行上述脚本后，MARLlib 将自动利用 Ray 进行分布式数据采集与模型训练，并在控制台输出训练日志。