คู่มือใช้งาน Qwen-Image-2.1: โค้ด Diffusers, สร้างภาพโปร่งใส, พร้อม API ทดลอง

Qwen-Image-2.1 คือโมเดลรูปภาพแบบ open-weights ที่ Alibaba เปิดตัวเมื่อวันที่ 20 กันยายน 2026: ซึ่งเป็นตัวสร้างภาพขนาด 7B พารามิเตอร์ ที่รองรับการแปลงข้อความเป็นรูปภาพ การแก้ไขรูปภาพด้วยภาพอ้างอิงสูงสุด 10 ภาพ และการสร้างภาพแบบโปร่งใส (RGBA) โดยธรรมชาติ คู่มือนี้จะแนะนำคุณตั้งแต่ pip install ไปจนถึงการใช้งาน HTTP endpoint ที่ทำงานได้จริง ครอบคลุมเส้นทางโค้ดอ้างอิงทั้งสี่จาก GitHub README การตั้งค่าที่สำคัญ ตัวห่อหุ้ม FastAPI ขนาดเล็กเพื่อให้สามารถเรียกใช้โมเดลได้เหมือนกับ API รูปภาพอื่น ๆ และวิธีทดสอบ endpoint นั้นใน Apidog เพื่อให้การเปลี่ยนแปลง prompt และการอัปเดตโมเดลไม่ทำให้แอปของคุณเสียหาย

หากคุณต้องการข้อมูลเบื้องต้นก่อน Qwen-Image-2.1 คืออะไร ครอบคลุมถึงสถาปัตยกรรมและใบอนุญาต ใบอนุญาตฉบับย่อระบุว่า: สำหรับการวิจัยและการใช้งานที่ไม่ใช่เชิงพาณิชย์เท่านั้น เว้นแต่จะได้รับข้อตกลงเชิงพาณิชย์แยกต่างหากจาก Qwen ข้อมูลทั้งหมดด้านล่างนี้ใช้ได้สำหรับการประเมินผล

ก่อนเริ่มต้น

ติดตั้ง:

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

การรวม diffusers เข้ามาอยู่ใน PR เฉพาะกิจในวันเปิดตัว ดังนั้น PyPI release ที่เก่ากว่าวันที่ 20 กันยายน จะไม่มีคลาส 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 ที่กำหนดตายตัวจะทำให้ image endpoint สามารถทำซ้ำได้เพียงพอสำหรับการยืนยัน

ส่งค่า width และ height จากตารางที่รองรับเมื่อคุณต้องการเอาต์พุตที่ไม่ใช่สี่เหลี่ยมจัตุรัส:

ขั้นตอนที่ 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))

การยืนยันนั้นคือการทดสอบแรกที่คุณจะนำไปใช้ใน Apidog ในภายหลัง โมเดลที่ส่งคืน RGB โดยไม่มีการแจ้งเตือนเมื่อคุณขอ RGBA ถือเป็นข้อผิดพลาดที่ผู้ใช้ของคุณจะพบก่อนที่คุณจะพบ

ขั้นตอนที่ 3: การแก้ไข, ด้วยรูปภาพหนึ่งรูปหรือสูงสุดสิบรูป

pipeline เดียวกันนี้จะแก้ไขเมื่อคุณส่ง image:

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, คำอธิบายประกอบที่วาดด้วยมือ หรือภาพต้นฉบับที่ไม่ถูกแตะต้องรวมกับภาพมาสก์แยกต่างหากที่ส่งเป็นอินพุตสองรายการ README ไม่มีตัวอย่างมาสก์โดยเฉพาะ ดังนั้นรูปแบบอินพุตสองรายการจึงเป็นสิ่งแรกที่ควรลอง: image=[original, mask] พร้อม prompt ที่อธิบายว่าจะใส่อะไรลงในบริเวณที่ถูกมาสก์ [ยืนยันกับ README เมื่อมีตัวอย่างมาสก์ออกมา]

