How qwenlm/qwen-image works
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: demo.py Demo · README.md README · edit_demo.py Edit Demo · generate_w_prompt_enhance.py Gen + Prompt
Components 18
Docs
Repository docs and release pages
- README · Main overview, usage, deployment, and ecosystem guide
README.md - Qwen-Image · Text-to-image release notes and showcase
Qwen-Image.md - Qwen-Edit · Editing release notes and showcase
Qwen-Image-Edit.md - Edit 2509 · Later editing release notes and showcase
Qwen-Image-Edit-2509.md - Assets · Static supporting materials used by documentation
assets
Examples
Runnable demo and prompt tooling
- Demo · Interactive multi-GPU web demo and task runner
src/examples/demo.py - Edit Demo · Editing-focused example entry point
src/examples/edit_demo.py - Gen + Prompt · Generation script with prompt enhancement
src/examples/generate_w_prompt_enhance.py - Prompt Utils · Prompt rewrite and edit-prompt polishing helpers
src/examples/tools/prompt_utils.py - Prompt 2512 · Version-specific prompt rewriting helpers
src/examples/tools/prompt_utils_2512.py
External
Hosted models, services, and downstream runtimes
- DashScope · Upstream prompt enhancement service used for rewrite and polish
- Diffusers · External pipeline runtime that loads Qwen checkpoints
- Qwen T2I · Text-to-image model weights hosted externally
- Qwen Edit · Image-editing model weights hosted externally
- Edit Plus · Multi-image editing checkpoint used by newer releases
- HF / ModelScope · Model distribution and checkpoint hosting boundary
- Ecosystems · External consumers such as ComfyUI, SGLang-Diffusion, and vLLM-Omni
- Image Output · Saved or returned generated images
Connections 37
- 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