Skip to content

Latest commit

 

History

History
586 lines (471 loc) · 40.7 KB

README.zh.md

File metadata and controls

586 lines (471 loc) · 40.7 KB
Raw

LightZero

Twitter PyPI PyPI - Python Version Loc Comments

Code Test Badge Creation Package Release

GitHub Org's stars GitHub stars GitHub forks GitHub commit activity GitHub issues GitHub pulls Contributors GitHub license

最近更新于 2024.11.23 LightZero-v0.1.0

English | 简体中文 | 文档 | LightZero 论文 | 🔥UniZero 论文 | 🔥ReZero 论文

LightZero 是一个轻量、高效、易懂的 MCTS+RL 开源算法库。 有关 LightZero 的任何疑问，您都可以咨询基于 RAG 技术的问答助手：ZeroPal。

🔍 背景

以 AlphaZero, MuZero 为代表的结合蒙特卡洛树搜索 (Monte Carlo Tree Search, MCTS) 和深度强化学习 (Deep Reinforcemeent Learning, DRL) 的方法，在诸如围棋，Atari 等各种游戏上取得了超人的水平，也在诸如蛋白质结构预测，矩阵乘法算法寻找等科学领域取得了可喜的进展。下图为蒙特卡洛树搜索（MCTS）算法族的发展历史： pipeline

🎨 概览

LightZero 是一个结合了蒙特卡洛树搜索和强化学习的开源算法工具包。 它支持一系列基于 MCTS 的 RL 算法，具有以下优点：

  • 轻量。
  • 高效。
  • 易懂。

详情请参考特点、框架结构和集成算法。

LightZero 的目标是标准化 MCTS 算法族，以加速相关研究和应用。 Benchmark 中介绍了目前所有已实现算法的性能比较。

导航

💥 特点

轻量：LightZero 中集成了多种 MCTS 族算法，能够在同一框架下轻量化地解决多种属性的决策问题。

高效：LightZero 针对 MCTS 族算法中耗时最长的环节，采用混合异构计算编程提高计算效率。

易懂：LightZero 为所有集成的算法提供了详细文档和算法框架图，帮助用户理解算法内核，在同一范式下比较算法之间的异同。同时，LightZero 也为算法的代码实现提供了函数调用图和网络结构图，便于用户定位关键代码。

🧩 框架结构

Image Description 2

上图是 LightZero 的框架流程图。我们在下面简介其中的3个核心模块:

Model: Model 用于定义网络结构，包含__init__函数用于初始化网络结构，和forward函数用于计算网络的前向传播。

Policy: Policy 定义了对网络的更新方式和与环境交互的方式，包括三个过程，分别是训练过程（learn）、采样过程（collect）和评估过程（evaluate）。

MCTS:

MCTS 定义了蒙特卡洛搜索树的结构和与Policy的交互方式。MCTS的实现包括 python 和 cpp 两种，分别在ptree和ctree中实现。

关于 LightZero 的文件结构，请参考 lightzero_file_structure。

🎁 集成算法

LightZero 是基于 PyTorch 实现的 MCTS 算法库，在 MCTS 的实现中也用到了 cython 和 cpp。同时，LightZero 的框架主要基于 DI-engine 实现。目前 LightZero 中集成的算法包括：

LightZero 目前支持的环境及算法如下表所示：

