Skip to content

Commit 99d2062

Browse files
PommesPeterPommesPeter
committed
docs(rfcs): added rfc for No.48 in hackathon 10th
1 parent ef08af9 commit 99d2062

1 file changed

Lines changed: 293 additions & 0 deletions

File tree

‎rfcs/FastDeploy/20260317_add_sd3_flux_diffusion_models_for_fastdeploy.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# FastDeploy 新增 SD3、Flux 扩散模型支持设计文档
2+
3+
| 任务名称 | 为 FastDeploy 新增 SD3、Flux 扩散模型 |
4+
|------|------|
5+
| 提交作者 | xiejunlin |
6+
| 提交时间 | 2026-03-17 |
7+
| 版本号 | V1.0 |
8+
| 文件名 | 20260317_add_sd3_flux_diffusion_models_for_fastdeploy.md |
9+
10+
# 一、概述
11+
12+
## 1、相关背景
13+
14+
Stable Diffusion 3（SD3）和 Flux.1 是当前最先进的文生图扩散模型，均采用 Diffusion Transformer（DiT）架构替代了传统的 UNet 骨干网络，在图像生成质量和文本理解能力上取得了显著突破。
15+
16+
- **SD3** 由 Stability AI 发布，基于 MMDiT（Multi-Modal Diffusion Transformer）架构，使用三个文本编码器（CLIP-L + OpenCLIP-G + T5-XXL）和 16 通道 VAE，参数量从 2B（Medium）到 8B（Large）。
17+
- **Flux.1** 由 Black Forest Labs 发布，采用混合 Transformer 架构（19 层 Double Stream + 38 层 Single Stream），使用两个文本编码器（CLIP-L + T5-XXL），总参数量约 12B。Flux.1 有三个变体：schnell（1-4 步快速生成）、dev（20-50 步高质量）、pro（API 服务）。
18+
19+
FastDeploy 当前专注于 LLM/VLM 推理服务，尚未支持扩散模型。PaddleMIX 项目中的 PPDiffusers 已有 SD3 和 Flux 的 PaddlePaddle 实现，但缺乏高性能推理服务能力。本任务旨在为 FastDeploy 引入扩散模型推理和服务能力，填补这一空白。
20+
21+
## 2、功能目标
22+
23+
* 在 FastDeploy 中实现 SD3 和 Flux 扩散模型的高性能推理
24+
* 提供 OpenAI Images API 兼容的服务接口（`/v1/images/generations`）
25+
* 适配 FastDeploy 现有的量化推理能力（FP8、WINT4、WINT8 等）
26+
* 支持张量并行（Tensor Parallelism）实现多卡推理
27+
* 提供 CLI 入口和离线推理接口
28+
29+
## 3、意义
30+
31+
扩展 FastDeploy 从纯文本生成到多模态生成的能力边界，为用户提供统一的大模型推理服务平台，覆盖 LLM、VLM 和图像生成三大场景。
32+
33+
# 二、现状分析
34+
35+
## FastDeploy 现状
36+
37+
FastDeploy 当前的架构围绕 LLM 推理设计，核心执行流为 **Engine → Worker → ModelRunner → Model**，存在以下与扩散模型不兼容的设计假设：
38+
39+
| 维度 | LLM 推理（当前） | 扩散模型推理（目标） |
40+
|------|----------------|-------------------|
41+
| 执行模式 | 逐 token 自回归生成 | 固定步数迭代去噪 |
42+
| 缓存机制 | KV Cache 管理 | 无 KV Cache，需管理 latent 状态 |
43+
| 输出格式 | token 序列/文本 | 图像张量/base64 编码 |
44+
| 调度策略 | prefill-decode 两阶段 | 批量请求并行去噪 |
45+
| 模型基类 | `ModelForCasualLM`（logits 输出） | 需要新基类（noise prediction 输出） |
46+
| API 接口 | Chat/Completion | Images Generation |
47+
48+
## 可复用的基础设施
49+
50+
| 组件 | 复用方式 |
51+
|------|---------|
52+
| 量化框架（FP8、WINT4/8 等） | 直接应用于 Transformer 和 VAE 的线性层 |
53+
| 张量并行线性层 | 用于 MMDiT/Flux Transformer 的 QKV 投影和 MLP |
54+
| 注意力后端（Flash Attention 等） | 用于 Joint Attention 计算 |
55+
| RMSNorm / LayerNorm | 用于 Transformer 块的归一化 |
56+
| RoPE 实现 | Flux 使用 2D RoPE 编码空间位置 |
57+
| 分布式通信 | 张量并行的 all-reduce 通信 |
58+
| Worker 抽象 | GPU/XPU 等多硬件支持 |
59+
| FastAPI 服务框架 | 扩展新的 API 端点 |
60+
61+
## PaddleMIX/PPDiffusers 现有实现
62+
63+
PaddleMIX 项目中 PPDiffusers 已有完整的 Paddle 实现，可作为组网参考：
64+
- `ppdiffusers/models/transformer_sd3.py` — SD3Transformer2DModel（MMDiT）
65+
- `ppdiffusers/pipelines/flux/modeling_flux.py` — FluxTransformer2DModel
66+
- `ppdiffusers/models/autoencoder_kl.py` — AutoencoderKL（16 通道 VAE）
67+
- `ppdiffusers/schedulers/scheduling_flow_match_euler_discrete.py` — FlowMatchEulerDiscreteScheduler
68+
69+
# 三、业内方案调研
70+
71+
## 1) HuggingFace Diffusers
72+
73+
业内最成熟的扩散模型推理框架，提供完整的 SD3 和 Flux pipeline 实现。核心设计：
74+
- Pipeline 模式：将文本编码、去噪循环、VAE 解码封装为统一 pipeline
75+
- 组件可替换：scheduler、text encoder、transformer、VAE 均可独立替换
76+
- 优化手段：`torch.compile`、Flash Attention、VAE tiling、model offloading
77+
- 局限：面向单用户推理，缺乏高并发服务能力和请求调度
78+
79+
## 2) ComfyUI / AUTOMATIC1111
80+
81+
社区主流的扩散模型推理 UI 工具，以节点图/WebUI 形式提供推理能力。优化手段包括模型缓存、注意力切片、FP8 量化等。但本质是单机单用户工具，不具备生产级服务能力。
82+
83+
## 3) TensorRT / ONNX Runtime
84+
85+
NVIDIA TensorRT 提供了 SD3 的图优化和算子融合加速方案，可实现 2-4x 推理加速。但需要预编译引擎，灵活性较差，且不提供服务框架。
86+
87+
## 4) SGLang / vLLM
88+
89+
SGLang 近期开始探索扩散模型支持（DiT serving），采用类似 LLM 的请求调度方式管理扩散模型推理。vLLM 目前尚未支持扩散模型。这一方向验证了在 LLM 推理框架中集成扩散模型的可行性。
90+
91+
## 调研结论
92+
93+
当前业内缺乏一个同时具备高性能推理、量化加速、多卡并行和 API 服务能力的扩散模型部署方案。FastDeploy 已有的量化、并行、服务基础设施为实现这一目标提供了良好基础。
94+
95+
# 四、设计思路与实现方案
96+
97+
## 总体架构
98+
99+
在 FastDeploy 现有架构基础上，新增扩散模型推理路径：
100+
101+
```
102+
用户请求
103+
│
104+
▼
105+
API Server ──── /v1/images/generations (新增)
106+
│
107+
▼
108+
DiffusionEngine (新增，管理扩散推理生命周期)
109+
│
110+
▼
111+
GpuWorker (复用) ──── DiffusionModelRunner (新增)
112+
│
113+
▼
114+
DiffusionModel (新增基类)
115+
├── TextEncoder (CLIP / T5)
116+
├── Transformer (SD3 MMDiT / Flux Hybrid)
117+
├── VAE Decoder
118+
└── Scheduler (FlowMatchEuler)
119+
```
120+
121+
## 目录结构
122+
123+
```
124+
fastdeploy/model_executor/diffusion_models/ # 扩散模型主目录（新增）
125+
├── __init__.py
126+
├── diffusion_base.py # 扩散模型基类
127+
├── sd3/ # SD3 模型
128+
│ ├── __init__.py
129+
│ ├── sd3_transformer.py # MMDiT Transformer
130+
│ └── sd3_pipeline.py # SD3 推理 pipeline
131+
├── flux/ # Flux 模型
132+
│ ├── __init__.py
133+
│ ├── flux_transformer.py # Hybrid Transformer
134+
│ └── flux_pipeline.py # Flux 推理 pipeline
135+
├── components/ # 共享组件
136+
│ ├── __init__.py
137+
│ ├── vae.py # AutoencoderKL (16通道)
138+
│ ├── text_encoders.py # CLIP / T5 文本编码器
139+
│ ├── scheduler.py # FlowMatchEulerDiscreteScheduler
140+
│ └── embeddings.py # 时间步/位置编码
141+
├── layers/ # 扩散模型专用层
142+
│ ├── __init__.py
143+
│ ├── dit_attention.py # Joint Attention / DiT Attention
144+
│ ├── dit_block.py # MMDiT Block / Single-Double Stream Block
145+
│ └── adaptive_norm.py # adaLN-Zero / adaLN-Single
146+
fastdeploy/engine/diffusion_engine.py # 扩散推理引擎（新增）
147+
fastdeploy/worker/diffusion_model_runner.py # 扩散模型 Runner（新增）
148+
fastdeploy/entrypoints/openai/serving_images.py # 图像生成 API（新增）
149+
```
150+
151+
如需开发自定义算子：
152+
```
153+
custom_ops/gpu_ops/
154+
└── diffusion_ops/ # 扩散模型专用算子（按需）
155+
├── fused_adaln.cu # 融合 adaLN 算子
156+
└── patchify.cu # 融合 patchify/unpatchify 算子
157+
```
158+
159+
<!-- PLACEHOLDER_PHASE1 -->
160+
161+
---
162+
163+
### Phase 1: 基础框架搭建 (1 周)
164+
165+
**目标**: 建立扩散模型的基类、配置系统和推理引擎骨架。
166+
167+
* **新增** `fastdeploy/model_executor/diffusion_models/diffusion_base.py`：定义文生图推理的统一接口（如 `encode_prompt`, `denoise_step`, `generate` 等）。
168+
* **修改** `fastdeploy/config.py`：
169+
* 新增 `DiffusionConfig` 数据类，包含步数、引导强度、宽高、VAE Tiling 等配置。
170+
* 在 `FDConfig` 中支持 `runner_type = "diffusion"`。
171+
172+
173+
* **新增** `fastdeploy/engine/diffusion_engine.py`：实现轻量级引擎，负责管理扩散推理的生命周期。
174+
* **新增** `fastdeploy/worker/diffusion_model_runner.py`：继承 `ModelRunnerBase`，负责根据模型类型加载对应的 Pipeline。
175+
176+
**里程碑**: 完成基础框架后，具备扩散模型的加载和空跑能力。
177+
178+
179+
### Phase 2: 共享组件实现 (1 周)
180+
181+
**目标**: 实现 SD3 和 Flux 共享的核心组件——文本编码器、VAE、调度器。
182+
183+
* **新增** `components/text_encoders.py`：实现 CLIP-L、OpenCLIP-G 和 T5-XXL 文本编码器组。
184+
* **新增** `components/vae.py`：实现 16 通道 VAE 编解码器，支持 VAE Tiling 优化。
185+
* **新增** `components/scheduler.py`：实现 `FlowMatchEulerDiscreteScheduler` 调度器。
186+
* **新增** `components/embeddings.py`：实现时间步编码、Patch 嵌入以及 Flux 专用的 2D RoPE。
187+
188+
**里程碑**: 完成共享组件后，文本编码、VAE 解码、调度器均可独立测试验证。
189+
190+
### Phase 3: SD3 Transformer 组网 & Phase 4: Flux Transformer 组网
191+
192+
**目标**: 实现 SD3 的 MMDiT（Multi-Modal Diffusion Transformer）骨干网络和完整推理 pipeline。实现 Flux 的混合 Transformer 架构（Double Stream + Single Stream）和完整推理 pipeline。
193+
194+
* **新增** `layers/adaptive_norm.py`：实现 adaLN-Zero 和 adaLN-Single 自适应归一化层。
195+
* **新增** `layers/dit_attention.py`：实现 Joint Self-Attention（联合注意力机制）。
196+
* **新增** `layers/dit_block.py`：实现 MMDiT Block（SD3）以及 Double/Single Stream Block（Flux）。
197+
* **新增** `sd3/` 目录：包含 SD3 特有的 Transformer 组网和推理 Pipeline。
198+
* **新增** `flux/` 目录：包含 Flux 特有的混合 Transformer 组网和推理 Pipeline。
199+
200+
**里程碑**: SD3 模型可加载权重并完成端到端文生图推理。Flux 模型可加载权重并完成端到端文生图推理，支持 schnell 和 dev 两个变体。
201+
202+
### Phase 5: API 服务与 CLI 集成 (0.5 周)
203+
204+
**目标**: 提供 OpenAI Images API 兼容的服务接口和 CLI 入口。
205+
206+
* **修改** `fastdeploy/entrypoints/openai/protocol.py`：新增 `ImageGenerationRequest` 和 `ImageGenerationResponse` 协议类。
207+
* **新增** `fastdeploy/entrypoints/openai/serving_images.py`：实现符合 OpenAI 标准的 `/v1/images/generations` 服务接口。
208+
* **修改** `fastdeploy/entrypoints/openai/api_server.py`：注册图像生成路由。
209+
* **修改** `fastdeploy/entrypoints/cli/main.py`：新增 `run_diffusion` 子命令支持离线推理。
210+
211+
**里程碑**: 用户可通过 CLI 启动扩散模型服务，并通过 OpenAI 兼容 API 调用图像生成。
212+
213+
### Phase 6: 量化与并行适配 (1 周)
214+
215+
**目标**: 适配 FastDeploy 现有的量化和张量并行能力，降低显存占用并支持多卡推理。
216+
217+
* **修改** `layers/dit_attention.py` 与 `dit_block.py`：将标准线性层替换为 `get_quantized_linear`，以支持 FP8、WINT4/8 量化。
218+
* **新增** `custom_ops/gpu_ops/diffusion_ops/`：实现高性能 C++/CUDA 融合算子（如 `fused_adaln`）。
219+
220+
**里程碑**: Flux 12B 可在单卡 24GB GPU 上以 FP8 运行，或在 2 卡上以 FP16 张量并行运行。
221+
222+
# 五、测试和验收的考量
223+
224+
## 1、单元测试
225+
226+
```
227+
tests/diffusion_models/
228+
├── test_vae.py # VAE 编解码正确性
229+
├── test_scheduler.py # FlowMatch 调度器步进正确性
230+
├── test_text_encoders.py # 文本编码输出形状和数值
231+
├── test_sd3_transformer.py # SD3 MMDiT 前向输出形状
232+
├── test_flux_transformer.py # Flux Transformer 前向输出形状
233+
├── test_dit_blocks.py # MMDiT Block / Single-Double Stream Block
234+
└── test_quantization.py # 量化后模型输出一致性
235+
```
236+
237+
## 2、端到端测试
238+
239+
- SD3 Medium 文生图：加载权重，生成 1024x1024 图像，验证输出为合理图像（非噪声）
240+
- Flux schnell 文生图：4 步生成，验证输出质量
241+
- Flux dev 文生图：28 步生成，与 PPDiffusers 参考输出对比 PSNR/SSIM
242+
- 量化推理：FP8/WINT8 量化后生成图像，与 FP16 基线对比质量
243+
244+
## 3、API 测试
245+
246+
- `/v1/images/generations` 端点：请求/响应格式兼容性
247+
- 并发请求：多请求批量处理正确性
248+
- 错误处理：无效参数、超时等边界情况
249+
250+
## 4、性能基准
251+
252+
| 指标 | SD3 Medium | Flux schnell | Flux dev |
253+
|------|-----------|-------------|---------|
254+
| 单图延迟 (1024x1024) | 目标 < 5s | 目标 < 3s | 目标 < 10s |
255+
| 吞吐量 (images/min) | 待测 | 待测 | 待测 |
256+
| 显存占用 (FP16) | < 12GB | < 24GB | < 24GB |
257+
| 显存占用 (FP8) | < 8GB | < 14GB | < 14GB |
258+
259+
# 六、可行性分析
260+
261+
## 可行性分析
262+
263+
1. **组网参考充分**: PPDiffusers 已有完整的 Paddle 实现，可直接参考模型结构和权重映射
264+
2. **基础设施成熟**: FastDeploy 的量化、并行、服务框架可直接复用
265+
3. **架构兼容**: 扩散模型的 Transformer 结构与 LLM 共享大量基础组件（线性层、注意力、归一化）
266+
4. **风险可控**: 扩散模型推理流程相对固定（编码→去噪→解码），不涉及复杂的调度策略
267+
268+
# 七、影响面
269+
270+
## 新增模块
271+
272+
本任务为纯新增功能，不修改 FastDeploy 现有 LLM 推理逻辑：
273+
274+
- 新增 `fastdeploy/model_executor/diffusion_models/` 目录（扩散模型组网代码）
275+
- 新增 `fastdeploy/engine/diffusion_engine.py`（扩散推理引擎）
276+
- 新增 `fastdeploy/worker/diffusion_model_runner.py`（扩散模型 Runner）
277+
- 新增 `fastdeploy/entrypoints/openai/serving_images.py`（图像生成 API）
278+
- 可选新增 `custom_ops/gpu_ops/diffusion_ops/`（融合算子）
279+
280+
## 需修改的现有文件
281+
282+
| 文件 | 修改内容 |
283+
|------|---------|
284+
| `fastdeploy/config.py` | 新增 `DiffusionConfig`，`runner_type` 支持 `"diffusion"` |
285+
| `fastdeploy/entrypoints/openai/api_server.py` | 注册 `/v1/images/generations` 路由 |
286+
| `fastdeploy/entrypoints/openai/protocol.py` | 新增 `ImageGenerationRequest/Response` |
287+
| `fastdeploy/entrypoints/cli/main.py` | 新增 `run_diffusion` 子命令 |
288+
289+
## 文档交付
290+
291+
- `docs/get_started/sd3_flux.md` — SD3/Flux 部署指南
292+
- `docs/features/image_generation.md` — 图像生成 API 使用说明
293+
- `docs/quantization/diffusion_quant.md` — 扩散模型量化指南

0 commit comments

Comments
 (0)