如何在 diffusers 中使用 Qwen-Image-2.1：透明输出与可测试的 API

Qwen-Image-2.1 是阿里在 2026 年 9 月 20 日发布的开放权重图像模型：一个 7B 参数的生成器，同时支持文生图、最多 10 张参考图的编辑，以及原生透明（RGBA）输出。本指南带你从 pip install 一路走到一个可用的 HTTP 接口。内容覆盖 GitHub README 里的四条参考代码路径、真正影响结果的各项设置、一个能把模型像其他图像 API 一样调用的轻量 FastAPI 封装，以及如何在 Apifox 中测试这个接口，让 prompt 改动和模型更新不会打挂你的应用。

如果你想先了解背景，可以参考 What is Qwen-Image-2.1 中关于架构和许可证的说明。许可证的简短版本是：仅限研究和非商业用途，除非你从 Qwen 单独获得商业协议。下文的所有内容用于评估都没有问题。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始之前

要求	说明
Python 包	`torch>=2.4.0`、`transformers>=5.17`、来自 GitHub main 的 `diffusers`、`accelerate`、`pillow`
Pipeline 类	`QwenImage21Pipeline`（生成和编辑共用一个类）
权重	Qwen/Qwen-Image-2.1，bf16 safetensors
GPU	Qwen 未给出具体规格；参考代码面向单张 CUDA 设备、bfloat16 精度，并以 `enable_model_cpu_offload()` 作为兜底
默认输出	2048 x 2048；40 个推理步
可选	`Qwen-Image-2.1-PE-T2I` / `PE-I2I` prompt 改写模型

安装：

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

diffusers 的集成是在发布当天通过一个专门的 PR 合并的，所以早于 9 月 20 日的 PyPI 版本里没有这个 pipeline 类。

第 1 步：文生图

import torch
from diffusers import QwenImage21Pipeline

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

