From f77e44d5bf350177ea1391f301ae0c3efb7d18f4 Mon Sep 17 00:00:00 2001
From: Samit <285365963@qq.com>
Date: Sun, 30 Nov 2025 17:46:39 +0800
Subject: [PATCH] [Docs] Add qwen image missing doc in user guide (#111)

Signed-off-by: samithuang <285365963@qq.com>
---
 docs/.nav.yml                                 |  2 +-
 .../examples/offline_inference/qwen_image.md  | 66 +++++++++++++++++++
 mkdocs.yml                                    |  1 +
 .../diffusion/models/qwen_image/__init__.py   |  3 +
 vllm_omni/diffusion/worker/__init__.py        |  7 ++
 5 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 docs/user_guide/examples/offline_inference/qwen_image.md
 create mode 100644 vllm_omni/diffusion/models/qwen_image/__init__.py
 create mode 100644 vllm_omni/diffusion/worker/__init__.py

diff --git a/docs/.nav.yml b/docs/.nav.yml
index a9cd65d33..fb9c7fb44 100644
--- a/docs/.nav.yml
+++ b/docs/.nav.yml
@@ -8,9 +8,9 @@ nav:
       - examples/README.md
       - Offline Inference:
         - Qwen2.5-Omni: user_guide/examples/offline_inference/qwen2_5_omni.md
+        - Qwen2.5-Image: user_guide/examples/offline_inference/qwen_image.md
       - Online Serving:
         - Qwen2.5-Omni: user_guide/examples/online_serving/qwen2_5_omni.md
-        - Qwen2.5-Image: user_guide/examples/offline_inference/qwen_image.md
     - General:
       - usage/*
     - Configuration:
diff --git a/docs/user_guide/examples/offline_inference/qwen_image.md b/docs/user_guide/examples/offline_inference/qwen_image.md
new file mode 100644
index 000000000..904a2c091
--- /dev/null
+++ b/docs/user_guide/examples/offline_inference/qwen_image.md
@@ -0,0 +1,66 @@
+# Offline Inference Example of vLLM-Omni for Qwen-Image
+
+Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inference/qwen_image>.
+
+
+## 🛠️ Installation
+
+Please refer to [installation](../../../getting_started/installation/README.md).
+
+## Run Offline inference with Qwen-Image
+
+First, navigate to the example folder
+```bash
+cd examples/offline_inference/qwen_image
+```
+
+This folder provides two simple entrypoints for experimenting with `Qwen/Qwen-Image` using vLLM-Omni:
+
+- `text_to_image.py`: command-line script for single image generation.
+- `gradio_demo.py`: lightweight Gradio UI for interactive prompt/seed/CFG exploration.
+
+### Command-line Usage
+
+```bash
+python text_to_image.py \
+  --prompt "a cup of coffee on the table" \
+  --seed 42 \
+  --cfg_scale 4.0 \
+  --num_images_per_prompt 1 \
+  --num_inference_steps 50 \
+  --height 1024 \
+  --width 1024 \
+  --output outputs/coffee.png
+```
+
+Key arguments:
+
+- `--prompt`: text description (string).
+- `--seed`: integer seed for deterministic sampling.
+- `--cfg_scale`: true CFG scale (model-specific guidance strength).
+- `--num_images_per_prompt`: number of images to generate per prompt (saves as `output`, `output_1`, ...).
+- `--num_inference_steps`: diffusion sampling steps (more steps = higher quality, slower).
+- `--height/--width`: output resolution (defaults 1024x1024).
+- `--output`: path to save the generated PNG.
+
+??? abstract "text_to_image.py"
+    ``````py
+    --8<-- "examples/offline_inference/qwen_image/text_to_image.py"
+    ``````
+
+> ℹ️ Qwen-Image currently publishes best-effort presets at `1328x1328`, `1664x928`, `928x1664`, `1472x1140`, `1140x1472`, `1584x1056`, and `1056x1584`. Adjust `--height/--width` accordingly for the most reliable outcomes.
+
+### Web UI Demo
+
+Launch the gradio demo:
+
+```bash
+python gradio_demo.py --port 7862
+```
+
+Then open `http://localhost:7862/` on your local browser to interact with the web UI.
+
+??? abstract "gradio_demo.py"
+    ``````py
+    --8<-- "examples/offline_inference/qwen_image/gradio_demo.py"
+    ``````
diff --git a/mkdocs.yml b/mkdocs.yml
index 73783ab8c..dfa29f59b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -87,6 +87,7 @@ plugins:
       show_full_namespace: false  # Show only module name, not full path
       exclude:
         - "re:vllm_omni\\._.*"  # Internal modules
+        - "vllm_omni.diffusion.models.qwen_image"  # avoid importing vllm in mkdocs building
   - mkdocstrings:
       handlers:
         python:
diff --git a/vllm_omni/diffusion/models/qwen_image/__init__.py b/vllm_omni/diffusion/models/qwen_image/__init__.py
new file mode 100644
index 000000000..69d6821f4
--- /dev/null
+++ b/vllm_omni/diffusion/models/qwen_image/__init__.py
@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Qwen Image model components."""
diff --git a/vllm_omni/diffusion/worker/__init__.py b/vllm_omni/diffusion/worker/__init__.py
new file mode 100644
index 000000000..068a25f8f
--- /dev/null
+++ b/vllm_omni/diffusion/worker/__init__.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Diffusion worker components."""
+
+from vllm_omni.diffusion.worker.gpu_worker import GPUWorker, WorkerProc
+
+__all__ = ["GPUWorker", "WorkerProc"]