异构智能体强化学习

本仓库包含基于 PyTorch 的 异构智能体强化学习（HARL） 算法的 官方实现，其中包括 HAPPO、HATRPO、HAA2C、HADDPG、HATD3、HAD3QN 和 HASAC。HARL 算法与 MAPPO 显著不同，它们普遍适用于异构智能体，并具有严格的理论支持，通常能够取得更优的性能。 本仓库使研究人员和从业者能够轻松复现我们在七个具有挑战性的基准测试上的结果，或将 HARL 算法应用于其目标应用场景。

概述

HARL 算法是我们针对一般 异构智能体 场景下实现有效多智能体协作的新颖解决方案，无需依赖限制性较强的 参数共享 技巧。

主要特点

• HARL 算法采用 顺序更新机制 实现智能体的协同更新，这与 MAPPO 和 MADDPG 所采用的 同步更新机制 不同。
• HARL 算法在理论上保证了 单调改进 和 收敛至均衡状态，从而确保其在促进智能体间合作行为方面的有效性。
• 无论是基于策略梯度的算法还是基于值函数的算法，例如分别以 HAPPO 和 HASAC 为代表的算法，在广泛的基准测试中均表现出优越的性能。

下图展示了 顺序更新机制：

更多详细信息，请参阅我们的 HARL（JMLR 2024）和 MEHARL（ICLR 2024 Spotlight）论文。

安装

安装 HARL

conda create -n harl python=3.8
conda activate harl
# 手动安装 pytorch>=1.9.0 (CUDA>=11.0)
git clone https://github.com/PKU-MARL/HARL.git
cd HARL
pip install -e .

安装环境依赖

除了 HARL 算法之外，我们还实现了七个常用环境的接口（SMAC、SMACv2、MAMuJoCo、MPE、Google Research Football、Bi-DexterousHands、Light Aircraft Game），可以直接使用。（我们还实现了 Gym 的接口。Gym 是一个单智能体环境，可以看作是多智能体环境的一种特殊情况，主要出于参考目的而包含在内。）您可以选择安装所需环境的依赖项。安装完成后，请按照 "解决依赖" 部分中的步骤操作。

安装 Bi-DexterousHands 的依赖

Bi-DexterousHands 依赖于 IsaacGym。必须满足 IsaacGym 的硬件要求。要安装 IsaacGym，从其官方网站下载 IsaacGym Preview 4 版本，然后在其 python 文件夹下运行 pip install -e .。

安装 Light Aircraft Game

Light Aircraft Game（LAG）是一个新近开发的红蓝双方飞机博弈的合作竞争环境，提供了单人控制、1v1 和 2v2 等多种场景设置。在多智能体场景中，LAG 目前仅支持 2v2 场景下的自对弈。为了解决这一局限性，我们引入了新颖的合作型无武器任务和发射导弹任务：两名智能体协作对抗由内置 AI 控制的两名对手。在无武器任务中，智能体被训练为飞向对手机尾并保持适当距离；而在发射导弹任务中，智能体则学习躲避对手导弹，并发射自己的导弹摧毁对手。

要安装 LAG，运行以下命令：

# 安装依赖
pip install torch pymap3d jsbsim==1.1.6 geographiclib gym==0.21.0 wandb icecream setproctitle
# 初始化子模块(*JSBSim-Team/jsbsim*)
git submodule init
git submodule update

安装 Google Research Football

请按照 官方说明安装 Google Research Football。

安装 SMAC

请按照 官方说明安装 SMAC。我们使用 Linux 上的 StarCraft II 版本 4.10。

安装 SMACv2

请按照 官方说明安装 SMACv2。

安装 MPE

pip install pettingzoo==1.22.2
pip install supersuit==3.7.0

安装 Gym 套件（除 MuJoCo 外）

# 安装 gym
pip install gym
# 安装经典控制
pip install gym[classic_control]
# 安装 box2d
conda install -c anaconda swig
pip install gym[box2d]
# 安装 atari
pip install --upgrade pip setuptools wheel
pip install opencv-python
pip install atari-py
pip install gym[atari]
pip install autorom[accept-rom-license]

