Pearl - 一款面向生产的强化学习智能体库

由 Meta 应用强化学习团队倾力打造

• v0.1 - Pearl 测试版现已发布！相关公告：Twitter 帖子、LinkedIn 帖子
  • 在 Meta NeurIPS 2023 官方网站上被重点推荐：官网
  • Meta 官方账号在 Twitter 和 LinkedIn 上也进行了重点推介：Twitter 帖子、LinkedIn 帖子。

更多关于该库的详细信息，请访问我们的官方网站。

Pearl 论文已在 Arxiv 上公开。

我们 NeurIPS 2023 的演示文稿已在此发布：这里。

概述

Pearl 是由 Meta 应用强化学习团队开源的一款全新的生产级强化学习智能体库。作为我们在开放人工智能创新方面努力的延续，Pearl 使研究人员和从业者能够开发强化学习智能体。这些智能体更注重长期累积反馈而非即时反馈，并且能够适应观测性有限、反馈稀疏且高度随机的环境。我们希望 Pearl 能为社区提供一种构建先进强化学习智能体的工具，使其能够适应各种复杂的生产环境。

新闻

2025年1月22日 - Pearl 组件序列化

Pearl 组件现在可以像 PyTorch 模块一样生成状态字典，这些状态字典可以使用 torch.save 和 torch.load 进行保存和加载！

以下是一个基本示例：

agent = PearlAgent(...)
# 保存智能体的状态字典
torch.save(agent.state_dict(), 'agent_state.pth')

agent2 = PearlAgent(...)  # agent2 必须与 agent 具有相同的结构
# 加载智能体的状态字典
agent2.load_state_dict(torch.load('agent_state.pth'))

assert agent2.compare(agent) == ""  # `compare` 是新引入的方法

请注意，这同样适用于子组件，例如 PolicyLearner、ExplorationModule 等。

如果您的组件包含非参数、非缓冲区或非子模块的属性，则这些属性不会自动包含在状态字典中。 在这种情况下，（就像在 PyTorch 中一样）需要定义 get_extra_state 和 set_extra_state 方法，以便将这些属性纳入状态字典中。 （例如，参见 ActorCriticBase.get_extra_state）。

在定义您自己的组件时，现在必须实现一个 compare 方法，该方法会返回一个字符串，列出两个组件之间的差异。 （例如，参见 PearlAgent.compare）。 此方法可用作通用的比较方法，以供测试之用。

开始使用

安装

要安装 Pearl，只需克隆本仓库并运行 pip install -e . 即可（需使用 ≥ 21.3 版本的 pip 和 ≥ 64 版本的 setuptools）：

git clone https://github.com/facebookresearch/Pearl.git
cd Pearl
pip install -e .

快速入门

要启动一个使用经典强化学习环境的 Pearl 智能体，以下是一个快速示例。

from pearl.pearl_agent import PearlAgent
from pearl.action_representation_modules.one_hot_action_representation_module import (
    OneHotActionTensorRepresentationModule,
)
from pearl.policy_learners.sequential_decision_making.deep_q_learning import (
    DeepQLearning,
)
from pearl.replay_buffers import (
    BasicReplayBuffer,
)
from pearl.utils.instantiations.environments.gym_environment import GymEnvironment

env = GymEnvironment("CartPole-v1")

num_actions = env.action_space.n
agent = PearlAgent(
    policy_learner=DeepQLearning(
        state_dim=env.observation_space.shape[0],
        action_space=env.action_space,
        hidden_dims=[64, 64],
        training_rounds=20,
        action_representation_module=OneHotActionTensorRepresentationModule(
            max_number_actions=num_actions
        ),
    ),
    replay_buffer=BasicReplayBuffer(10_000),
)

observation, action_space = env.reset()
agent.reset(observation, action_space)
done = False
while not done:
    action = agent.act(exploit=False)
    action_result = env.step(action)
    agent.observe(action_result)
    agent.learn()
    done = action_result.done

用户可以用任何实际问题替换环境。

教程

我们提供了一些 Jupyter 笔记本教程（并且目前正在制作更多！）：

1. 单件商品推荐系统。我们基于 MIND 数据集（Wu et al. 2020）构建了一个小型虚构的推荐系统环境。

2. 上下文 bandit。展示了上下文 bandit 算法及其在 Pearl 中的实现，使用来自 UCI 数据集的上下文 bandit 环境，并测试了 SquareCB、LinUCB 和 LinTS 的神经网络实现性能。

3. 冰冻湖泊。一个简单的示例，说明如何使用 one-hot 观测包装器来学习经典的 DQN 问题。

4. 深度 Q 学习 (DQN) 和双 DQN。演示如何在 Cart-Pole 环境上运行 DQN 和双 DQN。

5. 带有安全约束的演员-评论家算法。演示如何运行演员-评论家方法，包括带有安全约束的版本。

设计与特性

Pearl 采用模块化设计，因此行业从业者或学术研究人员可以自由选择任意子集，并灵活组合以下功能，以构建专为特定用例定制的 Pearl 智能体。Pearl 为生产环境提供了一系列独特的功能，包括动态动作空间、离线学习、智能神经探索、安全决策、历史摘要和数据增强。

