---

一、待解决问题

1.1 问题描述

为了对比学习使用多类MARL算法，实现最终应用场景的实验对比，需寻找一个集成多类算的MARL算法框架，“先复现后学习”！

1.2 解决方法

（1）调研当前主流的MARL算法框架
（2）学习经典MARL算法框架——“MARLlib”
（3）安装经典MARL算法框架——“MARLlib”
（4）复现经典MARL算法实例——“MAPPO+MPE-simple_spread”

二、方法详述

2.1 必要说明

MARL算法的基础是需要环境进行交互的，一些主流的多智能体交互环境先总结如下：

环境	创建团队	最近更新时间	链接	功能描述
PettingZoo	Farama Foundation	2025	PettingZoo GitHub	多智能体强化学习的标准API和环境库，支持多种环境和算法
SMAC		2023	SMAC GitHub	基于星际争霸II的多智能体强化学习环境，用于研究复杂的多智能体协作问题
SMAC-V2		2023	SMAC-V2 GitHub	SMAC的升级版本，提供了更多的地图和任务
MPE	OpenAI	2018	MPE GitHub	多智能体粒子环境，用于测试和验证多智能体强化学习算法

后续有时间再一并更新环境的调研与学习情况。

2.2 应用步骤

2.2.1 调研当前主流的MARL算法框架

通过文献及大模型的调研，将当前主流的MARL算法框架总结如下：

框架	创建团队	最近更新时间	链接	功能描述
MARLlib	University of Technology Sydney and Peking University	2024	MARLib GitHub	多智能体强化学习研究平台，支持≥18种算法和环境
HARL	Peking University	2024	HARL Github	关注异构多智能体算法，前沿的MARL算法，从而实现有效的多智能体合作，而无需依赖限制性的参数共享技巧。
MALib	Shanghai Jiao Tong University	2023	MALib Github	MALib 是一个基于种群的并行学习框架，嵌套有强化学习方法，如 Policy Space Response Oracle、Self-Play 和 Neural Fictitious Self-Play。
MAPPO benchmark	Tsinghua University	2022	MAPPO Github	提供了MAPPO、IPPO算法源码与测试环境
EPyMARL	University of California, Berkeley	2024	EPyMARL GitHub	EPyMARL 是 PyMARL 的扩展，支持新环境：原生集成 PettingZoo、VMAS、矩阵游戏、SMACv2 和 SMAClite，新增算法（IA2C、IPPO、MADDPG、MAA2C 和 MAPPO）
PyMARL3	University of Edinburgh	2023	pymarl3 GitHub	PyMARL2的进一步升级版本，MARL算法性能有提升，支持SMAC-V1 和 SMAC-V2环境
PyMARL2	Tianjin University	2021	pymarl2 GitHub	PyMARL的升级版本，MARL算法性能有提升，提供了更多的功能和改进
PyMARL	Russian-Armenian University and University of Oxford	2019	PyMARL GitHub	MARL研究框架，支持QMIX、COMA、VDN、IQL、QTRAN等多种算法，支持SMAC环境

有了大致的了解以后，为了找一个“正在更新、易上手、算法集成多、环境支持多”的框架首选了“MARLlib”。

✅理由如下：
① PyMARL v1-v3应该是与SMAC环境绑定使用的，能应用的“环境场景”有限；
② MAPPO benchmark仅提供了MAPPO、IPPO算法的实例，算法类型有限，不易于算法性能的对比；
③ HARL中提供了比较前沿的MARL算法，暂时可能先考虑稳定性能的算法，后续有需要再学习；
④ MALib、EPyMARL都是“支持多环境、集成多算法”的框架，可一个不错的选项，但类型数上没有MARLlib多，因此试用了MARLlib框架如果不好用的话，后续考虑学习此两个框架。

2.2.2 学习经典MARL算法框架——“MARLlib”

直接将MARLib Github的说明了解一遍，将要素总结如下：

（1）开发团队

该框架给出了其发表的论文：

MARLlib: A Scalable and Efficient Library For Multi-agent Reinforcement Learning

其主要的参研机构包含：

ReLER, AAII, University of Technology Sydney（悉尼科技大学-澳大利亚人工智能研究所）
Institute for Artificial Intelligence, Peking University（北京大学人工智能研究所）

