UniRL 分布式运行时深度解析:Ray、FSDP 与 TensorMeta 句柄代理数据面设计原理

原创2026-10-16 20:59:161,635 阅读

UniRL 分布式运行时深度解析:Ray、FSDP 与 TensorMeta 句柄代理数据面设计原理

UniRL 是一个面向多模态模型强化学习(Reinforcement Learning, RL)的统一训练框架,支持文本、图像、视频等多模态的 GRPO、PPO、DPO 等 RL 算法。它的核心难点不在算法本身,而在于"如何把采样(Rollout)、打分(Reward)、训练(Train)这三套程序同时铺到成百上千张 GPU 上,并且不让海量 Tensor 把驱动进程撑爆"。本文带你深入 UniRL 的分布式运行时(Distributed Runtime),讲透它基于 Ray 的 Worker 模型、基于 FSDP 的训练后端,以及最精妙的设计——TensorMeta 句柄代理数据面(Handle Proxy Data Plane):重张量永远留在 Worker 上,驱动进程只搬运"句柄"。

UniRL整体架构图:多模态模型强化学习框架的驱动进程、Worker 池与训练循环

一、为什么 RL 训练需要一套专门的分布式运行时 🤔

传统监督学习只有"数据 → 模型 → 梯度"一条流水线,而 RL 训练一次 train_step 实际上是多条流水线在交织运行:

  1. Rollout(采样):调用扩散模型或语言模型生成图像/视频/文本,可能消耗数百 GB 显存;
  2. Reward(打分):调用奖励模型给产物打分;
  3. Train(训练):用 GRPO/PPO 等算法更新策略模型;
  4. Sync(同步):把新权重推送回推理引擎。

这些角色分布在不同的 GPU 组上,彼此传递的是巨大的 Tensor(比如一整批视频 latent)。如果按直觉把这些 Tensor 全部收集回主进程(driver)再分发,驱动进程必然 OOM,网络带宽也会成为瓶颈。

UniRL 的答案是把运行时拆成三个子层,全部位于 unirl/distributed/:

子层 目录 职责
Worker 模型 unirl/distributed/group/ 用 Ray actor 把 GPU 变成 Worker,一次方法调用扇出到所有 Worker
数据面 unirl/distributed/tensor/ 定义 Tensor 在 Worker 之间"移动或原地不动"的规则
权重同步 unirl/distributed/weight_sync/ 训练侧 → 推理引擎的权重回边

官方对这一层的解释非常直白(见 unirl/distributed/README.md),可以归结为两条设计思想:

  • 调用一个方法,它就会在所有该运行的地方运行——训练代码读起来像单进程代码;
  • 驱动进程永远不持有重字节——大 Tensor 留在 Worker 上,driver 只传递轻量的 TensorMeta 句柄。

UniRL代码架构图:driver 驱动进程通过 Handle 把 Rollout、Reward、Train 等阶段装配成 Remote Worker 车队

二、Ray Worker 模型:一个 GPU 一个 Ray Actor

1. 三个核心抽象:Worker / Remote / Handle

UniRL 把"逻辑角色"和"物理 GPU"严格解耦:

  • Worker(unirl/distributed/group/worker.py):物理层的 Ray actor,一个 Worker 独占一张 GPU。它内部挂载一组具名角色字典 _roles。
  • Remote(unirl/distributed/group/remote.py):逻辑层角色——rollout 引擎、模型 Bundle、FSDP 后端、算法、训练栈都是 Remote 的子类,它们作为"邻居(siblings)"共存于同一个 Worker 内,按名字互相解析。
  • Handle(unirl/distributed/group/handle.py):driver 侧的 SPMD 代理。训练代码写的 self.rollout.generate(sample) 实际上是通过 Handle 把一个方法调用拆分成 N 个 Ray RPC 并发下发。

💡 你永远不会直接调用 Worker。Handle 绑定了每个标注了 @distributed 装饰器的方法,把"一次调用"翻译成"每 Worker 一次 Ray RPC"。

2. 四档 Dispatch 模式:一次调用如何扇出

@distributed 装饰器声明该方法的派发方式,注册表在 unirl/distributed/group/dispatch.py:

Dispatch 模式 行为 典型场景
BROADCAST 相同参数发给每个 Worker wake_up、sync() 权重同步
SCATTER 按 world 大小切片,每个 Worker 一片 全 Worker 异构切分
DP_SCATTER 按 dp_size 切片,DP 组内各 rank 收到同一分片,结果合并 generate、train_track(主力)
DP_SCATTER_HEAD 同 DP_SCATTER,但只有 DP 头接收分片,省 RPC 带宽 大张量输入

