Sample Factory

高吞吐量强化学习代码库。版本 2 已发布！🤗

资源：

• 文档： https://samplefactory.dev

• 论文： https://arxiv.org/abs/2006.11751

• 引用： BibTeX

• Discord： https://discord.gg/BCfHWaSMkr

• Twitter（更新）： @petrenko_ai

• 演讲（约 2021 年）： https://youtu.be/lLG17LKKSZc

Sample Factory 是什么？

Sample Factory 是最快的强化学习库之一，专注于高效同步和异步的策略梯度算法实现（PPO）。

Sample Factory 经过全面测试，被众多研究人员和从业者广泛使用。 我们的实现以在多种任务领域中达到最先进（SOTA）性能而闻名，同时最大限度地减少所需的训练时间和硬件需求。 以下视频展示了使用 Sample Factory 训练的 ViZDoom、IsaacGym、DMLab-30、Megaverse、Mujoco 和 Atari 智能体：

主要特性：

• 高度优化的算法架构，实现最大学习吞吐量
• 同步与异步训练模式
• 串行（单进程）模式便于调试
• 在基于 CPU 和 GPU 加速环境中均表现出色
• 支持单智能体与多智能体训练、自我对弈，并可同时在一台或多台 GPU 上训练 多个策略
• 基于群体的训练（PBT）
• 支持离散、连续及混合动作空间
• 支持向量型、图像型和字典型观测空间
• 可自动根据动作/观测空间规范构建模型架构，同时也支持 自定义模型架构
• 库设计为可导入其他项目，自定义环境被视为一等公民
• 提供详细的 WandB 和 TensorBoard 摘要以及 自定义指标
• HuggingFace 🤗 集成（可将训练好的模型和指标上传至 Hub）
• 提供多种 示例 环境 集成 与调优参数和训练好的模型

本 README 仅提供库的简要概述。 更多详细信息请访问完整文档：https://samplefactory.dev。

安装

只需从 PyPI 安装即可：

pip install sample-factory

SF 已知可在 Linux 和 macOS 上运行。目前暂不支持 Windows。 有关特定于环境的安装说明，请参阅 文档。

快速入门

使用命令行通过现有集成之一训练智能体，例如 Mujoco（可能需要先运行 pip install sample-factory[mujoco]）：

python -m sf_examples.mujoco.train_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir

当达到预期性能时，按 Ctrl+C 停止实验，然后评估智能体：

python -m sf_examples.mujoco.enjoy_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir

# 或者使用替代的评估脚本，虽然不进行渲染，但速度更快！（请确保 `sample_env_episodes` 大于等于 `num_workers` * `num_envs_per_worker`）。
python -m sf_examples.mujoco.fast_eval_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir --sample_env_episodes=128 --num_workers=16 --num_envs_per_worker=2

在基于像素的 VizDoom 环境中执行相同的操作（可能需要运行 pip install sample-factory[vizdoom]，请同时参阅 VizDoom 特定说明文档）：

python -m sf_examples.vizdoom.train_vizdoom --env=doom_basic --experiment=DoomBasic --train_dir=./train_dir --num_workers=16 --num_envs_per_worker=10 --train_for_env_steps=1000000
python -m sf_examples.vizdoom.enjoy_vizdoom --env=doom_basic --experiment=DoomBasic --train_dir=./train_dir

使用 TensorBoard 监控任何正在运行或已完成的实验：

tensorboard --logdir=./train_dir

（或参阅文档了解 WandB 集成方法）。

要继续深入，请复制并修改现有的环境集成代码，以在您自定义的环境中训练智能体。我们提供了适用于各种支持环境的示例，请参阅文档获取更多详细信息。

致谢

没有众多人士的杰出贡献，本项目将无法实现。在此特别感谢：

