# qwenlm/qwen-image architecture

> Architecture diagram of the GitHub repository qwenlm/qwen-image, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qwenlm/qwen-image
- Repository: https://github.com/qwenlm/qwen-image

## Overview

1. **Repository purpose and boundary**
   - This repo is primarily a **model distribution + usage repository**, not a full application.
   - The core model weights and inference engine live outside the repo in **Hugging Face `diffusers`** and the published model checkpoints (`Qwen/Qwen-Image*`).
   - What this repo adds is: documentation, prompt-optimization helpers, and runnable example scripts for generation/editing demos.

2. **Top-level content split**
   - **README.md** is the central architecture entry point: it documents model variants, quick-start usage, deployment notes, and external ecosystem support.
   - **`Qwen-Image.md`, `Qwen-Image-Edit.md`, `Qwen-Image-Edit-2509.md`** are versioned showcase/docs for specific releases.
   - **`assets/`** contains static supporting material used by the docs and contact links.
   - **`src/examples/`** is the only executable code area in the tree.

3. **Primary runtime model: external Diffusers pipelines**
   - The repo’s examples are built around **Diffusers pipelines**:
     - `QwenImagePipeline` for text-to-image.
     - `QwenImageEditPipeline` / `QwenImageEditPlusPipeline` for image editing.
   - The repo does not define these models itself; it assumes the user installs recent `transformers` and `diffusers`, then loads checkpoints via `from_pretrained(...)`.
   - This means the real computation boundary is: **Python example script → Diffusers pipeline → model weights/runtime → generated image**.

4. **Text-to-image data flow**
   - In the T2I examples, the input is a **text prompt** plus optional **negative prompt**, resolution, guidance scale, seed, and inference step count.
   - The prompt may first pass through a **prompt enhancement** helper before reaching the pipeline.
   - The pipeline runs on **CUDA if available, otherwise CPU**, and returns one or more generated images.
   - The output boundary is simple: **PIL image saved to disk** or returned to the caller.

5. **Image-editing data flow**
   - The editing path takes **one or more input images** plus a text instruction.
   - For newer edit releases, the example uses `QwenImageEditPlusPipeline`, which supports **multi-image input** and improved consistency.
   - The edit flow mirrors T2I but with an extra source-image boundary: **image(s) + edit prompt → pipeline → edited output image**.
   - The README emphasizes that editing is more stable when a rewritten/polished prompt is used before inference.

6. **Prompt enhancement subsystem**
   - `src/examples/tools/prompt_utils.py` and `prompt_utils_2512.py` are dedicated to **prompt rewriting / polishing**.
   - The README indicates these helpers use **DashScope-backed Qwen services**:
     - `rewrite(prompt)` for text-to-image prompt enhancement.
     - `polish_edit_prompt(prompt, pil_image)` for edit-task stabilization.
   - Architecturally, this is an **optional upstream NLP service** that sits between user input and the diffusion pipeline.
   - It is an important boundary because it changes the prompt before generation, but it is not part of the image model itself.

7. **Example scripts as orchestration layer**
   - `src/examples/demo.py` appears to be the **interactive multi-GPU demo server**.
   - `src/examples/edit_demo.py` likely provides an editing-focused demo entry point.
   - `src/examples/generate_w_prompt_enhance.py` is the CLI example for generation with prompt rewriting.
   - These scripts are the repo’s orchestration layer: they assemble prompt handling, model loading, inference parameters, and result saving/UI.

8. **Multi-GPU deployment mode**
   - The README describes a **Gradio-based web interface** started from `demo.py`.
   - It supports:
     - **multi-GPU parallel processing**
     - **queue management**
     - **task timeout**
     - **automatic prompt optimization**
     - **multiple aspect ratios**
   - Environment variables such as `NUM_GPUS_TO_USE`, `TASK_QUEUE_SIZE`, and `TASK_TIMEOUT` shape runtime behavior.
   - So the deployment architecture is: **web UI → queue → GPU workers → diffusion pipeline → rendered images**.

9. **Version-specific behavior**
   - The repo distinguishes between multiple model generations:
     - **Qwen-Image**: original text-to-image and edit variants.
     - **Qwen-Image-Edit-2509 / 2511**: stronger editing consistency, multi-image support.
     - **Qwen-Image-2512**: newer text-to-image release with improved realism and text rendering.
   - `prompt_utils_2512.py` suggests the prompt strategy differs by release, so prompt preprocessing is version-aware.
   - In a diagram, these should be shown as **separate model endpoints/checkpoints** sharing the same example/runtime framework.