การแก้ไขยังเป็นจุดที่แสดงให้เห็นถึงประสิทธิภาพด้านความเร็วของเวอร์ชัน 2.1 ภาพอ้างอิงและคำสั่งจะคงที่ตลอดขั้นตอนการลดสัญญาณรบกวน ดังนั้นโมเดลจะคำนวณ key-value cache เพียงครั้งเดียวและนำกลับมาใช้ใหม่ การอ้างอิงสิบภาพใช้ทรัพยากรน้อยกว่าสิบเท่าของการอ้างอิงภาพเดียวอย่างเห็นได้ชัด

ขั้นตอนที่ 4: ปรับให้เข้ากับ GPU ของคุณ

Qwen ยังไม่ได้เผยแพร่ตัวเลข VRAM หาก pipeline แบบ bf16 ไม่พอดี 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 ComfyUI มี การรองรับในตัว พร้อมเวิร์กโฟลว์เทมเพลต หากคุณไม่ต้องการเขียน Python เลย และหากคุณไม่มี GPU ตัวเลือกฟรี จะครอบคลุมถึง hosted demo และ Qwen Chat

ขั้นตอนที่ 5: การห่อหุ้มเป็น HTTP API

โค้ดแอปพลิเคชันไม่ควรนำเข้า 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 นี่เป็นทางเลือกเฉพาะสำหรับผลิตภัณฑ์เท่านั้นใน wrapper ส่วนที่เหลือคือ multipart endpoint ธรรมดา

ขั้นตอนที่ 6: ทดสอบ endpoint ใน Apidog

ตอนนี้มันเป็น API แล้ว และหลักการเดียวกันที่คุณจะใช้กับ gpt-image-2.5 API หรือ Nano Banana 2 API ก็ใช้ได้ที่นี่ ใน Apidog:

1. สร้าง endpoint เป็น POST {{base_url}}/v1/images ด้วย multipart body: prompt, aspect, transparent, seed, steps และฟิลด์ไฟล์ references ที่สามารถทำซ้ำได้ ใส่ base_url ใน environment เพื่อให้คอลเลกชันเดียวกันชี้ไปที่แล็ปท็อปของคุณ, GPU box หรือ mock
2. ส่งคำขอ text-to-image ด้วย seed=42 และ prompt ป้ายไฟนีออน ยืนยัน 200, Content-Type: image/png และ X-Image-Mode: RGB
3. เพิ่มการยืนยัน ใน post-processor: สถานะคือ 200, X-Image-Mode เท่ากับ RGBA เมื่อ transparent=true, ขนาด body ของการตอบกลับอยู่เหนือเกณฑ์ (ไฟล์ PNG ขนาด 2K ที่ส่งกลับมาเป็น 2 KB คือภาพว่างเปล่า) และ X-Seed สะท้อนสิ่งที่คุณส่งไป
4. ส่งกรณีความโปร่งใสและการแก้ไขสามภาพอ้างอิง ในลักษณะเดียวกัน โดยแนบรูปภาพในฟิลด์ไฟล์ บันทึกแต่ละกรณีเป็นการทดสอบ
5. เรียกใช้เป็นสถานการณ์การทดสอบ ตามกำหนดเวลาหรือใน CI เมื่อคุณสลับไปใช้ quantized build หรือเวอร์ชัน 2.2 ในอนาคต ชุดการทดสอบจะบอกคุณในไม่กี่นาทีว่าความโปร่งใสยังคงทำงานหรือไม่ และ seed ยังคงสร้างผลลัพธ์เดิมซ้ำได้หรือไม่
6. จำลอง (Mock) ขณะที่ GPU กำลังทำงาน mock อัจฉริยะของ Apidog จะส่งคืน PNG สำเร็จรูปสำหรับสัญญาเดียวกัน ดังนั้นส่วนหน้า (frontend) จึงยังคงสามารถพัฒนาต่อไปได้

เนื่องจาก Apidog ยังสร้าง OpenAPI spec และเอกสารจาก endpoint ที่คุณกำหนดไว้ สัญญาของ wrapper จึงสามารถแบ่งปันได้ทันทีที่มันทำงาน ดาวน์โหลด Apidog และนำเข้า endpoint ด้านบนเพื่อเริ่มต้น

