什么是 Qwen-Image-2.1?
Qwen Image 2.1 是一个统一的图像生成与编辑模型。
其视觉生成组件包含 70 亿个参数。该模型支持文生图生成、原生透明度、多张参考图,以及通过标注或掩膜引导的局部编辑。本教程聚焦基于单一参考图的 RGB 编辑。
模型本身已经具备编辑能力。我们的应用是在此基础上搭建工作流:选择输入、审阅候选、管理已接受的帧并导出。我们不进行新模型训练,也不添加运动模块。
最终的 GIF 播放的是独立生成的静态图像。它可以展示姿势变化与视觉变化,但并不等同于时间一致的视频生成。
Qwen Image 2.1 的工作原理
其 官方架构 描述指出了四个主要组件:
|
组件 |
规格 |
角色 |
|
视觉 Transformer |
32 层、70 亿参数的单流扩散 Transformer(DiT) |
在共享流中处理条件与目标图像的 tokens |
|
文本与图像编码器 |
Qwen3-VL 8B |
将指令与参考图编码为统一表征 |
|
图像自动编码器(VAE) |
64 潜变量通道、支持 RGBA、16× 空间压缩 |
将图像转换为紧凑潜变量,并将生成的潜变量解码为像素 |
|
生成过程 |
流匹配,采用 Euler 离散调度与动态移位 |
迭代更新目标图像潜变量,趋近生成图像 |
视觉 Transformer 含有 70 亿个参数。该统计不包括文本与图像编码器以及VAE。
VAE 的 64 个通道指的是其潜变量表征,并非 64 个输出颜色通道。
RGBA 输出包含红、绿、蓝和 Alpha 通道。应用会将上传内容展平为 RGB,因此未展示模型对原生透明度的支持。
阅读注意力示意图
Qwen Image 2.1 使用混合粒度的注意力掩码,彩色单元格允许注意力,灰色单元格阻断注意力。