10. **External ecosystem integrations**
   - The README references integrations with **Hugging Face**, **ModelScope**, **ComfyUI**, **SGLang-Diffusion**, **vLLM-Omni**, and other third-party acceleration stacks.
   - These are not implemented in this repo, but they define the repo’s external architecture boundary: the model can be consumed by multiple downstream runtimes and platforms.
   - For diagramming, treat them as **external consumers / deployment targets** of the Qwen image models.

11. **What is not in this repository**
   - There is no evidence here of:
     - training code,
     - checkpoint storage,
     - low-level diffusion model implementation,
     - API backend beyond the example demo,
     - dataset pipelines.
   - So the repo’s role is best described as **documentation + examples + prompt tooling around externally hosted model weights**.

12. **Best diagram shape**
   - A good architecture diagram should center on three layers:
     - **User / demo entry points**: CLI, Gradio demo, example scripts.
     - **Preprocessing & orchestration**: prompt rewrite/polish, queueing, multi-GPU selection.
     - **Inference engine**: Diffusers pipelines loading Qwen checkpoints and producing images.
   - Then show outbound boundaries to:
     - **DashScope/Qwen prompt enhancement service**
     - **Hugging Face / ModelScope model hosting**
     - **saved image outputs**
     - optionally, the external inference ecosystems listed in the README.