团队负责人应该是“杨耀东，北京大学人工智能研究院助理教授。科研领域包括强化学习、博弈论和多智能体强化学习”。

（2）简介

多智能体强化学习库（MARLlib）是一个利用 Ray 及其工具包之一 RLlib 的 MARL 库。它为在各种任务和环境中开发、训练和测试 MARL 算法提供了一个综合平台。

❓什么是“Ray 及其工具包之一 RLlib”？
✅Ray是一个用于构建和运行分布式应用程序的开源框架，它通过提供简单的编程模型和高效的资源调度，使得开发者能够轻松地将单机程序扩展到分布式环境。
✅RLlib是Ray框架中的一个强化学习工具包，它提供了多种强化学习算法的实现，包括A2C、PPO、DQN等，并支持在多种环境下进行训练和测试。

🌟主流MARL框架对比

框架	环境支持	算法包含	参数共享方式	包含模型
PyMARL	1 cooperative	5	share	GRU
PyMARL2	2 cooperative	11	share	MLP + GRU
MAPPO Benchmark	4 cooperative	1	share + separate	MLP + GRU
MAlib	4 self-play	10	share + group + separate	MLP + LSTM
EPyMARL	4 cooperative	9	share + separate	GRU
HARL	8 cooperative	9	share + separate	MLP + CNN + GRU
MARLlib	17 no task mode restriction	18	share + group + separate + customizable	MLP + CNN + GRU + LSTM

❓什么是“参数共享方式”？
✅参数共享是指网络中多个智能体之间是否共享模型的参数，“share” 表示所有智能体共享相同的参数，“separate” 表示每个智能体使用独立的参数，“group” 表示参数在特定组内共享。

MARLlib的关键功能：

① MARLlib 利用代理级分布式数据流统一了各种算法流水线，使研究人员能够在不同的任务和环境中开发、测试和评估 MARL 算法。
② MARLlib 支持所有任务模式，包括合作、协作、竞争和混合模式。这使得研究人员更容易在各种任务中训练和评估 MARL 算法。
③ MARLlib 提供了一个遵循 Gym 结构的新界面，使研究人员更容易在多代理环境中工作。
④ MARLlib 提供灵活、可定制的参数共享策略，允许研究人员针对不同的任务和环境优化算法。

MARLlib优势在于：

① 无需了解 MARL：MARLlib 提供 18 种预置算法和直观的应用程序接口，研究人员无需了解该领域的知识即可开始使用 MARL 进行实验。
② 支持所有任务模式MARLlib： 支持几乎所有多智能体环境，使研究人员更容易尝试不同的任务模式。
③ 可定制的模型架构：研究人员可以从模型园中选择自己喜欢的模型架构，也可以建立自己的模型架构。
④ 可定制的策略共享：MARLlib 为策略共享提供了分组选项，研究人员也可以创建自己的策略。
⑤ 访问一千多个已发布的实验的社区：研究人员可以访问一千多个已发布的实验，了解其他研究人员是如何使用 MARLlib 的。

2.2.3 安装经典MARL算法框架——“MARLlib”

⚠️⚠️⚠️请注意，目前 MARLlib 仅兼容 Linux作系统。⚠️⚠️⚠️

（1）安装依赖

#创建虚拟环境
conda create -n marllib python=3.9
conda activate marllib
git clone https://github.com/Replicable-MARL/MARLlib.git
#查看安装依赖项
cd code/MARLlib-master/
pip install -r requirements.txt

【！！！安装过程中出现两段报错！！！】
其一，较新的 setuptools 和 wheel 版本对 setup.py 的 extras_require 格式要求更严格，而 gym=0.20.0 的 setup.py 不兼容这些新版本。

其二，尝试安装依赖项，报错：“较高的pip版本无法匹配gym=0.20.0版本安装“
查看到requirements.txt文件中，setuptools版本是65.5.0，whell版本是0.38.0，pip版本是21，因此降低上述包的版本再安装。

conda list | grep setuptools
conda list | grep wheel
conda list | grep pip
pip install setuptools==65.5.0
pip install wheel==0.38.0
pip install pip==21.0
pip install -r requirements.txt

（2）安装环境

根据所需要的环境，进行对应的安装，众多MARL算法环境如下：Environment List。

后续MARL实例中，要用到 “MAPPO+MPE:simple_spread” 的场景，因此预装 MPE 环境。