• Vladlen Koltun，尤其是在项目早期阶段，他为我提供了卓越的指导与支持，帮助我巩固了最终形成该库的核心理念。
• 我的学术导师 Gaurav Sukhatme，多年来一直支持我的博士研究，并始终是一位出色的导师。
• Zhehui Huang 对原始 ICML 论文投稿的贡献、对库的严谨测试与评估工作，以及将其应用于自身研究的努力。
• Edward Beeching 对代码库的诸多出色贡献，包括混合动作分布、自定义模型构建器的新版本、多种环境集成，以及通过 HuggingFace 集成推广该库！
• Andrew Zhang 和 Ming Wang 在 HuggingFace 实习期间为代码库和文档做出的大量贡献！
• HuggingFace 的 Thomas Wolf 及其团队提供的难以置信（且出乎意料的）支持，以及他们为开源社区所做的卓越工作。
• Erik Wijmans 提供的反馈与洞见，尤其是他利用 PyTorch 的 PackedSequence 实现 RNN 反向传播、多层 RNN 等功能！
• Tushar Kumar 对原始论文的贡献，以及他在快速队列实现方面的帮助。
• Costa Huang 开发了 CleanRL，致力于强化学习算法的基准测试，并提供了宝贵的反馈与见解！
• Denys Makoviichuk 开发了 rl_games 这一极速强化学习库，为本库的诸多特性（如回报归一化、自适应学习率等）提供了灵感与反馈。
• Eugene Vinitsky 将本库应用于其研究，并提供了宝贵的意见。
• RESL 实验室的所有同事，他们在各自项目中使用了 Sample Factory，并给予了反馈与洞见！

衷心感谢所有未在此提及的各位，感谢你们的代码贡献、PR、问题与疑问！正是有了社区的支持，才成就了这个项目！

引用

如果您在工作中使用了本仓库，或希望引用它，请参考我们的 ICML 2020 论文。

@inproceedings{petrenko2020sf,
  author    = {Aleksei Petrenko and
               Zhehui Huang and
               Tushar Kumar and
               Gaurav S. Sukhatme and
               Vladlen Koltun},
  title     = {Sample Factory: Egocentric 3D Control from Pixels at 100000 {FPS}
               with Asynchronous Reinforcement Learning},
  booktitle = {Proceedings of the 37th International Conference on Machine Learning,
               {ICML} 2020, 13-18 July 2020, Virtual Event},
  series    = {Proceedings of Machine Learning Research},
  volume    = {119},
  pages     = {7652--7662},
  publisher = {{PMLR}},
  year      = {2020},
  url       = {http://proceedings.mlr.press/v119/petrenko20a.html},
  biburl    = {https://dblp.org/rec/conf/icml/PetrenkoHKSK20.bib},
  bibsource = {dblp computer science bibliography, https://dblp.org}
}

如有任何问题、意见或咨询，请加入 Discord 社区。欢迎提交 GitHub 问题和拉取请求！请查看贡献指南。

Sample Factory 快速上手指南

Sample Factory 是一个专注于高吞吐量的强化学习代码库，提供了策略梯度（PPO）的高效同步和异步实现。它以极低的训练时间和硬件需求，在多个领域达到了最先进（SOTA）的性能。

环境准备

• 操作系统：支持 Linux 和 macOS。暂不支持 Windows。
• Python 环境：建议安装 Python 3.7+。
• 前置依赖：确保已安装 pip。根据你要运行的具体环境示例（如 Mujoco 或 VizDoom），可能需要额外的系统级依赖库，请参考官方文档中的环境特定安装说明。

安装步骤

通过 PyPI 直接安装核心库：

pip install sample-factory

提示：如果你计划运行特定的示例环境，建议安装对应的额外依赖。例如：

• Mujoco 示例：pip install sample-factory[mujoco]
• VizDoom 示例：pip install sample-factory[vizdoom]

基本使用

以下以 Mujoco 环境为例，展示如何训练和评估智能体。

1. 训练智能体

运行以下命令开始训练。该示例使用 mujoco_ant 环境，实验命名为 Ant，模型保存在 ./train_dir 目录下。

python -m sf_examples.mujoco.train_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir

当达到预期性能后，按 Ctrl+C 停止训练。

2. 评估智能体

训练完成后，可以使用以下命令可视化评估智能体的表现：

python -m sf_examples.mujoco.enjoy_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir

如果需要更快速的非渲染评估（适用于批量测试），可以使用：

python -m sf_examples.mujoco.fast_eval_mujoco --env=mujoco_ant --experiment=Ant --train_dir=./train_dir --sample_env_episodes=128 --num_workers=16 --num_envs_per_worker=2

3. 监控训练过程

你可以使用 TensorBoard 实时监控训练指标：

tensorboard --logdir=./train_dir

也可以在浏览器中打开 TensorBoard 显示的地址查看损失函数、奖励曲线等详细数据。

---

更多资源：

• 完整文档：https://samplefactory.dev
• 社区交流：Discord