Diffusers 模块化扩散管线算子库 (Diffusers Library)

借助模块化 🧨 Diffusers 框架生态，自由构建灵活多变的多模态媒体生成与编辑工作流。

Diffusers 算子库专为希望对扩散推理全生命周期获得深度控制的创作者而设计。与直接执行固定黑盒、端到端的单一“生成图像”节点不同，它允许你将整个扩散演化过程彻底解构为多个可自由串联、组合的独立阶段——使你能够清晰审查、复用并定制化重塑管线的每一个微观计算切片。

实验性特性 — 处于活跃演进与迭代中

该库的底层 API 结构、算子连线接口、工作流模板以及代码组织架构可能在没有提前通知或迁移策略的情况下随时调整。如需生产环境稳定性，请显式锁定特定的 Git Commit 校验和；在拉取最新版本更新时请做好兼容性适配准备。

官方开源代码仓库：griptape-ai/griptape-nodes-library-diffusers
硬件与运行依赖要求：支持 GPU 加速计算的环境（CUDA 或 Apple Silicon MPS）
算子选择器分类：在算子面板中统一归类于 ModularDiffusion/… 树形分支

安装与集成途径 (Installation)

在编辑器顶部菜单栏依次打开 Manage → Library Management，点击 Add Library 并粘贴 Git 仓库地址：

https://github.com/griptape-ai/griptape-nodes-library-diffusers

在弹出的 Advanced Options (高级选项) 面板中，可指定锁定特定的 Git 分支 (Branch)、版本标签 (Tag) 或 Commit 哈希。亦可通过命令行 CLI 极速安装：

gtn libraries download https://github.com/griptape-ai/griptape-nodes-library-diffusers

有关常规的下载、版本升级与依赖排错，请参阅算子库管理手册。

模型文件下载与缓存机制 (Model downloads)

首次使用某个模型时，系统会自动将其拉取下载到 Hugging Face 的本机默认缓存区（Linux/macOS 默认为 ~/.cache/huggingface/hub，Windows 默认为 %USERPROFILE%\.cache\huggingface\hub）。若需更改至大容量独立固态硬盘存储，请在启动引擎前配置好 HF_HOME 环境变量。有关账号授权及访问 Token 登记，请参阅 Hugging Face 模型接入指南。

核心底层工作机制 (How it works)

一条典型的解耦扩散流水线通常由以下核心阶段构成：

单次构建管线：通过 Pipeline Builder 完成一次性实例化构建，并在后续的批量生成执行中持久化常驻复用；
初始化或加载潜空间张量 (Latents)：生成随机高斯噪声、空张量、编码自现有图像/视频的特征张量，或直接读取磁盘上存储的 Tensor；
驱动多步扩散去噪：连接 Generate Media Latents 步进演进生成全新的潜变量——支持级联串接，轻松实现多阶段精炼 (Multi-stage) 或重绘扩散 (Rediffusion)；
潜变量后处理变换：在各个去噪阶段之间穿插执行张量代数运算（加/减/乘）、基于蒙版的空间混合合成或潜空间超分辨率重采样；
逆变换解码成片：使用 Decode Media Latent 算子将最终去噪完毕的潜变量张量还原反变换为直观的实体图像或连续视频流。

由于每个微元皆为一个独立的算子节点，你可以随心所欲地分流、级联与重排计算逻辑——这带来了单体黑盒节点无法企及的自由度，如：多阶段阶梯式画质精炼、ControlNet 多重堆叠融合、潜空间精准局部拼贴、视频首尾关键帧条件约束约束生成，以及无损潜空间升采样缩放。

支持的模型生态 (Supported models)

你可以在 Pipeline Builder 算子节点的 provider 下拉菜单中直接挑选目标骨干架构，当前原生支持：

Flux 与 Flux2（包含轻量高速版 Flux2-Klein）
Stable Diffusion XL (SDXL)
Qwen-Image（以及 Qwen-Edit 图像编辑变体）
Z-Image
LTX（视频生成底模）
LTX-2.x（文生视频、图生视频、视频重绘 (V2V)，支持单图/多图条件注入、连续视频前置条件约束、IC-LoRA 以及用于导出原生线性 HDR 画面的 HDR IC-LoRA）
WAN（文生视频与图生视频架构）

所有模型均直接从 Hugging Face 仓库按标准的 Diffusers 格式进行流式拉取（不支持直接挂载单体 .safetensors Checkpoint 权重——请统一使用 Hugging Face 的 Repo ID 标识）。此外，可在 Pipeline Builder 构建时无缝附加绑定多个 LoRA 微调适配层。

算子节点参考矩阵 (Node reference)

算子分类与编辑器节点拾取器内的层级严格镜像对齐：

1. 管线构建组 (Pipeline)

Modular Diffusion Pipeline Builder — 模块化扩散管线总装配器
ControlNet Pipeline — 挂载 ControlNet 空间结构控制网络
Load LoRA — 从磁盘或远程拉取 LoRA 微调权重
LoRA Pipeline — 将多个 LoRA 权重动态打包注入主干管线

2. 张量初始化组 (Create)

Create Noise Latents — 生成高斯随机噪声张量
Create Empty Latents — 初始化全零/空白潜空间基底

3. 去噪与推理处理组 (Processing)

