Qwen-Image-2.1 Nasıl Kullanılır: Diffusers Kodu, Şeffaf Çıktı ve Test Edilebilir API

Qwen-Image-2.1, Alibaba'nın 20 Eylül 2026'da yayımladığı açık ağırlıklı görüntü modelidir: metinden görüntüye oluşturma, 10'a kadar referans görüntü ile düzenleme ve yerel şeffaf (RGBA) çıktı sağlayan 7 milyar parametreli bir oluşturucudur. Bu kılavuz, sizi pip install komutundan çalışan bir HTTP uç noktasına ulaştırır. GitHub README'deki dört referans kod yolunu, önemli ayarları, modelin diğer herhangi bir görüntü API'si gibi çağrılabilmesi için küçük bir FastAPI sarmalayıcıyı ve istem değişikliklerinin ve model güncellemelerinin uygulamanızı bozmaması için bu uç noktanın Apidog'da nasıl test edileceğini kapsar.

Önce arka planı isterseniz, Qwen-Image-2.1 Nedir mimariyi ve lisansı kapsar. Lisansın kısa versiyonu: Qwen'den ayrı bir ticari anlaşma almadığınız sürece yalnızca araştırma ve ticari olmayan kullanım içindir. Aşağıdaki her şey değerlendirme için uygundur.

Başlamadan önce

Kurulum:

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

Diffusers entegrasyonu lansman gününde özel bir PR ile eklendi, bu nedenle 20 Eylül'den daha eski bir PyPI sürümünde işlem hattı sınıfı bulunmayacaktır.

Adım 1: metinden görüntüye

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")

Fark etmeniz gereken iki şey var. İstem, tabela metnini tırnak içine alır; Qwen'in metin işleme yeteneği, insanların bu model ailesini seçmesinin nedenidir ve literal diziyi tırnak içine almak önceki sürümlerden gelen bir gelenektir. Ayrıca, tohum açıkça belirtilmiştir. Test etmeyi düşündüğünüz her istekte bunu bu şekilde tutun, çünkü sabit bir tohum, bir görüntü uç noktasını yeterince tekrarlanabilir kılar.

Kare olmayan bir çıktıya ihtiyacınız olduğunda desteklenen tablodan width ve height değerlerini geçirin:

Adım 2: şeffaf çıktı

Şeffaflık istem tabanlıdır. README'nin önerdiği ifade literaldir, bu yüzden onu kullanın:

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")

Güvenmek yerine sonucu kontrol edin:

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

Bu doğrulama, daha sonra Apidog'a aktaracağınız ilk testtir. RGBA istediğinizde sessizce RGB döndüren bir model, kullanıcılarınızın sizden önce bulacağı bir hatadır.

Adım 3: tek veya on adede kadar görüntü ile düzenleme

Aynı işlem hattı, image'ı geçtiğinizde düzenlemeler yapar:

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")

Birden fazla referans için bir liste geçirin (lansman gönderisinin sınırı 10'dur):

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")

Lansman gönderisinde yerel düzenleme üç şekilde çalışır: istemde rengine göre referans verdiğiniz renkli daireler, boyalı ek açıklamalar veya dokunulmamış orijinal artı iki giriş olarak iletilen ayrı bir maske görüntüsü. README özel bir maske örneği sunmadığı için, ilk denenecek olan iki girişli form şudur: maskelenmiş bölgeye neyin gideceğini açıklayan bir istemle birlikte image=[orijinal, maske] [bir maske örneği geldiğinde README ile DOĞRULA].

Düzenleme aynı zamanda 2.1'in hız çalışmasının görüldüğü yerdir. Referans görüntüler ve talimat, gürültü giderme adımları boyunca statiktir, bu nedenle model anahtar-değer önbelleklerini bir kez hesaplar ve yeniden kullanır. On referansın maliyeti, tek bir referansın on katından gözle görülür şekilde daha azdır.

Adım 4: GPU'nuza sığdırın

Qwen VRAM sayılarını yayımlamadı. bf16 işlem hattı sığmazsa, README şunları önerir:

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

Sunum için README, vLLM-Omni (FP8 ile), SGLang ve LightX2V'yi işaret eder. ComfyUI, hiç Python yazmak istemiyorsanız bir şablon iş akışı ile yerel desteğe sahiptir. Ve eğer GPU'nuz yoksa, ücretsiz seçenekler barındırılan demoyu ve Qwen Chat'i kapsar.

Adım 5: Bir HTTP API olarak sarın

Uygulama kodu diffusers'ı içe aktarmamalıdır. İşlem hattını küçük bir hizmetin arkasına koyun, böylece sürümleyebileceğiniz, taklit edebileceğiniz ve test edebileceğiniz bir sözleşmeye sahip olur. Bu FastAPI sarmalayıcı yaklaşık 40 satırdır ve PNG baytları döndürür:

# 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 ile çalıştırın. İki yanıt başlığı, X-Image-Mode ve X-Seed, bir testin PNG'yi çözmeden şeffaflığı ve tekrarlanabilirliği kontrol edebilmesi için mevcuttur. Bu, sarmalayıcıdaki tek ürüne özgü seçimdir; gerisi basit bir multipart uç noktadır.

Adım 6: uç noktayı Apidog'da test edin

Artık bu bir API, ve gpt-image-2.5 API'sine veya Nano Banana 2 API'sine uygulayacağınız aynı disiplin burada da geçerlidir. Apidog'da:

1. Uç noktayı oluşturun: POST {{base_url}}/v1/images olarak bir multipart gövde ile: prompt, aspect, transparent, seed, steps ve tekrarlanabilir bir references dosya alanı. Aynı koleksiyonun dizüstü bilgisayarınıza, GPU kutusuna veya bir sahteye işaret etmesi için base_url'yi bir ortama koyun.
2. seed=42 ve neon-tabela istemiyle metinden görüntüye bir istek gönderin. 200, Content-Type: image/png ve X-Image-Mode: RGB olduğunu doğrulayın.
3. Son işlemcide doğrulamalar ekleyin: durum 200, transparent=true olduğunda X-Image-Mode, RGBA'ya eşit, yanıt gövdesi boyutu bir tabanın üzerinde (2 KB olarak dönen 2K'lık bir PNG boş bir görüntüdür) ve X-Seed gönderdiğiniz değeri yankılar.
4. Şeffaflık durumunu ve üç referanslı bir düzenlemeyi aynı şekilde gönderin, görüntüleri dosya alanına ekleyerek. Her birini bir test durumu olarak kaydedin.
5. Bunları bir zaman çizelgesinde veya CI'da bir test senaryosu olarak çalıştırın. Kuantize edilmiş bir derlemeyi veya gelecekteki 2.2'yi değiştirdiğinizde, paket şeffaflığın hala çalışıp çalışmadığını ve tohumun hala tekrarlanıp tekrarlanmadığını size dakikalar içinde bildirir.
6. GPU meşgulken taklit edin. Apidog'un akıllı taklidi, aynı sözleşme için önceden hazırlanmış bir PNG döndürür, böylece ön uç oluşturmaya devam eder.

Apidog, tanımladığınız uç noktadan OpenAPI spesifikasyonunu ve belgelerini de oluşturduğu için, sarmalayıcının sözleşmesi çalışmaya başladığı anda paylaşılabilir hale gelir. Başlamak için Apidog'u indirin ve yukarıdaki uç noktayı içe aktarın.

İsteğe Bağlı: PE-T2I ile istem yeniden yazma

Demo Ortamı, Qwen-Image-2.1-PE-T2I kullanarak tek satırlık istekleri genişletilmiş İngilizce istem ve önerilen en boy oranı ile JSON döndüren, ince ayarlı bir Qwen3.5-VL 9B olan uzun, yapılandırılmış istemlere dönüştürür. Bunu /v1/images önünde ikinci bir hizmet olarak çalıştırın veya atlayıp kendi tam istemlerinizi yazın. Eğer eklerseniz, ayrı olarak test edin: bu, JSON sözleşmeli bir metin API'sidir ve bozuk bir yeniden yazıcı, bir jeneratör hatası gibi görünen kötü görüntüler üretir.

Sıkça Sorulan Sorular

Tek bir işlem hattı hem oluşturma hem de düzenleme yapabilir mi? Evet. QwenImage21Pipeline, yalnızca bir istemle çağrıldığında oluşturur ve image (tek bir PIL görüntüsü veya 10 adede kadar bir liste) geçirdiğinizde düzenler.

Şeffaf bir PNG'yi nasıl elde edebilirim? İstem'i “This is an RGBA image with transparency” (Bu, şeffaflığı olan bir RGBA görüntüsüdür) ile başlatın ve arka planın şeffaf olduğunu belirtin. Sonuçta image.mode == "RGBA" olup olmadığını kontrol edin.

Önerilen ayarlar nelerdir? README'ye göre 40 çıkarım adımı ve bfloat16. 2.1 için yönlendirme değerleri listelenmemiştir; önceki Qwen-Image sürümleri true_cfg_scale=4.0 kullanıyordu, bu nedenle çıktılar yetersiz yönlendirilmiş görünüyorsa bunu deneyin [DOĞRULA].

Bunu ticari bir üründe kullanabilir miyim? Varsayılan lisans altında hayır. Qwen-Image-2.1, Qwen Araştırma Lisansı altında sunulmaktadır; ticari kullanım için Qwen'den ayrı bir lisans gereklidir. Detaylar için Qwen-Image-2.1 Nedir bölümüne bakın.

Bunun yerine barındırılan bir API var mı? Qwen Image 3.0 ve 3.0 Pro, Alibaba'nın görüntü başına fiyatlandırma ile sunulan barındırılan görüntü modelleridir. 2.1 ve 3.0 karşılaştırması, ne zaman kendi sunucunuzda barındıracağınızı ve ne zaman kiralayacağınızı kapsar.

Sonraki Adımlar

Artık dört çalışan çağrıya, istikrarlı bir sözleşmeye sahip bir sarmalayıcıya ve bu model için en önemli iki özellik olan şeffaflığı ve tekrarlanabilirliği kontrol eden bir test paketine sahipsiniz. Sonra, araştırma lisansının kullanımınıza uygun olup olmadığına veya barındırılan 3.0 API'sinin daha iyi bir seçenek olup olmadığına karar verin ve her ikisini de aynı Apidog koleksiyonunun arkasında tutun, böylece geçiş bir temel URL değişikliği olur, yeniden yazma değil.