BenchMARL

python benchmarl/run.py algorithm=mappo task=vmas/balance

• 观看关于BenchMARL和TorchRL中多智能体仿真与学习的演讲。
• 观看关于在VMAS中创建自定义场景并在BenchMARL中训练该场景的讲座

什么是BenchMARL 🧐？

BenchMARL是一个多智能体强化学习（MARL）训练库，旨在实现不同MARL算法和环境之间的可重复性和基准测试。其使命是提供一个标准化的接口，便于新算法和环境的集成，从而与现有解决方案进行公平比较。BenchMARL以TorchRL为后端，这使其具备高性能和最先进的实现。它还使用hydra进行灵活且模块化的配置，并且其数据报告与marl-eval兼容，以支持标准化和统计上稳健的评估。

BenchMARL的核心设计原则包括：

• 通过系统化的配置基础和标准化实现可重复性
• 标准化且统计稳健的绘图与报告
• 实验独立于算法、环境和模型的选择
• 覆盖广泛的MARL生态系统
• 易于实现新的算法、环境和模型
• 充分利用TorchRL的知识与基础设施，而不重复造轮子

我为什么要使用BenchMARL 🤔？

你可能会问，为什么我要使用BenchMARL呢？其实，你可以用BenchMARL来比较不同的算法、环境和模型，检验你的新研究与现有成果的差异，或者只是想初步了解这一领域，快速掌握当前的研究现状。

目录

• BenchMARL
  • 如何使用
    • Notebooks
    • 安装
    • 运行
  • 概念
  • 精细调优的公开基准
  • 报告与绘图
  • 扩展
  • 配置
    • 实验
    • 算法
    • 任务
    • 模型
  • 特性
    • 日志记录
    • 检查点
    • 回调函数
  • 引用BenchMARL

如何使用

Notebooks

•   运行BenchMARL实验。
•   在VMAS中创建场景并在BenchMARL中训练。我们将创建一个场景，其中多个具有不同形态的机器人需要在避开彼此及障碍物的同时到达各自的目标，并使用MAPPO和MLP/GNN策略进行训练。

安装

安装TorchRL

你可以从PyPI安装TorchRL。

pip install torchrl

更多详细信息或安装夜间版本，请参阅 TorchRL安装指南。

安装BenchMARL

你可以直接从GitHub安装：

pip install benchmarl

或者克隆到本地以访问配置文件和脚本：

git clone https://github.com/facebookresearch/BenchMARL.git
pip install -e BenchMARL

安装环境

BenchMARL中的所有环境依赖项都是可选的，可以单独安装。

VMAS

pip install vmas

PettingZoo

pip install "pettingzoo[all]"

MeltingPot

pip install dm-meltingpot

MAgent2

pip install git+https://github.com/Farama-Foundation/MAgent2

SMACv2

请按照环境仓库中的说明进行操作。 这里是我们如何在Linux上安装它的方法。

运行

实验使用一个默认配置启动，该配置可以通过多种方式覆盖。要了解如何自定义和覆盖配置，请参阅配置部分。

命令行

要从命令行启动一个实验，可以执行以下命令：

python benchmarl/run.py algorithm=mappo task=vmas/balance

得益于hydra，你可以像运行多组实验一样执行基准测试，例如：

python benchmarl/run.py -m algorithm=mappo,qmix,masac task=vmas/balance,vmas/sampling seed=0,1

hydra 多组运行的默认实现是顺序执行，但也有并行和slurm启动器可供选择。

脚本

你也可以在脚本中加载并启动你的实验：

experiment = Experiment(
    task=VmasTask.BALANCE.get_from_yaml(),
    algorithm_config=MappoConfig.get_from_yaml(),
    model_config=MlpConfig.get_from_yaml(),
    critic_model_config=MlpConfig.get_from_yaml(),
    seed=0,
    config=ExperimentConfig.get_from_yaml(),
)
experiment.run()

你还可以在Benchmark中运行多个实验：

benchmark = Benchmark(
    algorithm_configs=[
        MappoConfig.get_from_yaml(),
        QmixConfig.get_from_yaml(),
        MasacConfig.get_from_yaml(),
    ],
    tasks=[
        VmasTask.BALANCE.get_from_yaml(),
        VmasTask.SAMPLING.get_from_yaml(),
    ],
    seeds={0, 1},
    experiment_config=ExperimentConfig.get_from_yaml(),
    model_config=MlpConfig.get_from_yaml(),
    critic_model_config=MlpConfig.get_from_yaml(),
)
benchmark.run_sequential()