其中 DP_SCATTER 是整个框架的"主力":驱动进程用 pytree_chunk 把 batch 按数据并行组切片,各 Worker 独立采样/训练,结果再由 pytree_cat 合并回来。训练代码因此读起来像单进程代码——这正是整个 group 层的价值。

3. DevicePool 与 placement:GPU 如何被"圈地"

  • DevicePool(unirl/distributed/group/device_pool.py):每节点申请一个 Ray placement group(每个 bundle 一张 GPU),维护全局 GPU 池;
  • placement(...) 上下文(unirl/distributed/group/placement.py):像"圈地"一样从池中划出一块 GPU slab,其内部的 create_remote 调用都落在这块 slab 上。默认是纯数据并行(rank == dp_rank),TP/FSDP 分片在各角色的 initialize() 内部完成。

这套机制让"rollout 用哪 8 张卡、train 用哪 16 张卡"完全由 trainer 用两行 placement 声明式地表达。

UniRL数据流图:一次 train_step 中 RolloutReq 经 DP_SCATTER 扇出到 Worker,再逐层装饰同一 track 的完整流程

三、TensorMeta 句柄代理数据面:本文的核心设计

这是 UniRL 分布式层最"微妙也最值得理解"的部分:一个 Tensor 如何在不离开 Worker 的情况下,被"搬运"到另一个角色手里。

1. "脱水—搬运—水化"三步走

整个数据面围绕一组命名展开:

  1. 脱水(dehydrate):generate 以 DP_SCATTER 在 rollout Worker 上运行。每个 Worker 返回的 Sample 里,每个重 Tensor 都被存入本 Worker 的 TensorStore,原位置替换为 TensorMeta(本质是 TensorRef:一个不透明引用 + shape/dtype/device 元信息),定义见 unirl/distributed/tensor/ref.py;
  2. 搬句柄,不搬字节:driver 合并各 Worker 结果时,TensorRef.concat 只拼接 spans 列表(句柄),重字节从未离开 Worker。driver 只对小的 rewards/advantages 向量做水化(hydrate)——因为只有这几百个浮点数需要回到主进程算优势值;
  3. 定位(localize):train_track 再次 DP_SCATTER 时,refs 被重新切分到训练 Worker。每个训练 Worker 在自己的 transport 上把 TensorMeta 解析回真实 Tensor——解析发生的物理位置,正是布局(layout)显现的地方。