Env./Algo. AlphaZero MuZero Sampled MuZero EfficientZero Sampled EfficientZero Gumbel MuZero Stochastic MuZero UniZero Sampled UniZero ReZero
TicTacToe ✔ ✔ 🔒 🔒 🔒 ✔ 🔒 ✔ 🔒 🔒
Gomoku ✔ ✔ 🔒 🔒 🔒 ✔ 🔒 ✔ 🔒 ✔
Connect4 ✔ ✔ 🔒 🔒 🔒 🔒 🔒 ✔ 🔒 ✔
2048 --- ✔ 🔒 🔒 🔒 🔒 ✔ ✔ 🔒 🔒
Chess 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
Go 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
CartPole --- ✔ 🔒 ✔ ✔ ✔ ✔ ✔ 🔒 ✔
Pendulum --- ✔ ✔ ✔ ✔ ✔ ✔ 🔒 ✔ 🔒
LunarLander --- ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ 🔒
BipedalWalker --- ✔ ✔ ✔ ✔ ✔ 🔒 🔒 ✔ 🔒
Atari --- ✔ 🔒 ✔ ✔ ✔ ✔ ✔ 🔒 ✔
DeepMind Control --- --- ✔ --- ✔ 🔒 🔒 🔒 ✔ 🔒
MuJoCo --- ✔ 🔒 ✔ ✔ 🔒 🔒 🔒 🔒 🔒
MiniGrid --- ✔ 🔒 ✔ ✔ 🔒 🔒 ✔ 🔒 🔒
Bsuite --- ✔ 🔒 ✔ ✔ 🔒 🔒 ✔ 🔒 🔒
Memory --- ✔ 🔒 ✔ ✔ 🔒 🔒 ✔ 🔒 🔒
SumToThree (billiards) --- 🔒 🔒 🔒 ✔ 🔒 🔒 🔒 🔒 🔒

(1): "✔" 表示对应的项目已经完成并经过良好的测试。

(2): "🔒" 表示对应的项目在等待列表中（正在进行中）。

(3): "---" 表示该算法不支持此环境。

⚙️ 安装方法

可以用以下命令从 Github 的源码中安装最新版的 LightZero：

git clone https://github.com/opendilab/LightZero.git
cd LightZero
pip3 install -e .

请注意，LightZero 目前仅支持在 Linux 和 macOS 平台上进行编译。 我们正在积极将该支持扩展到 Windows 平台。

使用 Docker 进行安装

我们也提供了一个Dockerfile，用于设置包含运行 LightZero 库所需所有依赖项的环境。此 Docker 镜像基于 Ubuntu 20.04，并安装了Python 3.8以及其他必要的工具和库。 以下是如何使用我们的 Dockerfile 来构建 Docker 镜像，从该镜像运行一个容器，并在容器内执行 LightZero 代码的步骤。

  1. 下载 Dockerfile：Dockerfile 位于 LightZero 仓库的根目录中。将此文件下载到您的本地机器。

  2. 准备构建上下文：在您的本地机器上创建一个新的空目录，将 Dockerfile 移动到此目录，并导航到此目录。这一步有助于在构建过程中避免向 Docker 守护进程发送不必要的文件。

    mkdir lightzero-docker
mv Dockerfile lightzero-docker/
cd lightzero-docker/

  3. 构建 Docker 镜像：使用以下命令构建 Docker 镜像。此命令应在包含 Dockerfile 的目录内运行。

    docker build -t ubuntu-py38-lz:latest -f ./Dockerfile .

  4. 从镜像运行容器：使用以下命令以交互模式启动一个 Bash shell 的容器。

    docker run -dit --rm ubuntu-py38-lz:latest /bin/bash

  5. 在容器内执行 LightZero 代码：一旦你在容器内部，你可以使用以下命令运行示例 Python 脚本：

    python ./LightZero/zoo/classic_control/cartpole/config/cartpole_muzero_config.py

🚀 快速开始

使用如下代码在 CartPole 环境上快速训练一个 MuZero 智能体:

cd LightZero
python3 -u zoo/classic_control/cartpole/config/cartpole_muzero_config.py

使用如下代码在 Pong 环境上快速训练一个 MuZero 智能体：

cd LightZero
python3 -u zoo/atari/config/atari_muzero_config.py

使用如下代码在 TicTacToe 环境上快速训练一个 MuZero 智能体：

cd LightZero
python3 -u zoo/board_games/tictactoe/config/tictactoe_muzero_bot_mode_config.py

使用如下代码在 Pong 环境上快速训练一个 UniZero 智能体：

cd LightZero
python3 -u zoo/atari/config/atari_unizero_config.py

📚 文档

