教程 ↗

Qwen-Image-2.1-Turbo 接入:为什么只改推理步数不生效

用 QwenImage21Pipeline 加载 Turbo 权重,保留自带的 8 步采样调度,核对 Diffusers 依赖、KV 缓存和图片编辑输入。

采样路径将图像逐步整理成形的线稿示意

把现有 Diffusers 脚本换成 Qwen/Qwen-Image-2.1-Turbo 后,先检查管线是否读到了权重自带的采样调度。这个版本把推荐的 8 步调度一起保存进了 checkpoint;按照官方模型卡,只传 num_inference_steps 不会覆盖它。

这会影响常见的迁移方式:旧脚本可能统一传入 num_inference_steps=30,日志也把请求参数记成 30,但实际调度仍取自 checkpoint。接入时应该先跑通官方默认配置,再决定要实验哪些参数。下面按官方文档整理加载与检查步骤,未在本机执行模型推理,因此没有速度、显存或画质实测数据。

先确认管线和依赖

Turbo 是 Qwen-Image-2.1 的加速 checkpoint,官方介绍为 7B 视觉生成架构,支持文生图与图片编辑,使用 QwenImage21Pipeline 加载。模型卡要求兼容 CUDA 的 PyTorch,并给出以下安装方式:

pip install git+https://github.com/huggingface/diffusers.git
pip install "transformers>=5.17.0" accelerate pillow

这里直接安装 Diffusers 源码有具体原因:需要包含 PR #14950 引入的管线采样 sigmas 支持。若旧环境无法导入 QwenImage21Pipeline,先核对实际安装版本和当前 Python 环境,继续改生成参数解决不了缺少管线的问题。

Qwen 官方英文模型卡中的八步采样说明和安装依赖

Qwen 官方模型卡列出了 8 步调度、KV 缓存和所需依赖。完整命令见正文。

安装验证通过后,把 PyTorch、Diffusers 和 Transformers 的实际版本记录到自己的运行记录中。由于源码安装会随上游变化,后续复现还需要保留所用提交。模型卡没有在这里给出经过核验的最低显存门槛,不能仅凭“7B”推算一张显卡一定装得下。

用默认调度建立第一份输出

下面沿用官方文生图调用,缩短了示例提示词;这是一段文档适配示例,图片内容与效果尚未验证。

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1-Turbo",
    dtype=torch.bfloat16,
).to("cuda")

prompt = (
    "A portrait editorial illustration of a small blue bicycle "
    "beside a white wall, soft daylight, generous empty space."
)

image = pipe(
    prompt=prompt,
    width=1696,
    height=2528,
    use_kv_cache=True,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]

image.save("t2i.png")

这份调用保留了三个容易在封装层丢掉的设置:

  • 明确加载 QwenImage21Pipeline,使 checkpoint 的配置由相应管线读取。
  • 保留默认采样调度,不加一组从其他模型复制的 sigmas。
  • 开启 use_kv_cache=True,按官方说明在去噪步骤间复用文本和参考图的上下文。

模型默认 CFG 为 1。第一次接入先使用这套默认组合,保存提示词、seed、宽高、依赖版本和实际输出,再做同条件比较。固定 seed 有助于控制一次比较的变量,但不同硬件和依赖版本下的逐像素一致性仍需自己核验。

步数参数和采样调度要分开记录

num_inference_steps 是你传给调用的参数;sigmas 描述每一步使用的噪声水平。Turbo 的推荐调度已经保存在 checkpoint 中,官方明确说明:单独设置前者不会覆盖保存的调度。若你正在做统一图片生成服务,界面上显示的“步数”应能追溯到实际采用的调度,避免把请求值当成执行值。

显式传入调用时的 sigmas 可以覆盖 checkpoint 调度,但官方尚未评估这个 checkpoint 在其他调度下的表现。需要实验时,把它作为独立配置保留,比较同一提示词、seed、分辨率下的输出;不要把“成功生成文件”直接记录成“质量与默认版本一致”。

如果还在接入其他生成模型,可以对照 FLUX 3 Image Klein 的蒸馏推理配置。两者都需要核对模型专属默认值,FLUX 的 prompt upsampler 与这里的采样调度承担不同职责,不能直接互换参数。

切换到图片编辑

官方编辑示例复用同一个管线,把参考图转换为 RGBA 后传入 image,输出尺寸采用 2048 × 2048。下面将官方在线样本替换为你自己的本地文件,保留调用结构:

from PIL import Image

input_image = Image.open("input.png").convert("RGBA")

image = pipe(
    prompt="Keep the object shape and replace the background with a plain blue wall.",
    image=input_image,
    width=2048,
    height=2048,
    use_kv_cache=True,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]

image.save("edit.png")

RGBA 是输入处理方式;这段代码没有要求输出背景透明,也没有保证原图每个边缘都会被保留。检查输出时,应把主体形状、文字、遮挡和边缘分别与输入比较。若需要把输出做成固定尺寸的网页素材,可继续阅读 1024 × 1024 图片的裁剪与补边方法。

官方给出的横向 16:9 预设为 2752 × 1536,纵向 9:16 为 1536 × 2752;方图为 2048 × 2048。先从相应预设开始,比任意缩放宽高更容易与官方例子对照。

发布或商用集成前,还需核对 Qwen Research License Agreement 对用途的具体约束。模型卡标注的是 qwen-research。本篇完成的是接入参数梳理;在你自己的 GPU 上得到第一份输出后,再补上实际耗时、显存和同任务画质比较,才有依据决定是否替换现有生成链路。

← 返回列表