Generate Media Latents — 驱动核心调度器执行去噪步进循环
Latent Upsampler — 对潜变量执行空间尺寸超分辨率升采样

4. 潜变量空间变换组 (Transform)

Add Latents — 潜变量张量逐元素相加
Subtract Latents — 潜变量张量逐元素相减
Multiply Latents — 潜变量张量逐元素标量/权重缩放
Latents Composite Mask — 依据 Alpha/二值蒙版对两路潜变量执行精准空间融合

5. 条件注入引导组 (Conditioning)

Configure ControlNet — 细粒度调节 ControlNet 的介入时序区间与引导强度权重
Media Generation Conditioning — 汇聚 Prompt 词嵌入、首尾参考帧等全维度多模态引导条件

6. 特征编码与反显解码组 (Encode / Decode)

Encode Media Latent — 将物理像素图像/视频通过 VAE 编码压入潜变量空间
Encode Masked Media Latent — 结合遮罩蒙版执行精准局部编码
Decode Media Latent — 将去噪完毕的潜变量张量反显还原为常规色彩像素
Decode HDR Latents — 解码具备原生高动态范围的 16 位/32 位 HDR 影视级线性像素

7. 数据存盘交互组 (IO)

Save Latent Tensor — 将中间潜变量张量无损序列化落盘为 .pt / .safetensors 文件

实时画面去噪预览 (Live previews)

开启实时画面预览功能后，引擎会在每一步或特定去噪步长将中间潜变量即时解码并流式回传至画布前端。非常适用于长周期视频渲染的过程监视，但会微幅牺牲整体推理吞吐速度：

在编辑器顶部菜单栏依次打开 Settings → Library Settings；
向下滚动定位至 Modular Diffusion Library 专属配置区域；
将 Enable Image Preview Intermediates 开关置为开启状态。

硬件性能榨取与显存调优指南 (Performance and memory)

Pipeline Builder 具备自动感知驻留能力：首次加载完毕后会在显存中智能维系管线对象，多次执行时直接命中热缓存，唯有在物理拓扑或核心超参发生变更时才会触发局部重构。

针对中低显存显卡（如 8GB~16GB 消费级显卡），构建器开放了细致入微的 Memory Optimization Strategy (显存调优策略) 档位选择：

Automatic (全自动模式)：Griptape Nodes 根据当前检测到的显卡体质与选定模型自动推断出兼顾速度与显存的最优平衡组合；
Manual (深度手动模式)：赋予你逐项操控硬件旋钮的绝对权限：
- Quantization mode (模型量化)：提供 fp8、int8 或 int4 规格（基于 optimum-quanto 或 bitsandbytes 引擎驱动）——大幅压缩 Transformer 骨干网络显存占用，仅微幅牺牲极少许动态画质；
- CPU offload strategy (显存/内存逐层卸载)：支持 Model（以子模块为单位卸载）或 Sequential（以单层 Layer 为粒度循环卸载）——在特定网络层处于闲置时将其动态置换回系统主机内存，极大拓展大模型容纳上限，但会带来主机总线交换开销；
- Attention slicing (自注意力切片)：将大尺寸 Attention 运算切分为微小分块并行串行计算；极具性价比的显存节省策略，仅带来极小幅速度衰减；
- VAE slicing (编解码分块切片)：以 Batch=1 的极限微批次逐个解码潜变量，完美杜绝大画幅反解时的瞬时爆显存 OOM；
- Transformer layerwise casting (逐层动态精度转换)：保持 Transformer 在低精度状态存储，并在计算前线按层级瞬时动态升阶计算。

调优建议：按需微调开启各项优化——每项参数均以不同程度的吞吐耗时置换宝贵的物理显存。Pipeline Builder 算子内部对每个参数均内嵌了提示徽章，悬停即可探查底层影响。

与 Advanced Media Library 共同载入时的显存冲突风险

Diffusers 算子库与 Advanced Media Library 在底层共享了多项上游庞大依赖包（如 diffusers、transformers、torch），且各自维护着独立的显存管线对象池。若在同一个运行会话中同时拖入并运行两个算子库中的重型模型，系统很可能在显存中同时常驻两份庞大的模型权重镜像，极易诱发 CUDA Out of Memory (OOM) 崩溃。在生产排期中，强烈建议在同一个工程中专一选用其中一个算子库；若必须混用，请务必在上述显存调优面板中开启积极的 CPU 卸载机制。

随库内附的标准工作流样板 (Workflow templates)

安装本算子库后，你可在模板库中即刻调取如下工业级开箱范例：

Text2Image — 标准文生图基础拓扑
MultistageText2Image — 粗模生成到精修细化的多阶段串联工作流
LoRAText2Image — 动态注入风格化 LoRA 权重的生图管线
ControlnetText2Image — 基于边缘/深度/姿态约束的受控空间生成
Image2Image — 图生图重绘与风格迁移流
FirstAndLastFrameImage2Video — 基于首尾双关键帧强约束的时序视频插值生成
LTX23-HDR-Text2Video-Upsample-Two-Stage — 结合 LTX 视频底模、原生 HDR 线性解码与两阶段潜变量空间超分辨率重采样的超高规格电影级视频管线

技术支持与社区反馈 (Support)

若在扩散推理或算子组合中捕获到底层异常，或有新增模型适配需求，欢迎前往 GitHub Issues 页面提交工单反馈。