LightZero的文档可以在这里找到。文档中包含教程和API参考。

为希望定制环境和算法的用户，我们提供了相应的指南：

如有任何疑问，欢迎随时联系我们。

📊 基线算法比较

点击查看

tictactoe_bot-mode_main connect4_bot-mode_main gomoku_bot-mode_main

pong_main qbert_main mspacman_main mspacman_sez_K

其中 Factored Policy 表示智能体学习一个输出离散分布的策略网络，上述5种环境手动离散化后的动作空间维度分别为11、49（7^2）、256（4^4)、64 (4^3) 和 4096 (4^6)。Gaussian Policy表示智能体学习一个策略网络，该网络直接输出高斯分布的参数 μ 和 σ。

pendulum_main pendulum_sez_K lunarlander_main

bipedalwalker_main hopper_main walker2d_main

pong_gmz_ns mspacman_gmz_ns gomoku_bot-mode_gmz_ns lunarlander_gmz_ns

2048_stochasticmz_mz mspacman_gmz_ns

keycorridors3r3_exploration fourrooms_exploration

📝 MCTS 相关笔记

论文笔记

以下是 LightZero 中集成算法的中文详细文档：

点击折叠

AlphaZero

MuZero

EfficientZero

SampledMuZero

GumbelMuZero

StochasticMuZero

算法概览图符号表

也可参考相应的知乎专栏: MCTS+RL 前沿理论和应用的深入解析。

算法框架图

以下是 LightZero 中集成算法的框架概览图：

(点击查看)

MCTS 相关论文

以下是关于 MCTS 相关的论文集合，这一部分 将会持续更新，追踪 MCTS 的前沿动态。

重要论文

(点击查看)

LightZero Implemented series

AlphaGo series

MuZero series

MCTS Analysis

MCTS Application

其他论文

(点击查看)

ICML

ICLR

NeurIPS

Other Conference or Journal

💬 反馈意见和贡献

  • 有任何疑问或意见都可以在 github 上直接 提出 issue

  • 开启或参加 GitHub 论坛

  • 在 LightZero discord server 上进行讨论

  • 或者联系我们的邮箱 ([email protected])

  • 感谢所有的反馈意见，包括对算法和系统设计。这些反馈意见和建议都会让 LightZero 变得更好。

🌏 引用

@article{niu2024lightzero,
  title={LightZero: A Unified Benchmark for Monte Carlo Tree Search in General Sequential Decision Scenarios},
  author={Niu, Yazhe and Pu, Yuan and Yang, Zhenjie and Li, Xueyan and Zhou, Tong and Ren, Jiyuan and Hu, Shuai and Li, Hongsheng and Liu, Yu},
  journal={Advances in Neural Information Processing Systems},
  volume={36},
  year={2024}
}

@article{pu2024unizero,
  title={UniZero: Generalized and Efficient Planning with Scalable Latent World Models},
  author={Pu, Yuan and Niu, Yazhe and Ren, Jiyuan and Yang, Zhenjie and Li, Hongsheng and Liu, Yu},
  journal={arXiv preprint arXiv:2406.10667},
  year={2024}
}

@article{xuan2024rezero,
  title={ReZero: Boosting MCTS-based Algorithms by Backward-view and Entire-buffer Reanalyze},
  author={Xuan, Chunyu and Niu, Yazhe and Pu, Yuan and Hu, Shuai and Liu, Yu and Yang, Jing},
  journal={arXiv preprint arXiv:2404.16364},
  year={2024}
}

💓 致谢

此算法库的实现部分基于以下 GitHub 仓库，非常感谢这些开创性工作：

特别感谢以下贡献者 @PaParaZz1, @karroyan, @nighood, @jayyoung0802, @timothijoe, @TuTuHuss, @HarryXuancy, @puyuan1996, @HansBug 对本项目的贡献和支持。

感谢所有为此项目做出贡献的人：

🏷️ 许可证

本仓库中的所有代码都符合 Apache License 2.0。

(回到顶部)