{
  "hf_id": "Qwen/Qwen-Image",
  "meta": {
    "title": "Qwen-Image",
    "slug": "qwen-image",
    "provider": "Qwen",
    "description": "Text-to-image diffusion model (20B parameters) from the Qwen-Image family, served via vLLM-Omni.",
    "date_added": "2026-04-03",
    "date_updated": "2026-04-17",
    "tasks": [
      "omni"
    ],
    "performance_headline": "Shared DiT core across T2I, image editing, and layered-image variants; accelerated via Cache-DiT, TeaCache, and sequence parallelism",
    "related_recipes": []
  },
  "model": {
    "model_id": "Qwen/Qwen-Image",
    "min_vllm_version": "0.18.0",
    "architecture": "dense",
    "parameter_count": "20B",
    "active_parameters": "20B",
    "context_length": 0,
    "base_args": [],
    "base_env": {},
    "install": {
      "pip": {
        "command": "uv venv\nsource .venv/bin/activate\nuv pip install -U vllm --torch-backend auto"
      },
      "docker": {
        "command": "docker pull vllm/vllm-openai:latest"
      },
      "extras": [
        {
          "note": "vLLM-Omni must be installed from source and pins vllm==0.18.0 for diffusion support",
          "command": "git clone https://github.com/vllm-project/vllm-omni.git && cd vllm-omni && uv pip install -e . vllm==0.18.0"
        }
      ]
    }
  },
  "omni": {
    "tasks": [
      "t2i"
    ]
  },
  "features": {},
  "opt_in_features": [],
  "variants": {
    "default": {
      "precision": "bf16",
      "vram_minimum_gb": 48,
      "description": "Full precision BF16 — use CPU offload / layerwise offload for lower VRAM"
    },
    "fp8": {
      "precision": "fp8",
      "vram_minimum_gb": 24,
      "description": "FP8 quantization with `img_mlp` kept at full precision for quality.",
      "extra_args": [
        "--quantization",
        "fp8",
        "--ignored-layers",
        "img_mlp"
      ]
    },
    "int8": {
      "precision": "int8",
      "vram_minimum_gb": 24,
      "description": "INT8 quantization (`--quantization int8`).",
      "extra_args": [
        "--quantization",
        "int8"
      ]
    }
  },
  "hardware_overrides": {},
  "guide": "## Overview\n\nQwen-Image is a diffusion-based text-to-image model. This recipe documents the Qwen-Image family served via **vLLM-Omni**:\n\n| Model | HuggingFace | Description |\n|-------|-------------|-------------|\n| **Qwen-Image** | [Qwen/Qwen-Image](https://huggingface.co/Qwen/Qwen-Image) | Text-to-image (20B, Aug 2025) |\n| **Qwen-Image-2512** | [Qwen/Qwen-Image-2512](https://huggingface.co/Qwen/Qwen-Image-2512) | Updated T2I with enhanced realism (Dec 2025) |\n| **Qwen-Image-Edit** | [Qwen/Qwen-Image-Edit](https://huggingface.co/Qwen/Qwen-Image-Edit) | Single-image editing (Aug 2025) |\n| **Qwen-Image-Edit-2509** | [Qwen/Qwen-Image-Edit-2509](https://huggingface.co/Qwen/Qwen-Image-Edit-2509) | Multi-image editing (Sep 2025) |\n| **Qwen-Image-Edit-2511** | [Qwen/Qwen-Image-Edit-2511](https://huggingface.co/Qwen/Qwen-Image-Edit-2511) | Enhanced consistency + built-in LoRA (Nov 2025) |\n| **Qwen-Image-Layered** | [Qwen/Qwen-Image-Layered](https://huggingface.co/Qwen/Qwen-Image-Layered) | Decomposes input into RGBA layers (Dec 2025) |\n\nAll models share the same DiT transformer core — acceleration methods are applicable across the entire series.\n\n## Prerequisites\n\n```bash\ngit clone https://github.com/vllm-project/vllm-omni.git\ncd vllm-omni\nuv venv\nsource .venv/bin/activate\nuv pip install -e . vllm==0.18.0\n```\n\n## Usage\n\n### Text-to-Image\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image \\\n    --prompt \"a cup of coffee on the table\" \\\n    --output output_qwen_image.png \\\n    --num-inference-steps 50 \\\n    --cfg-scale 4.0\n```\n\n### Image Editing (Qwen-Image-Edit)\n```bash\npython3 ./examples/offline_inference/image_to_image/image_edit.py \\\n    --model Qwen/Qwen-Image-Edit \\\n    --image qwen_bear.png \\\n    --prompt \"Let this mascot dance under the moon, surrounded by floating stars\" \\\n    --output output_image_edit.png \\\n    --num-inference-steps 50 \\\n    --cfg-scale 4.0\n```\n\n### Layered RGBA Decomposition\n```bash\npython3 ./examples/offline_inference/image_to_image/image_edit.py \\\n    --model Qwen/Qwen-Image-Layered \\\n    --image input.png \\\n    --prompt \"\" \\\n    --output layered \\\n    --num-inference-steps 50 \\\n    --cfg-scale 4.0 \\\n    --layers 4 \\\n    --color-format \"RGBA\"\n```\n\n## Acceleration\n\nPick one cache backend AND any supported parallel strategy.\n\n### Cache-DiT\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --cache-backend cache_dit\n```\n\n### TeaCache\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --cache-backend tea_cache\n```\n\n### Ulysses / Ring Sequence Parallelism\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --ulysses-degree 4\n```\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --ring-degree 4\n```\n\n### CFG Parallelism (2 GPUs, non-distilled models with `cfg-scale > 1`)\n```bash\npython3 ./examples/offline_inference/image_to_image/image_edit.py \\\n    --model Qwen/Qwen-Image-Edit --image qwen_bear.png --prompt \"...\" \\\n    --cfg-parallel-size 2 --num-inference-steps 50 --cfg-scale 4.0\n```\n\n### Tensor Parallelism\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --tensor-parallel-size 2\n```\n\n### CPU / Layerwise Offload (low VRAM)\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --enable-cpu-offload\n```\n```bash\npython3 ./examples/offline_inference/image_to_image/image_edit.py \\\n    --model Qwen/Qwen-Image-Edit --image qwen_bear.png --prompt \"...\" \\\n    --enable-layerwise-offload\n```\n\n### VAE Patch Parallelism\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" \\\n    --height 1536 --width 1536 \\\n    --ulysses-degree 2 --vae-patch-parallel-size 2\n```\nMust be combined with another parallel method.\n\n### Quantization (Qwen-Image / Qwen-Image-2512 only)\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --quantization fp8 \\\n    --ignored-layers \"img_mlp\"\n```\n```bash\npython3 ./examples/offline_inference/text_to_image/text_to_image.py \\\n    --model Qwen/Qwen-Image --prompt \"...\" --quantization int8\n```\n\nQwen-Image-Edit variants do **not** support quantization.\n\n## Configuration Tips\n\n- **Cache + SP** is the recommended combo for long-sequence generation.\n- **Sequence parallelism** (Ulysses / Ring) beats TP for high-res / long-sequence.\n- **Tensor parallelism** is most useful when model weights alone don't fit on one GPU.\n- **CFG parallelism** targets non-distilled diffusion with full CFG (not for guidance-distilled models).\n- To reduce peak VRAM, use CPU/layerwise offload and/or VAE patch parallelism.\n- TeaCache and Cache-DiT cannot be used together.\n- `--enforce-eager` disables torch.compile if needed.\n\nSee the [Feature Support Table](https://github.com/vllm-project/vllm-omni/blob/main/docs/user_guide/diffusion_features.md#supported-models) and [Feature Compatibility Guide](https://github.com/vllm-project/vllm-omni/blob/main/docs/user_guide/feature_compatibility.md) for combinations.\n\n## References\n\n- [Model card](https://huggingface.co/Qwen/Qwen-Image)\n- [vLLM-Omni](https://github.com/vllm-project/vllm-omni)\n",
  "source": {
    "source": "vllm-omni",
    "repo": "vllm-project/vllm-omni",
    "ref": "main",
    "sha": "cda4a1ef83b295ba332146a7709e6277725edc9f",
    "path": "recipes/models/Qwen/Qwen-Image.yaml",
    "edit_url": "https://github.com/vllm-project/vllm-omni/edit/main/recipes/models/Qwen/Qwen-Image.yaml",
    "overlays": []
  }
}