Ray RLlib 架构入门指导
面向：想快速理解 RLlib 在做什么、核心组件如何协作、如何跑通第一条分布式 RL 训练链路的读者。
依据：RLlib Key Concepts、Scaling Guide、New API Stack（Ray 2.4x+ 默认启用）。
1. 一句话理解 RLlib
RLlib是构建在 Ray 上的可扩展强化学习库。
它解决的核心问题是：
RL 训练天然包含「采样」与「学习」两件可并行的事；单机循环写起来简单，但要扩到多核 / 多机 / 多 GPU 时，环境交互、模型前向、损失与梯度更新会缠在一起。
RLlib 的答案是：Algorithm 做运行时编排，把采样交给EnvRunner，把更新交给Learner，中间用统一的Episode数据与RLModule神经网络抽象解耦。
2. 为什么需要这套架构
2.1 RL 训练的两段活
| 阶段 | 含义 | 例子 |
|---|---|---|
| 采样（Sample） | 在环境里按策略行动，攒轨迹 | CartPole 上跑若干 episode |
| 学习（Learn） | 用轨迹算损失、反传、更新网络 | PPO clip loss + value loss |
小规模时可以「一个进程里 for-loop 又采样又更新」。
规模上来后出现三条扩缩轴（见后文 §7）：
- 更多EnvRunner并行采环境
- 每个 EnvRunner 上更多向量化子环境
- 更多Learner（DDP）并行算梯度
2.2 总览直觉图
┌──────────────────────────────────────────────┐ │ Algorithm + AlgorithmConfig │ ← 实验运行时 / 配置入口 │ (algo.train() 主循环) │ └───────────────┬──────────────────┬───────────┘ │ │ ┌──────────▼──────────┐ ┌────▼───────────────┐ │ EnvRunnerGroup │ │ LearnerGroup │ │ n × EnvRunner │ │ m × Learner │ │ (采样 / 推理) │ │ (损失 / 梯度 / 优化)│ └──────────┬──────────┘ └────┬───────────────┘ │ Episode 列表 │ 更新后的权重 └────────┬─────────┘ │ sync weights（inference_only） ▼ EnvRunner 上的 RLModule 副本记住三句话即可入门：
- 配置用 AlgorithmConfig，运行用 Algorithm。
- EnvRunner 采 Episode，Learner 吃 Episode 做更新。
- RLModule 是网络本体；采样侧常是轻量
inference_only副本，学习侧是完整训练副本。
3. 核心概念速查
| 概念 | 是什么 | 入门只需知道 |
|---|---|---|
| AlgorithmConfig | 类型安全的配置构建器 | PPOConfig().environment(...).training(...).build() |
| Algorithm | 一次实验的运行时 | algo.train()跑一轮；也可交给 Ray Tune |
| EnvRunner | 环境 + 策略交互的 Actor | 产出SingleAgentEpisode/MultiAgentEpisode列表 |
| EnvRunnerGroup | 一组 EnvRunner 的管理器 | 含 1 个 local +n个 remote；故障可恢复 |
| RLModule | 框架相关的神经网络封装 | 三个前向：forward_exploration/forward_inference/forward_train |
| MultiRLModule | 多子模块字典 | 多智能体 / 多网络时用，按ModuleID索引 |
| Episode | 统一轨迹容器 | 存 obs / actions / rewards / infos / 模型附加输出 |
| Learner | 损失 + 优化器 + 更新逻辑 | 算法相关（PPO Learner ≠ DQN Learner） |
| LearnerGroup | 一组 Learner | 自动做数据并行（DDP） |
| ConnectorV2 | 可插拔数据变换管道 | env→module、module→env、Learner 三条管线 |
新 API 栈（默认开启）：用
RLModule/Learner/EnvRunner/Episode/ConnectorV2取代旧栈的Policy/ModelV2/RolloutWorker/SampleBatch等。除非维护旧代码，入门请直接学新栈。
4. 仓库 / 模块地图（先认路）
逻辑上可按这条路径读代码与文档：
ray.rllib/ algorithms/ # PPO、DQN、SAC、APPO、IMPALA… algorithm.py # Algorithm 基类：train / checkpoint / eval algorithm_config.py # AlgorithmConfig 链式 API env/ env_runner.py # EnvRunner 抽象 single_agent_env_runner.py multi_agent_env_runner.py single_agent_episode.py multi_agent_episode.py core/ rl_module/ # RLModule / MultiRLModule / Spec learner/ # Learner / LearnerGroup connectors/ # ConnectorV2 管道 offline/ # OfflineData（离线 RL，基于 Ray Data）官方文档入口：Key Concepts。
5. 用「像单机一样」的代码读懂架构
5.1 最小可运行示例
fromray.rllib.algorithms.ppoimportPPOConfig config=(PPOConfig().environment("CartPole-v1").env_runners(num_env_runners=2).training(train_batch_size_per_learner=2000,lr=0.0004,))algo=config.build()print(algo.train())# 一轮：采样 → 更新 → 同步权重algo.stop()5.2 一轮train()里实际发生了什么
对PPO这类 on-policy 算法，逻辑近似：
1. EnvRunnerGroup 并行 sample → 得到若干 Episode（或片段） 2. 凑够 train_batch_size_per_learner，交给 LearnerGroup.update(...) 3. Learner：Connector 把 Episode → train batch → forward_train → loss → 反传 → optimizer.step 4. Algorithm 从 Learner 取 inference_only 权重，sync 回所有 EnvRunner 5. 返回 metrics（回报、loss、吞吐等）读这段时请对照：
sample：环境交互 +forward_exploration（训练采样时常带探索）。update：真正的分布式学习步。sync weights：保证下一轮采样用的是最新策略。- 评估可用单独的
eval_env_runner_group，走forward_inference（更贪心 / 少随机）。
这就是 RLlib 的可编程性：换算法 ≈ 换 Algorithm/Learner 的采样-更新编排与损失，而 EnvRunner / Episode / 扩缩机制可复用。
6. 一次完整上手链路（从安装到跑通）
推荐顺序：
- 环境：安装匹配版本的
ray[rllib]、PyTorch、gymnasium（按 Installation）。 - 先单机小环境：
CartPole-v1/Pendulum-v1，确认algo.train()有回报上升趋势。 - 调扩缩：先加
num_env_runners，再试num_envs_per_env_runner；有 GPU 再设learners(num_learners=..., num_gpus_per_learner=1)。 - 换环境：自定义
gymnasium.Env，用.environment(env=YourEnv, env_config={...})。 - 观察指标：
episode_return_mean、采样步数、learner loss、耗时。 - 可选 Tune：用
tune.Tuner("PPO", param_space=config, ...)做停条件与超参搜索。
6.1 入门必懂的几个配置旋钮
| 配置项 | 含义 |
|---|---|
environment(...) | 环境 ID 或类、env_config |
env_runners(num_env_runners=n) | 远程采样 Actor 数；0= 只用 local |
env_runners(num_envs_per_env_runner=p) | 每个 Actor 上的向量环境数 |
learners(num_learners=m) | 远程 Learner 数；0= local Learner |
learners(num_gpus_per_learner=1) | 每个 Learner 占几张 GPU（可为小数） |
training(train_batch_size_per_learner=...) | 每个 Learner 一轮更新的 batch 规模 |
training(lr=..., gamma=...) | 学习率、折扣等通用训练项 |
rl_module(model_config=...) | 默认网络宽度/深度等（新栈不用旧model={...}） |
7. 三条扩缩轴（入门版）
吞吐 ≈ f( num_env_runners , num_envs_per_env_runner , num_learners )| 轴 | 配置 | 典型用途 |
|---|---|---|
| 更多采样进程 | num_env_runners | 环境慢、需要更多并行轨迹 |
| 向量化环境 | num_envs_per_env_runner | 单进程内 batched 推理；可再开 ASYNC 向量化 |
| 更多学习卡 | num_learners+ GPU | 加大有效 batch、多卡 DDP |
入门实践建议：
- 先采样后学习：多数瓶颈在环境步进 → 先加 EnvRunner / 向量环境。
- GPU 给 Learner：EnvRunner 默认 CPU 即可；除非环境或推理本身要 GPU。
- IMPALA/APPO：单卡时
num_learners=0 + num_gpus_per_learner=1与num_learners=1 + CPU的性能选择不同，见官方 Scaling Guide。
8. Episode：数据长什么样
长度 20 的SingleAgentEpisode示意：
obs: (21, ...) # 含 reset 的初始观测，比动作多 1 actions: (20, ...) rewards: (20, ...) infos: 长度 21 的 dict 列表 extra_model_outputs: 如 action_dist_inputs / logp is_terminated / is_truncated: 结束原因设计要点（入门记住即可）：
- 不单独存
next_obs：与下一时刻obs重叠，约省一半观测内存。 - 复杂
Dict观测保持嵌套结构，叶子是 NumPy，便于网络传输。 - 多智能体用
MultiAgentEpisode（内含多个单智能体轨迹 + 步进时序关系）。
9. 和周边组件的关系（心智对齐）
| 组件 | 在 RLlib 里通常扮演 |
|---|---|
| Ray Core（Actors） | EnvRunner / Learner 进程与 RPC |
| Ray Tune | 实验管理、停条件、超参搜索（Algorithm 是 Trainable） |
| Ray Data | 新栈离线 RL 的读写与预处理 |
| Gymnasium | 环境标准接口；向量环境 API |
| PyTorch | 主流 RLModule / Learner 实现框架 |
RLlib 不是「又一个 PPO 脚本」，而是把采样与学习拆成可独立扩缩的 Actor 图，上面挂统一的模块与数据协议。
10. 入门学习路径（建议 1–2 周）
| 阶段 | 目标 | 材料 |
|---|---|---|
| Day 1–2 | 建立 Algorithm / EnvRunner / Learner / RLModule 心智模型 | 本文 §1–5；Key Concepts |
| Day 3–4 | 跑通 CartPole PPO，改扩缩轴 | Scaling Guide |
| Day 5–6 | 自定义环境 + 读默认 RLModule 配置 | RL Environments、RLModules |
| Day 7+ | 试 DQN/SAC 或简单多智能体；了解新栈迁移词表 | Algorithms、Migration Guide |
入门验收标准：
- 能画 Algorithm ↔ EnvRunnerGroup ↔ LearnerGroup 关系图
- 能解释为何采样侧常用
inference_onlyRLModule - 能独立改环境、batch、EnvRunner/Learner 数量并跑通
- 能说明 Episode 相对旧 SampleBatch 的基本职责
11. 常见坑（入门版）
- 还在用旧栈配置（
model={...}、num_workers）→ 新栈请用rl_module(...)、num_env_runners。 num_gpus_per_learner>0但集群无卡 / 未开 autoscaler→ 实验像「卡住」在等资源。- 把 GPU 全分给 EnvRunner、Learner 没卡→ 学习极慢或落在 CPU。
- 一上来就自定义 Policy/ModelV2→ 新栈应扩展
RLModule+Learner。 - 忽略权重同步→ 改 Learner 后 EnvRunner 仍用旧权重（正常由 Algorithm 处理；自写循环时容易漏）。
12. 小结
RLlib 入门只需抓住一条主线：
AlgorithmConfig 描述实验 → Algorithm 编排采样与学习 → EnvRunner 产 Episode → Learner 更新 RLModule → 权重同步回采样侧。
搞清这条主线后，再深入自定义 RLModule/Learner、ConnectorV2、多智能体 MultiRLModule、离线 RL、高吞吐 APPO/IMPALA 等，请阅读同目录下的《Ray RLlib 架构精通指导》。
参考链接
- Key Concepts：https://docs.ray.io/en/latest/rllib/key-concepts.html
- Scaling Guide：https://docs.ray.io/en/latest/rllib/scaling-guide.html
- Algorithms：https://docs.ray.io/en/latest/rllib/rllib-algorithms.html
- RLModules：https://docs.ray.io/en/latest/rllib/rl-modules.html
- New API Stack 迁移：https://docs.ray.io/en/latest/rllib/new-api-stack-migration-guide.html
- 代码：https://github.com/ray-project/ray/tree/master/rllib