Qwen-Image 2.1

Setup으로 텍스트-투-이미지, 단일 이미지 편집, 또는 다중 이미지 편집을 선택합니다. Server는 배치(placement), 어텐션, 인코더 스케줄링, VAE 타일링, 그래프 실행, 요청 배칭을 제어합니다. Request는 배경, 해상도, 스텝, 출력 수를 제어합니다. Variables 아래에 레퍼런스 PNG 경로를 설정하세요. 편집은 cURL을 실행하는 머신에서 파일을 업로드하므로 서버에 존재할 필요가 없습니다.

하드웨어 선택은 해당 GPU에 권장 배치를 적용합니다. H200, B200, RTX PRO 6000 96GB, DGX Spark는 가중치를 상주시키고, RTX 5090과 RTX 4090은 전체 파이프라인에 맞도록 선택 컴포넌트를 오프로드합니다. 테스트되지 않은 토폴로지와 기능 조합은 여전히 선택 가능하며 Unverified로 표시됩니다. 잘못된 토폴로지 조합은 Copy를 비활성화합니다. 이 통합은 현재 Python/소스 명령을 사용하며, 공개된 Docker 이미지가 검증된 것은 없습니다.

두 요청 모드 모두 base64 PNG를 반환합니다. 모든 반환 이미지를 저장하려면 요청 명령에 > response.json을 추가한 후 실행:

python - <<'PY'
import base64
import json
from pathlib import Path

for i, item in enumerate(json.loads(Path("response.json").read_text())["data"]):
    Path(f"output-{i}.png").write_bytes(base64.b64decode(item["b64_json"]))
PY

권장 하드웨어 설정 (Recommended hardware settings)

선택기는 기본적으로 네이티브 BF16/FP32 정밀도, 정확 어텐션, eager 실행, 전체-이미지 VAE 디코딩을 사용합니다. 명령은 GPU 1개, 인코더 auto 스케줄링, 배치 크기 1 같은 기본값을 생략합니다. 명시적 배치·어텐션 오버라이드는 각 레시피를 보존합니다.

2026-09-20에 1024×1024, 40 스텝, CFG 1, 요청당 RGBA PNG 1개로 측정. 시간은 워밍업 후 중앙값 HTTP 지연으로, PNG 직렬화를 포함하고 시작은 제외. VRAM은 샘플링된 요청 단계 최고. 프롬프트와 소프트웨어 버전이 지연·메모리 사용에 모두 영향을 줍니다.

RTX 5090은 DiT layerwise 오프로드와 Torch SDPA를 사용합니다. 이 레시피는 업데이트된 체크포인트로 재테스트되지 않았습니다. RTX 5090과 RTX PRO 6000은 모두 이 런타임에서 FlashAttention이 선택되면 SDPA를 사용합니다. CPU 오프로드는 호스트 RAM이 필요합니다.

DGX Spark

Linux ARM64 + CUDA 13에서 GB10 GPU 1개에는 DGX Spark를 선택하세요. 위 소스 설치를 사용하세요. 권장 구성은 모든 컴포넌트를 상주시키고 네이티브 BF16/FP32 정밀도를 사용하며 런타임이 Torch SDPA를 선택하게 합니다:

sglang serve \
  --model-path Qwen/Qwen-Image-2.1 \
  --performance-mode speed

128 GB 통합 메모리는 CPU와 GPU가 공유합니다. 검증된 단일 이미지 1024×1024 워크로드에는 CPU 오프로드가 필요 없습니다. 전체-이미지 VAE 디코딩과 eager 실행을 유지하세요. 생성, 편집, 투명 생성, 투명 편집이 PyTorch 2.13.0+cu130으로 검증되었습니다. Spark는 nvidia-smi에서 별도 VRAM 사용을 보고하지 않습니다. 이 레시피는 Spark 1개를 다룹니다. 다중 노드 배포와 배칭은 검증되지 않았습니다.

배칭 (Batching)

대화형 사용에는 Request batching → Off와 Outputs → 1을 유지하세요. 배칭은 개별 요청 지연을 늘리고 더 높은 처리량을 보장하지 않습니다. 활성화 전에 워크로드를 측정하세요.