安装 MuJoCo

首先，按照 https://github.com/openai/mujoco-py、https://www.roboti.us/ 和 https://github.com/deepmind/mujoco 上的说明，下载您所需的正确版本的 MuJoCo。

其次，创建 ~/.mujoco 目录。

第三，将 .tar.gz 或 .zip 文件移动到 ~/.mujoco 中，并使用 tar -zxvf 或 unzip 解压。

第四，在 .bashrc 文件中添加以下行：

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/<user>/.mujoco/<文件夹名称，例如 mujoco210、mujoco-2.2.1>/bin

第五，运行以下命令：

sudo apt install libosmesa6-dev libgl1-mesa-glx libglfw3
pip install mujoco
pip install gym[mujoco]
sudo apt-get update -y
sudo apt-get install -y patchelf

安装 MAMuJoCo 的依赖

首先按照上述说明安装 MuJoCo。然后运行以下命令。

pip install "mujoco-py>=2.1.2.14"
pip install "Jinja2>=3.0.3"
pip install "glfw>=2.5.1"
pip install "Cython>=0.29.28"

需要注意的是，mujoco-py 与 mujoco210 兼容（详见 此处）。因此，请务必下载 mujoco210 并将其解压到正确的位置。

解决依赖项

在完成上述安装后，运行以下命令以解决依赖项。

pip install gym==0.21.0
pip install pyglet==1.5.0
pip install importlib-metadata==4.13.0

如果在使用 pip install gym==0.21.0 时遇到问题，请尝试使用以下命令：

conda install -c conda-forge gym=0.21.0

使用方法

在现有环境中训练

要在提供的环境中训练算法，用户可以根据需要修改 harl/configs/algos_cfgs 和 harl/configs/envs_cfgs 目录下的相应算法和环境的 YAML 配置文件，然后进入 examples 文件夹，使用一行命令开始训练：python train.py --algo <ALGO> --env <ENV> --exp_name <EXPERIMENT NAME> 或者 python train.py --load_config <CONFIG FILE PATH> --exp_name <EXPERIMENT NAME>。后者通常用于复现实验。我们在 tuned_configs 文件夹中为每个环境提供了算法的调优配置。用户可以通过运行 python train.py --load_config <TUNED CONFIG PATH> --exp_name <EXPERIMENT NAME> 来复现我们的结果，只需将 <TUNED CONFIG PATH> 替换为本地机器上该调优配置文件的绝对路径即可。

训练过程中，用户将在终端中持续获得日志反馈。

训练完成后，用户可以在生成的 results 文件夹中查看日志文件、TensorBoard 输出、实验配置以及保存的模型。此外，用户还可以通过在算法配置文件中设置 use_render: True 和 model_dir: <path to trained models> 来渲染训练好的模型（对于足球环境，还需在环境配置文件中设置 render: True），然后再次使用上述相同的训练命令。对于 SMAC 和 SMACv2 环境，渲染将以视频回放的形式自动保存到 StarCraftII/Replays 文件夹中（更多详情请参阅 这里）。

为了支持批量运行，我们允许用户在命令行中直接修改 YAML 配置文件。每次训练时，用户只需在命令中指定与配置文件中同名的特殊参数即可。例如，如果您想在 SMAC 任务上使用 HAPPO 算法，并采用三个随机种子进行训练，可以自定义配置并用以下命令替换 train.sh：

for seed in $(seq 1 3)
do
	python train.py --algo happo --env smac --exp_name test --seed $seed
done

应用于新环境

若要将 HA 系列算法应用于解决新任务，您需要按照已提供的七个环境的示例实现环境接口。一个最简单的接口可能如下所示：