概念

BenchMARL 的目标是将不同的多智能体强化学习环境和算法统一到相同的接口下，从而实现公平且可重复的比较与基准测试。BenchMARL 是一个全流程的统一训练库，旨在让用户只需一行代码就能在我们的算法和任务之间进行任何他们想要的比较。为了实现这一目标，BenchMARL 将来自TorchRL的组件相互连接起来，后者提供了一个高效可靠的后端。

该库为每个组件都提供了一个默认配置。虽然其中一些配置是可以更改的（例如实验配置），但另一些配置（如任务）则不应被更改，以确保结果的可重复性。为此，BenchMARL 的每个版本都会配有一个默认配置。

接下来，我们将介绍该库中的每个组件。

实验。实验是一次训练运行，其中算法、任务和模型都是固定的。实验通过传递这些值以及随机种子和实验超参数来配置。实验的超参数涵盖了在线和离线算法、离散和连续动作，以及概率性和确定性策略（因为它们与所使用的算法或任务无关）。实验可以从命令行或脚本中启动。更多信息请参阅运行部分。

基准测试。在该库中，我们称“基准测试”为一组实验的集合，这些实验可以在任务、算法或模型上有所不同。基准测试中的所有实验共享相同的实验配置。基准测试允许以标准化的方式比较不同的多智能体强化学习组件。基准测试可以从命令行或脚本中启动。更多信息请参阅运行部分。

算法。算法是由多个组件（例如损失函数、回放缓冲区等）组成的集合，它们决定了训练策略。以下是 BenchMARL 中当前已实现算法的表格。

名称	开关策略	策略-价值网络	评价网络是否具备完全可观测性	动作兼容性	概率型策略网络
MAPPO	开	是	是	连续 + 离散	是
IPPO	开	是	否	连续 + 离散	是
MADDPG	关	是	是	连续	否
IDDPG	关	是	否	连续	否
MASAC	关	是	是	连续 + 离散	是
ISAC	关	是	否	连续 + 离散	是
QMIX	关	否	不适用	离散	否
VDN	关	否	不适用	离散	否
IQL	关	否	不适用	离散	否

任务。任务是来自特定环境的场景，构成了需要解决的多智能体强化学习挑战。 它们在许多方面有所不同，以下是BenchMARL中当前环境的表格：

环境	任务	合作性	全局状态	奖励函数	动作空间	向量化
VMAS	27	合作 + 竞争	否	共享 + 独立 + 全局	连续 + 离散	是
SMACv2	15	合作	是	全局	离散	否
MPE	8	合作 + 竞争	是	共享 + 独立	连续 + 离散	否
SISL	2	合作	否	共享	连续	否
MeltingPot	49	合作 + 竞争	是	独立	离散	否
MAgent2	1	合作 + 竞争	是	分组全局	离散	否

[!NOTE]
BenchMARL 使用 TorchRL MARL API 来对智能体进行分组。 在竞争性环境中，例如 MPE，队伍会分属不同组别。每个组别都有自己的损失、模型、经验回放池等。 参数共享选项指的是组内共享。更多信息请参阅创建自定义算法 的示例。

模型。模型是用于处理数据的神经网络。它们可以作为策略网络使用，也可以根据需求用作评价网络。我们提供了一组基础模型（层）以及一个用于串联不同层的SequenceModel。所有模型都可以在智能体组内选择是否进行参数共享。以下是BenchMARL中实现的模型列表：

名称	去中心化	局部输入的集中式	全局输入的集中式
MLP	是	是	是
GRU	是	是	是
LSTM	是	是	是
GNN	是	是	否
CNN	是	是	是
Deepsets	是	是	是

微调后的公开基准测试

[!WARNING]
本节仍在开发中。我们正不断优化实验，以便用户能够访问最先进的基准测试。
如果您希望参与这项工作，请与我们联系。

在 fine_tuned 文件夹中，我们收集了一些针对特定环境的已测试超参数，以帮助用户快速启动基准测试。您只需运行该文件夹中的脚本，即可自动使用建议的超参数。

