BenchMARL

BenchMARL

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

观看关于BenchMARL和TorchRL中多智能体仿真和学习的讲座。

BenchMARL是什么？🧐

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

BenchMARL的核心设计原则是：

通过系统性的基础和标准化配置实现可复现性
标准化和统计上强大的绘图和报告
实验独立于算法、环境和模型选择
涵盖MARL生态系统的广度
易于实现新的算法、环境和模型
利用TorchRL的专业知识和基础设施，避免重复造轮子

为什么要使用BenchMARL？🤔

你可能会问，为什么要使用BenchMARL？好吧，你可以使用BenchMARL来比较不同的算法、环境和模型，检查你的新研究与现有研究相比如何，或者如果你只是想接触这个领域并希望轻松地了解整体情况。

如何使用

笔记本

运行BenchMARL实验。

安装

安装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

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的目标是将不同的MARL环境和算法统一在相同的接口下，以实现公平和可复现的比较和基准测试。BenchMARL是一个完整的统一训练库，旨在使用户只需一行代码就能在我们的算法和任务之间进行任何想要的比较。为了实现这一目标，BenchMARL与TorchRL的组件相互连接，提供高效可靠的后端支持。

该库为每个组件提供了默认配置。虽然部分配置应该被更改(例如实验配置)，但其他部分(如任务)不应被更改以保证可重复性。为此，BenchMARL的每个版本都与默认配置相对应。

现在让我们介绍库中的每个组件。

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

基准测试。在库中，我们将一组可以在任务、算法或模型上变化的实验称为benchmark。基准测试在所有实验中共享相同的实验配置。基准测试允许以标准化的方式比较不同的MARL组件。基准测试可以从命令行或脚本启动。有关更多信息，请参阅运行部分。

算法。算法是确定训练策略的组件(例如，损失、重放缓冲区)的集合。下表列出了BenchMARL中当前实现的算法。

名称	在策略/离策略	Actor-critic	Critic中的完全可观察性	动作兼容性	概率性actor
MAPPO	在策略	是	是	连续 + 离散	是
IPPO	在策略	是	否	连续 + 离散	是
MADDPG	离策略	是	是	连续	否
IDDPG	离策略	是	否	连续	否
MASAC	离策略	是	是	连续 + 离散	是
ISAC	离策略	是	否	连续 + 离散	是
QMIX	离策略	否	不适用	离散	否
VDN	离策略	否	不适用	离散	否
IQL	离策略	否	不适用	离散	否

任务。任务是特定环境中构成MARL挑战的场景。它们在许多方面有所不同，下表列出了BenchMARL中当前的环境

环境	任务数量	合作方式	全局状态	奖励函数	动作空间	向量化
VMAS	[27](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/conf/task/vmas	合作 + 竞争	否	共享 + 独立 + 全局	连续 + 离散	是
SMACv2	[15](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/conf/task/smacv2	合作	是	全局	离散	否
MPE	[8](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/conf/task/pettingzoo	合作 + 竞争	是	共享 + 独立	连续 + 离散	否
SISL	[2](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/conf/task/pettingzoo	合作	否	共享	连续	否
MeltingPot	[49](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/conf/task/meltingpot	合作 + 竞争	是	独立	离散	否

[!注意]
BenchMARL 使用 TorchRL MARL API 来对代理进行分组。在像 MPE 这样的竞争环境中，不同的队伍将被分到不同的组。每个组有自己的损失函数、模型、缓冲区等。参数共享选项指的是组内的共享。有关更多信息，请参阅创建自定义算法的示例。

模型。模型是用于处理数据的神经网络。它们可以用作演员（策略）或者在需要时用作评论家。我们提供了一组基础模型（层）和一个 SequenceModel 来连接不同的层。所有模型都可以在代理组内使用或不使用参数共享。下面是 BenchMARL 中实现的模型表格

名称	去中心化	基于局部输入的中心化	基于全局输入的中心化
[MLP](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/mlp.py	是	是	是
[GRU](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/gru.py	是	是	是
[LSTM](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/lstm.py	是	是	是
[GNN](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/gnn.py	是	是	否
[CNN](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/cnn.py	是	是	是
[Deepsets](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/models/deepsets.py	是	是	是

微调的公开基准

[!警告]
本节正在进行中。我们正在不断努力微调我们的实验，以使我们的用户能够访问最先进的基准。如果您想在这项工作中合作，请与我们联系。

在 [fine_tuned](https://github.com/facebookresearch/BenchMARL/blob/main/fine_tuned 文件夹中，我们正在收集一些针对特定环境测试过的超参数，以便用户能够快速启动他们的基准测试。您可以直接运行此文件夹中的脚本，自动使用建议的超参数。

我们将为您调整基准并在 Wandb 上公开发布配置和基准图表

目前可用的有：

VMAS:

以下是结果表格：

<p align="center">环境</p>	<p align="center">样本效率曲线（所有任务）</p>	<p align="center">性能剖析</p>	<p align="center">汇总得分</p>
VMAS	<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/68bbbd20-8482-464a-994e-f195ab38c9b1.png"/>	<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/70535bb1-60a1-456d-99e1-8d0fe5b52248.png"/>	<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/d078113f-d3d3-4590-af1f-8310e3f8f925.png"/>

报告和绘图

报告和绘图与 marl-eval 兼容。如果 experiment.create_json=True（这是实验配置中的默认设置），将在实验输出文件夹中创建一个名为 {experiment_name}.json 的文件，格式符合 marl-eval。您可以使用 [eval_results](https://github.com/facebookresearch/BenchMARL/blob/main/benchmarl/eval_results.py 中的实用工具加载和合并这些文件，为您的基准创建漂亮的图表。再也不用为 matplotlib 和 latex 而苦恼了！

aggregate_scores sample_efficiancy performace_profile

扩展

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 生态系统中，以获得专门支持

日志记录

BenchMARL 与 TorchRL 日志记录器兼容。可以在实验配置中提供日志记录器名称列表。可用选项的示例有：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"

回调

实验可以选择性地采用 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: Benchmarking Multi-Agent Reinforcement Learning},
  journal = {Journal of Machine Learning Research},
  year    = {2024},
  volume  = {25},
  number  = {217},
  pages   = {1--10},
  url     = {http://jmlr.org/papers/v25/23-1612.html}
}