- 如果您希望获得更高的采样效率，请使用 qmix_high_sample_efficiency.yaml，
- 该配置使用4个进程进行训练，速度较慢但采样效率更高。
- 使用不同数量的进程训练得到的模型性能*不可比较*。

PyMARL2

用于重新思考合作式多智能体强化学习中的实现技巧与单调性约束的开源代码。

本仓库针对星际争霸多智能体挑战赛（SMAC）进行了优化。对于其他多智能体任务，我们也推荐一个优化版的QMIX实现：https://github.com/marlbenchmark/off-policy。

星际争霸2版本：SC2.4.10，难度：7。

2022年10月10日更新：新增 qmix_high_sample_efficiency.yaml，该配置使用4个进程进行训练，速度较慢但采样效率更高。

2021年10月28日更新：新增谷歌足球环境 [vdn_gfootball.yaml]（使用 `simple115 features`）。

2021年10月4日更新：新增带有注意力机制的QMIX（qmix_att.yaml），作为通信任务的基线模型。

细调版-QMIX

在多智能体强化学习（MARL）中，有许多代码层面的技巧，例如：

• 价值函数裁剪（对QMIX的最大Q值进行裁剪）
• 价值归一化
• 奖励缩放
• 正交初始化和层缩放
• Adam优化器
• 神经网络隐藏层大小
• 学习率退火
• 奖励裁剪
• 观测归一化
• 梯度裁剪
• 大批量训练
• N步回报（包括GAE($\lambda$)和Q($\lambda$)等）
• 并行采样进程数
• $\epsilon$-贪婪策略的退火步数
• 死亡智能体掩码

相关工作

• 深度强化学习中的实现细节：以PPO和TRPO为例
• 在基于策略的强化学习中，哪些因素最重要？一项大规模实证研究
• MAPPO在合作式多智能体游戏中的惊人效果

通过运用上述部分技巧（加粗显示），我们使QMIX（qmix.yaml）能够解决SMAC中的几乎所有困难场景（为每个场景单独调整超参数）。

场景	难度	QMIX (batch_size=128)	细调版-QMIX
8m	容易	-	100%
2c_vs_1sc	容易	-	100%
2s3z	容易	-	100%
1c3s5z	容易	-	100%
3s5z	容易	-	100%
8m_vs_9m	困难	84%	100%
5m_vs_6m	困难	84%	90%
3s_vs_5z	困难	96%	100%
bane_vs_bane	困难	100%	100%
2c_vs_64zg	困难	100%	100%
corridor	超难	0%	100%
MMM2	超难	98%	100%
3s5z_vs_3s6z	超难	3%	93%(hidden_size = 256, qmix_large.yaml)
27m_vs_30m	超难	56%	100%
6h_vs_8z	超难	0%	93%($\lambda$ = 0.3, epsilon_anneal_time = 500000)

重新评估

随后，我们对众多QMIX变体进行了重新评估，统一了标准化的技巧设置（一套通用的超参数），结果发现QMIX达到了当前最优水平。

场景	难度	基于值的方法					基于策略的方法
		QMIX	VDNs	Qatten	QPLEX	WQMIX	LICA	VMIX	DOP	RIIT
2c_vs_64zg	困难	100%	100%	100%	100%	100%	100%	98%	84%	100%
8m_vs_9m	困难	100%	100%	100%	95%	95%	48%	75%	96%	95%
3s_vs_5z	困难	100%	100%	100%	100%	100%	96%	96%	100%	96%
5m_vs_6m	困难	90%	90%	90%	90%	90%	53%	9%	63%	67%
3s5z_vs_3s6z	超难	75%	43%	62%	68%	56%	0%	56%	0%	75%
corridor	超难	100%	98%	100%	96%	96%	0%	0%	0%	100%
6h_vs_8z	超难	84%	87%	82%	78%	75%	4%	80%	0%	19%
MMM2	超难	100%	96%	100%	100%	96%	0%	70%	3%	100%
27m_vs_30m	超难	100%	100%	100%	100%	100%	9%	93%	0%	93%
Discrete PP	-	40	39	-	39	39	30	39	38	38
平均得分	困难+	94.9%	91.2%	92.7%	92.5%	90.5%	29.2%	67.4%	44.1%	84.0%

通信

我们还测试了带有注意力机制的QMIX（qmix_att.yaml，$\lambda=0.3$，attention_heads=4）在一些需要通信的地图上（来自NDQ）。

场景（20万步）	难度	细调版-QMIX（无通信）	带有注意力的QMIX（通信）
1o_10b_vs_1r	-	56%	87%
1o_2r_vs_4r	-	50%	95%
bane_vs_hM	-	0%	0%

Google Football

我们还在一些地图上测试了VDN（vdn_gfootball.yaml）（来自Google Football）。特别地，我们使用simple115特征来训练模型（Google Football的原始论文使用的是复杂的CNN特征）。我们没有测试QMIX，因为这个环境不提供全局状态信息。

场景	难度	VDN ($\lambda=1.0$)
academy_counterattack_hard	-	0.71 (测试分数)
academy_counterattack_easy	-	0.87 (测试分数)

使用方法

PyMARL是WhiRL用于深度多智能体强化学习的框架，包含了以下算法的实现：

基于价值的方法：

• QMIX: QMIX：用于深度多智能体强化学习的单调值函数分解
• VDN: 用于合作型多智能体学习的价值分解网络
• IQL: 独立Q学习
• QTRAN: 用于合作型多智能体强化学习的学习转换因子分解
• Qatten: Qatten：一种通用的合作型多智能体强化学习框架
• QPLEX: Qplex：双工斗士型多智能体Q学习
• WQMIX: 加权QMIX：扩展单调值函数分解