class Env:
    def __init__(self, args):
        self.env = ...
        self.n_agents = ...
        self.share_observation_space = ...
        self.observation_space = ...
        self.action_space = ...

    def step(self, actions):
        return obs, state, rewards, dones, info, available_actions

    def reset(self):
        return obs, state, available_actions

    def seed(self, seed):
        pass

    def render(self):
        pass

    def close(self):
        self.env.close()

接口的作用是隐藏环境特定的细节，暴露统一的交互协议，从而使其他模块能够以统一的方式处理数据。

您可能还希望在训练过程中产生持续的日志输出。如果您打算使用基于策略的算法，则需要为您的环境实现一个日志记录器。最简单的日志记录器可以继承 harl/common/base_logger.py 中的 BaseLogger 类，并实现 get_task_name 函数。对于更定制化的日志需求，可以通过扩展或重写更多函数来满足。我们建议参考各环境目录中的现有日志记录器，了解其编写方式。如果使用的是基于价值的算法，则可以直接通过修改基于价值的运行器代码来定制日志记录。最后，请注册日志记录器（如有），添加 YAML 配置文件，并在 examples/train.py、harl/utils/configs_tool.py 和 harl/utils/envs_tool.py 中添加必要的代码。同样，参照现有的七个环境示例将非常方便。

完成这些步骤后，您就可以像之前一样立即应用这些算法了。

算法适用范围

	连续动作空间	离散动作空间	多离散动作空间
HAPPO	√	√	√
HATRPO	√	√
HAA2C	√	√	√
HADDPG	√
HATD3	√
HAD3QN		√
HASAC	√	√	√
MAPPO	√	√	√
MADDPG	√
MATD3	√

在合作型多智能体强化学习基准上的性能

MPE

MAMuJoCo

HAPPO、HADDPG 和 HATD3 的表现优于 MAPPO、MADDPG 和 MATD3；其中，HAPPO 和 HATD3 是处理异构智能体合作任务最有效的方法。

SMAC & SMACv2

HAPPO 和 HATRPO 在 SMAC 和 SMACv2 中的表现与 MAPPO 和 QMIX 不相上下甚至更好，这表明它们在以同质智能体为主的场景中具有很强的能力。

GRF

HAPPO 在 GRF 上的表现始终优于 MAPPO 和 QMIX，且随着智能体数量和异质性的增加，性能差距也在不断扩大。

双灵巧手

HAPPO 始终优于 MAPPO，同时也优于单智能体基线 PPO，并且表现出更低的方差。

HASAC 的实验结果可在 https://sites.google.com/view/meharl 查看

引用

本仓库隶属于 北京大学 和 BIGAI。如果您在研究或项目中使用了我们的论文或本仓库，请考虑使用以下 BibTeX 格式的引用：