Main entry points: [`src/examples/demo.py`](https://github.com/qwenlm/qwen-image/blob/main/src/examples/demo.py) (Demo), [`README.md`](https://github.com/qwenlm/qwen-image/blob/main/README.md) (README), [`src/examples/edit_demo.py`](https://github.com/qwenlm/qwen-image/blob/main/src/examples/edit_demo.py) (Edit Demo), [`src/examples/generate_w_prompt_enhance.py`](https://github.com/qwenlm/qwen-image/blob/main/src/examples/generate_w_prompt_enhance.py) (Gen + Prompt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_readme["README<br/>entry doc<br/>[README.md]"]
  node_qwen_image_md["Qwen-Image<br/>release doc<br/>[Qwen-Image.md]"]
  node_qwen_edit_md["Qwen-Edit<br/>release doc<br/>[Qwen-Image-Edit.md]"]
  node_qwen_edit_2509_md["Edit 2509<br/>release doc"]
  node_assets["Assets"]
end

subgraph group_examples["Examples"]
  node_demo_py["Demo<br/>[demo.py]"]
  node_edit_demo_py["Edit Demo<br/>[edit_demo.py]"]
  node_gen_prompt_py["Gen + Prompt<br/>cli example"]
  node_prompt_utils_py["Prompt Utils<br/>prompt rewrite<br/>[prompt_utils.py]"]
  node_prompt_utils_2512_py["Prompt 2512<br/>prompt rewrite"]
end

subgraph group_external["External"]
  node_dashscope[("DashScope<br/>external nlp service")]
  node_diffusers["Diffusers<br/>inference runtime"]
  node_qwen_t2i[("Qwen T2I<br/>model checkpoint")]
  node_qwen_edit[("Qwen Edit<br/>model checkpoint")]
  node_qwen_edit_plus[("Edit Plus<br/>model checkpoint")]
  node_hf_modelscope[("HF / ModelScope<br/>hosting platform")]
  node_ecosystems["Ecosystems<br/>downstream runtimes"]
  node_outputs["Image Output<br/>generated artifact"]
end

node_readme -->|"documents"| node_qwen_image_md
node_readme -->|"documents"| node_qwen_edit_md
node_readme -->|"documents"| node_qwen_edit_2509_md
node_readme -->|"points to"| node_demo_py
node_readme -->|"points to"| node_edit_demo_py
node_readme -->|"points to"| node_gen_prompt_py
node_readme -->|"uses"| node_assets
node_demo_py -->|"enhances prompts"| node_prompt_utils_py
node_demo_py -->|"versioned prompts"| node_prompt_utils_2512_py
node_demo_py -->|"runs on"| node_diffusers
node_demo_py -->|"writes"| node_outputs
node_demo_py -->|"loads"| node_qwen_t2i
node_demo_py -->|"loads"| node_qwen_edit
node_demo_py -.->|"optional upstream"| node_dashscope
node_edit_demo_py -->|"enhances prompts"| node_prompt_utils_py
node_edit_demo_py -->|"versioned prompts"| node_prompt_utils_2512_py
node_edit_demo_py -->|"runs on"| node_diffusers
node_edit_demo_py -->|"loads"| node_qwen_edit_plus
node_edit_demo_py -->|"writes"| node_outputs
node_edit_demo_py -.->|"optional upstream"| node_dashscope
node_gen_prompt_py -->|"enhances prompts"| node_prompt_utils_py
node_gen_prompt_py -->|"runs on"| node_diffusers
node_gen_prompt_py -->|"loads"| node_qwen_t2i
node_gen_prompt_py -->|"writes"| node_outputs
node_gen_prompt_py -.->|"optional upstream"| node_dashscope
node_prompt_utils_py -->|"calls"| node_dashscope
node_prompt_utils_2512_py -->|"calls"| node_dashscope
node_diffusers -->|"loads"| node_qwen_t2i
node_diffusers -->|"loads"| node_qwen_edit
node_diffusers -->|"loads"| node_qwen_edit_plus
node_qwen_t2i -->|"hosted on"| node_hf_modelscope
node_qwen_edit -->|"hosted on"| node_hf_modelscope
node_qwen_edit_plus -->|"hosted on"| node_hf_modelscope
node_qwen_t2i -->|"consumed by"| node_ecosystems
node_qwen_edit -->|"consumed by"| node_ecosystems
node_qwen_edit_plus -->|"consumed by"| node_ecosystems
node_dashscope -.->|"influences"| node_outputs

click node_readme "https://github.com/qwenlm/qwen-image/blob/main/README.md"
click node_qwen_image_md "https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image.md"
click node_qwen_edit_md "https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image-Edit.md"
click node_qwen_edit_2509_md "https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image-Edit-2509.md"
click node_assets "https://github.com/qwenlm/qwen-image/tree/main/assets"
click node_demo_py "https://github.com/qwenlm/qwen-image/blob/main/src/examples/demo.py"
click node_edit_demo_py "https://github.com/qwenlm/qwen-image/blob/main/src/examples/edit_demo.py"
click node_gen_prompt_py "https://github.com/qwenlm/qwen-image/blob/main/src/examples/generate_w_prompt_enhance.py"
click node_prompt_utils_py "https://github.com/qwenlm/qwen-image/blob/main/src/examples/tools/prompt_utils.py"
click node_prompt_utils_2512_py "https://github.com/qwenlm/qwen-image/blob/main/src/examples/tools/prompt_utils_2512.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_qwen_image_md,node_qwen_edit_md,node_qwen_edit_2509_md,node_assets toneBlue
class node_demo_py,node_edit_demo_py,node_gen_prompt_py,node_prompt_utils_py,node_prompt_utils_2512_py toneAmber
class node_dashscope,node_diffusers,node_qwen_t2i,node_qwen_edit,node_qwen_edit_plus,node_hf_modelscope,node_ecosystems,node_outputs toneMint
```

## Components

### Docs

Repository docs and release pages

- [README](https://github.com/qwenlm/qwen-image/blob/main/README.md): entry doc · Main overview, usage, deployment, and ecosystem guide · `README.md`
- [Qwen-Image](https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image.md): release doc · Text-to-image release notes and showcase · `Qwen-Image.md`
- [Qwen-Edit](https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image-Edit.md): release doc · Editing release notes and showcase · `Qwen-Image-Edit.md`
- [Edit 2509](https://github.com/qwenlm/qwen-image/blob/main/Qwen-Image-Edit-2509.md): release doc · Later editing release notes and showcase · `Qwen-Image-Edit-2509.md`
- [Assets](https://github.com/qwenlm/qwen-image/tree/main/assets): doc assets · Static supporting materials used by documentation · `assets`

### Examples

Runnable demo and prompt tooling

- [Demo](https://github.com/qwenlm/qwen-image/blob/main/src/examples/demo.py): gradio demo · Interactive multi-GPU web demo and task runner · `src/examples/demo.py`
- [Edit Demo](https://github.com/qwenlm/qwen-image/blob/main/src/examples/edit_demo.py): edit demo · Editing-focused example entry point · `src/examples/edit_demo.py`
- [Gen + Prompt](https://github.com/qwenlm/qwen-image/blob/main/src/examples/generate_w_prompt_enhance.py): cli example · Generation script with prompt enhancement · `src/examples/generate_w_prompt_enhance.py`
- [Prompt Utils](https://github.com/qwenlm/qwen-image/blob/main/src/examples/tools/prompt_utils.py): prompt rewrite · Prompt rewrite and edit-prompt polishing helpers · `src/examples/tools/prompt_utils.py`
- [Prompt 2512](https://github.com/qwenlm/qwen-image/blob/main/src/examples/tools/prompt_utils_2512.py): prompt rewrite · Version-specific prompt rewriting helpers · `src/examples/tools/prompt_utils_2512.py`

### External

Hosted models, services, and downstream runtimes

- **DashScope**: external nlp service · Upstream prompt enhancement service used for rewrite and polish
- **Diffusers**: inference runtime · External pipeline runtime that loads Qwen checkpoints
- **Qwen T2I**: model checkpoint · Text-to-image model weights hosted externally
- **Qwen Edit**: model checkpoint · Image-editing model weights hosted externally
- **Edit Plus**: model checkpoint · Multi-image editing checkpoint used by newer releases
- **HF / ModelScope**: hosting platform · Model distribution and checkpoint hosting boundary
- **Ecosystems**: downstream runtimes · External consumers such as ComfyUI, SGLang-Diffusion, and vLLM-Omni
- **Image Output**: generated artifact · Saved or returned generated images

## Connections

- README → Qwen-Image: documents · Release-specific showcase and usage
- README → Qwen-Edit: documents · Editing release overview
- README → Edit 2509: documents · Later editing release overview
- README → Demo: points to · Primary interactive demo entry point
- README → Edit Demo: points to · Editing demo entry point
- README → Gen + Prompt: points to · CLI generation example
- README → Assets: uses · Documentation assets
- Demo → Prompt Utils: enhances prompts · Optional prompt rewrite/polish
- Demo → Prompt 2512: versioned prompts · Release-specific prompt strategy
- Demo → Diffusers: runs on · Gradio demo orchestrates pipeline inference
- Demo → Image Output: writes · Generated images are returned or saved
- Demo → Qwen T2I: loads · Text-to-image checkpoint
- Demo → Qwen Edit: loads · Edit checkpoint when using editing flows
- Demo → DashScope: optional upstream · Prompt optimization service
- Edit Demo → Prompt Utils: enhances prompts · Edit prompt stabilization
- Edit Demo → Prompt 2512: versioned prompts · Release-specific edit prompting
- Edit Demo → Diffusers: runs on · Editing pipeline execution
- Edit Demo → Edit Plus: loads · Multi-image editing checkpoint
- Edit Demo → Image Output: writes · Edited images are saved or returned
- Edit Demo → DashScope: optional upstream · Prompt polishing service
- Gen + Prompt → Prompt Utils: enhances prompts · Text-to-image prompt rewriting
- Gen + Prompt → Diffusers: runs on · Single-shot generation script
- Gen + Prompt → Qwen T2I: loads · Text-to-image checkpoint
- Gen + Prompt → Image Output: writes · Generated image file output
- Gen + Prompt → DashScope: optional upstream · Prompt optimization service
- Prompt Utils → DashScope: calls · Uses Qwen prompt services for rewrite and polish
- Prompt 2512 → DashScope: calls · Version-specific prompt rewriting
- Diffusers → Qwen T2I: loads · Text-to-image pipeline binds to checkpoint
- Diffusers → Qwen Edit: loads · Edit pipeline binds to checkpoint
- Diffusers → Edit Plus: loads · Plus edit pipeline binds to checkpoint
- Qwen T2I → HF / ModelScope: hosted on · External model distribution boundary
- Qwen Edit → HF / ModelScope: hosted on · External model distribution boundary
- Edit Plus → HF / ModelScope: hosted on · External model distribution boundary
- Qwen T2I → Ecosystems: consumed by · Downstream inference and UI stacks
- Qwen Edit → Ecosystems: consumed by · Downstream inference and UI stacks
- Edit Plus → Ecosystems: consumed by · Downstream inference and UI stacks
- DashScope → Image Output: influences · Improves prompt quality before generation