图 1: Qwen Image 2.1 的混合粒度注意力架构(Qwen 博文)
按行阅读示意图:Q 表示查询 tokens,K 表示其可关注的 tokens。序列包含系统前缀、可选的输入图像、编辑指令和目标图像。
文本使用因果注意力,因为文本 token 可以关注自身及更早的位置。同一图像块内的 tokens 可以双向相互关注。
这就形成了图 1 中的三角形文本区域与实心图像块。
掩码规则将这种组合表达为:
allowed = (q_idx >= kv_idx) or same_image_block
这是一条针对一对 token 位置的概念性规则,并非要粘贴到 Notebook 里的额外设置。它允许关注更早的位置,并在每个图像块内实现全连接注意力。
为什么可以缓存前缀?
系统前缀、参考图像和指令都无法关注到后面的目标图像块。
因此,随着目标图像更新,它们的表征无需改变。
Qwen 会在第一个去噪步骤中计算它们的注意力键和值,并在后续步骤中复用它们。目标图像 tokens 仍需在每一步计算,关注缓存的前缀与彼此。
以 40 步为例,固定前缀可在第一步后复用;这并不意味着 40 倍提速,因为仍有大量目标图像计算。
该缓存复用发生在一次生成内部的各个去噪步骤之间。这并不代表模型会记住早前的用户请求,或我们的应用会自动在不同的独立编辑中复用同一缓存。
演示:用 Qwen Image 2.1 构建图像编辑器
在构建应用之前,先将模型设置与应用决策区分开来。请注意,增加步数并不能修复一个会不断把受损图像重新输入模型的流水线。
|
设置 |
使用的值 |
重要性 |
|
参考图像 |
最终应用的每次编辑都使用原始图像 |
避免将一个生成帧的伪影传递到下一帧 |
|
分辨率 |
1024 |
在此后端中约等于一百万像素的编辑目标 |
|
推理步数 |
40 |
主实验中使用的采样预算 |
|
随机种子 |
42 |
在测试指令时固定采样种子 |
|
CFG |
1.0 |
与提供的工作流一致;在该值下,标准负分支引导不起作用 |
|
采样器/调度器 |
Euler / simple |
保持提供的采样配置不变 |
|
Denoise |
1.0 |
匹配该指令编辑工作流;这不是传统的低去噪 img2img 配方 |
|
VAE 解码 |
最终配置中为非分块(untiled) |
在开发过程中观察到画质提升后选定 |
|
权重 |
INT8 ConvRot 图像模型与文本编码器;BF16 VAE |
该演示使用的节省内存的后端 |
|
CPU 编码器/参考缓存卸载 |
起初禁用 |
在 A100 上无需启用这些额外卸载设置也能运行 |
这些是本项目的可用设置,但并非全局最优配置。我们没有对步数、CFG、采样器或量化格式进行系统化遍历。
采样器的取值来自 image-edit 工作流,这让我能在低显存环境中运行该模型。
步骤 1:准备 Colab 环境
记录的运行时环境为 NVIDIA A100-SXM4-40GB,主机内存 83.5 GiB。
我使用 alesha-pro 安装包 来安装 ComfyUI 并下载量化权重。
请注意,您需要预留约 45 GB 的可用存储,包括环境、模型、缓存与输出。
高内存运行时有助于加载与卸载过程中的缓冲。
首先,设置路径并检查 GPU:
import sys, os, json, time, uuid, shutil, subprocess, copy, io, threading
from pathlib import Path
from PIL import Image, ImageDraw, ImageFilter, ImageOps
import numpy as np
import requests
import gradio as gr
from IPython.display import display, Image as DisplayImage
ROOT = Path('/content/qwen_gif_demo')
ROOT.mkdir(parents=True, exist_ok=True)
TOOLS = ROOT / 'tools'
COMFY = ROOT / 'ComfyUI'
RUNS = ROOT / 'runs'
RUNS.mkdir(exist_ok=True)
REPO_REV = 'dc0083c0d17581f04ebbca962771e36f82f31af8'
BASE = 'http://127.0.0.1:8188'
def run_cmd(args, **kwargs):
print('Running:', ' '.join(map(str, args)), flush=True)
subprocess.run(list(map(str, args)), check=True, **kwargs)
if not shutil.which('nvidia-smi'):
raise RuntimeError('Select a GPU runtime before continuing.')
print(subprocess.check_output(['nvidia-smi'], text=True))
如果 Colab 仍在使用 CPU 运行时,GPU 检查会停止执行;在安装前我们还会打印主机内存与可用磁盘空间的详情。
导入内容较为基础,包括 Python 标准库,用于处理文件路径、JSON 工作流、后端进程、计时及后台监控。
Pillow 与 NumPy 负责图像处理,Requests 与 ComfyUI 通信,Gradio 提供界面,IPython 用于在 Notebook 中显示图像。
将后端与 UI 分离安装
ComfyUI 运行在其独立的虚拟环境中。Notebook 内核负责上传、HTTP 请求与 Gradio。
if not TOOLS.exists():
run_cmd(['git', 'init', TOOLS])
run_cmd(['git', '-C', TOOLS, 'remote', 'add', 'origin', 'https://github.com/alesha-pro/tools.git'])
run_cmd(['git', '-C', TOOLS, 'fetch', '--depth', '1', 'origin', REPO_REV])
run_cmd(['git', '-C', TOOLS, 'checkout', '--detach', 'FETCH_HEAD'])
assert subprocess.check_output(['git', '-C', str(TOOLS), 'rev-parse', 'HEAD'], text=True).strip() == REPO_REV
PKG = TOOLS / 'qwen-image-2.1'
VERSIONS = json.loads((PKG / 'install/versions.json').read_text())
print('Pinned backend:', VERSIONS)
driver = subprocess.check_output(['nvidia-smi', '--query-gpu=driver_version', '--format=csv,noheader'], text=True).splitlines()[0]
# Conservative selector; the backend CUDA smoke test is authoritative.
TORCH_INDEX = 'https://download.pytorch.org/whl/cu130' if int(driver.split('.')[0]) >= 580 else 'https://download.pytorch.org/whl/cu128'
print('Driver:', driver, '| wheel index:', TORCH_INDEX)
run_cmd([sys.executable, PKG / 'install/setup.py', 'install', '--dir', COMFY, '--torch-index', TORCH_INDEX])
BACKEND_PY = COMFY / '.venv/bin/python'
run_cmd([BACKEND_PY, '-c', "import torch; print(torch.__version__, torch.version.cuda); print(torch.cuda.get_device_name(0)); x=torch.ones(16,device='cuda'); print(x.sum().item())"])
run_cmd([BACKEND_PY, PKG / 'install/download_models.py', '--models-dir', COMFY / 'models'])
这段代码获取固定版本的源码、读取其版本配置、安装后端、进行 CUDA 张量的冒烟测试并下载模型。
CUDA 轮子(wheel)的选择以驱动版本为初始启发式。
CUDA 冒烟测试是重要的验证步骤,因为仅有 A100 并不能保证与所有 PyTorch 构建兼容。我的会话使用的驱动为 580.82.07。
步骤 2:启动后端并设置推理参数
启动单元会在 127.0.0.1:8188 上启动 ComfyUI,等待其就绪,并获取可用的节点定义。
代码通过一个小型 HTTP 助手与其通信:
def api(path, body=None):
r = requests.get(BASE + path, timeout=30) if body is None else requests.post(BASE + path, json=body, timeout=30)
if not r.ok:
raise RuntimeError(f'{path}: HTTP {r.status_code}: {r.text[:3000]}')
return r.json()
该助手将服务端失败转换为可读的异常。启动后,可通过以下方式获取节点模式:
INFO = api('/object_info')
启动代码会在启动新进程前检查是否已有服务器在运行。因此本设置中没有独立的公共 ComfyUI 隧道。
现在设置我们用于编辑的参数:
CPU_ENCODER = False
CPU_REFERENCE_CACHE = False
TILED_VAE = False
STEPS = 40
SIZE = 1024
SEED = 42
这些设置的含义如下:
STEPS:更多的采样迭代通常意味着更长时间。我们使用 40。SIZE:在编辑图中,分辨率 1024 目标约为一百万像素,同时按参考图自适应长宽比。它不会强制正方形输出。SEED:固定种子便于在相同设置下比较。它不保证身份保持,亦不保证不同提示之间的平滑过渡。TILED_VAE:非分块解码在不走小块解码路径的情况下处理整幅图像,可能需要更多内存。我们偏好它源于视觉测试,而非受控证明所有伪影均由分块导致。- CPU 卸载标志:这些是内存管理控制,而非画质控制。仅在必要时启用,并测量其带来的时延与内存占用。
类似地,在 CFG 为 1 的情况下,负面提示并非主要的调参手段。请留空,而不是指望一长串不希望的属性来修复薄弱的编辑。
步骤 3:将提示与参考图连接到模型
工作流构建器会加载一个 API 图,并替换其中与请求相关的输入。下面的片段展示了编辑路径:
g = json.loads((PKG / 'workflows/api/03-image-edit.json').read_text())
g['4']['inputs'].update(prompt=prompt, resolution=SIZE)
g['6']['inputs'].update(seed=int(seed), steps=int(STEPS))
g['9']['inputs']['image'] = upload_image(image_path)
if CPU_REFERENCE_CACHE:
g['11']['inputs']['device'] = 'cpu'
if CPU_ENCODER:
g['2']['inputs']['device'] = 'cpu'
这里,节点 4 接收编辑指令与分辨率。
节点 6 控制采样,节点 9 载入上传的参考图。
另外两个覆盖项可选择将编码器或参考缓存的工作卸载到主机内存。
推理助手随后提交该图并等待其自身的请求 ID:
response = api('/prompt', {
'prompt': g,
'client_id': uuid.uuid4().hex,
})
result = collect_result(response['prompt_id'], folder)
其中,folder 是在 infer() 内部为每次请求创建的输出目录。
收集器会轮询历史记录,并在匹配的作业完成后下载生成的 PNG。
我们还会保存输入、图、提交、历史与指标。这样当输出看起来异常时,便可以检查实际请求内容。
超时并不会自动取消 GPU 作业,因此在决定重试前请保留请求 ID。
步骤 4:准备一张原始图像
最终的应用始终需要一张未改变的参考图以便回退。下面的上传路径会应用方向校正、展平透明度,并在传给模型前把图像放到一个正方形画布上:
python
from google.colab import files
uploaded = files.upload()
assert len(uploaded) == 1, 'Upload exactly one image.'
with Image.open(io.BytesIO(next(iter(uploaded.values())))) as image:
rgba = ImageOps.exif_transpose(image).convert('RGBA')
background = Image.new('RGBA', rgba.size, (250, 240, 230, 255))
original = Image.alpha_composite(background, rgba).convert('RGB')
original = ImageOps.pad(original, (SIZE, SIZE), color=(250, 240, 230))
BASE_FRAME = ROOT / f'original-{uuid.uuid4().hex[:8]}.png'
original.save(BASE_FRAME)
填充会保留纵横比而非拉伸主体,但可能会引入边框。
在 Gradio 编辑器中的直接上传会走其自身的上传处理器,可能保留原始的上传尺寸。这也是应用在导出前会检查候选图像尺寸的原因。
对于姿势编辑,请选择留有足够运动空间的图像,并根据边界给出相应指令。
步骤 5:用文字与手绘引导编辑
当目标存在歧义时(例如在拥挤场景中选择一只手臂或一个物体),绘制标注会很有帮助。
在我们的应用中,这完全是可选的。
Gradio 的编辑器提供背景、绘制图层与合成图像;最终设计中的重要规则是加载原图,仅叠加绘制图层:
layers = editor_data.get('layers') or []
has_marks = any(
np.any(np.asarray(layer.convert('RGBA'))[..., 3] > 0)
for layer in layers if layer is not None
)
with Image.open(original_path) as image:
source = image.convert('RGBA').copy()
if has_marks:
for layer in layers:
if layer is None:
continue
layer = layer.convert('RGBA')
if layer.size != source.size:
raise ValueError('Clear the drawing and redraw on the original.')
source = Image.alpha_composite(source, layer)
这是编辑回调中的核心逻辑。
Alpha 通道可揭示图层是否包含可见标记,例如您画了一个圆、矩形或粗略笔触,它们都可以作为视觉引导。
这些标记并非严格的修复(inpainting)掩膜。它们告诉模型关注哪里,但并不能保证其他像素完全不变。
仅在存在标记时,我们才添加区域说明:
region_instruction = (
'The red hand-drawn marks identify the target region. '
'For an outline, edit the enclosed area; for painted strokes, '
'edit the indicated area. Remove the annotation marks '
'from the final result. '
) if has_marks else ''
prompt = (
'Edit <image1>. '
+ region_instruction
+ f'Requested change: {instruction.strip()} '
+ "Preserve unrelated content and the image's framing. "
+ "Keep the subject's identity and visual style consistent "
+ 'unless the requested change explicitly alters them.'
)
“保持”条款用于告知模型哪些内容重要,但它仍然只是指令而非保证。
为了更明确地测试,可指定相对于图像的方位与完成后的姿势,例如:
instruction = (
'Lower the arm on the right side of the image so it extends '
'diagonally downward. Keep the other arm, face, body position, '
'camera framing, and background unchanged.'
)
避免使用“再动一点”之类的说法,因为每次请求都是从原图开始。
模型并不会接收之前的对话或最后一次接受的姿势。
步骤 6:每个候选都从原图生成
本项目的第一个版本是通过将每次输出作为下一次请求的输入来生成序列:
result = edit_frame(manifest['frames'][-1], POSES[pose_index])