ทางเลือก: การเขียน prompt ซ้ำด้วย PE-T2I

Demo Space จะเปลี่ยนคำขอแบบบรรทัดเดียวให้เป็น prompt ที่มีโครงสร้างยาวๆ โดยใช้ Qwen-Image-2.1-PE-T2I ซึ่งเป็น Qwen3.5-VL 9B ที่ได้รับการปรับแต่งมาอย่างดี ซึ่งส่งคืน JSON พร้อม prompt ภาษาอังกฤษที่ขยายและอัตราส่วนภาพที่แนะนำ เรียกใช้เป็นบริการที่สองที่อยู่ด้านหน้า /v1/images หรือจะข้ามไปและเขียน prompt แบบเต็มด้วยตัวเอง หากคุณเพิ่มมันเข้าไป ให้ทดสอบแยกต่างหาก: มันคือ text API ที่มีสัญญา JSON และ rewriter ที่เสียจะสร้างภาพที่ไม่ดีซึ่งดูเหมือนข้อผิดพลาดของ generator

คำถามที่พบบ่อย

pipeline เดียวสามารถสร้างและแก้ไขได้ทั้งสองอย่างหรือไม่? ได้ QwenImage21Pipeline จะสร้างภาพเมื่อถูกเรียกใช้ด้วย prompt อย่างเดียว และแก้ไขภาพเมื่อคุณส่ง image (ภาพ PIL เดี่ยวหรือรายการสูงสุด 10 ภาพ)

ฉันจะสร้าง PNG แบบโปร่งใสได้อย่างไร? เริ่ม prompt ด้วย “This is an RGBA image with transparency” และระบุว่าพื้นหลังโปร่งใส ตรวจสอบ image.mode == "RGBA" บนผลลัพธ์

การตั้งค่าที่แนะนำคืออะไร? 40 inference steps และ bfloat16 ตามที่ระบุใน README ค่า guidance ไม่ได้ระบุไว้สำหรับเวอร์ชัน 2.1; Qwen-Image เวอร์ชันก่อนหน้าใช้ true_cfg_scale=4.0 ดังนั้นลองใช้ค่านี้หากผลลัพธ์ดูเหมือนขาดการชี้นำ [ตรวจสอบ]

ฉันสามารถใช้สิ่งนี้ในผลิตภัณฑ์เชิงพาณิชย์ได้หรือไม่? ไม่ได้ภายใต้ใบอนุญาตเริ่มต้น Qwen-Image-2.1 มาพร้อมกับ Qwen Research License; การใช้งานเชิงพาณิชย์ต้องได้รับใบอนุญาตแยกต่างหากจาก Qwen ดูรายละเอียดใน Qwen-Image-2.1 คืออะไร

มี API แบบโฮสต์ให้ใช้แทนหรือไม่? Qwen Image 3.0 และ 3.0 Pro เป็นโมเดลรูปภาพแบบโฮสต์ของ Alibaba ที่มีการกำหนดราคาต่อรูปภาพ การเปรียบเทียบ 2.1 กับ 3.0 ครอบคลุมว่าเมื่อใดควรโฮสต์ด้วยตัวเองและเมื่อใดควรเช่า

จะไปต่อที่ไหน

ตอนนี้คุณมีสี่การเรียกใช้งานที่ทำงานได้จริง, wrapper ที่มีสัญญาที่มั่นคง และชุดการทดสอบที่ตรวจสอบคุณสมบัติสองประการที่สำคัญที่สุดสำหรับโมเดลนี้ นั่นคือความโปร่งใสและการทำซ้ำได้ ถัดไป ให้ตัดสินใจว่าใบอนุญาตการวิจัยเหมาะสมกับการใช้งานของคุณหรือไม่ หรือ hosted 3.0 API เหมาะสมกว่า และเก็บทั้งสองอย่างไว้เบื้องหลังคอลเลกชัน Apidog เดียวกัน เพื่อให้การสลับเป็นการเปลี่ยน base URL ไม่ใช่การเขียนใหม่