교차 요청 배칭은 호환되는 텍스트-투-이미지 요청을 병합합니다. 이미지 편집은 별도로 실행됩니다. Outputs는 한 요청 내 여러 이미지를 제어합니다. RTX 4090에서 여러 출력 또는 요청 배칭을 선택하면 메모리 여유를 위해 DiT layerwise 오프로드로 전환합니다. 업데이트된 Server 명령으로 재시작하세요.

배칭은 네이티브 정밀도를 보존하지만 같은 시드에서도 부동소수점 반올림과 출력 픽셀을 바꿀 수 있습니다. 수용 규칙·메트릭은 추론 배칭 참조.

2. 모델 기능 (Model capabilities)

Qwen-Image 2.1은 텍스트-투-이미지 생성, 단일·다중 이미지 편집, RGBA 출력을 지원합니다. 모든 모드에 하나의 체크포인트를 사용하세요.

다회차 편집의 경우 이전 출력을 다음 레퍼런스 이미지로 보냅니다. 서버는 대화 상태를 유지하지 않습니다. 조건-프리픽스 KV 캐시는 한 요청 내에서 재사용됩니다. 교차 요청·대화 기록 캐싱은 구현되지 않았습니다.

3. 체크포인트 레이아웃 (Checkpoint layout)

체크포인트 디렉터리는 model_index.json과 processor, text_encoder, transformer, vae, scheduler 하위 디렉터리를 포함해야 합니다. processor는 Qwen3-VL 토크나이저 자산을 포함하므로 별도 tokenizer 디렉터리가 필요 없습니다. 로컬 체크포인트 디렉터리 이름이 다를 때 --model-id Qwen-Image-2.1을 사용하세요. 이전 Qwen-Image·Qwen-Image-Edit transformer/VAE 가중치는 호환되지 않습니다.

SGLang의 설치된 의존성을 유지하세요. 그 네이티브 인코더는 런타임 전반 다운그레이드 없이 레퍼런스의 Transformers 4.57.3 컨디셔닝 의미를 보존합니다.

투명 PNG 출력 (Transparent PNG output)

Request 아래에서 Transparent / alpha를 선택하고 프롬프트에 투명 배경의 분리된 주체를 설명하세요. 선택기가 이 지시를 추가하고 PNG를 선택합니다. background: "transparent"만으로는 컨디셔닝을 바꾸거나 배경을 제거하지 않습니다. JPEG는 알파를 유지할 수 없습니다.

PNG 레퍼런스는 편집 중 알파 채널을 유지합니다. RGB 레퍼런스는 불투명 알파 채널을 받습니다. 모델은 부분적으로 투명한 가장자리를 포함한 연속 알파 값을 임계값 처리 없이 예측합니다.

4. 오프라인 요청 (Offline requests)

기본값은 1024×1024, 40 스텝, CFG 1, 시드 42이며 출력 저장이 활성화됩니다. 오프로드가 필요한 GPU는 선택기의 배치 플래그도 전달하세요.

텍스트-투-이미지 (Text-to-image)

sglang generate \
  --model-path Qwen/Qwen-Image-2.1 \
  --prompt "A capybara reading a book by candlelight"

이미지 조건 편집 (Image-conditioned editing)

sglang generate \
  --model-path Qwen/Qwen-Image-2.1 \
  --image-path /path/to/input.png \
  --prompt "Move the scene to a snowy mountain at sunrise"

높이·너비는 32의 양의 배수여야 합니다. 레퍼런스 이미지는 자체 종횡비를 보존하고 요청 출력 면적에 대략 맞게 리사이즈됩니다. 같은 리사이즈 이미지가 VLM과 VAE에 공급됩니다. 이미지 레이블은 결정적(Picture 1, Picture 2 등)입니다. 여러 출력은 독립 노이즈 시드와 독립 프리픽스 캐시를 받습니다.

5. 런타임 기능 (Runtime features)

기본은 CFG 비활성화된 40 Euler flow-matching 스텝입니다. CFG에는 --negative-prompt와 1보다 큰 --guidance-scale을 제공하세요. API는 텍스트 프롬프트를 요구합니다. 사전 계산된 임베딩만으로는 불충분합니다.

