仿生学习基准实现

本项目旨在提供清晰的仿生学习和奖励学习算法实现。目前，我们已实现了以下算法。“离散”和“连续”分别表示该算法是否支持离散或连续的动作/状态空间。

算法（+ 论文链接）	API 文档	离散	连续
行为克隆	algorithms.bc	✅	✅
DAgger	algorithms.dagger	✅	✅
基于密度的奖励建模	algorithms.density	✅	✅
最大因果熵逆强化学习	algorithms.mce_irl	✅	❌
对抗式逆强化学习	algoritms.airl	✅	✅
生成对抗仿生学习	algorithms.gail	✅	✅
基于人类偏好的深度强化学习	algorithms.preference_comparisons	✅	✅
软Q仿生学习	algorithms.sqil	✅	❌

您可以在此处找到文档。

您还可以阅读最新的基准测试结果这里。

安装

先决条件

• Python 3.8+
• （可选）OpenGL（用于渲染 Gymnasium 环境）
• （可选）FFmpeg（用于编码渲染视频）

注意：imitation仅兼容较新的gymnasium环境API，不支持旧版gymAPI。

安装 PyPI 发布版本

安装 PyPI 发布版本是使用 imitation 的标准方式，也是大多数用户的推荐方式。

pip install imitation

从源代码安装

如果您愿意，可以从源代码安装 imitation，以便参与项目贡献，或者在稳定版本发布前抢先体验最新功能。您可以通过克隆 GitHub 仓库并直接运行安装程序来完成此操作。首先执行： git clone http://github.com/HumanCompatibleAI/imitation && cd imitation。

对于开发模式，请运行：

pip install -e ".[dev]"

这将以开发模式运行 setup.py，并安装开发所需的额外依赖项。对于常规使用，则应运行：

pip install .

根据您的需求，还可选择其他附加包。例如，tests用于运行测试套件，docs用于构建文档，parallel用于并行化训练，而atari则用于包含 Atari 环境。dev附加包会自动安装 tests、docs 和 atari 的依赖项，且 tests 也会自动安装 atari 的依赖项。

对于 macOS 用户，运行实验需要一些软件包（详情请参阅 ./experiments/README.md）。首先，如果尚未安装 Homebrew，请先安装（参见 Homebrew）。然后运行：

brew install coreutils gnu-getopt parallel

CLI 快速入门

我们提供了若干 CLI 脚本，作为 imitation 中所实现算法的前端接口。这些脚本使用Sacred进行配置和可重复性管理。

来自 examples/quickstart.sh:

# 在摆杆环境中训练 PPO 智能体，并收集专家演示数据。TensorBoard 日志将保存在 quickstart/rl/ 目录下。
python -m imitation.scripts.train_rl with pendulum environment.fast policy_evaluation.fast rl.fast fast logging.log_dir=quickstart/rl/

# 从演示数据中训练 GAIL。TensorBoard 日志将保存在 output/ 目录中（默认日志目录）。
python -m imitation.scripts.train_adversarial gail with pendulum environment.fast demonstrations.fast policy_evaluation.fast rl.fast fast demonstrations.path=quickstart/rl/rollouts/final.npz demonstrations.source=local

# 从示范数据中训练 AIRL。TensorBoard 日志保存在 output/ 目录中（默认日志目录）。
python -m imitation.scripts.train_adversarial airl with pendulum environment.fast demonstrations.fast policy_evaluation.fast rl.fast fast demonstrations.path=quickstart/rl/rollouts/final.npz demonstrations.source=local

提示：

• 可以移除上述命令中的“fast”选项，以便让训练完整运行。
• python -m imitation.scripts.train_rl print_config 将列出 Sacred 脚本的选项。这些配置选项已在每个脚本的文档字符串中说明。

有关如何配置 Sacred CLI 选项的更多信息，请参阅 Sacred 文档。

Python 接口快速入门

请参阅 examples/quickstart.py，其中包含一个示例脚本，用于加载 CartPole-v1 的示范数据，并基于该数据训练 BC、GAIL 和 AIRL 模型。

密度奖励基线

我们还实现了一个基于密度的奖励基线。您可以在 此处找到示例笔记本。

引用（BibTeX）

