UniRL 分布式运行时深度解析:Ray、FSDP 与 TensorMeta 句柄代理数据面设计原理
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 上,驱动进程只搬运"句柄"。
一、为什么 RL 训练需要一套专门的分布式运行时 🤔
传统监督学习只有"数据 → 模型 → 梯度"一条流水线,而 RL 训练一次 train_step 实际上是多条流水线在交织运行:
- Rollout(采样):调用扩散模型或语言模型生成图像/视频/文本,可能消耗数百 GB 显存;
- Reward(打分):调用奖励模型给产物打分;
- Train(训练):用 GRPO/PPO 等算法更新策略模型;
- 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句柄。
二、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 声明式地表达。
三、TensorMeta 句柄代理数据面:本文的核心设计
这是 UniRL 分布式层最"微妙也最值得理解"的部分:一个 Tensor 如何在不离开 Worker 的情况下,被"搬运"到另一个角色手里。
1. "脱水—搬运—水化"三步走
整个数据面围绕一组命名展开:
- 脱水(dehydrate):
generate以DP_SCATTER在 rollout Worker 上运行。每个 Worker 返回的Sample里,每个重 Tensor 都被存入本 Worker 的 TensorStore,原位置替换为TensorMeta(本质是TensorRef:一个不透明引用 + shape/dtype/device 元信息),定义见 unirl/distributed/tensor/ref.py; - 搬句柄,不搬字节:driver 合并各 Worker 结果时,
TensorRef.concat只拼接 spans 列表(句柄),重字节从未离开 Worker。driver 只对小的rewards/advantages向量做水化(hydrate)——因为只有这几百个浮点数需要回到主进程算优势值; - 定位(localize):
train_track再次DP_SCATTER时,refs 被重新切分到训练 Worker。每个训练 Worker 在自己的 transport 上把TensorMeta解析回真实 Tensor——解析发生的物理位置,正是布局(layout)显现的地方。
TensorRef 内部是一组 TensorSpan(start:stop) 行窗口),切片、gather、permute 都只改窗口、不动数据(select_ranges 是唯一的选取引擎,见 [ref.py)。这保证 driver 侧的"重排 batch"操作是纯索引运算,零数据拷贝。
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 传输。
例外:trainside 引擎直接在进程内采样"活的"训练权重,天然不需要 sync——这也是 unirl/distributed/weight_sync/ 文档里反复强调的布局差异。
五、新手上手与扩展指南 ✅
快速理解路径(推荐按此顺序读源码):
- unirl/distributed/README.md —— 数据面全景与常见坑(Gotchas 一节非常实用);
- unirl/distributed/group/dispatch.py —— 看 4 种派发模式各 30 行左右的实现;
- unirl/distributed/tensor/ref.py ——
TensorRef/TensorSpan的脱水模型; - 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 集群上。




