Documentation | Getting Started | Usage | Contributing | Paper | Join Us

一个针对组合优化（CO）的强化学习（RL）基准测试平台。我们的目标是为基于强化学习的组合优化算法提供统一的框架，并促进该领域的可复现研究，从而将科学研究与工程实现分离。

RL4CO 基于以下技术构建：

• TorchRL：PyTorch 官方提供的用于强化学习算法及 GPU 上向量化环境的框架
• TensorDict：一个用于轻松处理状态、动作和奖励等异构数据的库
• PyTorch Lightning：一个轻量级的 PyTorch 封装，专为高性能 AI 研究设计
• Hydra：一个用于优雅配置复杂应用的框架

我们提供了灵活高效的策略实现，包括：

• 构造型：从零开始学习构建解决方案
  • 自回归（AR）：通过解码器逐步构建解决方案
  • 非自回归（NAR）：学习预测启发式信息，例如热力图，进而构建解决方案
• 改进型：学习如何改进已有的解决方案

我们还提供多种实用工具和模块化设计。例如，我们将可重用组件（如“环境嵌入”）进行模块化，以便轻松替换以解决新问题。

入门

RL4CO 现在可以通过 pip 安装！

pip install rl4co

要开始使用，我们建议您查看我们的快速入门笔记本或下面的极简示例。

从源代码安装

此命令会安装最新的 main 分支版本，适合希望紧跟最新进展的情况——例如，当某个错误已在最新版本中修复，但尚未发布新正式版时：

pip install -U git+https://github.com/ai4co/rl4co.git

本地安装与开发

我们推荐使用速度极快的 uv 包管理器进行本地开发，例如：

git clone https://github.com/ai4co/rl4co && cd rl4co
uv sync --all-extras
source .venv/bin/activate

这将会在 .venv/ 目录下创建一个新的虚拟环境，并安装所有依赖项。

使用方法

使用默认配置训练模型（AM 模型在 TSP 环境上）：

python run.py

[!TIP] 您可以参考这个笔记本，开始使用 Hydra 进行配置！

python run.py experiment=routing/am env=tsp env.num_loc=50 model.optimizer_kwargs.lr=2e-4

python run.py experiment=routing/am logger=none '~callbacks.learning_rate_monitor'

python run.py -m experiment=routing/am  model.optimizer.lr=1e-3,1e-4,1e-5

极简示例

以下是一个极简示例，仅用不到 30 行代码即可在 TSP 问题上训练带有贪婪回放基线的注意力模型：

from rl4co.envs.routing import TSPEnv, TSPGenerator
from rl4co.models import AttentionModelPolicy, POMO
from rl4co.utils import RL4COTrainer

# 实例化生成器和环境
generator = TSPGenerator(num_loc=50, loc_distribution="uniform")
env = TSPEnv(generator)

# 创建策略和强化学习模型
policy = AttentionModelPolicy(env_name=env.name, num_encoder_layers=6)
model = POMO(env, policy, batch_size=64, optimizer_kwargs={"lr": 1e-4})

# 实例化训练器并进行训练
trainer = RL4COTrainer(max_epochs=10, accelerator="gpu", precision="16-mixed")
trainer.fit(model)

更多示例请参阅我们的文档！

测试

在根目录下使用 pytest 运行测试：

pytest tests

已知问题

您可以查看问题和讨论。我们也会定期在常见问题解答部分发布更新。

贡献

您有建议、需求，或者发现了 bug？欢迎随时提交 issue或拉取请求。如果您希望参与贡献，请查看我们的贡献指南这里。我们欢迎并期待所有对 RL4CO 的贡献！

如果您有任何问题，或想与我们讨论 RL4CO，也欢迎加入我们的Slack 社区。我们非常乐意与大家合作，并期待您的来信 🚀

贡献者

引用

如果您认为 RL4CO 对您的研究或应用项目有价值：

