框架设计
xDiT 的模型集成分为两层:runner 适配器定义用户接口和模型能力,模型及 pipeline 实现负责分布式执行。添加模型时,先阅读模型集成指南。
Runner 适配器
xFuserModel 提供配置校验、初始化、预热、计时和输出处理。模型适配器声明 checkpoint 别名、ModelCapabilities、DefaultInputValues、ModelSettings 和 LoadSupport,并实现 _load_model() 与 _run_pipe()。能力声明只是校验依据,实际加载和执行代码仍须实现对应功能。
FLUX.1-dev 适配器 有两条执行路径:
- 未启用 PipeFusion 时,使用 Diffusers
FluxPipeline和继承原始 transformer 的xFuserFlux1Transformer2DWrapper,在 transformer 中实现序列并行。 - 启用 PipeFusion 时,使用
xFuserFluxPipeline和组合式xFuserFluxTransformer2DWrapper,将 transformer 分配到多个 stage。
Z-Image 适配器 保留原始 Diffusers pipeline,在 transformer 中实现 CFG 和序列划分。因此,新模型不一定需要编写 pipeline wrapper。应根据模型接口和并行需求选择实现方式。
组件 Wrapper
此图只描述组合式 wrapper,不包含继承 Diffusers transformer 的实现或独立的 runner xFuserModel。
| 组件 | 职责 | 源码 |
|---|---|---|
xFuserBaseWrapper |
转发原始模块属性并检查执行条件 | Base wrapper |
xFuserPipelineBaseWrapper |
初始化 runtime、转换组件、处理 DP 装饰器及共享 patch/输出逻辑 | Pipeline base |
xFuserTransformerBaseWrapper |
划分 stage 的 block 列表,包装指定子模块 | Transformer base |
xFuserLayerBaseWrapper |
Layer wrapper 的共享接口 | Layer base |
xFuserSchedulerBaseWrapper |
Scheduler wrapper 的共享接口 | Scheduler base |
各 registry 将 Diffusers 类型映射到对应 wrapper。新模型需要注册其实际使用的 pipeline、transformer、layer、scheduler 和 attention processor,并确保注册模块被导入。仅继承基类不能自动获得所有并行能力。
未注册的 scheduler 会保留原始实现并输出警告;这不代表它支持 PipeFusion 的 patch 更新。未支持的 attention processor 会报错,添加模型时应检查当前 processor registry。
分布式状态
| 源码 | 职责 |
|---|---|
| parallel_state.py | 初始化 rank 和进程组,提供访问接口 |
| group_coordinator.py | Tensor 通信操作 |
| runtime_state.py | 输入尺寸、patch 索引、attention 配置和执行元数据 |
| pipefusion/ | Patch layout、payload、transport、schedule 和编译辅助逻辑 |
Runtime state 是进程内对象。每个 rank 必须初始化一致的布局,并以匹配的顺序调用 collective;读取 Python 全局变量不会同步进程。划分 tensor 前设置输入元数据,并按 schedule 顺序推进 patch 状态。
验证
保留模型输入输出、scheduler、位置编码、mask 和 callback 的语义。先比较原始 pipeline 与单设备路径,再在合适的硬件上验证分布式布局及声明支持的组合。测试范围遵循仓库的 testing policy。