XuanCe：全面且统一的深度强化学习库

完整文档 | 中文文档 | README_CN.md

XuanCe 是一个开源的深度强化学习（DRL）算法集合。

我们将其命名为中文名“玄策”。“玄”意为不可思议、神奇之盒，“策”意为策略。

DRL 算法对超参数调优非常敏感，不同的技巧会带来性能差异，且训练过程往往不稳定。因此，DRL 算法有时显得难以捉摸，仿佛充满“玄机”。本项目提供了全面、高质量且易于理解的 DRL 算法实现，希望能为读者揭示强化学习的奥秘。

我们期望该库能够兼容多种深度学习后端（PyTorch、TensorFlow 和 MindSpore），并真正成为一个丰富的 DRL 算法库。

论文链接: https://arxiv.org/pdf/2312.16248.pdf

目录：

• 特性
• 算法
• 环境
• 安装
• 快速开始
• 社区
• 引用

特性

• :school_satchel: 高度模块化。
• :thumbsup: 易于学习、安装和使用。
• :twisted_rightwards_arrows: 模型组合灵活。
• :tada: 丰富的算法，涵盖多种任务。
• :couple: 同时支持单智能体和多智能体强化学习任务。
• :key: 对不同用户具有高度兼容性。（PyTorch、TensorFlow2、MindSpore、CPU、GPU、Linux、Windows、MacOS 等）
• :zap: 利用并行环境实现快速运行。
• :computer: 支持多 GPU 分布式训练。
• 🎛️ 支持自动超参数调优。
• :chart_with_upwards_trend: 可与 tensorboard 或 wandb 工具结合，提供良好的可视化效果。

算法

:point_right: 单智能体强化学习

• DQN: 深度 Q 网络 [论文]
• Double DQN: 带双 Q 学习的 DQN [论文]
• Dueling DQN: 带决斗网络的 DQN [论文]
• PER: 带优先经验回放的 DQN [论文]
• NoisyDQN: 带参数空间噪声以促进探索的 DQN [论文]
• DRQN: 深度循环 Q 网络 [论文]
• QRDQN: 带分位数回归的 DQN [论文]
• C51: 分布式强化学习 [论文]
• PG: 原始策略梯度 [论文]
• NPG: 自然策略梯度 [论文]
• PPG: 瞬态策略梯度 [论文] [代码]
• A2C: 优势演员评论家 [论文] [代码]
• SAC: 软演员评论家 [论文] [代码]
• SAC-Discrete: 适用于离散动作的软演员评论家 [论文] [代码]
• PPO-Clip: 带截断目标的近端策略优化 [论文] [代码]
• PPO-KL: 带 KL 散度的近端策略优化 [论文] [代码]
• DDPG: 深度确定性策略梯度 [论文] [代码]
• TD3: 双延迟深度确定性策略梯度 [论文][代码]
• P-DQN: 参数化的深度 Q 网络 [论文]
• MP-DQN: 多通道参数化的深度 Q 网络 [论文] [代码]
• SP-DQN: 分割式参数化的深度 Q 网络 [论文]

:point_right: 基于模型的强化学习 (MBRL)

• DreamerV2 [论文] [代码]
• DreamerV3 [论文] [代码]
• HarmonyDream [论文] [代码]

:point_right: 多智能体强化学习 (MARL)

• IQL: 独立Q学习 [论文] [代码]
• VDN: 值分解网络 [论文] [代码]
• QMIX: Q混合网络 [论文] [代码]
• WQMIX: 加权Q混合网络 [论文] [代码]
• QTRAN: Q变换 [论文] [代码]
• DCG: 深度协调图 [论文] [代码]
• IDDPG: 独立深度确定性策略梯度 [论文] [代码]
• MADDPG: 多智能体深度确定性策略梯度 [论文] [代码]
• IAC: 独立演员-评论家 [论文] [代码]
• COMA: 反事实多智能体策略梯度 [论文] [代码]
• VDAC: 值分解演员-评论家 [论文] [代码]
• IPPO: 独立近端策略优化 [论文] [代码]
• MAPPO: 多智能体近端策略优化 [论文] [代码]
• MFQ: 平均场Q学习 [论文] [代码]
• MFAC: 平均场演员-评论家 [论文] [代码]
• ISAC: 独立软演员-评论家
• MASAC: 多智能体软演员-评论家 [论文]
• MATD3: 多智能体双延迟深度确定性策略梯度 [论文]
• IC3Net: 个体化控制连续通信模型 [论文] [代码]
• CommNet: 通信神经网络 [论文][代码]