这是我在最终应用中改变的行为,因为重复编辑会传播伪影,每次新请求都是以前一次模型输出为起点。
在我们早期的植物序列中,后面的图像明显更嘈杂。
最终的生成路径改为使用原始参考图(可选带注释):
input_path = ROOT / f'edit-input-{uuid.uuid4().hex[:8]}.png'
source.convert('RGB').save(input_path)
result_path = infer(
'edit',
prompt,
seed=int(seed),
image_path=input_path,
)
这样就去除了通过先前生成图像形成的反馈路径。
这并不能消除单个输出中的伪影,也不能强制独立生成的帧完全一致。
如果某个已接受的图像中出现了一朵玫瑰,下一次请求并不会自动继承它。若要在改变姿势的同时保留玫瑰,我们需要同时包含这两项要求:
instruction = (
'Make the character hold a red rose in the hand on the right '
'side of the image, with that arm extended downward. '
'Preserve the other hand, face, background, and camera framing.'
)
这种权衡有助于从共同的参考图生成多样化结果。
对于需要累积式编辑的任务,顺序工作流仍可能合适,但需要对累积变化有不同的预期。
步骤 7:在保存前审阅候选
应用通过 Gradio 的 State 函数将原图、已接受序列与待定结果分开管理:
original_state = gr.State(initial_path)
frames_state = gr.State(initial_frames)
pending_state = gr.State(None)
序列从原图开始,只有在用户接受候选后才会增长。待定状态保存尚未接受的生成文件。
核心的接受操作为:
updated_frames = list(frames) + [pending_path]
在该更新之后,完整的回调会清空待定候选与提示,将编辑器回到原图。
丢弃会清除待定结果而不改变已接受的帧。重置会将序列恢复为仅有原图的一帧,并清空当前指令与下载输出。这两项操作都不需要重新加载模型。
步骤 8:构建 Gradio 应用
最终界面将编辑、已保存帧与导出分为三个选项卡。