• 병렬성: TP, Ulysses, Ring, CFG 병렬성, 인코더 폴딩이 선택기에서 제공됩니다. 대상 토큰 수 (height / 16) × (width / 16)는 SP 정도로 나누어져야 합니다. Ring은 FlashAttention 또는 SageAttention이 필요합니다.
• 메모리: 하드웨어의 권장 배치를 사용하세요. All components layerwise는 인코더와 VAE 블록도 스트리밍해 전송과 더 낮은 디바이스 메모리를 맞바꿉니다.
• VAE: 전체-이미지 디코딩이 기본입니다. 타일링은 경계 근처 픽셀을 바꿀 수 있습니다. GPU가 2개 이상이면 Spatial shard가 타일링 없이 전체-이미지 디코딩을 분산합니다. 부동소수점 반올림은 여전히 다를 수 있습니다.

구성 지원은 호환성 인벤토리, 공유 런타임 옵션은 성능 가이드 참조.

양자화 (Quantization)

네이티브 정밀도가 기본입니다. 양자화는 이미지와 알파 값을 바꿉니다. 자신의 프롬프트·레퍼런스 이미지에서 품질을 확인하세요. 내보낸 형식을 선택할 때 Variables 아래에 호환 컴포넌트 경로를 설정하세요. 네이티브 가중치에 양자화 메타데이터를 추가해도 변환되지 않습니다.

온라인 FP8의 경우 --component-quantizations.transformer fp8, --component-quantizations.text_encoder fp8 또는 둘 다 사용하세요.

직렬화 FP8 컴포넌트 (Serialized FP8 components)

Serialized FP8 옵션을 선택하고 내보낸 컴포넌트 디렉터리를 설정하세요. 각 디렉터리는 아키텍처 config.json, 가중치, 양자화 메타데이터가 필요합니다. --component-paths.transformer 및/또는 --component-paths.text_encoder를 사용하세요. 온라인 양자화 플래그는 생략하세요. 형식은 양자화 가이드 참조.

GGUF 컴포넌트

GGUF 옵션을 선택하고 .gguf 파일을 설정하세요. 선택기는 --component-weights-paths.transformer 및/또는 --component-weights-paths.text_encoder를 사용하며 기본 체크포인트에서 아키텍처 구성을 유지합니다. 각 파일은 네이티브 텐서 이름으로 전체 컴포넌트를 포함해야 합니다. GGUF는 가중치 저장을 줄이지만 낮은 지연을 보장하지 않습니다. GGUF 가이드 참조.

NVFP4 컴포넌트

NVFP4는 Blackwell과 호환 ModelOpt 내보내기가 필요합니다. --component-paths.transformer 및/또는 --component-paths.text_encoder로 컴포넌트 디렉터리를 선택하세요. RTX 5090, RTX PRO 6000, DGX Spark에서 FlashInfer 백엔드를 auto로 유지하세요. TensorRT-LLM FP4 GEMM은 SM12.x를 지원하지 않습니다. 이 GPU들은 이 모델의 NVFP4 내보내기에 대해 검증되지 않았습니다. NVFP4 가이드 참조.

LoRA와 실행 옵션 (LoRA and execution options)

--lora-path와 --lora-merge-mode dynamic|merge 또는 런타임 어댑터 API를 사용하세요. transformer. 접두사의 Diffusers 어댑터 키는 네이티브 DiT에 매핑됩니다.

eager 실행을 기본으로 유지하세요. Breakable CUDA Graph 재생은 일치하는 해상도와 조건-프리픽스 길이가 필요합니다. 보이지 않는 형태는 eager로 실행됩니다. 텍스트 버킷만으로는 재생을 보장하지 않습니다. SageAttention과 Cache-DiT는 수치 결과를 바꿀 수 있으며 워크로드 품질 검사가 필요합니다.

Cache-DiT

--enable-cache-dit true 또는 SGLANG_CACHE_DIT_ENABLED=true로 활성화하세요. 2.1 프리픽스 KV는 레이어별입니다. 각 블록은 _layer_id로 캐시를 슬라이스합니다. Cache-DiT는 transformer_blocks를 감싸고 같은 extras를 모든 레이어에 전달합니다. 그 슬라이스가 없으면 더 나중 레이어가 레이어 0을 재사용해 이미지가 컬러 노이즈로 붕괴됩니다. Cache-DiT 가이드 참조.

더 알아보기 (Learn more)

• Qwen-Image 2.1
• 성능 가이드
• 양자화 가이드
• Cache-DiT 가이드