@article{JMLR:v25:23-0488,
  author  = {Yifan Zhong 和 Jakub Grudzien Kuba 和 Xidong Feng 和 Siyi Hu 和 Jiaming Ji 和 Yaodong Yang},
  title   = {异构智能体强化学习},
  journal = {机器学习研究期刊},
  year    = {2024},
  volume  = {25},
  number  = {32},
  pages   = {1--67},
  url     = {http://jmlr.org/papers/v25/23-0488.html}
}

@inproceedings{
liu2024maximum,
title={最大熵异构智能体强化学习},
author={Jiarong Liu 和 Yifan Zhong 和 Siyi Hu 和 Haobo Fu 和 QIANG FU 和 Xiaojun Chang 和 Yaodong Yang},
booktitle={第十二届国际学习表征会议},
year={2024},
url={https://openreview.net/forum?id=tmqOhBC4a5}
}

HARL 快速上手指南

HARL (Heterogeneous-Agent Reinforcement Learning) 是一个基于 PyTorch 的异质智能体强化学习算法库，包含 HAPPO、HATRPO、HASAC 等先进算法。相比 MAPPO，HARL 不依赖参数共享技巧，适用于异质智能体场景，并具备单调改进和收敛的理论保证。

环境准备

系统要求

• 操作系统: Linux (推荐，部分环境如 SMAC 仅支持 Linux)
• Python: 3.8
• PyTorch: >= 1.9.0 (需手动安装，建议搭配 CUDA >= 11.0)
• 硬件:
  • 常规训练：标准 GPU
  • Bi-DexterousHands 环境：需满足 IsaacGym 硬件要求

前置依赖

在开始之前，请确保已安装 conda 和 git。若使用 MuJoCo 或特定游戏环境（如 StarCraft II），需提前下载对应软件及授权文件。

安装步骤

1. 创建虚拟环境并安装 HARL

conda create -n harl python=3.8
conda activate harl
# 请手动安装 pytorch>=1.9.0 (CUDA>=11.0)
# 例如: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

git clone https://github.com/PKU-MARL/HARL.git
cd HARL
pip install -e .

2. 解决核心依赖冲突

安装完主程序后，必须执行以下命令以固定关键库版本，避免兼容性问题：

pip install gym==0.21.0
pip install pyglet==1.5.0
pip install importlib-metadata==4.13.0

注：若 pip install gym==0.21.0 失败，可尝试 conda install -c conda-forge gym=0.21.0。

3. 安装特定环境依赖（按需）

HARL 支持 7 种主流多智能体环境，请根据需求选择安装：

• MPE (Multi-Particle Environments)

  pip install pettingzoo==1.22.2
  pip install supersuit==3.7.0
  

• Light Aircraft Game (LAG)

  pip install torch pymap3d jsbsim==1.1.6 geographiclib gym==0.21.0 wandb icecream setproctitle
  git submodule init
  git submodule update
  

• MuJoCo / MAMuJoCo 需先前往 MuJoCo 官网 或 GitHub 下载对应版本（如 mujoco210），解压至 ~/.mujoco 并配置 LD_LIBRARY_PATH，然后运行：

  sudo apt install libosmesa6-dev libgl1-mesa-glx libglfw3
  pip install mujoco
  pip install "mujoco-py>=2.1.2.14"
  pip install "Jinja2>=3.0.3" "glfw>=2.5.1" "Cython>=0.29.28"
  

• 其他环境 (SMAC, SMACv2, Google Football, Bi-DexterousHands) 请参考各环境官方仓库的安装说明进行安装。例如 SMAC 需要安装 StarCraft II 4.10 版本。

基本使用

1. 快速开始训练

HARL 提供了调优好的配置文件。你可以直接使用一行命令在指定环境中训练算法。

示例：在 SMAC 环境中使用 HAPPO 算法进行训练

cd examples
python train.py --algo happo --env smac --exp_name my_first_experiment

示例：复现论文结果（使用预调优配置）

python train.py --load_config /绝对路径/to/tuned_configs/smac/happo.yaml --exp_name reproduce_result

2. 批量运行实验

可以通过 Shell 脚本循环修改随机种子进行批量实验：

for seed in $(seq 1 3)
do
	python train.py --algo happo --env smac --exp_name test_batch --seed $seed
done

3. 查看结果与渲染

• 日志与模型：训练结束后，检查 results 文件夹，内含 TensorBoard 日志、配置文件及保存的模型。
• 渲染演示：修改算法配置文件，设置 use_render: True 和 model_dir: <模型路径>，再次运行训练命令即可渲染。
  • 注意：对于 Football 环境，还需在环境配置中设置 render: True；SMAC 环境会自动生成视频回放至 StarCraftII/Replays。

4. 适配新环境

若需在新任务上应用 HARL，需实现统一的环境接口类：

class Env:
    def __init__(self, args):
        self.env = ...
        self.n_agents = ...
        self.share_observation_space = ...
        self.observation_space = ...
        self.action_space = ...

    def step(self, actions):
        return obs, state, rewards, dones, info, available_actions

    def reset(self):
        return obs, state, available_actions

    def seed(self, seed):
        pass

    def render(self):
        pass

    def close(self):
        self.env.close()

实现后，参照现有环境示例注册 Logger、添加 YAML 配置并在 examples/train.py 中接入即可。