Qwen-Image-2.1은 2026년 9월 20일 알리바바가 공개한 오픈 가중치 이미지 모델입니다. 이 모델은 텍스트-이미지 생성, 최대 10개의 참조 이미지를 사용한 편집, 그리고 기본 투명(RGBA) 출력을 처리하는 70억 매개변수 생성기입니다. 이 가이드는 pip install부터 작동하는 HTTP 엔드포인트까지 안내합니다. [GitHub README](https://github.com/QwenLM/Qwen-Image-2.1)에서 제공하는 4가지 참조 코드 경로, 중요한 설정, 모델을 다른 이미지 API처럼 호출할 수 있도록 하는 작은 FastAPI 래퍼, 그리고 프롬프트 변경 및 모델 업데이트가 앱을 손상시키지 않도록 [Apidog](https://apidog.com)에서 엔드포인트를 테스트하는 방법을 다룹니다.
배경 정보가 먼저 필요하다면, Qwen-Image-2.1이란 무엇인가에서 아키텍처와 라이선스를 다룹니다. 라이선스 요약: Qwen으로부터 별도의 상업적 계약을 얻지 않는 한 연구 및 비상업적 용도로만 사용 가능합니다. 아래의 모든 내용은 평가를 위해 사용해도 좋습니다.
버튼
시작하기 전에
| 요구 사항 | 세부 정보 |
|---|---|
| Python 패키지 | torch>=2.4.0, transformers>=5.17, GitHub main의 diffusers, accelerate, pillow |
| 파이프라인 클래스 | QwenImage21Pipeline (생성 및 편집을 위한 단일 클래스) |
| 가중치 | Qwen/Qwen-Image-2.1, bf16 safetensors |
| GPU | Qwen에서 지정하지 않음; 참조 코드는 bfloat16에서 하나의 CUDA 장치를 대상으로 하며, enable_model_cpu_offload()가 대체 옵션임 |
| 기본 출력 | 2048 x 2048; 40 추론 단계 |
| 선택 사항 | Qwen-Image-2.1-PE-T2I / PE-I2I 프롬프트 재작성 모델 |
설치:
pip install "torch>=2.4.0" "transformers>=5.17" accelerate pillow
pip install git+https://github.com/huggingface/diffusers
diffusers 통합은 출시일에 전용 PR로 적용되었으므로, 9월 20일 이전의 PyPI 릴리스에는 파이프라인 클래스가 없을 것입니다.
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")
두 가지 주목할 점이 있습니다. 프롬프트는 간판 텍스트를 따옴표로 묶습니다. Qwen의 텍스트 렌더링은 사람들이 이 모델 라인을 선택하는 이유이며, 문자열을 따옴표로 묶는 것은 이전 릴리스부터의 관례입니다. 그리고 시드는 명시적입니다. 테스트하려는 모든 요청에서 이 방식을 유지하십시오. 고정된 시드만이 이미지 엔드포인트를 충분히 재현 가능하게 만들어 검증할 수 있기 때문입니다.
정사각형이 아닌 출력이 필요한 경우 지원되는 표에서 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단계: 투명 출력
투명도는 프롬프트에 의해 결정됩니다. 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으로 가져갈 첫 번째 테스트가 될 것입니다. RGBA를 요청했을 때 조용히 RGB를 반환하는 모델은 사용자 여러분이 먼저 발견할 버그입니다.
3단계: 한 개 또는 최대 열 개의 이미지로 편집하기
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")
출시 게시물에서 로컬 편집은 세 가지 방식으로 작동합니다: 프롬프트에서 색상으로 참조하는 색상 원, 그림 주석, 또는 수정되지 않은 원본과 별도의 마스크 이미지를 두 개의 입력으로 전달하는 방식입니다. README에는 전용 마스크 예제가 없으므로, 먼저 image=[original, mask] 형식과 마스크된 영역에 들어갈 내용을 설명하는 프롬프트를 시도해 보십시오 [마스크 예제가 추가되면 README와 비교하여 확인].
편집은 또한 2.1의 속도 작업이 드러나는 부분이기도 합니다. 참조 이미지와 지침은 노이즈 제거 단계 전반에 걸쳐 정적이므로, 모델은 키-값 캐시를 한 번 계산하고 재사용합니다. 10개의 참조는 1개 참조의 10배보다 훨씬 적은 비용이 듭니다.
4단계: GPU에 맞추기
Qwen은 VRAM 수치를 공개하지 않았습니다. 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는 템플릿 워크플로우를 통해 기본 지원을 제공합니다. GPU가 없는 경우, 무료 옵션은 호스팅된 데모와 Qwen Chat을 다룹니다.
5단계: HTTP API로 래핑하기
애플리케이션 코드는 diffusers를 직접 임포트해서는 안 됩니다. 파이프라인을 작은 서비스 뒤에 두어 버전 관리, 모의(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단계: Apidog에서 엔드포인트 테스트하기
이제 이것은 API이며, gpt-image-2.5 API 또는 Nano Banana 2 API에 적용하는 것과 동일한 규칙이 여기에 적용됩니다. Apidog에서:
- 엔드포인트 생성:
POST {{base_url}}/v1/images로 엔드포인트를 생성하며, 멀티파트 바디에는prompt,aspect,transparent,seed,steps, 그리고 반복 가능한references파일 필드를 포함합니다.base_url을 환경에 넣어 동일한 컬렉션이 노트북, GPU 서버 또는 모의(mock)를 가리키도록 합니다. seed=42와 네온사인 프롬프트를 사용하여 텍스트-이미지 요청 전송합니다.200,Content-Type: image/png,X-Image-Mode: RGB를 확인합니다.- 사후 처리기에 어설션 추가: 상태는 200이고,
transparent=true일 때X-Image-Mode는RGBA와 같아야 하며, 응답 본문 크기는 최소 크기 이상이어야 합니다 (2KB로 돌아오는 2K PNG는 빈 이미지입니다), 그리고X-Seed는 보낸 값을 반영해야 합니다. - 동일한 방식으로 투명성 케이스와 세 개의 참조 이미지 편집 요청을 파일 필드에 이미지를 첨부하여 보냅니다. 각각을 테스트 케이스로 저장합니다.
- 일정에 따라 또는 CI에서 테스트 시나리오로 실행합니다. 양자화된 빌드나 미래의 2.2 버전으로 교체할 때, 이 스위트(suite)는 투명성이 여전히 작동하는지, 시드가 여전히 재현되는지 몇 분 안에 알려줍니다.
- GPU가 바쁠 때 모의(mock) 테스트합니다. Apidog의 스마트 모의는 동일한 계약에 대해 미리 준비된 PNG를 반환하므로 프론트엔드는 계속 빌드할 수 있습니다.
Apidog은 정의한 엔드포인트에서 OpenAPI 스펙과 문서를 생성하기 때문에, 래퍼의 계약은 작동하는 즉시 공유 가능해집니다. Apidog 다운로드 후 위에 설명된 엔드포인트를 임포트하여 시작하십시오.
선택 사항: PE-T2I를 사용한 프롬프트 재작성
데모 Space는 Qwen-Image-2.1-PE-T2I를 사용하여 한 줄 요청을 길고 구조화된 프롬프트로 변환합니다. Qwen-Image-2.1-PE-T2I는 확장된 영어 프롬프트와 권장 종횡비를 포함하는 JSON을 반환하는 미세 조정된 Qwen3.5-VL 9B 모델입니다. 이것을 /v1/images 앞에 두 번째 서비스로 실행하거나, 건너뛰고 직접 전체 프롬프트를 작성할 수 있습니다. 추가한다면 별도로 테스트하십시오: 이것은 JSON 계약을 가진 텍스트 API이며, 손상된 재작성기는 생성기 버그처럼 보이는 나쁜 이미지를 생성할 수 있습니다.
자주 묻는 질문 (FAQ)
하나의 파이프라인으로 생성과 편집을 모두 할 수 있나요? 네. QwenImage21Pipeline은 프롬프트만으로 호출될 때 이미지를 생성하고, image(단일 PIL 이미지 또는 최대 10개의 이미지 리스트)를 전달하면 이미지를 편집합니다.
투명한 PNG를 어떻게 얻나요? 프롬프트를 "이것은 투명도가 있는 RGBA 이미지입니다(This is an RGBA image with transparency)"로 시작하고 배경이 투명하다고 명시하세요. 결과에서 image.mode == "RGBA"인지 확인하세요.
권장 설정은 무엇인가요? README에 따르면 40 추론 단계와 bfloat16입니다. 2.1 버전에서는 가이던스 값이 명시되어 있지 않지만, 이전 Qwen-Image 릴리스에서는 true_cfg_scale=4.0을 사용했으므로, 출력이 충분히 가이드되지 않은 것처럼 보인다면 이를 시도해 보세요 [확인 필요].
상업용 제품에 사용할 수 있나요? 기본 라이선스 하에서는 불가능합니다. Qwen-Image-2.1은 Qwen 연구 라이선스(Qwen Research License)로 제공되며, 상업적 사용은 Qwen으로부터 별도의 라이선스를 받아야 합니다. 자세한 내용은 Qwen-Image-2.1이란 무엇인가를 참조하십시오.
호스팅된 API가 대신 있나요? Qwen Image 3.0 및 3.0 Pro는 이미지당 가격이 책정되는 알리바바의 호스팅 이미지 모델입니다. 2.1과 3.0 비교는 자체 호스팅 시기와 임대 시기를 다룹니다.
다음 단계
이제 네 가지 작동하는 호출, 안정적인 계약을 가진 래퍼, 그리고 이 모델에서 가장 중요한 두 가지 속성인 투명성과 재현성을 확인하는 테스트 스위트를 갖게 되었습니다. 다음으로, 연구 라이선스가 사용 목적에 맞는지, 또는 호스팅된 3.0 API가 더 적합한지 결정하고, 스위칭이 기본 URL 변경이지 재작성이 아니도록 두 가지 모두 동일한 Apidog 컬렉션 뒤에 유지하십시오.