您可以在 utils/scripts/benchmark_config.py 中找到许多通过混合搭配强化学习功能而生成的 Pearl 智能体候选方案。

在真实场景中的应用

Pearl 目前正逐步支持各类实际应用场景，包括推荐系统、拍卖竞价系统和创意内容筛选等。这些场景各自需要 Pearl 提供的部分功能。下表展示了上述各应用所使用的功能子集：

Pearl 功能	推荐系统	拍卖竞价	创意内容筛选
策略学习	✅	✅	✅
智能探索	✅	✅	✅
安全性		✅
历史摘要		✅
回放缓冲区	✅	✅	✅
上下文 bandit			✅
离线强化学习	✅	✅
动态动作空间	✅		✅
大规模神经网络	✅

与其他库的对比

Pearl 功能	Pearl	ReAgent（已被 Pearl 取代）	RLLib	SB3	天授	多巴胺
智能体模块化	✅	❌	❌	❌	❌	❌
动态动作空间	✅	✅	❌	❌	❌	❌
离线强化学习	✅	✅	✅	✅	✅	❌
智能探索	✅	❌	❌	❌	⚪（有限支持）	❌
上下文 bandit	✅	✅	⚪（仅支持线性模型）	❌	❌	❌
安全决策	✅	❌	❌	❌	❌	❌
历史摘要	✅	❌	✅	❌	⚪（需修改环境状态）	❌
数据增强型回放缓冲区	✅	❌	✅	✅	✅	❌

引用我们

@article{pearl2023paper,
    title = {Pearl: 一款适用于生产环境的强化学习智能体},
    author = {朱哲青、罗德里戈·德·萨尔沃·布拉兹、贾拉吉·班达里、丹尼尔·江、万毅、约纳坦·埃夫罗尼、许睿阳、王丽媛、郭洪波、亚历克斯·尼库尔科夫、德米特罗·科伦凯维奇、乌润·多甘、弗兰克·程、吴铮、徐万乔},
    eprint = {arXiv 预印本 arXiv:2312.03814},
    year = {2023}
}

许可证

Pearl 采用 MIT 许可证，详情请参阅 LICENSE 文件。

Pearl 快速上手指南

Pearl 是由 Meta 应用强化学习团队开源的生产级强化学习智能体库。它专为复杂生产环境设计，支持动态动作空间、离线学习、安全决策及历史状态摘要等高级特性，帮助开发者构建适应稀疏反馈和高随机性环境的 AI 智能体。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS（Windows 用户建议使用 WSL2）。
• Python 版本：推荐 Python 3.8 及以上版本。
• 依赖工具：
  • pip 版本 ≥ 21.3
  • setuptools 版本 ≥ 64
• 前置知识：熟悉 PyTorch 基础及强化学习基本概念（如 Agent, Environment, Replay Buffer）。

提示：国内用户建议在安装 Python 依赖时使用清华或阿里镜像源，以加速下载过程。

安装步骤

通过克隆 GitHub 仓库并以可编辑模式安装是最推荐的安装方式，便于后续开发和调试。

1. 克隆仓库

   git clone https://github.com/facebookresearch/Pearl.git
   cd Pearl
   

2. 执行安装 使用 pip 进行本地安装（国内用户可添加 -i 参数指定镜像源）：

   # 标准安装命令
   pip install -e .
   
   # 国内加速安装示例（使用清华源）
   # pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

以下是一个基于经典 CartPole-v1 环境的快速启动示例，展示了如何初始化环境、构建 DQN 智能体并进行训练循环。

from pearl.pearl_agent import PearlAgent
from pearl.action_representation_modules.one_hot_action_representation_module import (
    OneHotActionTensorRepresentationModule,
)
from pearl.policy_learners.sequential_decision_making.deep_q_learning import (
    DeepQLearning,
)
from pearl.replay_buffers import (
    BasicReplayBuffer,
)
from pearl.utils.instantiations.environments.gym_environment import GymEnvironment

# 1. 初始化环境
env = GymEnvironment("CartPole-v1")

num_actions = env.action_space.n

# 2. 构建 Pearl 智能体
agent = PearlAgent(
    policy_learner=DeepQLearning(
        state_dim=env.observation_space.shape[0],
        action_space=env.action_space,
        hidden_dims=[64, 64],
        training_rounds=20,
        action_representation_module=OneHotActionTensorRepresentationModule(
            max_number_actions=num_actions
        ),
    ),
    replay_buffer=BasicReplayBuffer(10_000),
)

# 3. 重置环境与智能体
observation, action_space = env.reset()
agent.reset(observation, action_space)

done = False
# 4. 运行交互循环
while not done:
    # 选择动作 (exploit=False 表示包含探索)
    action = agent.act(exploit=False)
    
    # 环境步进
    action_result = env.step(action)
    
    # 观察结果并学习
    agent.observe(action_result)
    agent.learn()
    
    done = action_result.done

说明：

• 该示例使用了 DeepQLearning 策略和 BasicReplayBuffer。
• 您可以轻松替换 policy_learner 或 environment 以适应具体的业务场景（如推荐系统、竞价系统等）。
• Pearl 的模块化设计允许您灵活组合不同的组件（如安全约束模块、上下文多臂老虎机算法等）。