SCOPE-RL: 用于离线强化学习、离线策略评估和选择的Python库

文档可在此处获取

稳定版本可在PyPI获取

幻灯片可在此处获取

日本语版本请点击这里

概述

SCOPE-RL是一个开源Python软件，用于实现**离线强化学习（offline RL）**的端到端流程，包括数据收集、离线策略学习、离线策略性能评估和策略选择。我们的软件包含一系列模块，用于实现合成数据集生成、数据集预处理、离线策略评估（OPE）估计器和离线策略选择（OPS）方法。

该软件还与d3rlpy兼容，后者实现了一系列在线和离线RL方法。SCOPE-RL可以在任何具有OpenAI Gym和Gymnasium类接口的环境中进行简单、透明和可靠的离线RL研究实验。它还有助于在各种自定义数据集和真实世界数据集上实现离线RL。

特别是，SCOPE-RL能够促进和便利与以下研究主题相关的评估和算法比较：

• 离线强化学习：离线RL旨在仅使用由行为策略收集的离线日志数据来学习新策略。SCOPE-RL支持使用由各种行为策略和环境收集的自定义数据集进行灵活的实验。

• 离线策略评估：OPE旨在仅使用离线日志数据评估反事实策略的性能。SCOPE-RL支持许多OPE估计器，并简化了评估和比较OPE估计器的实验流程。此外，我们还实现了高级OPE方法，如基于状态-动作密度估计和累积分布估计的估计器。

• 离线策略选择：OPS旨在使用离线日志数据从多个候选策略池中识别表现最佳的策略。SCOPE-RL支持一些基本的OPS方法，并提供几个指标来评估OPS的准确性。

这个软件的灵感来自Open Bandit Pipeline，后者是一个用于上下文赌臂问题中OPE的库。然而，SCOPE-RL还实现了一套OPE估计器和工具，以便于进行上下文赌臂设置的OPE实验，以及RL的OPE实验。

实现

SCOPE-RL主要由以下三个模块组成。

• dataset模块：该模块提供工具，用于在OpenAI Gym和Gymnasium类接口之上从任何环境生成合成数据。它还提供工具来预处理日志数据。
• policy模块：该模块为d3rlpy提供一个包装器类，以实现灵活的数据收集。
• ope模块：该模块提供一个通用抽象类来实现OPE估计器。它还提供一些有用的工具来执行OPS。

请注意，除了上述OPE和OPS方法外，研究人员还可以通过SCOPE-RL中实现的通用抽象类轻松实现和比较自己的估计器。此外，从业者可以将上述方法应用于他们的实际数据，以评估和选择适合自身实际情况的反事实策略。

SCOPE-RL的OPE/OPS模块的显著特点总结如下。

为了提供模拟实际设置的自定义实验示例，我们还提供了RTBGym和RecGym，这是用于实时竞价（RTB）和推荐系统的RL环境。

安装

你可以使用Python的包管理器pip来安装SCOPE-RL。

pip install scope-rl

你也可以从源代码安装SCOPE-RL。

git clone https://github.com/hakuhodo-technologies/scope-rl
cd scope-rl
python setup.py install

SCOPE-RL支持Python 3.9或更新版本。有关其他要求，请参阅requirements.txt。当遇到一些依赖冲突时，请同时参考问题#17。

使用方法

这里，我们提供了一个示例工作流程，展示如何使用SCOPE-RL在RTBGym上执行离线RL、OPE和OPS。

合成数据集生成和数据预处理

让我们从生成一些用于执行离线RL的合成日志数据开始。

# 在RTBGym环境中实现数据收集程序

# 导入SCOPE-RL模块
from scope_rl.dataset import SyntheticDataset
from scope_rl.policy import EpsilonGreedyHead
# 导入d3rlpy算法
from d3rlpy.algos import DoubleDQNConfig
from d3rlpy.dataset import create_fifo_replay_buffer
from d3rlpy.algos import ConstantEpsilonGreedy
# 导入rtbgym和gym
import rtbgym
import gym
import torch
# 随机状态
random_state = 12345
device = "cuda:0" if torch.cuda.is_available() else "cpu"

# (0) 设置环境
env = gym.make("RTBEnv-discrete-v0")

# (1) 在在线环境中学习基准策略（使用d3rlpy）
# 初始化算法
ddqn = DoubleDQNConfig().create(device=device)
# 训练在线策略
# 这大约需要5分钟计算时间
ddqn.fit_online(
    env,
    buffer=create_fifo_replay_buffer(limit=10000, env=env),
    explorer=ConstantEpsilonGreedy(epsilon=0.3),
    n_steps=100000,
    n_steps_per_epoch=1000,
    update_start_step=1000,
)

