Viggle/Qwen-Image-2.1-viggle-turbo · Hugging Face 来源：https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo

基于 Qwen 构建。 这是 Qwen/Qwen-Image-2.1 (https://huggingface.co/Qwen/Qwen-Image-2.1) 的一个经过少步数蒸馏的学生模型，由 Viggle 使用分布匹配蒸馏训练而成。它能够执行文本到图像生成和指令驱动的图像编辑（使用 1-3 张参考图像），仅需 6 次 transformer 前向传播，而非原始模型的 40 次，并且无需使用无分类器引导。其端到端速度比 40 步基础模型快约 5 倍，并且质量与之非常有竞争力：在官方 Qwen 示例上，两者在大多数提示词下几乎难以区分。最明显的差距在于细小、密集的文字，基础模型仍略胜一筹（使用 8 步可以缩小此差距）。您可以在演示空间 (https://huggingface.co/spaces/Viggle/Qwen-Image-2.1-viggle-turbo) 的“对比”标签页中亲自查看：其中包含 32 个 Qwen/Qwen-Image-2.1 空间 (https://huggingface.co/spaces/Qwen/Qwen-Image-2.1) 的示例，对比了 turbo 模型使用 6 步（5 个密集文字示例使用 8 步）与基础模型使用 40 步的结果，相同提示词、输入和随机种子，每次生成一张样本，以图像滑块形式呈现。复杂的编辑仍可能不及基础模型（已知限制 (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#known-limitations)）。

v0.2.1 (2026-09-24) — 请使用此版本：

• Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r256.safetensors — LoRA 适配器（rank 256，alpha 256，bf16，1.3 GB），在运行时加载于基础 transformer 之上。使用内置的 sigma 节点采样 6 步：sigmas=[1.0, 0.9375, 0.875, 0.75, 0.5, 0.25]（参见“用法”）。这正是**演示空间 (https://huggingface.co/spaces/Viggle/Qwen-Image-2.1-viggle-turbo)**运行的版本。
• Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r128.safetensors — 同一个适配器，截断为 rank 128（alpha 128，680 MB），被 ComfyUI 工作流 (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#comfyui) 使用。用法与 r256 相同；参见 rank 128 (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#rank-128) 了解其效果差距。

ComfyUI： 自定义节点和开箱即用的文本到图像/编辑工作流位于 comfyui/ (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo/tree/main/comfyui)；设置说明见 ComfyUI (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#comfyui)。 坦诚提醒：我并非 ComfyUI 的日常用户，此移植主要是借助 AI 编程助手凭感觉编写的。它已针对 diffusers 流水线进行了验证（ComfyUI 部分提供了数字），并能端到端运行，但可能存在粗糙之处。非常欢迎更熟悉 ComfyUI 的用户提出问题和修复方案。

v0.2.1 是某次训练的第 700 步检查点，其第 600 步检查点已于 2026-09-23 作为 v0.2 发布：增加了 100 个训练步数，使用相同配方和 6 步调度。与 v0.2 相比，它略微更清晰（拉普拉斯清晰度 0.0199 对比 0.0187），多样性略有提高（为基准模型的 0.98 倍 对比 0.97 倍），组合漂移率同为 0%。v0.2 文件（Qwen-Image-2.1-viggle-turbo-v0.2-5step-lora-r256.safetensors、r128 截断版、peft_v0.2/）保持不变留存在仓库中；可使用相同的 6 步节点对其进行采样（其文件名中的 5step 是其发布时的调度，参见关键规则 (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#rules-that-matter)）。

与 v0.1 相比的变化，基于我们保留的 96 个用户请求（文本到图像和编辑）测试集，与使用其官方提示词增强的 40 步基础模型对比：

1 每提示词 8 个随机种子下的平均 DINOv2 补丁距离，对 40 步基础模型取比值（1.00 = 与基准模型同等多样）。v0.1 导致不同种子生成几乎相同的布局；v0.2 保持了基准模型的分散度。 2 对于相同提示词和种子，学生模型图像质心相对于基础模型输出的平均水平漂移（以图像宽度为单位）；0 表示学生模型放置主体的位置与基础模型一致。 3 96 个提示词中，学生模型组合与基础模型有明显差异（质心漂移超过 0.05 个图像宽度）的比例。

实践中，v0.2 和 v0.2.1 比 v0.1 更明显地遵循提示词和参考图像——更少出现指令丢失或合并，更少出现重复主体的重影——并在清晰度上匹配了基础模型（v0.1 LoRA 在清晰度上偏软）。v0.2 文件和 v0.1 产物（transformer/ 全量微调版和 r64 LoRA，均为 4 步）保留在仓库中以供复现；没有理由优先使用它们。

已知限制。 复杂编辑（多参考图像合成、换脸、保持身份的编辑、包含多个约束的指令）仍可能不及 40 步基础模型。我们将随着蒸馏技术的改进持续更新此仓库。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#whats-inside 包含内容

Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r256.safetensors  # v0.2.1 LoRA (rank 256, alpha 256), diffusers key 格式, bf16 <- 使用此文件
peft_v0.2.1/  # 同一个 v0.2.1 适配器，peft key 格式, F32 (训练格式)
Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r128.safetensors  # v0.2.1 LoRA 截断至 rank 128 (alpha 128), diffusers key 格式, bf16
comfyui/  # ComfyUI 自定义节点 (viggle_turbo.py), 文本到图像和编辑工作流, 示例输入
scheduler/scheduler_config.json  # 基础调度器配置，含 shift_terminal: null
Qwen-Image-2.1-viggle-turbo-v0.2-5step-lora-r256.safetensors  # v0.2 LoRA (同一次训练的第 600 步), 供参考
Qwen-Image-2.1-viggle-turbo-v0.2-5step-lora-r128.safetensors  # v0.2 LoRA 截断至 rank 128, 供参考
peft_v0.2/  # v0.2 适配器，peft key 格式, F32
Qwen-Image-2.1-viggle-turbo-4step-lora-r64.safetensors  # v0.1 LoRA (rank 64), 4 步, 供参考
peft/  # v0.1 适配器，peft key 格式, F32
transformer/  # v0.1 全量微调的 transformer (bf16), 4 步, 供参考
LICENSE, NOTICE, README.md

已发布的检查点： v0.2.1 是某次 LoRA 运行（在 attention、image-MLP、modulation 和 timestep-embedder 投影上 rank 为 256）的第 700 步 EMA 学生模型（v0.2 是第 600 步），该训练在 DMD 目标之上增加了 SenseFlow 风格的段内引导（学生模型每个段上的速度回归到教师模型的速度上）和提示词增强的教师目标；它在 4 步调度上训练，采样时将第一个（噪声最高的）段分割成三段（6 步），这消除了纯 4 步展开（5 步，段分割为两段，是初始调度；6 步在所有跟踪指标上均严格更优，权重相同）中的细节损失、重影和组合漂移。LoRA 永远不会合并到 transformer 中——合并到 bf16 格式是有损的，运行时加载才是精确的。文本编码器、VAE 和处理器未重新分发；它们从基础仓库加载。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#install 安装

pip install -U torch "transformers>=5.17,<6" accelerate safetensors peft pillow
pip install "git+https://github.com/huggingface/diffusers.git@80c7ed262aeffbeb43ef13ae04baeb9b84515a69"

QwenImage21Pipeline 尚未在发布的 diffusers 中，因此需要固定 git 安装。需要 peft。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#usage 用法

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#load-the-v021-lora 加载 v0.2.1 LoRA

import torch
from diffusers import QwenImage21Pipeline, FlowMatchEulerDiscreteScheduler

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16)
pipe.load_lora_weights(
    "Viggle/Qwen-Image-2.1-viggle-turbo",
    weight_name="Qwen-Image-2.1-viggle-turbo-v0.2.1-6step-lora-r256.safetensors",
)
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_pretrained(
    "Viggle/Qwen-Image-2.1-viggle-turbo", subfolder="scheduler"
)
pipe.to("cuda")

STEPS, SIGMAS = 6, [1.0, 0.9375, 0.875, 0.75, 0.5, 0.25]  # v0.2.1 调度；每次调用都传入这两个参数

v0.1 学生模型 (4 步，供参考)

# v0.1 全量微调的 transformer
from diffusers import QwenImage21Transformer2DModel
transformer = QwenImage21Transformer2DModel.from_pretrained(
    "Viggle/Qwen-Image-2.1-viggle-turbo", subfolder="transformer", torch_dtype=torch.bfloat16
)
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", transformer=transformer, dtype=torch.bfloat16)

# v0.1 LoRA
pipe.load_lora_weights("Viggle/Qwen-Image-2.1-viggle-turbo", weight_name="Qwen-Image-2.1-viggle-turbo-4step-lora-r64.safetensors")

# 两者：使用上述发布的调度器，然后设置 num_inference_steps=4 且不传 sigmas= 参数

切勿叠加两个学生模型（将 LoRA 加载到全量微调的 transformer 上，或同时使用两个 LoRA）。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#text-to-image 文本到图像

image = pipe(
    prompt="一位老渔夫在修理渔网的工作室肖像，温暖的轮廓光，85mm镜头。",
    height=1024,
    width=1024,
    num_inference_steps=STEPS,
    sigmas=SIGMAS,
    true_cfg_scale=1.0,  # 无 CFG (也是默认值)
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("out.png")

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#image-editing-13-reference-images 图像编辑 (1-3 张参考图)

from diffusers.utils import load_image

image = pipe(
    # 与上面相同的 pipe 对象
    prompt="将背景替换为日落海滩，保持主体不变。",
    image=[load_image("input.png")],  # 列表；顺序固定 image_1, image_2, ...
    output_resolution=1024,
    num_inference_steps=STEPS,
    sigmas=SIGMAS,
    true_cfg_scale=1.0,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#rules-that-matter 关键规则

• 使用 num_inference_steps=6 和 sigmas=[1.0, 0.9375, 0.875, 0.75, 0.5, 0.25]，true_cfg_scale=1.0，无需负面提示词。 这些是原始 sigma 节点：流水线会像对其默认节点一样应用其分辨率相关的时间偏移，因此对于任何分辨率都请如上所述传入它们。它们是 4 步训练节点 linspace(1, 1/4, 4) 的变体，将第一个（噪声最高的）段 1 → 0.75 分割成三段。num_inference_steps=4 且不指定 sigmas= 是训练调度，同样有效，但细节和多样性略少（见上表）。
• 如果您更改步数，请仅在高端噪声端增加或减少步骤。 组合关系在原始 sigma 1 和 0.875 之间决定（偏移后，大约是 1024² 分辨率下噪声范围的前 5%），在那里进行一个大的 Euler 步会导致布局重影和漂移；低噪声节点 0.75, 0.5, 0.25 是学生模型训练的目标落点，移动它们（例如 6 步使用 [1, 0.958, 0.917, 0.875, 0.625, 0.375]）会使每张图像明显变软（拉普拉斯清晰度 0.014 对比 0.020）。因此保持 0.875, 0.75, 0.5, 0.25 并将 1 → 0.875 均匀分割：5 步 [1, 0.875, 0.75, 0.5, 0.25]（初始调度，4% 提示词漂移），如上所述的 6 步（0%），7 步 [1, 0.9583, 0.9167, 0.875, 0.75, 0.5, 0.25]（也是 0%，略清晰，但不比 6 步明显更好）。均匀的 linspace 调度配合其他步数，以及 CFG，都没有帮助。
• 使用发布的调度器配置（或 FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, shift_terminal=None)）。基础配置中的 shift_terminal: 0.02 会破坏最后一步。
• 保持 LoRA scale 为 1.0（alpha 等于 rank）。
• 参考图像的顺序决定了提示词中 image_1/image_2 指代哪张图像。如果未指定 height/width，输出宽高比将跟随最后一张参考图（在 ComfyUI 中：跟随第一张）。训练中最多使用了 3 张参考图。
• 建议使用官方 PE-T2I (https://huggingface.co/Qwen/Qwen-Image-2.1-PE-T2I) / PE-I2I (https://huggingface.co/Qwen/Qwen-Image-2.1-PE-I2I) 重写器重写提示词：学生模型是在提示词增强的教师目标上蒸馏的，重写器有助于改善构图和渲染文字。上述数据使用了它们。原始提示词也可以工作。
• peft 用户可以直接加载 peft_v0.2.1/：pipe.transformer.load_lora_adapter("Viggle/Qwen-Image-2.1-viggle-turbo", subfolder="peft_v0.2.1", weight_name="adapter_model.safetensors", prefix=None) — 权重相同，键名不同；选择一种路径，不要同时使用。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#resolutions 分辨率

训练尺寸遵循基础模型的 calculate_dimensions(area, aspect_ratio) 并四舍五入到 32 的倍数。文本到图像在 1024² 和 2048² 面积上训练，编辑在 1024² 和 1536² 面积上训练（参考图像始终编码为 1024² 面积）。其他尺寸也可工作；这些是训练数据集中中的分布。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#rank-128 Rank 128

...-lora-r128.safetensors 是通过精确的逐层 SVD（其更新量 ΔW = B A）将 r256 适配器截断得到的，这是最佳的 rank-128 近似（Eckart–Young）。逐层来看，它保留了更新量 83-100% 的能量（中位数 95%）；其丢弃的部分低于基础权重的 0.05%。在 96 个保留请求上，使用相同的噪声和提示词，其图像与 r256 适配器的差异为 LPIPS 0.0244。即使以全秩重新分解 r256 适配器（除了浮点舍入外没有任何改变），差异也已经达到 0.0239，因此 r128 处于该噪声基线（rank 64：0.0267）。LPIPS 数字是在 v0.2 版本对上测量的；v0.2.1 的截断具有相同的频谱（每层保留 83-100% 能量，中位数 95%）。

https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo#comfyui ComfyUI

此 ComfyUI 移植主要是凭感觉编写的：我不是 ComfyUI 的日常用户，节点和工作流主要借助 AI 编程助手编写。已验证的内容：sigma 调度与 diffusers 浮点精度匹配，与 diffusers 的图像差距见下表。工作流的人体工程学和非常规设置未经充分测试；如果有问题，请发起讨论。使用 ComfyUI 0.37.0（前端 1.53.6）测试，该版本原生支持 Qwen-Image-2.1。 在 comfyui/ (https://huggingface.co/Viggle/Qwen-Image-2.1-viggle-turbo/tree/main/comfyui) 中：

• viggle_turbo.py — 两个自定义节点。将其复制到 ComfyUI/custom_nodes/ 并重启 ComfyUI。
• Qwen-Image-2.1-viggle-turbo-t2i.json、Qwen-Image-2.1-viggle-tbo-edit.json — 工作流（拖入 ComfyUI）。每个都有一个说明设置和可选提示词增强组的便签。
• input/woman2.webp、input/cat.webp — 编辑工作流的示例参考图；将它们复制到 ComfyUI/input/。像演示空间 (https://huggingface.co/spaces/Viggle/Qwen-Image-2.1-viggle-turbo) 中的参考照片一样，它们来自 black-forest-labs/flux-klein-9b-kv (https://huggingface.co/spaces/black-forest-labs/flux-klein-9b-kv) 空间。 模型文件（工作流中包含其下载链接）： 基础文件来自 Comfy-Org，与 ComfyUI 自身的 Qwen-Image-2.1 模板使用的相同。工作流默认使用 int8 的 transformer 和文本编码器、r128 LoRA 并开启提示词增强器；在所有模型保持加载的情况下，处理 1248 × 832 图像时 VRAM 峰值占用为 26 GB。bf16 文件