我们将为您调整基准测试，并将配置文件和基准测试图表公开发布到 Wandb 上。

目前可用的基准包括：

• VMAS:

以下是结果表格：

环境	样本效率曲线（所有任务）	性能概况	综合评分
VMAS

报告与绘图

报告与绘图功能与 marl-eval 兼容。
如果 experiment.create_json=True（这是 实验配置 中的默认设置），则会在实验输出文件夹中生成一个名为 {experiment_name}.json 的文件，其格式符合 marl-eval 的标准。
您可以使用 eval_results 中的工具加载并合并这些文件，从而轻松创建美观的基准测试图表。再也不用为 matplotlib 和 LaTeX 而烦恼了！

扩展

BenchMARL 的核心原则之一是允许用户利用现有的算法和任务实现来评估自己新提出的解决方案。

为此，我们在 算法、任务 和 模型 中提供了具有简单抽象方法的标准接口。
要在库中引入您的解决方案，您只需实现这些基类所暴露的抽象方法，这些基类使用 TorchRL 库中的对象。

以下是一个如何创建自定义算法的示例 。

以下是一个如何创建自定义任务的示例 。

以下是一个如何创建自定义模型的示例 。

配置

如 运行 部分所述，该项目既可以在脚本本身中进行配置，也可以通过 hydra 进行配置。
我们建议您阅读 hydra 的文档，以熟悉其所有功能。

项目中的每个组件都在 BenchMARL 的 conf 树 中拥有对应的 YAML 配置文件。
这些配置文件会被加载到 Python 数据类中，作为验证参数名称和类型的模式。这样我们既能将配置与代码分离，又能通过强类型检查确保参数的正确性！
您还可以直接从脚本中调用 ComponentConfig.get_from_yaml() 来加载和验证配置 YAML 文件，而无需使用 hydra。

实验

实验配置位于 benchmarl/conf/config.yaml。借助 Hydra 配置，运行自定义实验变得极为简便。库的默认配置包含在 benchmarl/conf 文件夹中。

运行实验时，可以通过以下方式覆盖其超参数：

python benchmarl/run.py task=vmas/balance algorithm=mappo experiment.lr=0.03 experiment.evaluation=true experiment.train_device="cpu"

实验超参数从 benchmarl/conf/experiment/base_experiment.yaml 加载到一个数据类 ExperimentConfig 中，该类定义了这些参数的有效范围。这样可以确保只加载预期的参数，并且类型正确。你也可以通过调用 ExperimentConfig.get_from_yaml() 直接从脚本中加载这些参数。

以下是使用 Hydra 覆盖实验超参数的示例 ，或直接从脚本中覆盖 。

算法

在启动 BenchMARL 时，你可以覆盖算法的配置。

python benchmarl/run.py task=vmas/balance algorithm=masac algorithm.num_qvalue_nets=3 algorithm.target_entropy=auto algorithm.share_param_critic=true

可用算法及其默认配置可在 benchmarl/conf/algorithm 中找到。它们会被加载到每个算法对应的数据类 AlgorithmConfig 中，以定义其参数范围。这确保了只会加载预期的参数，并且类型正确。你也可以通过调用 YourAlgorithmConfig.get_from_yaml() 直接从脚本中加载这些配置。

以下是使用 Hydra 覆盖算法超参数的示例 ，或直接从脚本中覆盖 。

任务

在启动 BenchMARL 时，你可以覆盖任务的配置。然而，出于可重复性的考虑，不建议在基准测试中这样做，因为任务应具有固定的版本和参数。

python benchmarl/run.py task=vmas/balance algorithm=mappo task.n_agents=4

可用任务及其默认配置可在 benchmarl/conf/task 中找到。它们会被加载到一个数据类 TaskConfig 中，用于定义任务的范围。任务是以环境名称为前缀的枚举类型。例如，VmasTask.NAVIGATION 表示 VMAS 模拟器中的导航任务。这支持自动补全功能，并能一次性查看所有可用任务。你也可以通过调用 YourEnvTask.TASK_NAME.get_from_yaml() 直接从脚本中加载这些配置。

以下是使用 Hydra 覆盖任务超参数的示例 ，或直接从脚本中覆盖 。