TensorRef 内部是一组 TensorSpan(start:stop) 行窗口),切片、gather、permute 都只改窗口、不动数据(select_ranges 是唯一的选取引擎,见 [ref.py)。这保证 driver 侧的"重排 batch"操作是纯索引运算,零数据拷贝。

UniRL分布式拓扑图:TensorMeta 句柄代理数据面在 trainside/colocate 与 separate 两种布局下的控制面、数据面与权重同步路径

2. 三种可插拔 Transport 后端

TensorTransport 抽象契约(put / get / is_ref)定义在 unirl/distributed/tensor/transport.py,集群统一通过 transport_kind 参数选择后端,构建入口在 unirl/distributed/tensor/factory.py:

后端 字节存哪 跨卡解析方式 适用场景
colocate_store(默认) 生产方 Worker 进程内存 本地直读 / 跨卡 NCCL 一 Worker 一 GPU 的标准场景
gpu_store 每卡独立 CUDA-IPC 缓冲 CUDA-IPC 零拷贝 同一张卡多 slot 共置
transfer_queue 全局总线(simple 内存 / mooncake RDMA) 队列读取,RDMA 跨节点 生产级跨节点、解耦收发

后端的实现位于 unirl/distributed/tensor/backend/。以默认后端为例,ColocateStoreTransport 维护一张带引用计数的 TensorStore,跨 Worker 解析走 nccl_send/nccl_recv(colocate_store/transport.py)。

3. localize:让"消费者在哪,数据就到哪"

路由逻辑在 unirl/distributed/tensor/worker_local.py 的 localize 中,分三步:FIND(判断 ref 是否本地可解析)→ MOVE(按 (源设备, 目标设备) 分组,批量发起 worker→worker NCCL 一跳)→ REPLACE(把句柄里的 span 换成新句柄,仍是纯元数据操作)。

这一步的成本由部署布局决定:

  • trainside / colocate(共置):rollout 直接复用训练模型,生产 Worker 就是消费 Worker,解析是本地读,零跨卡传输——这是 trainside 配置族(如 sd3_trainside.yaml)快的原因;
  • separate(分离):rollout 与 train 各占一块不相交的 GPU slab,解析外部门句柄时触发一次 worker→worker 的 NCCL 直连跳,永远不经过 driver。

四、FSDP 训练后端与权重同步回边

1. FSDP 侧:训练权重如何分片

训练后端默认使用 PyTorch 的 FSDP2(unirl/train/backend/fsdp/,共享基类在 unirl/train/backend/base_backend.py):每张卡的 Worker 持有模型的一个分片(DTensor shard),梯度同步由 FSDP 的通信组在训练 slab 内部完成,driver 完全不参与。VeOmni 后端(unirl/train/backend/veomni/)则提供 EP/SP 等更细的并行选项。

2. 权重同步:gather 在所有 rank,push 只在 rank 0

在 separate / colocate 布局下,rollout 引擎持有的是独立副本,每步训练后必须把新权重推回去(unirl/distributed/weight_sync/README.md)。这里有一个反直觉但关键的设计:

读取 FSDP 权重本身就是一个集合通信——把每个 DTensor 分片重分布(all-gather)为完整张量,所有训练 rank 必须同步参与。所以 sync() 以 BROADCAST 派发:每个 rank 都执行 gather 阶段,rank 0 执行 push,rank ≥1 计算后丢弃。如果把 push 用 if rank == 0 提前 gate 掉,all-gather 会直接死锁。

push 阶段由 5 个 handler 组成"推什么 × 引擎在哪"的网格:LoRA(LocalLoraWeightSync / RemoteLoraWeightSync)与全量权重(TensorWeightSync / IPCWeightSync / NCCLWeightSync),分别覆盖 colocate 与 separate 布局,支持跨节点 NCCL 传输。

UniRL权重同步图:所有训练 rank all-gather FSDP 分片为完整张量后,五类 handler 按 LoRA/全量 × colocate/separate 网格推送给 SGLang 或 vLLM-Omni 推理引擎

例外:trainside 引擎直接在进程内采样"活的"训练权重,天然不需要 sync——这也是 unirl/distributed/weight_sync/ 文档里反复强调的布局差异。

五、新手上手与扩展指南 ✅

快速理解路径(推荐按此顺序读源码):

  1. unirl/distributed/README.md —— 数据面全景与常见坑(Gotchas 一节非常实用);
  2. unirl/distributed/group/dispatch.py —— 看 4 种派发模式各 30 行左右的实现;
  3. unirl/distributed/tensor/ref.py —— TensorRef/TensorSpan 的脱水模型;
  4. unirl/distributed/tensor/worker_local.py —— localize 的 FIND/MOVE/REPLACE 三段式路由。

扩展三个切面:

  • 新派发模式 = 一个枚举值 + dispatch.py 里一对 (dispatch, collect) 函数;
  • 新传输后端 = 在 tensor/backend/ 下实现 transport 契约并接入 build_transport() 的类型分派;
  • 新物理布局 = 在 trainer(如 unirl/trainer/diffusion.py)里加一段 placement(...) 装配。

两个新手最容易踩的坑(官方文档明确标注):

  • ⚠️ driver 侧持有的是代理不是张量:对 Sample 字段做算术前必须先 _hydrate_tensor_meta,否则会对着元信息做运算;
  • ⚠️ DP_SCATTER 按 pytree 中第一个 batch 维切片,且对前导维不一致的字段是静默复制而非报错——每 rollout 字段若恰好与 batch 前导维同形会被无声切碎,需要包一层 Broadcast(...) 显式退出切分。

六、总结:一张图看懂 UniRL 数据面的取舍

设计问题 UniRL 的答案
大 Tensor 怎么在 Worker 间流动? 不流动——字节留在生产方,只传 TensorMeta 句柄
消费者如何拿到数据? localize:本地直读(colocate)或一次 worker→worker NCCL 跳(separate)
驱动进程做什么? 只合并句柄、水化 rewards/advantages、编排控制流
训练侧如何分片? FSDP2 每卡一个 shard,集合通信全部在训练 slab 内
权重如何回到推理引擎? 全 rank gather + rank-0 push 的 5-handler 网格

一句话概括:Ray 负责"把方法扇出到所有卡",FSDP 负责"权重在训练组内分片",TensorMeta 句柄代理负责"重数据永不经过 driver"——三者叠加,让 UniRL 的多模态 RL 训练代码保持单进程的可读性,同时跑在任意规模的 GPU 集群上。

登录后查看全文
UniRL