🌟MPE简介：
多粒子环境（MPE）是一组以通信为导向的环境，在这些环境中，粒子代理可以（有时）移动、通信、相互看到、相互推动，并与固定地标进行交互。

了解过后，现在 PettingZoo 环境中继承了 MPE，因此直接安装 PettingZoo。并且，MARLlib也说明了框架中也是使用 PettingZoo 去调用 MPE 环境的。

#查看环境版本，官方建议 “建议安装gym 0.20.0相近的版本”
conda list | grep pettingzoo
conda list | grep gym

（3）安装补丁

#运行以下命令，使用补丁修复 RLlib 的错误
cd /Path/To/MARLlib/marllib/patch
python add_patch.py -y

（4）安装框架

官方教程中需要更新pip，但亲测千万不要运行这个更新语句 “pip install upgrade pip ”，这会导致后续安装不成功！
直接安装marllib即可！

pip install marllib

安装完成后，发现依然还是安装了torch=1.9.0，果断卸载重新安装pytorch。
查看CUDA版本，并安装pytorch，可参考：【OS安装与使用】part5-ubuntu22.04基于conda安装pytorch+tensorflow

pip uninstall torch
#安装新版本pytorch
nvcc -V
pip3 install torch torchvision torchaudio

出现一个报错，但是从直观上理解，torch版本确实需要与nvidia显卡对应才行。

（5）安装可视化工具

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

#安装tensorboard
pip install tensorboard
#安装可视化IDE
conda install spyder

使用以下语句可视化结果：

tensorboard --logdir .

2.2.4 复现经典MARL算法实例——“MAPPO+MPE:simple_spread”

以官方提供的 Quick Start 来复现经典MARL算法实例，如果先要深入理解相关“算法+环境”的可以参考以下链接：

MAPPO 算法论文：https://arxiv.org/abs/2103.01955
MAPPO 算法源码：https://github.com/marlbenchmark/on-policy
MPE 环境论文：http://arxiv.org/abs/1706.02275
MPE 环境源码：https://github.com/openai/multiagent-particle-envs
PettingZoo 环境源码：https://github.com/Farama-Foundation/PettingZoo

（1）MARLlib使用简述

您需要使用四个配置文件来确保训练需求的正确性：
① 场景：指定环境/任务设置
② 算法：微调算法超参数
③ 模型：自定义模型架构
④ ray/rllib：更改基本训练设置

（2）环境配置

MARLlib 提供了 10 个环境供您进行实验。您可以按照 Environments 部分中的说明安装它们并更改相应的配置以自定义所选任务。

（3）算法超参配置

设置环境后，您需要访问 MARL 算法的超参数目录。每种算法都有不同的超参数，您可以对其进行微调。
我们为三种最常用的 MARL 环境（包括 SMAC、MPE 和 MAMuJoCo）提供了常用超参数目录、纯测试超参数目录和微调超参数集。

🌟超参数目录：MARLlib-超参数目录

（4）模型架构配置

你可以在 model 的 config 中自定义你的模型。支持的架构更改包括：

① 观测/状态编码器：CNN、FC
② 多层感知器：MLP
③ 递归神经网络：GRU、LSTM
④ Q/Critic 值混频器：VDN、QMIX

（5）训练选项配置

Ray/RLlib 为 MARLlib 提供了灵活的多进程调度机制。您可以修改 ray 配置文件来调整以下内容：

① 采样速度（worker数量、CPU 数量）
② 训练速度（GPU 加速）
③ 运行模式（本地或分布式）
④ 参数共享策略（全部、组、单个）
⑤ 停止条件（迭代、奖励、时间步）

（6）算法实例运行

经典算法：MAPPO
经典环境：MPE-simple_spread

from marllib import marl
# prepare env
env = marl.make_env(environment_name="mpe", map_name="simple_spread")
# initialize algorithm with appointed hyper-parameters
mappo = marl.algos.mappo(hyperparam_source="mpe")
# build agent model based on env + algorithms + user preference
model = marl.build_model(env, mappo, {"core_arch": "mlp", "encode_layer": "128-256"})
# start training
mappo.fit(env, model, stop={"timesteps_total": 100000}, checkpoint_freq=100, share_policy="group")

首次运行代码报错：