image = pipe(
    prompt='A neon shop sign that reads "QWEN IMAGE 2.1", rainy night, reflections on wet pavement',
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("t2i_example.png")

有两点值得注意。prompt 里用引号包住了招牌文字；Qwen 的文字渲染正是人们选择这条模型线的原因，而把字面字符串加引号是此前几个版本沿用下来的惯例。另外，seed 是显式指定的。在你打算测试的每个请求里都保持这种写法，因为固定 seed 才能让图像接口具备可复现性，从而可以对其做断言。

需要非正方形输出时，从受支持的尺寸表里传入 width 和 height：

比例	尺寸
1:1	2048 x 2048
4:3 / 3:4	2400 x 1792 / 1792 x 2400
3:2 / 2:3	2528 x 1696 / 1696 x 2528
16:9 / 9:16	2752 x 1536 / 1536 x 2752

第 2 步：透明输出

透明效果由 prompt 驱动。README 推荐的措辞是固定句式，照用即可：

image = pipe(
    prompt=(
        "This is an RGBA image with transparency. A cute cartoon dragon sticker. "
        "The image has alpha channel and the background is transparent."
    ),
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("transparent_example.png")

不要直接相信结果，而要去校验它：

assert image.mode == "RGBA", image.mode
alpha = image.getchannel("A")
print("transparent pixels:", sum(1 for p in alpha.getdata() if p == 0))

这条断言就是稍后你要迁移进 Apifox 的第一个测试用例。当你要求 RGBA 却悄悄返回 RGB 的模型，是一个你的用户会比你更早发现的 bug。

第 3 步：用一张图或最多十张图做编辑

传入 image 时，同一个 pipeline 就变成编辑器：

from PIL import Image

input_image = Image.open("input.png")
edited = pipe(
    prompt="Change the background to a sunset beach",
    image=input_image,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
edited.save("edit_example.png")

要使用多张参考图，传入一个列表即可（发布说明里的上限是 10 张）：

refs = [Image.open(f"ref_{i}.png") for i in range(3)]
result = pipe(
    prompt="These three characters are sitting around a campfire in a forest",
    image=refs,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
result.save("multi_ref_example.png")

局部编辑在发布说明里有三种做法：在 prompt 中按颜色引用的彩色圆圈标注、手绘涂鸦标注，或者传入未改动的原图外加一张单独的 mask 图作为两个输入。README 没有提供专门的 mask 示例，所以建议先试双输入形式：image=[original, mask]，并在 prompt 中描述被遮罩区域里应该出现的内容 [VERIFY against the README once a mask example lands]。

编辑也是 2.1 速度优化的体现之处。参考图和指令在去噪过程中是静态不变的，因此模型只计算一次它们的 key-value cache 并复用。十张参考图的成本明显低于一张的十倍。

第 4 步：让它装进你的 GPU

Qwen 没有公布显存占用数字。如果 bf16 的 pipeline 装不下，README 提供了这个方案：

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

在服务化部署方面，README 指向了 vLLM-Omni（支持 FP8）、SGLang 和 LightX2V。如果你完全不想写 Python，ComfyUI 已经提供了原生支持和模板工作流。完全没有 GPU 的话，免费方案覆盖了托管 demo 和 Qwen Chat。

第 5 步：把它封装成 HTTP 接口

应用代码不应该 import diffusers。把 pipeline 放到一个小服务后面，它就有了可以版本化、mock 和测试的契约。下面这个 FastAPI 封装大约 40 行，返回 PNG 字节流：

# server.py
import io, torch
from fastapi import FastAPI, UploadFile, File, Form
from fastapi.responses import Response
from PIL import Image
from diffusers import QwenImage21Pipeline

app = FastAPI()
pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16
).to("cuda")

SIZES = {"1:1": (2048, 2048), "16:9": (2752, 1536), "9:16": (1536, 2752)}

@app.post("/v1/images")
async def generate(
    prompt: str = Form(...),
    aspect: str = Form("1:1"),
    transparent: bool = Form(False),
    seed: int = Form(42),
    steps: int = Form(40),
    references: list[UploadFile] = File(default=[]),
):
    if transparent and not prompt.startswith("This is an RGBA image"):
        prompt = ("This is an RGBA image with transparency. " + prompt +
                  " The image has alpha channel and the background is transparent.")
    refs = [Image.open(io.BytesIO(await f.read())) for f in references[:10]]
    w, h = SIZES.get(aspect, SIZES["1:1"])
    kwargs = dict(prompt=prompt, num_inference_steps=steps,
                  generator=torch.Generator("cuda").manual_seed(seed))
    if refs:
        kwargs["image"] = refs if len(refs) > 1 else refs[0]
    else:
        kwargs.update(width=w, height=h)
    image = pipe(**kwargs).images[0]
    buf = io.BytesIO()
    image.save(buf, format="PNG")
    return Response(buf.getvalue(), media_type="image/png",
                    headers={"X-Image-Mode": image.mode, "X-Seed": str(seed)})

用 uvicorn server:app --port 8000 启动它。两个响应头 X-Image-Mode 和 X-Seed 的作用，是让测试无需解码 PNG 就能检查透明度和可复现性。这是封装里唯一一处针对具体产品的设计选择，其余部分就是一个普通的多部分表单接口。

第 6 步：在 Apifox 中测试这个接口

到这里它已经是一个 API 了，你对 gpt-image-2.5 API 或 Nano Banana 2 API 使用的那套纪律同样适用。在 Apifox 中：

创建接口 POST {{base_url}}/v1/images，请求体使用 multipart 格式：prompt、aspect、transparent、seed、steps，以及可重复添加的 references 文件字段。把 base_url 放进环境里，这样同一个集合就能指向你的笔记本、GPU 机器或者 mock。
发送一个文生图请求，带上 seed=42 和霓虹招牌那段 prompt。确认返回 200、Content-Type: image/png 和 X-Image-Mode: RGB。
在后置操作里添加断言：状态码为 200；当 transparent=true 时 X-Image-Mode 等于 RGBA；响应体大小高于下限（一张 2K 的 PNG 只返回 2 KB，说明是空图）；X-Seed 回显你发送的值。
用同样的方式发送透明用例和三参考图编辑用例，在文件字段中附加图片。把每个都保存为测试用例。
把它们作为测试场景运行，可以按计划调度，也可以放到 CI 里。当你换上量化版本或者未来的 2.2 时，这套用例能在几分钟内告诉你透明输出是否仍然可用、seed 是否仍然可复现。
在 GPU 忙的时候 mock 它。Apifox 的智能 mock 会按同一份契约返回一张固定的 PNG，前端可以继续开发。

由于 Apifox 还能根据你定义的接口生成 OpenAPI 规范和文档，封装一旦跑通，它的契约立刻就可以分享出去。

可选：用 PE-T2I 改写 prompt

demo Space 使用 Qwen-Image-2.1-PE-T2I 把一句话的请求扩展成结构化的长 prompt，这是一个微调过的 Qwen3.5-VL 9B 模型，返回包含扩展英文 prompt 和建议宽高比的 JSON。你可以把它作为第二个服务运行在 /v1/images 前面，也可以跳过它自己写完整 prompt。如果加上它，要单独测试：它是一个带 JSON 契约的文本 API，而一个出问题的改写器会产出生看起来像生成器 bug 的糟糕图片。

常见问题

一个 pipeline 同时负责生成和编辑吗？ 是的。QwenImage21Pipeline 只传 prompt 时做生成，传入 image（单张 PIL 图片或最多 10 张的列表）时做编辑。

如何得到透明 PNG？ 用 “This is an RGBA image with transparency” 开头，并说明背景是透明的。然后在结果上检查 image.mode == "RGBA"。

推荐设置是什么？ 按 README 的说法是 40 个推理步和 bfloat16。2.1 没有列出 guidance 取值；更早的 Qwen-Image 版本使用 true_cfg_scale=4.0，如果输出看起来引导不足可以试试 [VERIFY]。

可以用在商业产品里吗？ 默认许可证下不可以。Qwen-Image-2.1 采用 Qwen Research License 发布，商业使用需要从 Qwen 获得单独许可。详情见 What is Qwen-Image-2.1。

有没有托管 API 可用？ Qwen Image 3.0 和 3.0 Pro 是阿里提供的托管图像模型，按张计费。2.1 vs 3.0 comparison 讨论了什么情况下自托管、什么情况下租用。

接下来做什么

你现在已经有了四条可用的调用、一个具备稳定契约的封装，以及一套测试用例，用来检查这个模型最关键的两个性质：透明度和可复现性。接下来，判断研究许可证是否适合你的用途，或者托管的 3.0 API 是否更合适，并把两者放在同一个 Apifox 集合里，这样切换只是改一个前置 URL，而不是重写代码。

HiFox ：将 Agent 变成真正的队友

另外，我们也在思考，AI 如何从个人提效走进团队协作。

HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。

👉 立即体验 Hifox：https://hifox.com

AI Coding 交流群