Ray RLlib 架构入门指导面向想快速理解 RLlib 在做什么、核心组件如何协作、如何跑通第一条分布式 RL 训练链路的读者。依据RLlib Key Concepts、Scaling Guide、New API StackRay 2.4x 默认启用。1. 一句话理解 RLlibRLlib是构建在 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 上更多向量化子环境更多LearnerDDP并行算梯度2.2 总览直觉图┌──────────────────────────────────────────────┐ │ Algorithm AlgorithmConfig │ ← 实验运行时 / 配置入口 │ (algo.train() 主循环) │ └───────────────┬──────────────────┬───────────┘ │ │ ┌──────────▼──────────┐ ┌────▼───────────────┐ │ EnvRunnerGroup │ │ LearnerGroup │ │ n × EnvRunner │ │ m × Learner │ │ (采样 / 推理) │ │ (损失 / 梯度 / 优化)│ └──────────┬──────────┘ └────┬───────────────┘ │ Episode 列表 │ 更新后的权重 └────────┬─────────┘ │ sync weightsinference_only ▼ EnvRunner 上的 RLModule 副本记住三句话即可入门配置用 AlgorithmConfig运行用 Algorithm。EnvRunner 采 EpisodeLearner 吃 Episode 做更新。RLModule 是网络本体采样侧常是轻量inference_only副本学习侧是完整训练副本。3. 核心概念速查概念是什么入门只需知道AlgorithmConfig类型安全的配置构建器PPOConfig().environment(...).training(...).build()Algorithm一次实验的运行时algo.train()跑一轮也可交给 Ray TuneEnvRunner环境 策略交互的 Actor产出SingleAgentEpisode/MultiAgentEpisode列表EnvRunnerGroup一组 EnvRunner 的管理器含 1 个 local n个 remote故障可恢复RLModule框架相关的神经网络封装三个前向forward_exploration/forward_inference/forward_trainMultiRLModule多子模块字典多智能体 / 多网络时用按ModuleID索引Episode统一轨迹容器存 obs / actions / rewards / infos / 模型附加输出Learner损失 优化器 更新逻辑算法相关PPO Learner ≠ DQN LearnerLearnerGroup一组 Learner自动做数据并行DDPConnectorV2可插拔数据变换管道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_runners2).training(train_batch_size_per_learner2000,lr0.0004,))algoconfig.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. LearnerConnector 把 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_learner1)。换环境自定义gymnasium.Env用.environment(envYourEnv, env_config{...})。观察指标episode_return_mean、采样步数、learner loss、耗时。可选 Tune用tune.Tuner(PPO, param_spaceconfig, ...)做停条件与超参搜索。6.1 入门必懂的几个配置旋钮配置项含义environment(...)环境 ID 或类、env_configenv_runners(num_env_runnersn)远程采样 Actor 数0 只用 localenv_runners(num_envs_per_env_runnerp)每个 Actor 上的向量环境数learners(num_learnersm)远程 Learner 数0 local Learnerlearners(num_gpus_per_learner1)每个 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 给 LearnerEnvRunner 默认 CPU 即可除非环境或推理本身要 GPU。IMPALA/APPO单卡时num_learners0 num_gpus_per_learner1与num_learners1 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 CoreActorsEnvRunner / Learner 进程与 RPCRay Tune实验管理、停条件、超参搜索Algorithm 是 TrainableRay Data新栈离线 RL 的读写与预处理Gymnasium环境标准接口向量环境 APIPyTorch主流 RLModule / Learner 实现框架RLlib 不是「又一个 PPO 脚本」而是把采样与学习拆成可独立扩缩的 Actor 图上面挂统一的模块与数据协议。10. 入门学习路径建议 1–2 周阶段目标材料Day 1–2建立 Algorithm / EnvRunner / Learner / RLModule 心智模型本文 §1–5Key ConceptsDay 3–4跑通 CartPole PPO改扩缩轴Scaling GuideDay 5–6自定义环境 读默认 RLModule 配置RL Environments、RLModulesDay 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_learner0但集群无卡 / 未开 autoscaler→ 实验像「卡住」在等资源。把 GPU 全分给 EnvRunner、Learner 没卡→ 学习极慢或落在 CPU。一上来就自定义 Policy/ModelV2→ 新栈应扩展RLModuleLearner。忽略权重同步→ 改 Learner 后 EnvRunner 仍用旧权重正常由 Algorithm 处理自写循环时容易漏。12. 小结RLlib 入门只需抓住一条主线AlgorithmConfig 描述实验 → Algorithm 编排采样与学习 → EnvRunner 产 Episode → Learner 更新 RLModule → 权重同步回采样侧。搞清这条主线后再深入自定义 RLModule/Learner、ConnectorV2、多智能体 MultiRLModule、离线 RL、高吞吐 APPO/IMPALA 等请阅读同目录下的《Ray RLlib 架构精通指导》。参考链接Key Conceptshttps://docs.ray.io/en/latest/rllib/key-concepts.htmlScaling Guidehttps://docs.ray.io/en/latest/rllib/scaling-guide.htmlAlgorithmshttps://docs.ray.io/en/latest/rllib/rllib-algorithms.htmlRLModuleshttps://docs.ray.io/en/latest/rllib/rl-modules.htmlNew API Stack 迁移https://docs.ray.io/en/latest/rllib/new-api-stack-migration-guide.html代码https://github.com/ray-project/ray/tree/master/rllib Ray RLlib 架构入门指导
Ray RLlib 架构入门指导面向想快速理解 RLlib 在做什么、核心组件如何协作、如何跑通第一条分布式 RL 训练链路的读者。依据RLlib Key Concepts、Scaling Guide、New API StackRay 2.4x 默认启用。1. 一句话理解 RLlibRLlib是构建在 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 上更多向量化子环境更多LearnerDDP并行算梯度2.2 总览直觉图┌──────────────────────────────────────────────┐ │ Algorithm AlgorithmConfig │ ← 实验运行时 / 配置入口 │ (algo.train() 主循环) │ └───────────────┬──────────────────┬───────────┘ │ │ ┌──────────▼──────────┐ ┌────▼───────────────┐ │ EnvRunnerGroup │ │ LearnerGroup │ │ n × EnvRunner │ │ m × Learner │ │ (采样 / 推理) │ │ (损失 / 梯度 / 优化)│ └──────────┬──────────┘ └────┬───────────────┘ │ Episode 列表 │ 更新后的权重 └────────┬─────────┘ │ sync weightsinference_only ▼ EnvRunner 上的 RLModule 副本记住三句话即可入门配置用 AlgorithmConfig运行用 Algorithm。EnvRunner 采 EpisodeLearner 吃 Episode 做更新。RLModule 是网络本体采样侧常是轻量inference_only副本学习侧是完整训练副本。3. 核心概念速查概念是什么入门只需知道AlgorithmConfig类型安全的配置构建器PPOConfig().environment(...).training(...).build()Algorithm一次实验的运行时algo.train()跑一轮也可交给 Ray TuneEnvRunner环境 策略交互的 Actor产出SingleAgentEpisode/MultiAgentEpisode列表EnvRunnerGroup一组 EnvRunner 的管理器含 1 个 local n个 remote故障可恢复RLModule框架相关的神经网络封装三个前向forward_exploration/forward_inference/forward_trainMultiRLModule多子模块字典多智能体 / 多网络时用按ModuleID索引Episode统一轨迹容器存 obs / actions / rewards / infos / 模型附加输出Learner损失 优化器 更新逻辑算法相关PPO Learner ≠ DQN LearnerLearnerGroup一组 Learner自动做数据并行DDPConnectorV2可插拔数据变换管道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_runners2).training(train_batch_size_per_learner2000,lr0.0004,))algoconfig.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. LearnerConnector 把 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_learner1)。换环境自定义gymnasium.Env用.environment(envYourEnv, env_config{...})。观察指标episode_return_mean、采样步数、learner loss、耗时。可选 Tune用tune.Tuner(PPO, param_spaceconfig, ...)做停条件与超参搜索。6.1 入门必懂的几个配置旋钮配置项含义environment(...)环境 ID 或类、env_configenv_runners(num_env_runnersn)远程采样 Actor 数0 只用 localenv_runners(num_envs_per_env_runnerp)每个 Actor 上的向量环境数learners(num_learnersm)远程 Learner 数0 local Learnerlearners(num_gpus_per_learner1)每个 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 给 LearnerEnvRunner 默认 CPU 即可除非环境或推理本身要 GPU。IMPALA/APPO单卡时num_learners0 num_gpus_per_learner1与num_learners1 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 CoreActorsEnvRunner / Learner 进程与 RPCRay Tune实验管理、停条件、超参搜索Algorithm 是 TrainableRay Data新栈离线 RL 的读写与预处理Gymnasium环境标准接口向量环境 APIPyTorch主流 RLModule / Learner 实现框架RLlib 不是「又一个 PPO 脚本」而是把采样与学习拆成可独立扩缩的 Actor 图上面挂统一的模块与数据协议。10. 入门学习路径建议 1–2 周阶段目标材料Day 1–2建立 Algorithm / EnvRunner / Learner / RLModule 心智模型本文 §1–5Key ConceptsDay 3–4跑通 CartPole PPO改扩缩轴Scaling GuideDay 5–6自定义环境 读默认 RLModule 配置RL Environments、RLModulesDay 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_learner0但集群无卡 / 未开 autoscaler→ 实验像「卡住」在等资源。把 GPU 全分给 EnvRunner、Learner 没卡→ 学习极慢或落在 CPU。一上来就自定义 Policy/ModelV2→ 新栈应扩展RLModuleLearner。忽略权重同步→ 改 Learner 后 EnvRunner 仍用旧权重正常由 Algorithm 处理自写循环时容易漏。12. 小结RLlib 入门只需抓住一条主线AlgorithmConfig 描述实验 → Algorithm 编排采样与学习 → EnvRunner 产 Episode → Learner 更新 RLModule → 权重同步回采样侧。搞清这条主线后再深入自定义 RLModule/Learner、ConnectorV2、多智能体 MultiRLModule、离线 RL、高吞吐 APPO/IMPALA 等请阅读同目录下的《Ray RLlib 架构精通指导》。参考链接Key Conceptshttps://docs.ray.io/en/latest/rllib/key-concepts.htmlScaling Guidehttps://docs.ray.io/en/latest/rllib/scaling-guide.htmlAlgorithmshttps://docs.ray.io/en/latest/rllib/rllib-algorithms.htmlRLModuleshttps://docs.ray.io/en/latest/rllib/rl-modules.htmlNew API Stack 迁移https://docs.ray.io/en/latest/rllib/new-api-stack-migration-guide.html代码https://github.com/ray-project/ray/tree/master/rllib