模型

在启动 BenchMARL 时，你可以覆盖模型的配置。默认情况下，会加载一个具有默认配置的 MLP 模型。你可以按如下方式更改：

python benchmarl/run.py task=vmas/balance algorithm=mappo model=layers/mlp model=layers/mlp model.layer_class="torch.nn.Linear" "model.num_cells=[32,32]" model.activation_class="torch.nn.ReLU"

可用模型及其配置可在 benchmarl/conf/model/layers 中找到。它们会被加载到一个数据类 ModelConfig 中，用于定义模型的参数范围。你也可以通过调用 YourModelConfig.get_from_yaml() 直接从脚本中加载这些配置。

以下是使用 Hydra 覆盖模型超参数的示例 ，或直接从脚本中覆盖 。

序列模型

你可以将多个层组合成一个序列模型。可用层的名称位于 benchmarl/conf/model/layers 文件夹中。

python benchmarl/run.py task=vmas/balance algorithm=mappo model=sequence "model.intermediate_sizes=[256]" "model/layers@model.layers.l1=mlp" "model/layers@model.layers.l2=mlp" "+model/layers@model.layers.l3=mlp" "model.layers.l3.num_cells=[3]"

使用 "+model/layers@model.layers.l3=mlp" 添加一层。

使用 "~model.layers.l2" 移除一层。

使用 "model.layers.l1.num_cells=[3]" 配置某一层。

以下是使用 Hydra 创建序列模型的示例 ，或直接从脚本中创建 。

功能

BenchMARL 具有以下几项功能：

• 包含集成和训练测试流程的测试 CI，适用于所有模拟器和算法。
• 集成到官方 TorchRL 生态系统中，提供专门的支持。
• 可以为不同的智能体群体使用不同的算法和模型（参见 examples/ensemble）。

日志记录

BenchMARL 兼容 TorchRL 日志记录器。可以在实验配置文件 (benchmarl/conf/experiment/base_experiment.yaml) 中提供日志记录器名称列表。可用选项包括：wandb、csv、mflow、tensorboard，以及 TorchRL 中提供的其他任何选项。你可以在 YAML 配置文件或脚本参数中指定日志记录器，例如：

python benchmarl/run.py algorithm=mappo task=vmas/balance "experiment.loggers=[wandb]"

wandb 日志记录器与实验恢复完全兼容，能够自动恢复已加载实验的运行。

检查点

实验可以每隔 experiment.checkpoint_interval 个收集到的帧进行一次检查点保存。 实验会使用一个用于日志记录和检查点保存的输出文件夹，该文件夹可以在 experiment.save_folder 中指定。 如果未指定， 默认将使用 Hydra 的输出文件夹（如果使用 Hydra）或当前脚本启动的目录。 输出文件夹中会为每个实验创建一个以实验名称命名的子文件夹， 其检查点文件将存储在该实验文件夹内的 "checkpoints" 文件夹中。

python benchmarl/run.py task=vmas/balance algorithm=mappo experiment.max_n_iters=3 experiment.on_policy_collected_frames_per_batch=100 experiment.checkpoint_interval=100

要从检查点加载模型，只需将检查点文件的绝对路径传递给 experiment.restore_file 即可。

python benchmarl/run.py task=vmas/balance algorithm=mappo experiment.max_n_iters=6 experiment.on_policy_collected_frames_per_batch=100 experiment.restore_file="/hydra/experiment/folder/checkpoint/checkpoint_300.pt"

以下是修改配置时的 Python 示例： 以及保持配置不变的示例： 。

此外，还可以直接通过文件名来恢复和评估 Hydra 实验：

python benchmarl/evaluate.py ../outputs/2024-09-09/20-39-31/mappo_balance_mlp__cd977b69_24_09_09-20_39_31/checkpoints/checkpoint_100.pt

python benchmarl/resume.py ../outputs/2024-09-09/20-39-31/mappo_balance_mlp__cd977b69_24_09_09-20_39_31/checkpoints/checkpoint_100.pt

回调函数

实验可以选择性地接受一个 Callback 列表，这些回调对象包含多个方法， 例如 on_batch_collected、on_train_end 和 on_evaluation_end，可用于监控训练过程中的各项指标。

引用 BenchMARL