@inproceedings{berto2025rl4co,
    title={{RL4CO: an Extensive Reinforcement Learning for Combinatorial Optimization Benchmark}},
    author={Federico Berto and Chuanbo Hua and Junyoung Park and Laurin Luttmann and Yining Ma and Fanchen Bu and Jiarui Wang and Haoran Ye and Minsu Kim and Sanghyeok Choi and Nayeli Gast Zepeda and Andr\'e Hottung and Jianan Zhou and Jieyi Bi and Yu Hu and Fei Liu and Hyeonah Kim and Jiwoo Son and Haeyeon Kim and Davide Angioni and Wouter Kool and Zhiguang Cao and Jie Zhang and Kijung Shin and Cathy Wu and Sungsoo Ahn and Guojie Song and Changhyun Kwon and Lin Xie and Jinkyoo Park},
    booktitle={Proceedings of the 31st ACM SIGKDD Conference on Knowledge Discovery and Data Mining},
    year={2025},
    url={https://github.com/ai4co/rl4co}
}

请注意，RL4CO 的早期版本也曾被接受为口头报告，发表于 NeurIPS 2023 GLFrontiers Workshop。自那时以来，该库已经得到了极大的发展和改进！

加入我们

我们诚挚邀请您加入 AI4CO 社区——一个专注于组合优化（CO）的人工智能（AI）开放研究小组！

RL4CO 快速上手指南

RL4CO 是一个基于 PyTorch 的组合优化（CO）强化学习（RL）基准框架。它旨在提供统一的算法实现，解耦科学研究与工程实现，支持构建式（Constructive）和改进式（Improvement）策略。

环境准备

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

• 操作系统: Linux, macOS, 或 Windows (推荐 Linux)
• Python: 3.8 或更高版本
• PyTorch: 已安装且版本兼容（建议参考 PyTorch 官网 安装）
• GPU (可选但推荐): 用于加速训练，需安装对应的 CUDA 版本

前置依赖库（通常随主包自动安装，也可手动预装）：

• torchrl (PyTorch RL 框架)
• tensordict (异构数据处理)
• pytorch-lightning (高性能训练封装)
• hydra-core (配置管理)

国内加速提示：如果下载依赖较慢，建议使用国内镜像源（如清华源、阿里源）。

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

安装步骤

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

直接安装最新稳定版：

pip install rl4co

如果需要安装包含最新修复但未发布版本的代码（bleeding edge）：

pip install -U git+https://github.com/ai4co/rl4co.git

方式二：源码安装（适合开发者）

推荐使用 uv 进行快速的本地开发和依赖管理：

git clone https://github.com/ai4co/rl4co && cd rl4co
uv sync --all-extras
source .venv/bin/activate

基本使用

1. 最小化代码示例

以下示例展示了如何在不到 30 行代码内，使用注意力模型（Attention Model）和 POMO 策略在 TSP（旅行商问题）上进行训练：

from rl4co.envs.routing import TSPEnv, TSPGenerator
from rl4co.models import AttentionModelPolicy, POMO
from rl4co.utils import RL4COTrainer

# 实例化生成器和环境
generator = TSPGenerator(num_loc=50, loc_distribution="uniform")
env = TSPEnv(generator)

# 创建策略和 RL 模型
policy = AttentionModelPolicy(env_name=env.name, num_encoder_layers=6)
model = POMO(env, policy, batch_size=64, optimizer_kwargs={"lr": 1e-4})

# 实例化 Trainer 并开始训练
trainer = RL4COTrainer(max_epochs=10, accelerator="gpu", precision="16-mixed")
trainer.fit(model)

2. 命令行运行

RL4CO 内置了基于 Hydra 的配置系统，可直接通过命令行启动训练。

使用默认配置训练 (默认为 TSP 环境上的 AM 模型)：

python run.py

自定义实验配置： 可以通过命令行参数修改环境、模型超参数等。例如，将城市数量设为 50，学习率设为 2e-4：

python run.py experiment=routing/am env=tsp env.num_loc=50 model.optimizer_kwargs.lr=2e-4

超参数扫描 (Multirun)： 使用 -m 标志对多个超参数组合进行并行实验：

python run.py -m experiment=routing/am  model.optimizer.lr=1e-3,1e-4,1e-5

禁用日志：

python run.py experiment=routing/am logger=none '~callbacks.learning_rate_monitor'

更多高级用法和 Notebook 示例请参考官方文档或项目中的 examples 目录。