:point_right: 对比强化学习 (CRL)

• CURL: 用于高效样本强化学习的对比无监督表征学习 [论文] [代码]
• SPR: 基于自我预测表征的数据高效强化学习 [论文] [代码]
• DrQ: 图像增强就够了：从像素中正则化深度强化学习 [论文] [代码]

环境

经典控制

小车倒立摆

单摆

双臂机器人

爬山车

Box2D

双足行走者

赛车

月球着陆器

MuJoCo环境

蚂蚁

半条猎豹

跳跃者

人形站立

人形

倒立摆

...

Atari 环境

Adventure

Air Raid

Alien

Amidar

Assault

Asterix

Asteroids

...

Minigrid 环境

GoToDoorEnv

LockedRoomEnv

MemoryEnv

PlaygroundEnv

...

无人机环境

Helix

单智能体悬停

多智能体悬停

...

MetaDrive

MPE 环境

Simple Push

Simple Reference

Simple Spread

Simple Adversary

...

机器人仓库

示例1

示例2

示例3

示例4

...

SMAC

Google Research 足球

:point_right: 安装

:computer: XuanCe 可以在 Linux、Windows、MacOS 以及 EulerOS 等操作系统上运行。

步骤 1：设置 Python 环境

我们建议安装 Anaconda 来管理你的 Python 环境。 （你也可以从这里下载特定的 Anaconda 安装程序。）

然后打开终端，创建或激活一个新的 conda 环境（推荐使用 Python >= 3.8）：

conda create -n xuance_env python=3.8 && conda activate xuance_env

步骤 2：安装 XuanCe

pip install xuance

此命令不包含深度学习后端的依赖项。若要安装带有深度学习工具的 XuanCe，可以输入 pip install xuance[torch] 用于 PyTorch， pip install xuance[tensorflow] 用于 TensorFlow2， pip install xuance[mindspore] 用于 MindSpore， 而 pip install xuance[all] 则会安装所有依赖项。

注意：某些额外的包需要手动安装才能进一步使用。 点击这里查看更详细的安装说明。

:point_right: 快速入门

训练一个模型

import xuance

runner = xuance.get_runner(algo='ppo',
                           env='classic_control',
                           env_id='CartPole-v1')
runner.run(mode='train')

测试模型

import xuance

runner = xuance.get_runner(algo='ppo',
                           env='classic_control',
                           env_id='CartPole-v1')
runner.run(mode='test')

可视化结果

TensorBoard

你可以使用 TensorBoard 来可视化训练过程中的各项指标。训练完成后，日志文件会自动保存在 .results/ 目录下，运行以下命令后即可查看训练数据。

$ tensorboard --logdir ./logs/dqn/torch/CartPole-v0

Weights & Biases (wandb)

XuanCe 还支持 Weights & Biases（wandb）工具，方便用户可视化运行结果。

如何在线使用 wandb？ :arrow_right: https://github.com/wandb/wandb.git/

如何离线使用 wandb？ :arrow_right: https://github.com/wandb/server.git/

基准测试

XuanCe 提供了官方的基准测试流程，用于评估深度强化学习和多智能体强化学习算法。

为了避免主仓库体积过大， 官方基准测试结果（包括评估曲线、汇总表格以及预训练模型） 被维护在一个独立的仓库中：

👉 https://github.com/agi-brain/xuance-benchmarks

用户可以选择：

• 使用提供的流程在本地运行基准测试；或
• 直接查看并复用官方基准测试结果，无需重新进行实验。

社区

• GitHub 问题：https://github.com/agi-brain/xuance/issues
• GitHub 讨论：https://github.com/orgs/agi-brain/discussions
• Discord 邀请链接：https://discord.gg/HJn2TBQS7y
• Slack 邀请链接：https://join.slack.com/t/xuancerllib/
• QQ 应用群号：552432695、153966755
• 微信公众号：“玄策 RLlib”