# (2) 生成日志数据集
# 将ddqn策略转换为随机行为策略
behavior_policy = EpsilonGreedyHead(
    ddqn,
    n_actions=env.action_space.n,
    epsilon=0.3,
    name="ddqn_epsilon_0.3",
    random_state=random_state,
)
# 初始化数据集类
dataset = SyntheticDataset(
    env=env,
    max_episode_steps=env.step_per_episode,
)
# 行为策略收集一些日志数据
train_logged_dataset = dataset.obtain_episodes(
  behavior_policies=behavior_policy,
  n_trajectories=10000,
  random_state=random_state,
)
test_logged_dataset = dataset.obtain_episodes(
  behavior_policies=behavior_policy,
  n_trajectories=10000,
  random_state=random_state + 1,
)

离线强化学习

现在我们准备使用d3rlpy从日志数据中学习新的策略（评估策略）。

# 使用SCOPE-RL和d3rlpy实现离线RL程序

# 导入d3rlpy算法
from d3rlpy.dataset import MDPDataset
from d3rlpy.algos import DiscreteCQLConfig

# (3) 从离线日志数据中学习新策略（使用d3rlpy）
# 将日志数据集转换为d3rlpy的数据集格式
offlinerl_dataset = MDPDataset(
    observations=train_logged_dataset["state"],
    actions=train_logged_dataset["action"],
    rewards=train_logged_dataset["reward"],
    terminals=train_logged_dataset["done"],
)
# 初始化算法
cql = DiscreteCQLConfig().create(device=device)
# 训练离线策略
cql.fit(
    offlinerl_dataset,
    n_steps=10000,
)

基本离线策略评估

然后，我们使用行为策略收集的离线日志数据来评估几种评估策略（ddqn、cql和随机）的性能。具体来说，我们比较了各种OPE估计器的估计结果，包括直接方法（DM）、轨迹重要性采样（TIS）、每步重要性采样（PDIS）和双重稳健（DR）。

# 使用SCOPE-RL实现基本的OPE程序

# 导入SCOPE-RL模块
from scope_rl.ope import CreateOPEInput
from scope_rl.ope import OffPolicyEvaluation as OPE
from scope_rl.ope.discrete import DirectMethod as DM
from scope_rl.ope.discrete import TrajectoryWiseImportanceSampling as TIS
from scope_rl.ope.discrete import PerDecisionImportanceSampling as PDIS
from scope_rl.ope.discrete import DoublyRobust as DR
# (4) 以离线方式评估学习到的策略
# 我们比较 ddqn、cql 和随机策略
cql_ = EpsilonGreedyHead(
    base_policy=cql,
    n_actions=env.action_space.n,
    name="cql",
    epsilon=0.0,
    random_state=random_state,
)
ddqn_ = EpsilonGreedyHead(
    base_policy=ddqn,
    n_actions=env.action_space.n,
    name="ddqn",
    epsilon=0.0,
    random_state=random_state,
)
random_ = EpsilonGreedyHead(
    base_policy=ddqn,
    n_actions=env.action_space.n,
    name="random",
    epsilon=1.0,
    random_state=random_state,
)
evaluation_policies = [cql_, ddqn_, random_]
# 创建 OPE 类的输入
prep = CreateOPEInput(
    env=env,
)
input_dict = prep.obtain_whole_inputs(
    logged_dataset=test_logged_dataset,
    evaluation_policies=evaluation_policies,
    require_value_prediction=True,
    n_trajectories_on_policy_evaluation=100,
    random_state=random_state,
)
# 初始化 OPE 类
ope = OPE(
    logged_dataset=test_logged_dataset,
    ope_estimators=[DM(), TIS(), PDIS(), DR()],
)
# 执行 OPE 并可视化结果
ope.visualize_off_policy_estimates(
    input_dict,
    random_state=random_state,
    sharey=True,
)

更正式的 RTBGym 示例实现可在 ./examples/quickstart/rtb/ 找到。RecGym 的示例也可在 ./examples/quickstart/rec/ 找到。

高级离线策略评估

除了预期性能外，我们还可以估计评估策略的各种统计数据，包括方差和条件风险值（CVaR），这是通过估计评估策略下奖励的累积分布函数（CDF）来实现的。

# 使用 SCOPE-RL 实现累积分布估计程序

# 导入 SCOPE-RL 模块
from scope_rl.ope import CumulativeDistributionOPE
from scope_rl.ope.discrete import CumulativeDistributionDM as CD_DM
from scope_rl.ope.discrete import CumulativeDistributionTIS as CD_IS
from scope_rl.ope.discrete import CumulativeDistributionTDR as CD_DR
from scope_rl.ope.discrete import CumulativeDistributionSNTIS as CD_SNIS
from scope_rl.ope.discrete import CumulativeDistributionSNTDR as CD_SNDR

