SLM Lab

基于PyTorch的模块化深度强化学习框架。
本书《深度强化学习基础》的配套库。Foundations of Deep Reinforcement Learning。
文档 · 基准测试结果

注意： v5.0 更新了 Gymnasium、uv 工具链以及现代依赖项，并增加了对 ARM 架构的支持——详情请参阅 CHANGELOG.md。

对于本书读者：请使用 git checkout v4.1.1 来获取《深度强化学习基础》中的代码。

BeamRider	Breakout	KungFuMaster	MsPacman
Pong	Qbert	Seaquest	Sp.Invaders
Ant	HalfCheetah	Hopper	Humanoid
Inv.DoublePendulum	InvertedPendulum	Reacher	Walker

SLM Lab 是一个用于 PyTorch 中 强化学习（RL）研究与应用的软件框架。强化学习通过试错来训练智能体做出决策，例如教机器人走路或让 AI 玩游戏。

SLM Lab 提供的功能

功能	描述
开箱即用的算法	PPO、SAC、CrossQ、DQN、A2C、REINFORCE——已在 70 多个环境中验证
简单配置	JSON 规范文件完全定义实验，无需修改代码
可重复性	每次运行都会保存规范和 git SHA，以便精确复现
自动分析	训练曲线、指标和 TensorBoard 日志开箱即用
云集成	dstack 用于 GPU 训练，HuggingFace 用于分享结果

算法

算法	类型	最适合	已验证环境
REINFORCE	在策略	学习/教学	经典
SARSA	在策略	表格式	经典
DQN/DDQN+PER	离策略	离散动作	经典、Box2D、Atari
A2C	在策略	快速迭代	经典、Box2D、Atari
PPO	在策略	通用	经典、Box2D、MuJoCo（11）、Atari（54）
SAC	离策略	连续控制	经典、Box2D、MuJoCo
CrossQ	离策略	高效采样控制	经典、Box2D、MuJoCo

详细性能数据请参阅 Benchmark Results。

环境

SLM Lab 使用 Gymnasium（OpenAI Gym 的维护分支）：

类别	示例	难度	文档
经典控制	CartPole、Pendulum、Acrobot	简单	Gymnasium Classic
Box2D	LunarLander、BipedalWalker	中等	Gymnasium Box2D
MuJoCo	Hopper、HalfCheetah、Humanoid	困难	Gymnasium MuJoCo
Atari	Breakout、MsPacman 等 54 款游戏	不同	ALE

任何兼容 Gymnasium 的环境都可以使用——只需在规范中指定其名称即可。

快速入门

# 安装
uv sync
uv tool install --editable .

# 运行演示（PPO CartPole）
slm-lab run                                    # PPO CartPole
slm-lab run --render                           # 带可视化

# 运行自定义实验
slm-lab run spec.json spec_name train          # 本地训练
slm-lab run-remote spec.json spec_name train   # 云端训练（dstack）

# 帮助（CLI 使用 Typer）
slm-lab --help                                 # 列出所有命令
slm-lab run --help                             # run 命令的选项

# 故障排除：如果找不到 slm-lab，请使用 uv run
uv run slm-lab run

云端训练（dstack）

在云端 GPU 上运行实验，并自动将结果同步到 HuggingFace。

# 设置
cp .env.example .env  # 添加 HF_TOKEN
uv tool install dstack  # 安装 dstack CLI
# 配置 dstack 服务器——详见 https://dstack.ai/docs/quickstart

# 在云端运行
slm-lab run-remote spec.json spec_name train           # CPU 训练（默认）
slm-lab run-remote spec.json spec_name search          # CPU ASHA 搜索（默认）
slm-lab run-remote --gpu spec.json spec_name train     # GPU 训练（适用于图像环境）

# 同步结果
slm-lab pull spec_name    # 从 HuggingFace 下载
slm-lab list              # 列出可用实验

.dstack/ 中的配置选项：run-gpu-train.yml、run-gpu-search.yml、run-cpu-train.yml、run-cpu-search.yml

极简安装（仅编排）

对于仅用于分发 dstack 作业、同步结果和生成图表的轻量级机器（不进行本地机器学习训练）：

uv sync --no-default-groups  # 跳过机器学习依赖（torch、gymnasium 等）
uv tool install dstack
uv run --no-default-groups slm-lab run-remote spec.json spec_name train
uv run --no-default-groups slm-lab pull spec_name
uv run --no-default-groups slm-lab plot -f folder1,folder2

引用

如果您在研究中使用 SLM Lab，请引用以下文献：

@misc{kenggraesser2017slmlab,
    author = {Keng, Wah Loon and Graesser, Laura},
    title = {SLM Lab},
    year = {2017},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/kengz/SLM-Lab}},
}

许可证

MIT

SLM-Lab 快速上手指南

SLM-Lab 是一个基于 PyTorch 的模块化深度强化学习（Deep RL）框架，也是书籍《Foundations of Deep Reinforcement Learning》的配套代码库。它支持 PPO、SAC、DQN 等主流算法，适用于从经典控制到 Atari 游戏等多种环境。

环境准备

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

• 操作系统：Linux, macOS, 或 Windows (WSL2 推荐)。
  • 注：v5.0+ 版本已原生支持 ARM 架构（如 Apple Silicon）。
• Python 版本：建议 Python 3.10 或更高版本。
• 前置工具：
  • uv：SLM-Lab v5.0 推荐使用 uv 进行依赖管理和工具安装（比 pip 更快）。
  • Git：用于克隆代码库。
• 硬件要求：
  • 基础实验：普通 CPU 即可。
  • 复杂环境（如 Atari, MuJoCo）：建议配备 NVIDIA GPU 以加速训练。

提示：国内开发者若遇到 uv 或 PyPI 源下载缓慢，可配置国内镜像加速：

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

SLM-Lab 使用 uv 管理项目依赖和命令行工具。请按以下步骤操作：

1. 克隆仓库

   git clone https://github.com/kengz/SLM-Lab.git
   cd SLM-Lab
   

   注意：如果您是为了配合书籍《Foundations of Deep Reinforcement Learning》学习，请切换到对应版本：

   git checkout v4.1.1
   

2. 同步依赖并安装工具 使用 uv 同步环境并将 slm-lab 命令安装到全局工具链中：

   uv sync
   uv tool install --editable .
   

3. 验证安装 查看帮助信息以确认安装成功：

   slm-lab --help
   

   如果终端提示找不到 slm-lab 命令，请使用 uv run slm-lab --help 运行。

基本使用

SLM-Lab 的核心设计理念是通过 JSON 配置文件定义实验，无需修改代码即可运行不同的算法和环境。

1. 运行默认示例

运行默认的 PPO 算法在 CartPole 环境上进行训练：

slm-lab run

若要实时可视化训练过程（弹出窗口显示游戏画面）：

slm-lab run --render

2. 运行自定义实验

您可以指定自己的配置文件（.json）和实验名称来启动训练：

# 格式：slm-lab run <配置文件> <实验名称> <模式>
slm-lab run spec.json my_experiment train

3. 查看结果

训练完成后，SLM-Lab 会自动生成训练曲线、指标数据，并支持 TensorBoard 查看。结果通常保存在 data/ 目录下。

4. 云端训练（可选）

如果您配置了 dstack 和 HuggingFace Token，可以将任务分发到云端 GPU：

# 需先在 .env 文件中配置 HF_TOKEN
slm-lab run-remote spec.json my_experiment train --gpu

---

更多详细算法基准测试和高级配置，请参阅官方文档或 docs/BENCHMARKS.md。