如果您在研究中使用了 BenchMARL，请使用以下 BibTeX 条目：

@article{bettini2024benchmarl,
  author  = {Matteo Bettini and Amanda Prorok and Vincent Moens},
  title   = {BenchMARL: 多智能体强化学习基准测试},
  journal = {机器学习研究期刊},
  year    = {2024},
  volume  = {25},
  number  = {217},
  pages   = {1--10},
  url     = {http://jmlr.org/papers/v25/25-217.html}
}

许可证

BenchMARL 采用 MIT 许可证授权。详情请参阅 LICENSE 文件。

BenchMARL 快速上手指南

BenchMARL 是一个基于 TorchRL 构建的多智能体强化学习（MARL）训练库，旨在提供标准化的接口，以便在不同算法和环境之间进行公平的比较和基准测试。它支持灵活的配置（Hydra）和强大的数据报告功能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 3.8, 3.9, 3.10 或 3.11
• 前置依赖: 建议先安装好 PyTorch。

国内加速提示： 建议使用国内镜像源加速 Python 包的安装。例如使用清华源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

1. 安装后端依赖 (TorchRL)

BenchMARL 依赖 TorchRL 作为后端。

pip install torchrl

2. 安装 BenchMARL

您可以直接通过 PyPI 安装，或者克隆源码以便修改配置和脚本。

方式一：直接安装（推荐）

pip install benchmarl

方式二：源码安装（便于开发）

git clone https://github.com/facebookresearch/BenchMARL.git
pip install -e BenchMARL

3. 安装环境依赖（可选）

BenchMARL 支持多种多智能体环境，您可以根据需要单独安装：

• VMAS (向量多智能体模拟器):

  pip install vmas
  

• PettingZoo:

  pip install "pettingzoo[all]"
  

• MeltingPot:

  pip install dm-meltingpot
  

• MAgent2:

  pip install git+https://github.com/Farama-Foundation/MAgent2
  

• SMACv2: 请参考其官方仓库说明进行安装。

基本使用

BenchMARL 的核心设计理念是通过一行命令即可启动实验。默认配置位于 benchmarl/conf，可通过命令行参数覆盖。

命令行运行单个实验

以下命令将使用 MAPPO 算法在 VMAS 的 balance 任务上运行训练：

python benchmarl/run.py algorithm=mappo task=vmas/balance

命令行运行基准测试（多实验并行）

利用 Hydra 的功能，您可以一次性运行多个算法、任务和随机种子的组合：

python benchmarl/run.py -m algorithm=mappo,qmix,masac task=vmas/balance,vmas/sampling seed=0,1

注：默认执行方式为串行，也可配置为并行或提交到 Slurm 集群运行。

Python 脚本运行

您也可以在 Python 代码中加载并运行实验或基准测试：

运行单个实验：

from benchmarl.experiment import Experiment
from benchmarl.tasks import VmasTask
from benchmarl.algorithms import MappoConfig
from benchmarl.models import MlpConfig
from benchmarl.experiment.common import ExperimentConfig

experiment = Experiment(
    task=VmasTask.BALANCE.get_from_yaml(),
    algorithm_config=MappoConfig.get_from_yaml(),
    model_config=MlpConfig.get_from_yaml(),
    critic_model_config=MlpConfig.get_from_yaml(),
    seed=0,
    config=ExperimentConfig.get_from_yaml(),
)
experiment.run()

运行基准测试：

from benchmarl.experiment import Benchmark
from benchmarl.algorithms import MappoConfig, QmixConfig, MasacConfig
from benchmarl.tasks import VmasTask
from benchmarl.models import MlpConfig
from benchmarl.experiment.common import ExperimentConfig

benchmark = Benchmark(
    algorithm_configs=[
        MappoConfig.get_from_yaml(),
        QmixConfig.get_from_yaml(),
        MasacConfig.get_from_yaml(),
    ],
    tasks=[
        VmasTask.BALANCE.get_from_yaml(),
        VmasTask.SAMPLING.get_from_yaml(),
    ],
    seeds={0, 1},
    experiment_config=ExperimentConfig.get_from_yaml(),
    model_config=MlpConfig.get_from_yaml(),
    critic_model_config=MlpConfig.get_from_yaml(),
)
benchmark.run_sequential()