# mindrl **Repository Path**: mindspore-lab/mindrl ## Basic Information - **Project Name**: mindrl - **Description**: MindSpore Reinforcement是一个开源的强化学习框架，支持使用强化学习算法对agent进行分布式训练。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 12 - **Forks**: 3 - **Created**: 2023-01-10 - **Last Updated**: 2025-07-11 ## Categories & Tags **Categories**: machine-learning **Tags**: None ## README # MindSpore Reinforcement [View English](./README.md) [![Python Version](https://img.shields.io/badge/python-3.7%2F3.8%2F3.9-green)](https://pypi.org/project/mindspore-rl/) [![LICENSE](https://img.shields.io/github/license/mindspore-ai/mindspore.svg?style=flat-square)](https://github.com/mindspore-ai/reinforcement/blob/master/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/mindspore-lab/mindrl/pulls) - [MindSpore Reinforcement](#mindspore-reinforcement) - [概述](#概述) - [安装](#安装) - [MindSpore版本依赖关系](#mindspore版本依赖关系) - [pip安装](#pip安装) - [源码编译安装](#源码编译安装) - [验证是否成功安装](#验证是否成功安装) - [快速入门](#快速入门) - [特性](#特性) - [算法](#算法) - [环境](#环境) - [经验回放](#经验回放) - [未来路标](#未来路标) - [社区](#社区) - [治理](#治理) - [交流](#交流) - [贡献](#贡献) - [许可证](#许可证) ## 概述 MindSpore Reinforcement是一个开源的强化学习框架，支持使用强化学习算法对agent进行**分布式训练**。MindSpore Reinforcement为编写强化学习算法提供了**干净整洁的API抽象**，它将算法与部署和执行注意事项解耦，包括加速器的使用、并行度和跨worker集群计算的分布。MindSpore Reinforcement将强化学习算法转换为一系列编译后的**计算图**，然后由MindSpore框架在CPU、GPU或Ascend AI处理器上高效运行。MindSpore Reinforcement的架构在如下展示: ![MindSpore_RL_Architecture](docs/images/mindspore_rl_architecture.png) ## 安装 MindSpore Reinforcement依赖MindSpore训练推理框架，安装完[MindSpore](https://gitee.com/mindspore/mindspore#%E5%AE%89%E8%A3%85)，再安装MindSpore Reinforcement。可以采用pip安装或者源码编译安装两种方式。 ### MindSpore版本依赖关系 由于MindSpore Reinforcement与MindSpore有依赖关系，请按照根据下表中所指示的对应关系，在[MindSpore下载页面](https://www.mindspore.cn/versions)下载并安装对应的whl包。 ```shell pip install https://ms-release.obs.cn-north-4.myhuaweicloud.com/{MindSpore-Version}/MindSpore/cpu/ubuntu_x86/mindspore-{MindSpore-Version}-cp37-cp37m-linux_x86_64.whl ``` | MindSpore Reinforcement | 分支 | MindSpore | | :---------------------: | :----------------------------------------------------------: | :-------: | | 0.7.0 | [r0.7](https://github.com/mindspore-lab/mindrl/tree/r0.7/) | 2.1.0 | | 0.6.0 | [r0.6](https://github.com/mindspore-lab/mindrl/tree/r0.6/) | 2.0.0 | | 0.5.0 | [r0.5](https://gitee.com/mindspore/reinforcement/tree/r0.5/) | 1.8.0 | | 0.3.0 | [r0.3](https://gitee.com/mindspore/reinforcement/tree/r0.3/) | 1.7.0 | | 0.2.0 | [r0.2](https://gitee.com/mindspore/reinforcement/tree/r0.2/) | 1.6.0 | | 0.1.0 | [r0.1](https://gitee.com/mindspore/reinforcement/tree/r0.1/) | 1.5.0 | ### pip安装 使用pip命令安装，请从[MindSpore Reinforcement下载页面](https://www.mindspore.cn/versions)下载并安装whl包。 ```shell pip install https://ms-release.obs.cn-north-4.myhuaweicloud.com/{MindSpore_version}/Reinforcement/any/mindspore_rl-{Reinforcement_version}-py3-none-any.whl --trusted-host ms-release.obs.cn-north-4.myhuaweicloud.com -i https://pypi.tuna.tsinghua.edu.cn/simple ``` > - 在联网状态下，安装whl包时会自动下载MindSpore Reinforcement安装包的依赖项（依赖项详情参见requirement.txt），其余情况需自行安装。 > - `{MindSpore_version}`表示MindSpore版本号，MindSpore和Reinforcement版本配套关系参见[页面](https://www.mindspore.cn/versions)。 > - `{Reinforcement_version}`表示Reinforcement版本号。例如下载0.1.0版本Reinforcement时，`{MindSpore_version}应写为1.5.0，{Reinforcement_version}`应写为0.1.0。 ### 源码编译安装 下载[源码](https://github.com/mindspore-lab/mindrl)，下载后进入`mindrl`目录。 ```shell git clone https://github.com/mindspore-lab/mindrl.git cd mindrl/ bash build.sh pip install output/mindspore_rl-{Reinforcement_version}-py3-none_{ARCH}.whl ``` 其中，`build.sh`为`mindrl`目录下的编译脚本文件。`{Reinforcement_version}`表示MindSpore Reinforcement版本号，`{ARCH}`表示系统架构，可选`x86_64`或`aarch64`。 安装依赖项 ```shell cd mindrl && pip install requirements.txt ``` ### 验证是否成功安装 执行以下命令，验证安装结果。导入Python模块不报错即安装成功： ```python import mindspore_rl ``` ## 快速入门 MindSpore Reinforcement的算法示例位于`mindrl/example/`下，以一个简单的算法[Deep Q-Learning (DQN)](https://www.mindspore.cn/reinforcement/docs/zh-CN/master/dqn.html) 示例，演示MindSpore Reinforcement如何使用。 第一种开箱即用方式，使用脚本文件直接运行: ```shell cd mindrl/example/dqn/scripts bash run_standalone_train.sh ``` 第二种方式，直接使用`config.py`和`train.py`，可以更灵活地修改配置： ```shell cd mindrl/example/dqn python train.py --episode 1000 --device_target GPU ``` 第一种方式会在当前目录会生成`dqn_train_log.txt`日志文件，第二种在屏幕上打印日志信息： ```shell Episode 0: loss is 0.396, rewards is 42.0 Episode 1: loss is 0.226, rewards is 15.0 Episode 2: loss is 0.202, rewards is 9.0 Episode 3: loss is 0.122, rewards is 15.0 Episode 4: loss is 0.107, rewards is 12.0 Episode 5: loss is 0.078, rewards is 10.0 Episode 6: loss is 0.075, rewards is 8.0 Episode 7: loss is 0.084, rewards is 12.0 Episode 8: loss is 0.069, rewards is 10.0 Episode 9: loss is 0.067, rewards is 10.0 Episode 10: loss is 0.056, rewards is 8.0 ----------------------------------------- Evaluate for episode 10 total rewards is 9.600 ----------------------------------------- ```
更多有关安装指南、教程和API的详细信息，请参阅[用户文档](https://www.mindspore.cn/reinforcement/docs/zh-CN/master/index.html)。 ## 特性 ### 算法
算法 RL版本 动作空间 设备 示例环境
离散连续 CPUGPUAscend
DQN >= 0.1 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
PPO >= 0.1 / ✔️ ✔️ ✔️ ✔️ HalfCheetah-v2
AC >= 0.1 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
A2C >= 0.2 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
DDPG >= 0.3 / ✔️ ✔️ ✔️ ✔️ HalfCheetah-v2
QMIX >= 0.5 ✔️ / ✔️ ✔️ ✔️ SMAC, Simple Spread
SAC >= 0.5 / ✔️ ✔️ ✔️ ✔️ HalfCheetah-v2
TD3 >= 0.6 / ✔️ ✔️ ✔️ ✔️ HalfCheetah-v2
C51 >= 0.6 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
A3C >= 0.6 ✔️ / / ✔️ ✔️ CartPole-v0
CQL >= 0.6 / ✔️ ✔️ ✔️ ✔️ Hopper-v0
MAPPO >= 0.6 ✔️ / ✔️ ✔️ ✔️ Simple Spread
GAIL >= 0.6 / ✔️ ✔️ ✔️ ✔️ HalfCheetah-v2
MCTS >= 0.6 ✔️ / ✔️ ✔️ / Tic-Tac-Toe
AWAC >= 0.6 / ✔️ ✔️ ✔️ ✔️ Ant-v2
Dreamer >= 0.6 / ✔️ / ✔️ ✔️ Walker-walk
IQL >= 0.6 / ✔️ ✔️ ✔️ ✔️ Walker2d-v2
MADDPG >= 0.6 ✔️ / ✔️ ✔️ ✔️ simple_spread
Double DQN >= 0.6 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
Policy Gradient >= 0.6 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
Dueling DQN >= 0.6 ✔️ / ✔️ ✔️ ✔️ CartPole-v0
### 环境 强化学习领域中，智能体与环境交互过程中，学习策略来使得数值化的收益信号最大化。“环境”作为待解决的问题，是强化学习领域中重要的要素。当前已支持的环境如下表所示：
环境 版本
Gym >= v0.1
MuJoCo >= v0.1
MPE >= v0.6
SMAC >= v0.5
DMC >= v0.6
PettingZoo-mpe >= v0.6
D4RL >= v0.6
### 经验回放 在强化学习中，ReplayBuffer是一个常用的基本数据存储方式，它的功能在于存放智能体与环境交互得到的数据。 使用ReplayBuffer可以解决以下几个问题： 1. 存储的历史经验数据，可以通过采样或一定优先级的方式抽取，以打破训练数据的相关性，使抽样的数据具有独立同分布的特性。 2. 可以提供数据的临时存储，提高数据的利用率。 一般情况下，算法人员使用原生的Python数据结构或Numpy的数据结构来构造ReplayBuffer, 或者一般的强化学习框架也提供了标准的API封装。不同的是，MindSpore实现了设备端的ReplayBuffer结构，一方面能在使用GPU/Ascend硬件时减少数据在Host和Device之间的频繁拷贝，另一方面，以MindSpore算子的形式表达ReplayBuffer，可以构建完整的IR图，使能MindSpore GRAPH_MODE的各种图优化，提升整体的性能。
类别 特性 设备
CPUGPUAscend
UniformReplayBuffer 1 FIFO先进先出
2 支持batch 输入		 ✔️ ✔️ /
PriorityReplayBuffer 1 proportional-based优先级策略
2 Sum Tree提升采样效率		 ✔️ ✔️ ✔️
ReservoirReplayBuffer 采用无偏采样 ✔️ ✔️ ✔️
### 分布式 MindSpore Reinforcement 将强化学习的算法定义与算法如何并行或分布式执行在硬件上进行了解偶。我们通过一个新的抽象，即数据流片段图（**Fragmented Dataflow Graphs**)来实现这一目标，算法的每一部分都将成为数据流片段，并由MSRL灵活地分发与并行。参考[更多信息](https://github.com/mindspore-lab/mindrl/tree/master/mindspore_rl/distribution/README.md)。 当前已经支持如下分布式策略：
策略类别 策略 示例
MultiActorSingleLearnerDP 同步单learner多actor结构分布式策略 ppo
AsyncMultiActorSingleLearnerDP 异步单learner多actor结构分布式策略 a3c
SingleActorLearnerWithMultEnvDP 单actor learner 多远端环境分布式策略 ppo
SingleActorLearnerWithMultEnvHeterDP 单actor learner 多远端环境异构分布式策略 ppo

MultiActorSingleLearnerDP

AsyncMultiActorSingleLearnerDP

SingleActorLearnerWithMultEnvDP
SingleActorLearnerWithMultEnvHeterDP
## 未来路标 MindSpore Reinforcement初始版本包含了一个稳定的API， 用于实现强化学习算法和使用MindSpore的计算图执行计算。现已支持算法并行和自动分布式执行能力，支持多智能体，offline-rl，门特卡罗树等多种场景。MindSpore Reinforcement的后续版本将继续完善并提升自动分布式功能以及接入大模型的能力，敬请期待。 ## 社区 ### 治理 查看MindSpore如何进行[开放治理](https://gitee.com/mindspore/community/blob/master/governance.md)。 ### 交流 - [MindSpore Slack](https://join.slack.com/t/mindspore/shared_invite/zt-dgk65rli-3ex4xvS4wHX7UDmsQmfu8w) 开发者交流平台。 - [MindSpore 论坛](https://bbs.huaweicloud.com/forum/forum-1076-1.html) 欢迎发帖。 - [Reinforcement issues](https://github.com/mindspore-lab/mindrl/issues) 欢迎提交问题。 ## 贡献 欢迎参与贡献。 MindSpore Reinforcement 会按3个月周期更新，如果遇到问题，请及时通知我们。我们感谢所有的贡献，可以通过issue/pr的形式提交您的问题或修改。 ## 许可证 [Apache License 2.0](https://gitee.com/mindspore/reinforcement/blob/master/LICENSE)