（注：你也可以在 Stack Overflow 上提问。）

(QQ 群和微信公众号的二维码)

QQ 群 1

QQ 群 2

官方微信公众号

引用

如果你在研究或开发中使用了 XuanCe，请引用以下论文：

@article{liu2023xuance,
  title={XuanCe: A Comprehensive and Unified Deep Reinforcement Learning Library},
  author={Liu, Wenzhang and Cai, Wenzhe and Jiang, Kun and Cheng, Guangran and Wang, Yuanda and Wang, Jiawei and Cao, Jingyu and Xu, Lele and Mu, Chaoxu and Sun, Changyin},
  journal={arXiv preprint arXiv:2312.16248},
  year={2023}
}

XuanCe (玄策) 快速上手指南

XuanCe 是一个全面且统一的深度强化学习（DRL）开源库，支持 PyTorch、TensorFlow 和 MindSpore 多种后端，涵盖单智能体（DRL）、多智能体（MARL）及基于模型的强化学习（MBRL）等多种算法。

1. 环境准备

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

• 操作系统: Linux, Windows, 或 MacOS
• Python 版本: 3.8 - 3.10 (推荐 3.9)
• 深度学习框架 (任选其一):
  • PyTorch >= 1.13.0
  • TensorFlow >= 2.6.0
  • MindSpore >= 1.10.1
• 环境交互库:
  • Gymnasium >= 0.28.1
  • PettingZoo >= 1.23.0 (用于多智能体任务)

提示: 建议先安装好对应的深度学习框架（如 pip install torch），XuanCe 会自动检测并适配后端。国内用户可使用清华源或阿里源加速依赖下载。

2. 安装步骤

方式一：通过 PyPI 安装（推荐）

使用 pip 直接安装最新稳定版：

pip install xuance

国内加速安装（使用清华镜像源）：

pip install xuance -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

如果您需要最新开发版功能，可以从 GitHub 克隆源码安装：

git clone https://github.com/agi-brain/xuance.git
cd xuance
pip install -e .

3. 基本使用

XuanCe 的设计高度模块化，使用流程通常分为：配置参数 -> 初始化环境 -> 初始化算法 -> 运行训练。

以下是一个使用 PPO-Clip 算法在 CartPole 环境中进行训练的最简示例（基于 PyTorch 后端）：

代码示例

import xuance as xc
from xuance.environment import make_envs
from xuance.agents import PPO_Clip

# 1. 设置超参数 (可以使用字典或加载配置文件)
args = {
    'algorithm': 'PPO-Clip',
    'env_name': 'CartPole-v1',
    'n_envs': 8,              # 并行环境数量
    'batch_size': 64,
    'n_steps': 2048,          # 每个环境采集步数
    'gamma': 0.99,
    'lr': 3e-4,
    'device': 'cuda:0' if xc.torch.cuda.is_available() else 'cpu',
    # ... 其他默认参数可参考文档
}

# 2. 初始化环境
# make_envs 自动处理 Gymnasium/PettingZoo 接口
envs = make_envs(
    env_name=args['env_name'],
    n_envs=args['n_envs'],
    device=args['device']
)

# 3. 初始化算法模型
agent = PPO_Clip(
    args=args,
    env_info=envs.env_info,
    policy=None # 若无预训练策略可设为 None
)

# 4. 开始训练
print("Start training...")
agent.run(envs=envs, total_steps=100000)

# 5. 关闭环境
envs.close()

运行说明

1. 将上述代码保存为 train_ppo.py。
2. 确保已安装 gymnasium[classic-control] 以支持 CartPole 环境：

   pip install "gymnasium[classic-control]"
   

3. 运行脚本：

   python train_ppo.py
   

训练过程中，XuanCe 默认会输出日志，并支持通过 TensorBoard 或 WandB 可视化训练曲线（需在 args 中配置相应参数）。

---

更多详细算法列表、高级配置及 API 文档，请访问 官方文档 或 中文文档。