基于策略梯度的方法：

• COMA: 反事实多智能体策略梯度
• VMIX: 值分解多智能体策略梯度
• LICA: 学习合作型多智能体强化学习中的隐式信用分配
• DOP: 离线多智能体分解策略梯度
• RIIT: 重新思考合作型多智能体强化学习中的实现技巧与单调性约束

安装说明

安装Python包

# 需要Anaconda 3或Miniconda 3
conda create -n pymarl python=3.8 -y
conda activate pymarl

bash install_dependecies.sh

设置StarCraft II（2.4.10）和SMAC：

bash install_sc2.sh

这将下载SC2.4.10到thirdparty文件夹，并复制运行所需的地图。

设置Google Football：

bash install_gfootball.sh

命令行工具

运行一个实验

# 对于SMAC
python3 src/main.py --config=qmix --env-config=sc2 with env_args.map_name=corridor

# 对于难度增强的捕食者-猎物任务
python3 src/main.py --config=qmix_predator_prey --env-config=stag_hunt with env_args.map_name=stag_hunt

# 对于通信任务
python3 src/main.py --config=qmix_att --env-config=sc2 with env_args.map_name=1o_10b_vs_1r

# 对于Google Football（测试不足）
# 地图名称：academy_counterattack_easy, academy_counterattack_hard, five_vs_five...
python3 src/main.py --config=vdn_gfootball --env-config=gfootball with env_args.map_name=academy_counterattack_hard env_args.num_agents=4

配置文件充当算法或环境的默认设置。

它们都位于src/config中。 --config指的是src/config/algs中的配置文件。 --env-config指的是src/config/envs中的配置文件。

并行运行n个实验

# bash run.sh config_name env_config_name map_name_list (arg_list threads_num gpu_list experinments_num)
bash run.sh qmix sc2 6h_vs_8z epsilon_anneal_time=500000,td_lambda=0.3 2 0 5

xxx_list用,分隔。

所有结果都将存储在Results文件夹中，并以map_name命名。

终止所有训练进程

# 当前用户的所有Python和游戏进程都会退出。
bash clean.sh

引用

@article{hu2021rethinking,
      title={Rethinking the Implementation Tricks and Monotonicity Constraint in Cooperative Multi-Agent Reinforcement Learning}, 
      author={Jian Hu and Siyang Jiang and Seth Austin Harding and Haibin Wu and Shih-wei Liao},
      year={2021},
      eprint={2102.03479},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

PyMARL2 快速上手指南

PyMARL2 是一个针对合作式多智能体强化学习（MARL）优化的开源框架，特别针对星际争霸多智能体挑战（SMAC）进行了微调。它实现了 QMIX、VDN、Qatten 等多种主流算法，并通过调整超参数和实现技巧显著提升了在困难场景下的性能。

环境准备

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

• 操作系统: Linux (推荐 Ubuntu 18.04/20.04)
• Python 版本: 3.8 (必须使用 Conda 管理)
• 依赖管理: Anaconda 3 或 Miniconda 3
• 游戏环境: StarCraft II (版本 2.4.10)
• 可选环境: Google Football (如需测试足球场景)

注意：本项目代码针对 SC2.4.10 版本优化，其他版本可能导致运行错误。

安装步骤

1. 创建并激活 Conda 环境

首先创建一个名为 pymarl 的 Python 3.8 环境：

conda create -n pymarl python=3.8 -y
conda activate pymarl

2. 安装项目依赖

运行官方提供的脚本来安装必要的 Python 包：

bash install_dependecies.sh

3. 设置 StarCraft II 和 SMAC

下载指定版本的星际争霸 II 及所需地图：

bash install_sc2.sh

该脚本会自动将 SC2.4.10 下载到 3rdparty 文件夹并复制必要的地图文件。

4. (可选) 设置 Google Football

如果您需要运行足球环境任务，请执行：

bash install_gfootball.sh

基本使用

配置文件中定义了算法默认参数和环境设置：

• --config: 对应 src/config/algs 下的算法配置（如 qmix, vdn）。
• --env-config: 对应 src/config/envs 下的环境配置（如 sc2, gfootball）。

运行单个实验

示例 1：在 SMAC 的 "corridor" 地图上运行 QMIX 算法

python3 src/main.py --config=qmix --env-config=sc2 with env_args.map_name=corridor

示例 2：运行需要通信的任务（使用带注意力机制的 QMIX）

python3 src/main.py --config=qmix_att --env-config=sc2 with env_args.map_name=1o_10b_vs_1r

示例 3：在 Google Football 上运行 VDN 算法

python3 src/main.py --config=vdn_gfootball --env-config=gfootball with env_args.map_name=academy_counterattack_hard env_args.num_agents=4

并行运行多个实验

使用 run.sh 脚本可以启动并行训练。以下示例展示了如何在 GPU 0 上启动 2 个线程，进行 5 次实验，并自定义超参数：

# 语法：bash run.sh [算法配置] [环境配置] [地图名] [超参数列表] [线程数] [GPU ID] [实验次数]
bash run.sh qmix sc2 6h_vs_8z epsilon_anneal_time=500000,td_lambda=0.3 2 0 5

• 超参数列表使用逗号 , 分隔。
• 所有结果将保存在 Results 文件夹中，并以地图名称命名子目录。

清理进程

如果需要强制停止所有当前的训练进程（包括 Python 和游戏进程）：

bash clean.sh