CUDA兼容性错误：
(pid=126645) NVIDIA GeForce RTX 4060 Laptop GPU with CUDA capability sm_89 is not compatible with the current PyTorch installation.
这表明你的 GPU 拥有 CUDA Capability sm_89，但当前安装的 PyTorch 版本不支持这个架构。

pettingzoo弃用警告：
UserWarning: The action_spaces dictionary is deprecated. Use the action_space function instead.
UserWarning: The observation_spaces dictionary is deprecated. Use the observation_space function instead.
PettingZoo 的新版本中，action_spaces 和 observation_spaces 字典已被弃用，取而代之的是 action_space 和 observation_space 函数。

警告暂且不管，先解决错误。
由于MARLlib中预装的时torch=1.9，这个需要根据自身显卡及CUDA版本对应安装，因此卸载并重装torch。

pip uninstall torch
#安装新版本pytorch
nvcc -V
pip3 install torch torchvision torchaudio

再次运行，无报错发生，成功运行完毕。
但关闭spyder再次运行时，出现如下报错，一开始非常郁闷，一直不知道如何解决。

TuneError: (‘Trials did not complete’, [MAPPOTrainer_mpe_simple_spread_c29a7_00000])”

直到看到，代码文件路径下多了一个文件夹，这个貌似是用来日志记录的，将其删除后再运行即可解决。

如果先要可视化的话，可参考 “code/MARLlib-master/examples” 下的示例代码

【load_and_render_model.py】：

from marllib import marl# prepare the environment
env = marl.make_env(environment_name="mpe", map_name="simple_spread", force_coop=True)# initialize algorithm and load hyperparameters
mappo = marl.algos.mappo(hyperparam_source="mpe")# build agent model based on env + algorithms + user preference if checked available
model = marl.build_model(env, mappo, {"core_arch": "mlp", "encode_layer": "128-256"})# rendering
mappo.render(env, model,restore_path={'params_path': "checkpoint/params.json",  # experiment configuration'model_path': "checkpoint/checkpoint-6250", # checkpoint path'render': True},  # renderlocal_mode=True,share_policy="all",checkpoint_end=False)

💐💐💐 完结撒花 💐💐💐

2.2.6 MARLlib注意事项

（1）兼容性问题

确保超参数选择在不同级别之间兼容非常重要。例如，多粒子环境（MPE）支持离散和连续动作。要启用连续动作空间设置，只需将 mpe.yaml 中的 continuous_actions 参数更改为 True 即可。在使用基于 API 的方法或命令行参数（如 marl.make_env(xxxx,continuous_actions=True)）时，必须注意相应的设置，其中的参数名称必须与 mpe.yaml 中的参数名称完全一致。

（2） pettingzoo调用API

⚠️⚠️⚠️ PettingZoo 环境调用API基于 Gymnasium ⚠️⚠️⚠️

MARLlib官方说明：

原文： PettingZoo has undergone significant updates, and we have made the decision to seamlessly integrate its latest version with Gymnasium, using Multi-Agent Particle Environment (MPE) as a prime example. This integration serves as a blueprint for incorporating any task from the most recent PettingZoo library into MARLlib.
翻译：PettingZoo 经历了重大更新，我们决定将其最新版本与 Gymnasium 无缝集成，并以多代理粒子环境（MPE）为例。这一集成是将最新 PettingZoo 库中的任何任务纳入 MARLlib 的蓝本。

调用方法（以 simple_spread 为例）：

from marllib import marl
env = marl.make_env(environment_name="gymnasium_mpe", map_name="simple_spread")

ps：但此教程中，gym版本为0.20.0，不是最新版本，因此不用调用 Gymnasium API。

（3）MARLlib版本

⏩ ⏩ ⏩ （2025.03.03补充） ⏩ ⏩ ⏩
如果参照官方教程安装，默认安装的是marllib=0.8版本，但我观察到还有其它版本可以使用。
若是代码运行不成功，可以转换成另一个版本安装试一试，可用版本参照下面。

三、疑问

暂无。

四、总结

• 安装环境和复现代码需时刻记录。当环境依赖项始终无法支持时，果断重建虚拟环境。
• github上有评论区，可以帮助解决一部分问题。
• 各个包的版本太重要了，除非有特殊需求，一定要按照版本要求安装。
• github源码学习时，先关注本身自带的教程和example！！！