离策略多智能体强化学习（MARL）算法

本仓库包含多种离策略多智能体强化学习（MARL）算法的实现。

作者：Akash Velu 和 Chao Yu

支持的算法：

• MADDPG（MLP 和 RNN）
• MATD3（MLP 和 RNN）
• QMIX（MLP 和 RNN）
• VDN（MLP 和 RNN）

支持的环境：

• StarCraftII (SMAC)
• 多智能体粒子世界环境（MPEs）

1. 使用说明

警告 #1：默认情况下，所有实验都假设所有智能体共享同一策略，即只有一个神经网络被所有智能体共享。

警告 #2：目前只有 QMIX 和 MADDPG 经过了充分测试；然而，我们的 VDN 和 MATD3 实现分别对 QMIX 和 MADDPG 做了少量修改。我们在此展示了使用我们实现的结果 这里。

所有核心代码都位于 offpolicy 文件夹中。algorithms/ 子文件夹包含了所有方法的特定于算法的代码。RMADDPG 和 RMATD3 分别指 MADDPG 和 MATD3 的 RNN 实现，而 mQMIX 和 mVDN 则指 QMIX 和 VDN 的 MLP 实现。我们还支持优先级经验回放（PER）。

• envs/ 子文件夹包含用于 MPEs 和 SMAC 的环境封装实现。

• 用于执行训练采样和策略更新的代码位于 runner/ 文件夹中——每个环境都有一个对应的 runner。

• 使用默认超参数进行训练的可执行脚本可以在 scripts/ 文件夹中找到。文件名格式为：train_algo_environment.sh。在每个文件中，可以更改地图名称（对于 SMAC 和 MPEs 而言）。

• 每个环境的 Python 训练脚本位于 scripts/train/ 文件夹中。

• config.py 文件包含了相关的超参数和环境设置。大多数超参数已默认设置为论文中使用的值；不过，请参阅附录以获取完整的超参数列表。

2. 安装

以下是在 CUDA == 10.1 上的安装示例。对于非 GPU 及其他 CUDA 版本的安装，请参考 PyTorch 官网。

# 创建 conda 环境
conda create -n marl python==3.6.1
conda activate marl
pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html

# 安装 on-policy 包
cd on-policy
pip install -e .

尽管我们提供了 requirement.txt 文件，但其中可能存在冗余。建议用户在运行代码时，根据实际需要自行安装缺失的依赖包。

2.1 安装 StarCraftII 4.10

unzip SC2.4.10.zip
# 密码是 iagreetotheeula
echo "export SC2PATH=~/StarCraftII/" > ~/.bashrc

• 下载 SMAC 地图，并将其移动到 ~/StarCraftII/Maps/。

• 若要使用 stableid，请将 stableid.json 从 https://github.com/Blizzard/s2client-proto.git 复制到 ~/StarCraftII/。

2.2 安装 MPE

# 首先安装此包
pip install seaborn

MPE 中有 3 种合作场景：

• simple_spread
• simple_speaker_listener，即论文中的“Comm”场景
• simple_reference

3. 训练

以下以 train_mpe_maddpg.sh 为例：

cd offpolicy/scripts
chmod +x ./train_mpe_maddpg.sh
./train_mpe_maddpg.sh

本地结果会存储在 scripts/results 子文件夹中。请注意，我们默认使用 Weights & Biases 作为可视化平台；若要使用 Weights & Biases，需先注册并登录该平台。更多关于 Weights & Biases 的使用说明可在其官方 文档 中找到。如果在命令行或 .sh 文件中添加 --use_wandb 参数，则会使用 TensorBoard 代替 Weights & Biases。

4. 结果

RMADDPG 和 QMIX 在粒子环境中的表现，以及 QMIX 在 SMAC 中的表现结果已在 这里 展示。这些结果是使用普通（非优先级）经验回放缓冲区获得的。

Off-Policy 多智能体强化学习快速上手指南

本指南帮助开发者快速部署并运行基于 Off-Policy 的多智能体强化学习（MARL）算法库，支持 MADDPG、MATD3、QMIX 和 VDN 等算法，适用于 StarCraftII (SMAC) 和 Multiagent Particle-World (MPE) 环境。

环境准备

• 操作系统: Linux (推荐 Ubuntu)
• Python 版本: 3.6.1
• CUDA 版本: 示例基于 CUDA 10.1 (其他版本请参考 PyTorch 官网调整)
• 前置依赖:
  • Conda (用于环境管理)
  • Git
  • StarCraft II (仅当使用 SMAC 环境时需要，版本 4.10)
  • Weights & Biases 账号 (可选，用于可视化，默认开启；若不使用可切换至 Tensorboard)

安装步骤

1. 创建 Python 环境并安装 PyTorch

# 创建 conda 环境
conda create -n marl python==3.6.1
conda activate marl

# 安装 PyTorch (示例为 CUDA 10.1，其他版本请前往 https://pytorch.org 获取对应命令)
pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html

2. 安装 off-policy 代码库

# 克隆仓库后进入目录 (假设当前已在项目根目录)
# 注意：原文 README 中此处写的是 cd on-policy，但项目名为 off-policy，请根据实际文件夹名称调整
cd off-policy 
pip install -e .

提示: 虽然项目提供了 requirement.txt，但可能存在冗余。建议先运行代码，根据报错信息按需安装缺失的包。

3. 配置仿真环境 (按需选择)

选项 A: 配置 StarCraft II (SMAC)

如需运行 SMAC 相关实验，需手动安装 SC2 和地图。

# 下载并解压 StarCraft II 4.10 (Linux 版)
wget http://blzdistsc2-a.akamaihd.net/Linux/SC2.4.10.zip
unzip SC2.4.10.zip
# 解压密码为: iagreetotheeula

# 配置环境变量
echo "export SC2PATH=~/StarCraftII/" >> ~/.bashrc
source ~/.bashrc

# 后续操作:
# 1. 下载 SMAC Maps 并移动至 ~/StarCraftII/Maps/
# 2. 从 https://github.com/Blizzard/s2client-proto.git 复制 stableid.json 到 ~/StarCraftII/

选项 B: 配置 MPE 环境

如需运行粒子世界实验，需安装 seaborn 及相关依赖。

pip install seaborn
# 确保已安装 openai/multiagent-particle-envs (通常包含在依赖中或需单独 git clone)

基本使用

以下以在 MPE 环境中训练 MADDPG 算法为例：

1. 进入脚本目录并赋予执行权限:

   cd offpolicy/scripts
   chmod +x ./train_mpe_maddpg.sh
   

2. 开始训练:

   ./train_mpe_maddpg.sh
   

说明:

• 结果存储: 训练结果默认保存在 scripts/results 子文件夹中。
• 可视化:
  • 默认使用 Weights & Biases (W&B)。首次使用前请注册并登录 W&B 平台。
  • 若希望使用 Tensorboard，请在命令行或 .sh 脚本中添加 --use_wandb 参数（注：原文逻辑为添加该标志使用 Tensorboard，请根据实际代码逻辑确认，通常为移除 wandb 相关标志或显式指定 tensorboard）。
• 修改配置:
  • 超参数和环境设置主要在 config.py 中调整。
  • 若要更改地图名称（SMAC 或 MPE），请编辑 scripts/ 目录下对应的 .sh 文件。

注意事项:

1. 默认情况下，所有智能体共享同一个策略网络（Shared Policy）。
2. QMIX 和 MADDPG 经过充分测试；VDN 和 MATD3 是基于前两者的小幅修改版本。