# (4) 以离线方式评估评估策略下奖励的累积分布函数
# 我们比较上一节（即基本 OPE 程序的第(3)部分）中定义的 ddqn、cql 和随机策略
# 初始化 OPE 类
cd_ope = CumulativeDistributionOPE(
    logged_dataset=test_logged_dataset,
    ope_estimators=[
      CD_DM(estimator_name="cd_dm"),
      CD_IS(estimator_name="cd_is"),
      CD_DR(estimator_name="cd_dr"),
      CD_SNIS(estimator_name="cd_snis"),
      CD_SNDR(estimator_name="cd_sndr"),
    ],
)
# 估计方差
variance_dict = cd_ope.estimate_variance(input_dict)
# 估计 CVaR
cvar_dict = cd_ope.estimate_conditional_value_at_risk(input_dict, alphas=0.3)
# 估计并可视化策略性能的累积分布函数
cd_ope.visualize_cumulative_distribution_function(input_dict, n_cols=4)

更多详细示例，请参考 quickstart/rtb/rtb_synthetic_discrete_advanced.ipynb。

离线策略选择和 OPE/OPS 评估

我们还可以基于 OPE 结果，使用 OPS 类从一组候选策略中选择表现最佳的策略。同时，还可以使用各种指标（如均方误差、排序相关性、遗憾和 I 类及 II 类错误率）来评估 OPE/OPS 的可靠性。

# 基于 OPE 结果进行离线策略选择

# 导入 SCOPE-RL 模块
from scope_rl.ope import OffPolicySelection

# (5) 进行离线策略选择
# 初始化 OPS 类
ops = OffPolicySelection(
    ope=ope,
    cumulative_distribution_ope=cd_ope,
)
# 根据（基本）OPE 估计的策略值对候选策略进行排序
ranking_dict = ops.select_by_policy_value(input_dict)
# 根据累积分布 OPE 估计的策略值对候选策略进行排序
ranking_dict_ = ops.select_by_policy_value_via_cumulative_distribution_ope(input_dict)
# 可视化前 k 个部署结果
ops.visualize_topk_policy_value_selected_by_standard_ope(
    input_dict=input_dict,
    compared_estimators=["dm", "tis", "pdis", "dr"],
    relative_safety_criteria=1.0,
)

# (6) 评估 OPS/OPE 结果
# 根据估计的下四分位数对候选策略进行排序并评估选择结果
ranking_df, metric_df = ops.select_by_lower_quartile(
    input_dict,
    alpha=0.3,
    return_metrics=True,
    return_by_dataframe=True,
)
# 使用真实指标可视化 OPS 结果
ops.visualize_conditional_value_at_risk_for_validation(
    input_dict,
    alpha=0.3,
    share_axes=True,
)

更多示例，请参考 quickstart/rtb/rtb_synthetic_discrete_advanced.ipynb 了解离散动作，以及 quickstart/rtb/rtb_synthetic_continuous_advanced.ipynb 了解连续动作。

引用

如果您在工作中使用了我们的软件，请引用我们的论文：

Haruka Kiyohara, Ren Kishimoto, Kosuke Kawakami, Ken Kobayashi, Kazuhide Nakata, Yuta Saito.
SCOPE-RL: A Python Library for Offline Reinforcement Learning and Off-Policy Evaluation
[arXiv] [幻灯片] Bibtex:

@article{kiyohara2023scope,
  author = {Kiyohara, Haruka and Kishimoto, Ren and Kawakami, Kosuke and Kobayashi, Ken and Nataka, Kazuhide and Saito, Yuta},
  title = {SCOPE-RL: 一个用于离线强化学习和离线策略评估的Python库},
  journal={arXiv preprint arXiv:2311.18206},
  year={2023},
}

如果您在研究中使用了我们提出的"SharpeRatio@k"指标，请引用我们的论文：

Haruka Kiyohara, Ren Kishimoto, Kosuke Kawakami, Ken Kobayashi, Kazuhide Nakata, Yuta Saito.
评估和基准测试离线策略评估的风险收益权衡
[arXiv] [幻灯片]

Bibtex:

@article{kiyohara2023towards,
  author = {Kiyohara, Haruka and Kishimoto, Ren and Kawakami, Kosuke and Kobayashi, Ken and Nataka, Kazuhide and Saito, Yuta},
  title = {评估和基准测试离线策略评估的风险收益权衡},
  journal={arXiv preprint arXiv:2311.18207},
  year={2023},
}

Google群组

如果您对SCOPE-RL感兴趣，请通过以下Google群组关注其更新： https://groups.google.com/g/scope-rl

贡献

我们非常欢迎对SCOPE-RL的任何贡献！ 请参阅CONTRIBUTING.md了解如何为项目做出贡献的一般指南。

许可证

本项目采用Apache 2.0许可证 - 详情请见LICENSE文件。

项目团队

• Haruka Kiyohara（主要贡献者；康奈尔大学）
• Ren Kishimoto（东京工业大学）
• Kosuke Kawakami（株式会社博报堂科技）
• Ken Kobayashi（东京工业大学）
• Kazuhide Nakata（东京工业大学）
• Yuta Saito（康奈尔大学）

联系方式

如果您对论文和软件有任何疑问，请随时联系：hk844@cornell.edu

参考文献