Ray RLlib 架构精通指导面向已跑通 PPO/DQN、需要自定义模型与损失、改采样-学习流水线、做多智能体/离线 RL、压吞吐或迁移旧栈的工程师与研究员。阅读建议先读同目录《Ray RLlib 架构入门指导》再按本文「问题驱动」深入。依据Ray 2.4x新 API 栈默认开启官方文档与ray/rllib主线实现。1. 精通目标你要能回答的问题新栈相对旧栈Policy / RolloutWorker / SampleBatch的职责切分与迁移映射是什么Algorithm.training_step如何编排 EnvRunnerGroup 与 LearnerGroup权重以何种形态同步RLModule三个 forward 与inference_only裁剪如何节省采样内存三条 ConnectorV2 管线env→module、module→env、Learner各自何时运行、如何扩展Learner/LearnerGroup如何做 DDP自定义算法要覆写哪些钩子多智能体下MultiRLModule、agent↔module 映射、共享编码器优化器陷阱在哪离线 RLRay Data OfflineData与在线采样如何共用 Learner三条扩缩轴的瓶颈诊断与 APPO/IMPALA 异步高吞吐的适用边界若以上都能画图并落到配置/代码路径即可视为「精通 RLlib 架构」。2. 新 API 栈设计精读2.1 旧 → 新 映射表旧 API 栈新 API 栈备注PolicyModelV2RLModule网络与三阶段 forwardPolicy内 loss / optimizerLearner损失与优化从 Policy 剥离RolloutWorkerEnvRunnerSingle/Multi更清晰的采样职责SampleBatch/EpisodeV2/ ViewRequirementSingleAgentEpisode/MultiAgentEpisode列式轨迹省 next_obsConnector旧ConnectorV2env↔module、Learner 管道num_workersnum_env_runners命名对齐组件关闭新栈仅维护遗留代码时config.api_stack(enable_rl_module_and_learnerFalse,enable_env_runner_and_connector_v2False,)精通立场新功能与文档默认新栈自定义与性能优化应落在 RLModule / Learner / ConnectorV2而不是复活 Policy API。2.2 分离采样与学习的软件动机RL 控制流Algorithm决定「先采多少、何时更新、何时评估、如何同步」 │ ├─ 计算流 AEnv 步进 推理前向EnvRunner可水平扩 └─ 计算流 Bloss / backward / DDPLearner可水平扩对比「全塞进一个 Worker」维度采样与学习耦合分离RLlib 新栈独立扩缩采样 vs 学习难三轴独立配置换损失 / 换网络易牵动采样路径Learner / RLModule 局部替换异步高吞吐IMPALA 系特例代码多同一 Actor 图上改编排单卡调试简单num_env_runners0、num_learners0可退回近单进程RLlib 明确选择用 Algorithm 薄编排层 可扩 Actor 组换算法主要改 training_step 与 Learner而不是重写分布式底座。3. 执行模型深潜3.1 Algorithm 持有的运行时对象Algorithm ├── env_runner_group: EnvRunnerGroup │ ├── local EnvRunner历史兼容未来可能弱化 │ └── remote EnvRunner × n ← 并行采样 ├── eval_env_runner_group ← 可选专用于评估 ├── learner_group: LearnerGroup │ └── Learner × m ← DDP 更新 └── offline_data: OfflineData ← 可选离线路径纪律不要直接拿底层 actor handle 乱调经EnvRunnerGroup/LearnerGroup的 foreach / update / sync API才能享受弹性与故障恢复。3.2 同步 on-policy以 PPO 为范型training_step / train iteration: episodes env_runner_group.sample(...) # 或等价收集 results learner_group.update(episodes...) rl_module_state learner_group.get_state( ..., inference_onlyTrue) env_runner_group.sync_env_runner_states( rl_module_state..., env_to_module..., module_to_env...)精通要点同步给 EnvRunner 的是inference_only状态去掉仅训练需要的头如部分 value 分支省内存与传输。Connector 状态归一化统计等也可随sync_env_runner_states对齐避免「训练侧统计 ≠ 采样侧统计」。on-policy采 → 学 → 同步强顺序过期策略数据不能当新鲜 PPO batch 用。3.3 高吞吐 / 异步系APPO、IMPALA架构同构编排不同EnvRunner 持续产出Learner 消费队列中的数据。重要性采样 / V-trace 等修正离策略偏差。GPU 布局敏感单卡时num_learners0 gpuvsnum_learners1 cpu吞吐差异显著见 Scaling Guide。精通者应能说明异步换的是GPU 利用率与样本新鲜度的权衡不是「免费加速」。4. RLModule网络与生命周期4.1 三个 forward 的契约方法调用场景典型行为forward_exploration训练采样带探索的动作分布采样forward_inference评估 / 生产更贪心或低随机forward_trainLearner 更新产出算 loss 所需张量logits、values、Q…自定义单智能体模块通常继承TorchRLModule在setup()建网实现上述逻辑。4.2 EnvRunner 侧 vs Learner 侧副本EnvRunner: RLModule(inference_onlyTrue) → 只要能出动作 Learner: RLModule(完整) → loss 所需一切 优化器状态在 LearnerRLModuleSpec(learner_onlyTrue)仅学习侧需要的子模块如某些自监督头不部署到 EnvRunner。4.3 MultiRLModule默认实现 ≈{ModuleID: RLModule}字典。多智能体config.multi_agent(policies..., policy_mapping_fn...)映射到模块。共享编码器陷阱若两个 policy 模块共享 encoder却用「每 module 一个 optimizer」的默认 Learner会出现两个优化器轮流更新同一 encoder → 不稳定。精通做法写多智能体 Learner对共享参数只用一个优化器更新 encoderheads。4.4 自监督 / 辅助损失实现SelfSupervisedLossAPI.compute_self_supervised_lossLearner 在forward_train后自动调用。可挂在线 batch 或离线数据。常配合learner_only与额外 Learner Connector保证辅助头吃到所需字段。5. ConnectorV2数据平面5.1 三条管道EnvRunner: Env ──► [env-to-module] ──► RLModule.forward_* ──► [module-to-env] ──► Env.step Learner: list[Episode] ──► [learner connector] ──► train batch ──► RLModule.forward_train管道位置职责示例env→moduleEnvRunner观测预处理、frame stack、agent→module 映射、组 batchmodule→envEnvRunner分布 → 环境动作、动作裁剪、反归一化LearnerLearnerEpisode → 列式 train batch、GAE/advantage 相关准备、设备搬运5.2 扩展方式在AlgorithmConfig中提供返回ConnectorV2或列表的工厂函数默认会前置到内置管道除非add_default_connectors_*False全权自定义。旧栈迁移Agent connector → env-to-module 片断Action connector → module-to-env 片断on_postprocess_trajectory→ 不再触发逻辑迁入 ConnectorV2精通纪律凡影响「模型看见什么 / 环境收到什么 / 训练 batch 长什么样」的变换优先进 Connector避免在 Env 与 Module 里各写一份不一致的预处理。6. Learner 与 LearnerGroup6.1 Learner 核心钩子方法用途configure_optimizers_for_module()为某 ModuleID 注册优化器compute_loss_for_module()计算可反传 lossbefore_gradient_based_update()梯度步之前的非梯度更新如加噪after_gradient_based_update()梯度步之后如 Polyak、系数日程算法差异主要落在loss采样基础设施可复用。6.2 LearnerGroup DDP 协调器num_learnersmm 份同构 Learner数据切分梯度聚合。update(..., num_epochs..., minibatch_size..., shuffle_batch_per_epoch...)PPO 式多 epoch / mini-batch。return_stateTrue更新后顺带返回一份模块状态避免额外get_weights往返利于同步 EnvRunner。异步update可与采样流水线重叠适合高吞吐算法。6.3 自定义算法的标准路径定义 / 复用RLModule或 MultiRLModule实现Learner.compute_loss_for_module及优化器配置子类化Algorithm覆写training_step采样量、是否从 OfflineData 取数、同步策略提供XxxConfig暴露超参用num_env_runners0、num_learners0单进程验算损失再开分布式7. Episode 数据模型精读7.1 设计选择列式 NumPy跨 Ray 网络传输友好。无 next_obs / 无重复 state_in观测与 RNN 状态近半内存优化。extra_model_outputs保存采样时的 logits、logp、hid state供 PPO ratio、RNN 续算。标准化列名见rllib/core/columns.py。7.2 与 batch 大小的关系EnvRunner: 产出长度约 rollout_fragment_length 的 episode chunks Algorithm: 聚合到每个 Learner 恰好 train_batch_size_per_learner精通调参改语义 batch→train_batch_size_per_learner、minibatch_size、num_epochs改采样切片粒度→rollout_fragment_length、向量环境数二者不对齐时会出现填充浪费或等待气泡7.3 多智能体 EpisodeMultiAgentEpisode记录各 agent 的异步步进关系。向量化多智能体环境仍是官方缺口之一Scaling Guide outlook大规模 MARL 需关注策略数量膨胀未来可能对 MultiRLModule 分组切分。8. 扩缩与性能精通级模型8.1 三轴再审视轴增加时提升什么何时失效num_env_runners环境并行度策略推理或权重同步成瓶颈集群调度开销num_envs_per_env_runner单 Actor 内 batch 推理环境 GIL/同步步进可试VectorizeMode.ASYNCnum_learners学习吞吐 / 有效 batch模型需装进单卡当前以 DDP 为主非张量并行8.2 资源放置直觉config.env_runners(num_env_runners8,num_cpus_per_env_runner1,num_gpus_per_env_runner0,# 多数仿真)config.learners(num_learners4,num_gpus_per_learner1,# 一卡一 Learner 最常见)小数 GPU如0.2可把多个实验挤进一卡注意争用。num_gpus_per_learner0会强制 CPU 模块即使集群有 GPU。当前限制超大模型 / LLM-RLHF 所需的张量并行与快速跨 Actor 权重交换仍在演进重度 LLM 后训练常看 verl 等专用栈RLlib 擅长经典/中等规模深度 RL 与多智能体。8.3 吞吐火焰图逻辑阶段阶段常见瓶颈方向env.step仿真慢、同步向量化加 EnvRunner、ASYNC vector、加速环境forward_exploration大模型 CPU 推理GPU EnvRunner、减小 inference 模块、批量化权重 sync频繁全量同步、模块过大降低 sync 频率若算法允许、inference_only、压缩learner updatebatch 小、DDP 通信、过多 epoch调 batch/learners、混合精度、减 epochconnectorPython 重预处理向量化、移入模块或 C/底层9. 离线 RL 架构要点新栈离线路径建立在Ray Data上默认读写 parquet变换尽量在进 Learner之前流式完成让 Learner 专注更新。在线与离线可共用同一套 RLModule/Learner差异在 Algorithm 的数据源EnvRunner vs OfflineData。旧SampleBatch录音config.offline_data(input_read_sample_batchesTrue)或先转成SingleAgentEpisode。精通点离线质量覆盖、分布偏移往往比再堆一个 Learner 更关键架构上先保证Episode schema 与 Connector 一致。10. 与 Tune、检查点、回调TuneAlgorithm是 Trainable用 Tuner 管 stop、checkpoint、网格搜索。精通时区分「算法超参」与「资源/扩缩超参」。CheckpointableLearnerGroup / RLModule 状态纳入 Algorithm 检查点恢复后需能再次 sync 到 EnvRunner。Callbacks新栈部分旧钩子消失如on_create_policy、on_postprocess_trajectory环境创建若走 gymnasium VectorEnv单 env-index 级钩子也受限。扩展优先 Connector 与自定义 EnvRunner/Learner。11. 算法选型与架构映射速查家族代表架构含义On-policyPPO同步采-学-同步多 epoch mini-batchOff-policyDQN、SACReplayLearner 与采样解耦更强高吞吐APPO、IMPALA异步队列 off-policy 修正Model-basedDreamerV3RLModule 内世界模型Learner 损失更复合Offline / ILBC、CQL、IQL、MARWILOfflineData 为主可无 EnvRunner扩展插件例ICM 等好奇心 → 常以辅助模块 额外 loss 挂入。12. 正确性雷区精通版训练用 exploration 分布、评估却忘改 inference→ 指标虚高或虚低。Connector 只改了采样侧、Learner 侧未对齐→ 归一化/stack 不一致静默损坏。PPO 使用过期策略数据却当 on-policy→ ratio 语义错误。MultiRLModule 共享参数 多优化器→ 训练震荡。自定义 training_step 漏 sync / 漏 metrics→ 难诊断的「学了但不涨分」。把 micro/向量环境数当算法语义旋钮乱扫→ 在实现正确时应主要影响吞吐不应用它「调收敛」代替 lr/clip/gamma。13. 配置与代码的「控制平面」精通者应能从一份配置还原运行时拓扑config(PPOConfig().environment(env...,env_config{...}).env_runners(num_env_runners...,num_envs_per_env_runner...,num_cpus_per_env_runner...,gym_env_vectorize_mode...,# SYNC / ASYNC).learners(num_learners...,num_gpus_per_learner...,).training(train_batch_size_per_learner...,lr...,gamma...,# PPO: clip_param, lambda_, use_gae, entropy_coeff, ...).rl_module(rl_module_spec...,# 或默认 model_config# model_configDefaultModelConfig(...),).evaluation(evaluation_num_env_runners...,evaluation_interval...,)# .offline_data(...) # 若离线# .multi_agent(...) # 若 MARL)代码阅读优先级algorithms/algo/algo.py的training_step对应*Learner.compute_loss_for_module默认RLModule与 Connector 构建处EnvRunner.sample主循环14. 精通学习路径建议阶段目标1对照源码走通一次 PPOtrain()采样 → update → sync2写最小自定义TorchRLModule 复用 PPO Learner3写自定义Learnerloss保持 EnvRunner 不动4插入一条 env-to-module Connector验证训练/评估一致性5多卡num_learners1与故障注入杀 EnvRunner观察弹性6多智能体 MultiRLModule 或一条 OfflineData 训练链路精通验收标准能默写新栈组件图与旧栈映射能独立实现「新损失 新网络」而不改 EnvRunner 内核能诊断采样瓶颈 vs 学习瓶颈 vs 同步瓶颈能说明何时该用 PPO 同步栈 vs APPO/IMPALA 异步栈能评估 RLlib 与 LLM-RL 专用框架如 verl的边界15. 小结RLlib 精通的主线是Algorithm 薄控制面 EnvRunner/Learner 可独立扩缩的计算面 RLModule/Episode/ConnectorV2 稳定协议换算法优先换 Learner 与 training_step换预处理优先换 Connector换容量优先拧三轴。入门心智见《Ray RLlib 架构入门指导》二者对照阅读可从「会跑」过渡到「会改、会扩、会排障」。参考链接Key Conceptshttps://docs.ray.io/en/latest/rllib/key-concepts.htmlScaling Guidehttps://docs.ray.io/en/latest/rllib/scaling-guide.htmlLearnerhttps://docs.ray.io/en/latest/rllib/rllib-learner.htmlRLModuleshttps://docs.ray.io/en/latest/rllib/rl-modules.htmlConnectorV2 / env-to-modulehttps://docs.ray.io/en/latest/rllib/connector-v2.htmlOffline RLhttps://docs.ray.io/en/latest/rllib/rllib-offline.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 架构精通指导面向已跑通 PPO/DQN、需要自定义模型与损失、改采样-学习流水线、做多智能体/离线 RL、压吞吐或迁移旧栈的工程师与研究员。阅读建议先读同目录《Ray RLlib 架构入门指导》再按本文「问题驱动」深入。依据Ray 2.4x新 API 栈默认开启官方文档与ray/rllib主线实现。1. 精通目标你要能回答的问题新栈相对旧栈Policy / RolloutWorker / SampleBatch的职责切分与迁移映射是什么Algorithm.training_step如何编排 EnvRunnerGroup 与 LearnerGroup权重以何种形态同步RLModule三个 forward 与inference_only裁剪如何节省采样内存三条 ConnectorV2 管线env→module、module→env、Learner各自何时运行、如何扩展Learner/LearnerGroup如何做 DDP自定义算法要覆写哪些钩子多智能体下MultiRLModule、agent↔module 映射、共享编码器优化器陷阱在哪离线 RLRay Data OfflineData与在线采样如何共用 Learner三条扩缩轴的瓶颈诊断与 APPO/IMPALA 异步高吞吐的适用边界若以上都能画图并落到配置/代码路径即可视为「精通 RLlib 架构」。2. 新 API 栈设计精读2.1 旧 → 新 映射表旧 API 栈新 API 栈备注PolicyModelV2RLModule网络与三阶段 forwardPolicy内 loss / optimizerLearner损失与优化从 Policy 剥离RolloutWorkerEnvRunnerSingle/Multi更清晰的采样职责SampleBatch/EpisodeV2/ ViewRequirementSingleAgentEpisode/MultiAgentEpisode列式轨迹省 next_obsConnector旧ConnectorV2env↔module、Learner 管道num_workersnum_env_runners命名对齐组件关闭新栈仅维护遗留代码时config.api_stack(enable_rl_module_and_learnerFalse,enable_env_runner_and_connector_v2False,)精通立场新功能与文档默认新栈自定义与性能优化应落在 RLModule / Learner / ConnectorV2而不是复活 Policy API。2.2 分离采样与学习的软件动机RL 控制流Algorithm决定「先采多少、何时更新、何时评估、如何同步」 │ ├─ 计算流 AEnv 步进 推理前向EnvRunner可水平扩 └─ 计算流 Bloss / backward / DDPLearner可水平扩对比「全塞进一个 Worker」维度采样与学习耦合分离RLlib 新栈独立扩缩采样 vs 学习难三轴独立配置换损失 / 换网络易牵动采样路径Learner / RLModule 局部替换异步高吞吐IMPALA 系特例代码多同一 Actor 图上改编排单卡调试简单num_env_runners0、num_learners0可退回近单进程RLlib 明确选择用 Algorithm 薄编排层 可扩 Actor 组换算法主要改 training_step 与 Learner而不是重写分布式底座。3. 执行模型深潜3.1 Algorithm 持有的运行时对象Algorithm ├── env_runner_group: EnvRunnerGroup │ ├── local EnvRunner历史兼容未来可能弱化 │ └── remote EnvRunner × n ← 并行采样 ├── eval_env_runner_group ← 可选专用于评估 ├── learner_group: LearnerGroup │ └── Learner × m ← DDP 更新 └── offline_data: OfflineData ← 可选离线路径纪律不要直接拿底层 actor handle 乱调经EnvRunnerGroup/LearnerGroup的 foreach / update / sync API才能享受弹性与故障恢复。3.2 同步 on-policy以 PPO 为范型training_step / train iteration: episodes env_runner_group.sample(...) # 或等价收集 results learner_group.update(episodes...) rl_module_state learner_group.get_state( ..., inference_onlyTrue) env_runner_group.sync_env_runner_states( rl_module_state..., env_to_module..., module_to_env...)精通要点同步给 EnvRunner 的是inference_only状态去掉仅训练需要的头如部分 value 分支省内存与传输。Connector 状态归一化统计等也可随sync_env_runner_states对齐避免「训练侧统计 ≠ 采样侧统计」。on-policy采 → 学 → 同步强顺序过期策略数据不能当新鲜 PPO batch 用。3.3 高吞吐 / 异步系APPO、IMPALA架构同构编排不同EnvRunner 持续产出Learner 消费队列中的数据。重要性采样 / V-trace 等修正离策略偏差。GPU 布局敏感单卡时num_learners0 gpuvsnum_learners1 cpu吞吐差异显著见 Scaling Guide。精通者应能说明异步换的是GPU 利用率与样本新鲜度的权衡不是「免费加速」。4. RLModule网络与生命周期4.1 三个 forward 的契约方法调用场景典型行为forward_exploration训练采样带探索的动作分布采样forward_inference评估 / 生产更贪心或低随机forward_trainLearner 更新产出算 loss 所需张量logits、values、Q…自定义单智能体模块通常继承TorchRLModule在setup()建网实现上述逻辑。4.2 EnvRunner 侧 vs Learner 侧副本EnvRunner: RLModule(inference_onlyTrue) → 只要能出动作 Learner: RLModule(完整) → loss 所需一切 优化器状态在 LearnerRLModuleSpec(learner_onlyTrue)仅学习侧需要的子模块如某些自监督头不部署到 EnvRunner。4.3 MultiRLModule默认实现 ≈{ModuleID: RLModule}字典。多智能体config.multi_agent(policies..., policy_mapping_fn...)映射到模块。共享编码器陷阱若两个 policy 模块共享 encoder却用「每 module 一个 optimizer」的默认 Learner会出现两个优化器轮流更新同一 encoder → 不稳定。精通做法写多智能体 Learner对共享参数只用一个优化器更新 encoderheads。4.4 自监督 / 辅助损失实现SelfSupervisedLossAPI.compute_self_supervised_lossLearner 在forward_train后自动调用。可挂在线 batch 或离线数据。常配合learner_only与额外 Learner Connector保证辅助头吃到所需字段。5. ConnectorV2数据平面5.1 三条管道EnvRunner: Env ──► [env-to-module] ──► RLModule.forward_* ──► [module-to-env] ──► Env.step Learner: list[Episode] ──► [learner connector] ──► train batch ──► RLModule.forward_train管道位置职责示例env→moduleEnvRunner观测预处理、frame stack、agent→module 映射、组 batchmodule→envEnvRunner分布 → 环境动作、动作裁剪、反归一化LearnerLearnerEpisode → 列式 train batch、GAE/advantage 相关准备、设备搬运5.2 扩展方式在AlgorithmConfig中提供返回ConnectorV2或列表的工厂函数默认会前置到内置管道除非add_default_connectors_*False全权自定义。旧栈迁移Agent connector → env-to-module 片断Action connector → module-to-env 片断on_postprocess_trajectory→ 不再触发逻辑迁入 ConnectorV2精通纪律凡影响「模型看见什么 / 环境收到什么 / 训练 batch 长什么样」的变换优先进 Connector避免在 Env 与 Module 里各写一份不一致的预处理。6. Learner 与 LearnerGroup6.1 Learner 核心钩子方法用途configure_optimizers_for_module()为某 ModuleID 注册优化器compute_loss_for_module()计算可反传 lossbefore_gradient_based_update()梯度步之前的非梯度更新如加噪after_gradient_based_update()梯度步之后如 Polyak、系数日程算法差异主要落在loss采样基础设施可复用。6.2 LearnerGroup DDP 协调器num_learnersmm 份同构 Learner数据切分梯度聚合。update(..., num_epochs..., minibatch_size..., shuffle_batch_per_epoch...)PPO 式多 epoch / mini-batch。return_stateTrue更新后顺带返回一份模块状态避免额外get_weights往返利于同步 EnvRunner。异步update可与采样流水线重叠适合高吞吐算法。6.3 自定义算法的标准路径定义 / 复用RLModule或 MultiRLModule实现Learner.compute_loss_for_module及优化器配置子类化Algorithm覆写training_step采样量、是否从 OfflineData 取数、同步策略提供XxxConfig暴露超参用num_env_runners0、num_learners0单进程验算损失再开分布式7. Episode 数据模型精读7.1 设计选择列式 NumPy跨 Ray 网络传输友好。无 next_obs / 无重复 state_in观测与 RNN 状态近半内存优化。extra_model_outputs保存采样时的 logits、logp、hid state供 PPO ratio、RNN 续算。标准化列名见rllib/core/columns.py。7.2 与 batch 大小的关系EnvRunner: 产出长度约 rollout_fragment_length 的 episode chunks Algorithm: 聚合到每个 Learner 恰好 train_batch_size_per_learner精通调参改语义 batch→train_batch_size_per_learner、minibatch_size、num_epochs改采样切片粒度→rollout_fragment_length、向量环境数二者不对齐时会出现填充浪费或等待气泡7.3 多智能体 EpisodeMultiAgentEpisode记录各 agent 的异步步进关系。向量化多智能体环境仍是官方缺口之一Scaling Guide outlook大规模 MARL 需关注策略数量膨胀未来可能对 MultiRLModule 分组切分。8. 扩缩与性能精通级模型8.1 三轴再审视轴增加时提升什么何时失效num_env_runners环境并行度策略推理或权重同步成瓶颈集群调度开销num_envs_per_env_runner单 Actor 内 batch 推理环境 GIL/同步步进可试VectorizeMode.ASYNCnum_learners学习吞吐 / 有效 batch模型需装进单卡当前以 DDP 为主非张量并行8.2 资源放置直觉config.env_runners(num_env_runners8,num_cpus_per_env_runner1,num_gpus_per_env_runner0,# 多数仿真)config.learners(num_learners4,num_gpus_per_learner1,# 一卡一 Learner 最常见)小数 GPU如0.2可把多个实验挤进一卡注意争用。num_gpus_per_learner0会强制 CPU 模块即使集群有 GPU。当前限制超大模型 / LLM-RLHF 所需的张量并行与快速跨 Actor 权重交换仍在演进重度 LLM 后训练常看 verl 等专用栈RLlib 擅长经典/中等规模深度 RL 与多智能体。8.3 吞吐火焰图逻辑阶段阶段常见瓶颈方向env.step仿真慢、同步向量化加 EnvRunner、ASYNC vector、加速环境forward_exploration大模型 CPU 推理GPU EnvRunner、减小 inference 模块、批量化权重 sync频繁全量同步、模块过大降低 sync 频率若算法允许、inference_only、压缩learner updatebatch 小、DDP 通信、过多 epoch调 batch/learners、混合精度、减 epochconnectorPython 重预处理向量化、移入模块或 C/底层9. 离线 RL 架构要点新栈离线路径建立在Ray Data上默认读写 parquet变换尽量在进 Learner之前流式完成让 Learner 专注更新。在线与离线可共用同一套 RLModule/Learner差异在 Algorithm 的数据源EnvRunner vs OfflineData。旧SampleBatch录音config.offline_data(input_read_sample_batchesTrue)或先转成SingleAgentEpisode。精通点离线质量覆盖、分布偏移往往比再堆一个 Learner 更关键架构上先保证Episode schema 与 Connector 一致。10. 与 Tune、检查点、回调TuneAlgorithm是 Trainable用 Tuner 管 stop、checkpoint、网格搜索。精通时区分「算法超参」与「资源/扩缩超参」。CheckpointableLearnerGroup / RLModule 状态纳入 Algorithm 检查点恢复后需能再次 sync 到 EnvRunner。Callbacks新栈部分旧钩子消失如on_create_policy、on_postprocess_trajectory环境创建若走 gymnasium VectorEnv单 env-index 级钩子也受限。扩展优先 Connector 与自定义 EnvRunner/Learner。11. 算法选型与架构映射速查家族代表架构含义On-policyPPO同步采-学-同步多 epoch mini-batchOff-policyDQN、SACReplayLearner 与采样解耦更强高吞吐APPO、IMPALA异步队列 off-policy 修正Model-basedDreamerV3RLModule 内世界模型Learner 损失更复合Offline / ILBC、CQL、IQL、MARWILOfflineData 为主可无 EnvRunner扩展插件例ICM 等好奇心 → 常以辅助模块 额外 loss 挂入。12. 正确性雷区精通版训练用 exploration 分布、评估却忘改 inference→ 指标虚高或虚低。Connector 只改了采样侧、Learner 侧未对齐→ 归一化/stack 不一致静默损坏。PPO 使用过期策略数据却当 on-policy→ ratio 语义错误。MultiRLModule 共享参数 多优化器→ 训练震荡。自定义 training_step 漏 sync / 漏 metrics→ 难诊断的「学了但不涨分」。把 micro/向量环境数当算法语义旋钮乱扫→ 在实现正确时应主要影响吞吐不应用它「调收敛」代替 lr/clip/gamma。13. 配置与代码的「控制平面」精通者应能从一份配置还原运行时拓扑config(PPOConfig().environment(env...,env_config{...}).env_runners(num_env_runners...,num_envs_per_env_runner...,num_cpus_per_env_runner...,gym_env_vectorize_mode...,# SYNC / ASYNC).learners(num_learners...,num_gpus_per_learner...,).training(train_batch_size_per_learner...,lr...,gamma...,# PPO: clip_param, lambda_, use_gae, entropy_coeff, ...).rl_module(rl_module_spec...,# 或默认 model_config# model_configDefaultModelConfig(...),).evaluation(evaluation_num_env_runners...,evaluation_interval...,)# .offline_data(...) # 若离线# .multi_agent(...) # 若 MARL)代码阅读优先级algorithms/algo/algo.py的training_step对应*Learner.compute_loss_for_module默认RLModule与 Connector 构建处EnvRunner.sample主循环14. 精通学习路径建议阶段目标1对照源码走通一次 PPOtrain()采样 → update → sync2写最小自定义TorchRLModule 复用 PPO Learner3写自定义Learnerloss保持 EnvRunner 不动4插入一条 env-to-module Connector验证训练/评估一致性5多卡num_learners1与故障注入杀 EnvRunner观察弹性6多智能体 MultiRLModule 或一条 OfflineData 训练链路精通验收标准能默写新栈组件图与旧栈映射能独立实现「新损失 新网络」而不改 EnvRunner 内核能诊断采样瓶颈 vs 学习瓶颈 vs 同步瓶颈能说明何时该用 PPO 同步栈 vs APPO/IMPALA 异步栈能评估 RLlib 与 LLM-RL 专用框架如 verl的边界15. 小结RLlib 精通的主线是Algorithm 薄控制面 EnvRunner/Learner 可独立扩缩的计算面 RLModule/Episode/ConnectorV2 稳定协议换算法优先换 Learner 与 training_step换预处理优先换 Connector换容量优先拧三轴。入门心智见《Ray RLlib 架构入门指导》二者对照阅读可从「会跑」过渡到「会改、会扩、会排障」。参考链接Key Conceptshttps://docs.ray.io/en/latest/rllib/key-concepts.htmlScaling Guidehttps://docs.ray.io/en/latest/rllib/scaling-guide.htmlLearnerhttps://docs.ray.io/en/latest/rllib/rllib-learner.htmlRLModuleshttps://docs.ray.io/en/latest/rllib/rl-modules.htmlConnectorV2 / env-to-modulehttps://docs.ray.io/en/latest/rllib/connector-v2.htmlOffline RLhttps://docs.ray.io/en/latest/rllib/rllib-offline.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