@misc{gleave2022imitation,
  author = {Gleave, Adam and Taufeeque, Mohammad and Rocamonde, Juan and Jenner, Erik and Wang, Steven H. and Toyer, Sam and Ernestus, Maximilian and Belrose, Nora and Emmons, Scott and Russell, Stuart},
  title = {imitation: 清洁的模仿学习实现},
  year = {2022},
  howPublished = {arXiv:2211.11972v1 [cs.LG]},
  archivePrefix = {arXiv},
  eprint = {2211.11972},
  primaryClass = {cs.LG},
  url = {https://arxiv.org/abs/2211.11972},
}

贡献

有关更多信息，请参阅 贡献 imitation。

Imitation 快速上手指南

imitation 是一个提供模仿学习（Imitation Learning）和奖励学习（Reward Learning）算法干净实现的开源项目，支持行为克隆、GAIL、AIRL 等主流算法。

环境准备

在开始之前，请确保满足以下系统要求：

• Python 版本：3.8 或更高版本
• 图形渲染（可选）：如需渲染 Gymnasium 环境，需安装 OpenGL
• 视频录制（可选）：如需录制渲染视频，需安装 FFmpeg
• 重要提示：本库仅兼容新版 gymnasium 环境 API，不支持旧版 gym API。

国内用户加速建议： 建议使用国内镜像源安装依赖，以提升下载速度。例如使用清华源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

方式一：通过 PyPI 安装（推荐）

这是大多数用户的标准安装方式：

pip install imitation

国内加速命令：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple imitation

方式二：从源码安装

如果您需要贡献代码或使用尚未发布的最新功能，可以从 GitHub 克隆源码安装。

1. 克隆仓库：

git clone http://github.com/HumanCompatibleAI/imitation && cd imitation

2. 开发模式安装（包含测试、文档等额外依赖）：

pip install -e ".[dev]"

3. 或者仅进行常规使用安装：

pip install .

macOS 用户额外步骤： 运行实验前需通过 Homebrew 安装部分工具：

brew install coreutils gnu-getopt parallel

基本使用

imitation 提供了命令行（CLI）和 Python 接口两种使用方式。

1. 命令行快速开始 (CLI)

项目内置了基于 Sacred 的脚本，用于配置和复现实验。以下示例展示了如何训练 PPO 专家策略，并基于该数据训练 GAIL 和 AIRL 模型。

注意：示例中的 fast 参数用于快速测试（减少训练步数）。正式训练时请移除所有 fast 选项。

步骤 1：训练 PPO 代理并收集专家演示

python -m imitation.scripts.train_rl with pendulum environment.fast policy_evaluation.fast rl.fast fast logging.log_dir=quickstart/rl/

步骤 2：基于演示训练 GAIL 模型

python -m imitation.scripts.train_adversarial gail with pendulum environment.fast demonstrations.fast policy_evaluation.fast rl.fast fast demonstrations.path=quickstart/rl/rollouts/final.npz demonstrations.source=local

步骤 3：基于演示训练 AIRL 模型

python -m imitation.scripts.train_adversarial airl with pendulum environment.fast demonstrations.fast policy_evaluation.fast rl.fast fast demonstrations.path=quickstart/rl/rollouts/final.npz demonstrations.source=local

• 查看可用配置选项：python -m imitation.scripts.train_rl print_config
• TensorBoard 日志默认保存在 output/ 目录（除非像步骤 1 那样指定了其他路径）。

2. Python 接口快速开始

您可以直接在 Python 代码中调用算法。以下逻辑展示了如何加载 CartPole 环境的演示数据并训练模型（完整代码请参考 examples/quickstart.py）：

import gymnasium as gym
from imitation.algorithms import bc, gail, airl
from imitation.data import rollout
from imitation.util import util

# 1. 创建环境
env = gym.make("CartPole-v1")

# 2. 加载专家演示数据 (此处仅为示意，实际需加载 npz 文件)
# rng = np.random.default_rng(0)
# expert_policy = ... 
# rolls = rollout.generate_expert_trajectories(...)

# 3. 训练行为克隆 (Behavioral Cloning)
bc_trainer = bc.BC(
    observation_space=env.observation_space,
    action_space=env.action_space,
    demonstrations=rolls, 
)
bc_trainer.train()

# 4. 训练 GAIL 或 AIRL (需要传入演示数据和环境)
# gail_trainer = gail.GAIL(...)
# gail_trainer.train()

对于密度奖励基线（Density-Based Reward），可参考官方提供的 Jupyter Notebook 教程：docs/tutorials/7_train_density.ipynb。