关键组件是图像编辑器:
editor = gr.ImageEditor(
value=initial_editor,
type='pil',
image_mode='RGBA',
label='Input',
height=480,
brush=gr.Brush(
colors=['#ff0000'],
color_mode='fixed',
default_size=8,
),
eraser=gr.Eraser(default_size=20),
transforms=(),
)
固定的画笔颜色与注释指令保持一致。
橡皮可帮助用户细化粗略区域;禁用变换则避免在此交互中涉及裁剪与旋转。
生成事件会将原图状态传入回调:
event_options = {
'concurrency_id': 'edit_workflow',
'concurrency_limit': 1,
}
generate_button.click(
fn=generate_edit,
inputs=[editor, instruction, seed, original_state],
outputs=[candidate, pending_state, status],
**event_options,
)
这些代码片段属于完整的 Blocks 布局之中。
该共享并发组在演示中串行化了生成与状态变更。重置会排队等待执行;它不是 GPU 作业取消控制。
定义好处理函数与组件后,通过运行以下命令启动应用:
demo.queue(default_concurrency_limit=1).launch(
share=True,
debug=True,
)
Gradio 的共享链接仅暴露前端,后端仍在本地运行。主题与 CSS 的调整可以改善呈现,但不会改变图像质量。
步骤 9:将已接受的帧转换为 GIF
导出器仅使用已接受的帧,因为它会创建共同调色板,并可在最后一帧后选择性地反向播放序列:
def export_gif(paths, destination, duration_ms=300, ping_pong=True):
frames = []
for path in paths:
with Image.open(path) as image:
frames.append(image.convert('RGB').copy())
if len(frames) < 2:
raise ValueError('Accept at least one edit first.')
if len({frame.size for frame in frames}) != 1:
raise ValueError('Frame dimensions must match.')
atlas = Image.new('RGB', (128 * len(frames), 128))
for i, frame in enumerate(frames):
atlas.paste(frame.resize((128, 128)), (128 * i, 0))
palette = atlas.quantize(colors=256)
converted = [
frame.quantize(palette=palette, dither=Image.Dither.NONE)
for frame in frames
]
if ping_pong:
converted += converted[-2:0:-1]
converted[0].save(
destination,
save_all=True,
append_images=converted[1:],
duration=int(duration_ms),
loop=0,
disposal=2,
optimize=False,
)
return str(destination)
共享调色板可减少一类潜在的调色板相关闪烁。
禁用抖动可避免在转换时引入抖动图案,但色彩压缩仍可能带来色带。
时长以毫秒计,设置 loop=0 表示循环播放。对于四帧,乒乓播放顺序为 0、1、2、3、2、1。
反向切片会排除重复的端点。它并不会进行运动插值,若要更平滑的动画,需要合适的中间姿势,而不仅仅是改变播放速度。
总结
我们构建了一个 Qwen Image 2.1 编辑器,它接受文本指令与可选绘制标注,让用户策展单个结果,并将其导出为 GIF。
关键的质量决策是保留固定的原始参考图,而非反复编辑生成的输出。
从可用的采样配置出发,把所需更改描述清楚,并在调整更多设置前先检查原始候选图。
当这些部分稳定后,再一次只改变一个变量来尝试分辨率或解码。这样就能得到一个实用的图像编辑工作流,并清晰地说明其能力与局限。
Qwen Image 2.1 常见问题
我能在 Colab 的 A100 上运行这个演示吗?
可以。我们在 40 GB 显存的 A100 上运行了量化的 ComfyUI 工作流。最终请求在分辨率 1024、40 步时,后端采样占用约 19.6 GiB GPU 显存。这是我们配置下的测量结果,并非最低硬件要求。
编辑前是否必须绘制区域?
不需要。您仅提供图像与文字指令也可以。用圆圈或粗略勾勒有助于定位特定目标或身体部位。它们可提供视觉引导,但并不保证标记区域外的像素保持不变。
为什么每次编辑都从原图开始?
我们早期的实验中,当每次生成的图像作为下一次输入时会累积伪影。回到原图可避免将这些伪影向前带。然而,每条提示都必须描述完整的期望结果,因为先前的编辑不会自动保留。
Qwen Image 2.1 会直接生成 GIF 吗?
不会。Qwen 生成的是单张编辑后的图像,而由 Pillow 将已接受的帧合成为 GIF。播放设置可控制时间与方向,但不会生成中间运动。
应修改哪些设置来改进输出?
从清晰的指令与干净的参考图开始。我们的配置使用 40 步、种子 42、CFG 1、Euler 采样、simple 调度器与 denoise 1。这些是可用设置,并非验证过的最优值。一次只更改一个设置,并在评判 GIF 之前比较原始 PNG。
我是一名 Google Developers 机器学习(生成式 AI)领域的专家、Kaggle 三项专家,以及 Women Techmakers 大使,拥有 3 年以上的技术从业经验。2020 年我共同创办了一家健康科技初创公司,目前在佐治亚理工学院攻读计算机科学硕士,专攻机器学习。

从一张图片制作 GIF 并不复杂。您只需向图像模型请求一个新姿势,重复此过程,然后以一定速度将输出拼接起来。实际操作中,输入策略与提示词同样关键。当我把每一帧的生成结果作为下一次请求的输入时,图像会逐渐累积伪影。
在本教程中,我们将使用 Qwen Image 2.1 构建一个交互式编辑器,以更可靠的方式完成这一实验。每次请求都从原始图像出发。用户可以用文字描述修改,还可以选择性地标记相关区域,并在导出 GIF 前对结果进行接受或丢弃。
我们将使用Qwen Image 2.1 进行编辑,使用 ComfyUI 进行推理,使用 Gradio 构建界面,并用 Pillow 导出。重点讨论影响结果的设计选择,如参考图选择、分辨率、采样参数、VAE 解码,以及精准的指令编写。
完成后,您将会: