Qwen-Image-2.1 là mô hình hình ảnh mã nguồn mở mà Alibaba phát hành vào ngày 20 tháng 9 năm 2026: một trình tạo 7B tham số xử lý văn bản thành hình ảnh, chỉnh sửa với tối đa 10 hình ảnh tham chiếu và xuất ảnh trong suốt (RGBA) gốc. Hướng dẫn này sẽ giúp bạn từ lệnh pip install đến một điểm cuối HTTP hoạt động. Nó bao gồm bốn đường dẫn mã tham chiếu từ GitHub README, các cài đặt quan trọng, một lớp bao bọc FastAPI nhỏ để mô hình có thể được gọi như bất kỳ API hình ảnh nào khác, và cách kiểm tra điểm cuối đó trong Apidog để các thay đổi prompt và cập nhật mô hình không làm hỏng ứng dụng của bạn.
Nếu bạn muốn biết thông tin cơ bản trước, bài viết Qwen-Image-2.1 là gì bao gồm kiến trúc và giấy phép. Tóm tắt giấy phép: chỉ sử dụng cho nghiên cứu và phi thương mại trừ khi bạn có thỏa thuận thương mại riêng với Qwen. Mọi thứ dưới đây đều tốt để đánh giá.
Trước khi bạn bắt đầu
| Yêu cầu | Chi tiết |
|---|---|
| Gói Python | torch>=2.4.0, transformers>=5.17, diffusers từ GitHub main, accelerate, pillow |
| Lớp pipeline | QwenImage21Pipeline (một lớp cho cả tạo và chỉnh sửa) |
| Trọng số | Qwen/Qwen-Image-2.1, bf16 safetensors |
| GPU | Không được Qwen chỉ định; mã tham chiếu nhắm mục tiêu một thiết bị CUDA ở bfloat16, với enable_model_cpu_offload() làm phương án dự phòng |
| Đầu ra mặc định | 2048 x 2048; 40 bước suy luận |
| Tùy chọn | Các mô hình viết lại prompt Qwen-Image-2.1-PE-T2I / PE-I2I |
Cài đặt:
pip install "torch>=2.4.0" "transformers>=5.17" accelerate pillow
pip install git+https://github.com/huggingface/diffusers
Việc tích hợp diffusers đã được đưa vào một PR chuyên dụng vào ngày ra mắt, vì vậy bản phát hành PyPI cũ hơn ngày 20 tháng 9 sẽ không có lớp pipeline này.
Bước 1: văn bản thành hình ảnh
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")
Có hai điều cần lưu ý. Prompt đặt văn bản biển hiệu trong dấu ngoặc kép; việc hiển thị văn bản của Qwen là lý do mọi người chọn dòng mô hình này, và việc đặt chuỗi ký tự trong dấu ngoặc kép là quy ước từ các bản phát hành trước. Và seed được chỉ định rõ ràng. Hãy giữ nguyên như vậy trong mọi yêu cầu bạn định kiểm tra, vì một seed cố định sẽ làm cho điểm cuối hình ảnh đủ khả năng tái tạo để xác nhận.
Truyền width và height từ bảng được hỗ trợ khi bạn cần đầu ra không vuông:
| Tỷ lệ | Kích thước |
|---|---|
| 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 |
Bước 2: đầu ra trong suốt
Tính trong suốt được điều khiển bằng prompt. Cụm từ khuyến nghị của README rất trực tiếp, vì vậy hãy sử dụng 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")
Kiểm tra kết quả thay vì tin tưởng nó:
assert image.mode == "RGBA", image.mode
alpha = image.getchannel("A")
print("transparent pixels:", sum(1 for p in alpha.getdata() if p == 0))
Xác nhận đó là thử nghiệm đầu tiên bạn sẽ chuyển sang Apidog sau này. Một mô hình trả về RGB một cách im lặng khi bạn yêu cầu RGBA là một lỗi mà người dùng của bạn sẽ tìm thấy trước bạn.
Bước 3: chỉnh sửa, với một hình ảnh hoặc tối đa mười hình ảnh
Cùng một pipeline sẽ chỉnh sửa khi bạn truyền 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")
Đối với nhiều tham chiếu, hãy truyền một danh sách (giới hạn của bài đăng ra mắt là 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")
Chỉnh sửa cục bộ hoạt động theo ba cách trong bài đăng ra mắt: các vòng tròn màu mà bạn tham chiếu theo màu trong prompt, các chú thích được vẽ, hoặc hình ảnh gốc không chạm vào cùng với một hình ảnh mặt nạ riêng biệt được truyền dưới dạng hai đầu vào. README không cung cấp ví dụ mặt nạ chuyên dụng, vì vậy dạng hai đầu vào là dạng đầu tiên cần thử: image=[original, mask] với một prompt mô tả những gì nằm trong vùng được che [XÁC MINH lại với README sau khi có ví dụ mặt nạ].
Chỉnh sửa cũng là nơi tốc độ của 2.1 thể hiện. Các hình ảnh tham chiếu và hướng dẫn là tĩnh qua các bước khử nhiễu, vì vậy mô hình tính toán bộ nhớ cache key-value của chúng một lần và tái sử dụng nó. Mười tham chiếu tốn ít hơn đáng kể so với mười lần một tham chiếu.
Bước 4: phù hợp với GPU của bạn
Qwen chưa công bố số liệu VRAM. Nếu pipeline bf16 không phù hợp, README cung cấp:
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()
Để phục vụ, README chỉ ra vLLM-Omni (với FP8), SGLang và LightX2V. ComfyUI có hỗ trợ nguyên bản với một quy trình làm việc mẫu nếu bạn không muốn viết Python chút nào. Và nếu bạn không có GPU, các tùy chọn miễn phí bao gồm bản demo được lưu trữ và Qwen Chat.
Bước 5: bọc nó dưới dạng API HTTP
Mã ứng dụng không nên import diffusers. Hãy đặt pipeline đằng sau một dịch vụ nhỏ để nó có một hợp đồng mà bạn có thể phiên bản, mô phỏng và kiểm tra. Lớp bao bọc FastAPI này khoảng 40 dòng và trả về byte 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)})
Chạy nó với uvicorn server:app --port 8000. Hai tiêu đề phản hồi, X-Image-Mode và X-Seed, tồn tại để một thử nghiệm có thể kiểm tra tính trong suốt và khả năng tái tạo mà không cần giải mã PNG. Đó là lựa chọn duy nhất cụ thể theo sản phẩm trong lớp bao bọc; phần còn lại là một điểm cuối multipart đơn giản.
Bước 6: kiểm tra điểm cuối trong Apidog
Bây giờ nó là một API, và các nguyên tắc tương tự mà bạn sẽ áp dụng cho API gpt-image-2.5 hoặc API Nano Banana 2 cũng áp dụng ở đây. Trong Apidog:
- Tạo điểm cuối dưới dạng
POST {{base_url}}/v1/imagesvới phần thân multipart:prompt,aspect,transparent,seed,stepsvà một trường tệpreferencescó thể lặp lại. Đặtbase_urltrong một môi trường để cùng một bộ sưu tập trỏ đến máy tính xách tay của bạn, hộp GPU hoặc một mô phỏng. - Gửi yêu cầu văn bản thành hình ảnh với
seed=42và prompt biển hiệu neon. Xác nhận200,Content-Type: image/pngvàX-Image-Mode: RGB. - Thêm các xác nhận trong bộ xử lý hậu kỳ: trạng thái là 200,
X-Image-ModebằngRGBAkhitransparent=true, kích thước phần thân phản hồi lớn hơn một ngưỡng (một PNG 2K trả về 2 KB là một hình ảnh trống), vàX-Seedlặp lại những gì bạn đã gửi. - Gửi trường hợp trong suốt và một chỉnh sửa ba tham chiếu theo cùng một cách, đính kèm hình ảnh vào trường tệp. Lưu mỗi cái dưới dạng một trường hợp thử nghiệm.
- Chạy chúng như một kịch bản thử nghiệm theo lịch trình hoặc trong CI. Khi bạn thay thế bằng một bản dựng đã được lượng tử hóa hoặc một bản 2.2 trong tương lai, bộ công cụ sẽ cho bạn biết trong vài phút liệu tính trong suốt còn hoạt động hay không và liệu seed còn tái tạo được hay không.
- Mô phỏng nó trong khi GPU đang bận. Mô phỏng thông minh của Apidog trả về một PNG đã được định sẵn cho cùng một hợp đồng, để giao diện người dùng tiếp tục xây dựng.
Vì Apidog cũng tạo đặc tả OpenAPI và tài liệu từ điểm cuối bạn đã định nghĩa, hợp đồng của lớp bao bọc sẽ có thể chia sẻ ngay khi nó hoạt động. Tải Apidog và nhập điểm cuối ở trên để bắt đầu.
Tùy chọn: viết lại prompt với PE-T2I
Space demo biến các yêu cầu một dòng thành các prompt có cấu trúc dài bằng cách sử dụng Qwen-Image-2.1-PE-T2I, một Qwen3.5-VL 9B đã được tinh chỉnh trả về JSON với một prompt tiếng Anh mở rộng và tỷ lệ khung hình được khuyến nghị. Chạy nó như một dịch vụ thứ hai trước /v1/images, hoặc bỏ qua nó và tự viết các prompt đầy đủ. Nếu bạn thêm nó, hãy kiểm tra riêng: đó là một API văn bản với hợp đồng JSON, và một bộ viết lại bị lỗi sẽ tạo ra các hình ảnh xấu trông giống như một lỗi trình tạo.
Câu hỏi thường gặp
Một pipeline có thực hiện cả tạo và chỉnh sửa không? Có. QwenImage21Pipeline tạo hình ảnh khi được gọi chỉ với một prompt và chỉnh sửa khi bạn truyền image (một hình ảnh PIL duy nhất hoặc một danh sách tối đa 10 hình ảnh).
Làm cách nào để có được một PNG trong suốt? Bắt đầu prompt bằng "This is an RGBA image with transparency" và nói rằng nền là trong suốt. Kiểm tra image.mode == "RGBA" trên kết quả.
Các cài đặt được khuyến nghị là gì? 40 bước suy luận và bfloat16, theo README. Các giá trị hướng dẫn không được liệt kê cho 2.1; các bản phát hành Qwen-Image trước đó đã sử dụng true_cfg_scale=4.0, vì vậy hãy thử nếu đầu ra trông kém được hướng dẫn [XÁC MINH].
Tôi có thể sử dụng cái này trong một sản phẩm thương mại không? Không theo giấy phép mặc định. Qwen-Image-2.1 được phát hành dưới Giấy phép Nghiên cứu Qwen; việc sử dụng thương mại yêu cầu một giấy phép riêng từ Qwen. Chi tiết trong Qwen-Image-2.1 là gì.
Có API được lưu trữ thay thế không? Qwen Image 3.0 và 3.0 Pro là các mô hình hình ảnh được lưu trữ của Alibaba với giá theo từng hình ảnh. So sánh 2.1 và 3.0 bao gồm khi nào nên tự lưu trữ và khi nào nên thuê.
Tiếp theo
Bây giờ bạn có bốn cuộc gọi đang hoạt động, một lớp bao bọc với hợp đồng ổn định và một bộ thử nghiệm kiểm tra hai thuộc tính quan trọng nhất đối với mô hình này, tính trong suốt và khả năng tái tạo. Tiếp theo, hãy quyết định xem giấy phép nghiên cứu có phù hợp với việc sử dụng của bạn không, hoặc liệu API 3.0 được lưu trữ có phù hợp hơn không, và giữ cả hai đằng sau cùng một bộ sưu tập Apidog để việc chuyển đổi chỉ là thay đổi URL cơ sở, chứ không phải viết lại.