chore: add qwen-image tests for v1, clean the requirements (#712)

* add the v1 tests

* formalize the requirements

* update

* update

* well format the dependency

* update docs

* update

* update

* update the dependency

* fix the version in ci

* well organize the dependency

* update the pr list

* update tests

* add tests for qwen-image

* add qwen-image lightning

* add tests

* update fp4 lpips

* add tests for qwen-image-edit

* update

* updat

* add 8 steps lora back

* update nvfp4 results

* add qwen-image-edit-lightning

* style: make linter happy

* do not use batch when batchsize is 1

* update

* finished all the tests

* add cn test

* style: make linter happy

* update

* add qwen-image controlnet

* update

* add fp4 metrics

* fix the tests

.github/workflows/build-docs.yaml

@@ -34,18 +34,7 @@ jobs:
           which python
           conda install -c conda-forge gxx=11 gcc=11
           echo "Installing dependencies"
-          pip install torch==2.7 torchvision==0.22 torchaudio==2.7 --index-url https://download.pytorch.org/whl/cu128
-          pip install git+https://github.com/huggingface/diffusers
-          pip install ninja wheel transformers==4.51 accelerate==1.7 sentencepiece==0.2 protobuf==6.31 huggingface_hub==0.34
-          pip install sphinx sphinx-tabs myst-parser sphinx-copybutton breathe sphinxcontrib-mermaid nbsphinx jupyter ipykernel graphviz sphinxext-rediraffe
-          pip install furo sphinxawesome-theme sphinx-book-theme sphinx-rtd-theme
-      - name: Build
-        run: |
-          source $(conda info --base)/etc/profile.d/conda.sh
-          conda activate nunchaku-docs || { echo "Failed to activate conda env"; exit 1; }
-          which python
-          NUNCHAKU_INSTALL_MODE=ALL python setup.py develop
-          pip install -r tests/requirements.txt
+          pip install -e ".[dev,docs]"
       - name: Build docs
         run: |
           source $(conda info --base)/etc/profile.d/conda.sh

.github/workflows/pr-test.yaml

@@ -8,7 +8,8 @@ on:
       - "tests/**"
       - "examples/**"
       - "scripts/**"
-      - ".github/workflows/**"
+      - ".github/workflows/pr-test.yaml"
+      - "!nunchaku/__version__.py"
   workflow_dispatch:
     inputs:
       ref:
@@ -44,23 +45,15 @@ jobs:
         run: |
           which python
           echo "Setting up Python with Conda"
-          conda create -n test_env python=3.12 -y
-      - name: Install dependencies
+          conda create -n test_env python=3.13 -y
+      - name: Install dependencies and build
         run: |
           source $(conda info --base)/etc/profile.d/conda.sh
           conda activate test_env || { echo "Failed to activate conda env"; exit 1; }
           which python
           echo "Installing dependencies"
-          pip install torch==2.7 torchvision==0.22 torchaudio==2.7 --index-url https://download.pytorch.org/whl/cu128
-          pip install diffusers==0.35.1
-          pip install ninja wheel transformers==4.55 accelerate==1.10 sentencepiece==0.2 protobuf==6.31 huggingface_hub==0.34
-      - name: Build
-        run: |
-          source $(conda info --base)/etc/profile.d/conda.sh
-          conda activate test_env || { echo "Failed to activate conda env"; exit 1; }
-          which python
-          NUNCHAKU_INSTALL_MODE=ALL python setup.py develop
-          pip install -r tests/requirements.txt
+          pip install torch==2.8 torchvision==0.23 --index-url https://download.pytorch.org/whl/cu128
+          pip install -e ".[ci]"
       - name: Setup ComfyUI
         run: |
           source $(conda info --base)/etc/profile.d/conda.sh
@@ -99,6 +92,7 @@ jobs:
           conda activate test_env || { echo "Failed to activate conda env"; exit 1; }
           which python
           pytest -s -x tests/flux/test_flux_examples.py
+          pytest -s -x tests/v1/test_examples.py
           python .github/workflows/run_all_tests.py
       - name: clean up
         if: always()

.github/workflows/run_all_tests.py

@@ -11,7 +11,9 @@ def run_all_tests():
             rel_path = file_path.relative_to(test_dir)
         except ValueError:
             continue
-        if str(rel_path) == "flux/test_flux_examples.py":
+        if "test_flux_examples.py" in str(rel_path):
+            continue
+        if "test_examples.py" in str(rel_path):
             continue
         test_files.append(str(file_path))
     print("Running tests:")

.gitignore

@@ -216,3 +216,5 @@ nunchaku-models/
 dev/
 .tmp/
 metrics.json
+*use_count.txt
+*use_record.txt

.pre-commit-config.yaml

@@ -72,3 +72,7 @@ repos:
     hooks:
       - id: rstcheck
         additional_dependencies: ['rstcheck[sphinx,toml]']
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: "v2.6.0"
+    hooks:
+      - id: pyproject-fmt

docs/source/developer/build_docs.rst

+Building the Documentation
+==========================
+
+Follow this guide to build the Nunchaku documentation locally using Sphinx.
+
+Step 1: Set Up the Environment
+------------------------------
+
+First, ensure your environment is prepared. This process is similar to :ref:`Installation <build-from-source>`.
+Make sure you have installed all the necessary development and documentation dependencies with the ``dev,docs`` extras:
+
+.. code-block:: shell
+
+    pip install -e ".[dev,docs]"
+
+Step 2: Build the Documentation
+-------------------------------
+
+Navigate to the ``docs`` directory and build the HTML documentation:
+
+.. code-block:: shell
+
+    cd docs
+    make clean
+    make html
+
+This will generate the HTML files in the ``docs/build/html`` directory.
+
+Step 3: Preview the Documentation
+---------------------------------
+
+To view the generated documentation locally, start a simple HTTP server:
+
+.. code-block:: shell
+
+    cd build/html
+    python -m http.server 2333
+
+Then open your browser and go to ``http://localhost:2333`` to browse the documentation.
+Feel free to change the port to any other port you prefer.
+
+.. tip::
+
+   If you make changes to the documentation source files, simply rerun ``make html`` to update the output.

docs/source/developer/contribution_guide.rst

@@ -24,17 +24,22 @@ follow these steps for a smooth and efficient contribution process.
 
 2. Install Dependencies & Build
 
-   To install dependencies and build the project, follow the instructions in :doc:`Installation <../installation/installation>`.
+   To set up your development environment, follow the steps in :ref:`Installation <build-from-source>`.
+   Be sure to install all development dependencies by running:
+
+   .. code-block:: shell
+
+      pip install -e ".[dev]"
 
 🧹 Code Formatting with Pre-Commit
 ----------------------------------
 
-We use `pre-commit <https://pre-commit.com/>`_ hooks to ensure code style consistency.
-Please install and run it before submitting your changes:
+We use `pre-commit <https://pre-commit.com/>`__ hooks to maintain consistent code style across the project.
+Before submitting your changes, please ensure pre-commit is installed and run:
 
 .. code-block:: shell
 
-   pip install pre-commit
+   pip install pre-commit  # This should already be installed with the development dependencies
    pre-commit install
    pre-commit run --all-files
 

docs/source/index.rst

@@ -52,3 +52,4 @@ Check out `DeepCompressor <github_deepcompressor_>`_ for the quantization librar
     faq/faq.rst
     developer/contribution_guide.rst
     developer/docstring.rst
+    developer/build_docs.rst

docs/source/installation/installation.rst

@@ -89,6 +89,8 @@ If you're using a **Blackwell (RTX 50-series)** GPU:
 - Use **PyTorch ≥ 2.7** with **CUDA ≥ 12.8**.
 - Use **FP4 models** instead of **INT4 models** for best compatibility and performance.
 
+.. _build-from-source:
+
 Option 2: Build from Source
 ---------------------------
 
@@ -127,18 +129,8 @@ Step 1: Set Up Environment
     # Install PyTorch
     pip install torch torchvision torchaudio
 
-    # Install dependencies
-    pip install ninja wheel diffusers transformers accelerate sentencepiece protobuf huggingface_hub
-
-    # Optional: For gradio demos
-    pip install peft opencv-python gradio spaces
-
 For Blackwell users (50-series), install PyTorch ≥ 2.7 with CUDA ≥ 12.8:
 
-.. code-block:: shell
-
-    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
-
 Step 2: Build and Install Nunchaku
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -148,19 +140,33 @@ Step 2: Build and Install Nunchaku
 
     conda install -c conda-forge gxx=11 gcc=11
 
-For Windows users, download and install the latest `Visual Studio <visual_studio_>`_ and use its development environment. See :doc:`Window Setup Guide <setup_windows>` for more details.
+For Windows users, download and install the latest `Visual Studio <visual_studio_>`_ and use its development environment.
+See :doc:`Window Setup Guide <setup_windows>` for more details.
 
-**Clone and build:**
+**Clone the Repository:**
 
 .. code-block:: shell
 
-    git clone https://github.com/nunchaku-tech/nunchaku.git
+    git clone --recurse-submodules https://github.com/nunchaku-tech/nunchaku.git
     cd nunchaku
-    git submodule init
-    git submodule update
-    python setup.py develop
 
-**To build a wheel for distribution:**
+**Build and Install:**
+
+.. code-block:: shell
+
+    pip install -e ".[dev,docs]"
+
+This command installs Nunchaku in editable mode along with all development dependencies, making it ideal for contributing or running tests.
+
+.. tip::
+   If you only need to use Nunchaku (and not develop, test, or build the documentation),
+   you can skip the development dependencies by running either ``pip install -e "."`` or ``python setup.py develop`` after cloning the repository.
+
+.. tip::
+   For a faster development workflow and efficient incremental builds, use ``python setup.py develop`` for the future builds.
+   The first run will take longer as it compiles the entire project, but subsequent builds will be much faster.
+
+**(Optional) Build a wheel for distribution:**
 
 .. code-block:: shell
 

docs/source/installation/setup_windows.rst

@@ -142,10 +142,8 @@ Step 2: Clone the Repository
 
 .. code-block:: bat
 
-   git clone https://github.com/nunchaku-tech/nunchaku.git
+   git clone --recurse-submodules https://github.com/nunchaku-tech/nunchaku.git
    cd nunchaku
-   git submodule init
-   git submodule update
 
 Step 3: Set Up Visual Studio Environment
 

examples/v1/qwen-image-edit-lightning.py

@@ -51,15 +51,13 @@ else:
     pipeline._exclude_from_cpu_offload.append("transformer")
     pipeline.enable_sequential_cpu_offload()
 
-image = load_image(
-    "https://qwen-qwen-image-edit.hf.space/gradio_api/file=/tmp/gradio/d02be0b3422c33fc0ad3c64445959f17d3d61286c2d7dba985df3cd53d484b77/neon_sign.png"
-).convert("RGB")
+image = load_image("https://huggingface.co/datasets/nunchaku-tech/test-data/resolve/main/inputs/neon_sign.png")
+image = image.convert("RGB")
 prompt = "change the text to read '双截棍 Qwen Image Edit is here'"
 inputs = {
     "image": image,
     "prompt": prompt,
     "true_cfg_scale": 1,
-    "negative_prompt": " ",
     "num_inference_steps": num_inference_steps,
 }
 

examples/v1/qwen-image-edit.py

@@ -26,9 +26,8 @@ else:
     pipeline._exclude_from_cpu_offload.append("transformer")
     pipeline.enable_sequential_cpu_offload()
 
-image = load_image(
-    "https://qwen-qwen-image-edit.hf.space/gradio_api/file=/tmp/gradio/d02be0b3422c33fc0ad3c64445959f17d3d61286c2d7dba985df3cd53d484b77/neon_sign.png"
-).convert("RGB")
+image = load_image("https://huggingface.co/datasets/nunchaku-tech/test-data/resolve/main/inputs/neon_sign.png")
+image = image.convert("RGB")
 prompt = "change the text to read '双截棍 Qwen Image Edit is here'"
 inputs = {
     "image": image,

examples/v1/qwen-image-lightning.py

@@ -49,10 +49,8 @@ else:
     pipe.enable_sequential_cpu_offload()
 
 prompt = """Bookstore window display. A sign displays “New Arrivals This Week”. Below, a shelf tag with the text “Best-Selling Novels Here”. To the side, a colorful poster advertises “Author Meet And Greet on Saturday” with a central portrait of the author. There are four books on the bookshelf, namely “The light between worlds” “When stars are scattered” “The slient patient” “The night circus”"""
-negative_prompt = " "
 image = pipe(
     prompt=prompt,
-    negative_prompt=negative_prompt,
     width=1024,
     height=1024,
     num_inference_steps=num_inference_steps,

examples/v1/qwen-image.py

@@ -4,7 +4,6 @@ from diffusers import QwenImagePipeline
 from nunchaku.models.transformers.transformer_qwenimage import NunchakuQwenImageTransformer2DModel
 from nunchaku.utils import get_gpu_memory, get_precision
 
-model_name = "Qwen/Qwen-Image"
 rank = 32  # you can also use rank=128 model to improve the quality
 
 # Load the model

nunchaku/pipeline/__init__.py

-from .pipeline_flux_pulid import PuLIDFluxPipeline
+try:
+    from .pipeline_flux_pulid import PuLIDFluxPipeline
+except ImportError:
+    PuLIDFluxPipeline = None
 
 __all__ = ["PuLIDFluxPipeline"]

pyproject.toml

-[tool.isort]
-profile = "black"
-known_first_party = ["nunchaku"]
-line_length = 120
-
-[tool.black]
-line-length = 120
-target-version = ['py311']
+[build-system]
+build-backend = "setuptools.build_meta"
 
-[tool.ruff]
-line-length = 120
+requires = [
+  "ninja",
+  "setuptools",
+  "torch>=2.5",
+  "wheel",
+]
 
 [project]
-dynamic = ["version"]
 name = "nunchaku"
+requires-python = ">=3.10"
+
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dynamic = [ "version" ]
 dependencies = [
+  "accelerate>=1.9",
   "diffusers>=0.35.1",
-    "transformers>=4.53.3",
-    "accelerate>=1.9.0",
-    "sentencepiece",
-    "protobuf",
-    "huggingface_hub>=0.34",
-    "peft>=0.17",
   "einops",
+  "huggingface-hub>=0.34",
+  "peft>=0.17",
+  "protobuf",
+  "sentencepiece",
+  "torchvision>=0.20",
+  "transformers>=4.53.3",
+]
+optional-dependencies.ci = [
+  "controlnet-aux==0.0.10",
+  "datasets==3.6",
+  "diffusers @ git+https://github.com/huggingface/diffusers@5796735",
+  "facexlib==0.3",
+  "image-gen-aux @ git+https://github.com/asomoza/image_gen_aux.git",
+  "insightface==0.7.3",
+  "onnxruntime==1.22.1",
+  "opencv-python==4.11.0.86",
+  "pytest==8.4.2",
+  "pytest-rerunfailures==16.0.1",
+  "timm==1.0.19",
+  "torchmetrics==1.8",
 ]
-requires-python = ">=3.10"
 
-[build-system]
-requires = [
-    "setuptools",
-    "torch>=2.5",
-    "wheel",
-    "ninja",
+optional-dependencies.demo = [
+  "controlnet-aux",
+  "gradio==5.39",
+  "image-gen-aux @ git+https://github.com/asomoza/image_gen_aux.git",
+  "spaces",
+]
+optional-dependencies.dev = [
+  "controlnet-aux",
+  "datasets<4",
+  "facexlib",
+  "image-gen-aux @ git+https://github.com/asomoza/image_gen_aux.git",
+  "insightface",
+  "onnxruntime",
+  "opencv-python",
+  "pre-commit",
+  "pytest",
+  "pytest-rerunfailures",
+  "timm",
+  "torchmetrics",
+]
+optional-dependencies.docs = [
+  "breathe",
+  "furo",
+  "graphviz",
+  "ipykernel",
+  "jupyter",
+  "myst-parser",
+  "nbsphinx",
+  "sphinx",
+  "sphinx-book-theme",
+  "sphinx-copybutton",
+  "sphinx-rtd-theme",
+  "sphinx-tabs",
+  "sphinxawesome-theme",
+  "sphinxcontrib-mermaid",
+  "sphinxext-rediraffe",
+]
+optional-dependencies.full = [
+  "controlnet-aux",
+  "facexlib",
+  "image-gen-aux @ git+https://github.com/asomoza/image_gen_aux.git",
+  "insightface",
+  "onnxruntime",
+  "opencv-python",
+  "timm",
 ]
-build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
-include = ["nunchaku"]
+include = [ "nunchaku" ]
+
+[tool.black]
+line-length = 120
+target-version = [ 'py311' ]
+
+[tool.ruff]
+line-length = 120
+
+[tool.isort]
+profile = "black"
+known_first_party = [ "nunchaku" ]
+line_length = 120
 
 [tool.doc8]
 max-line-length = 120
-ignore-path = ["docs/_build"]
-ignore = ["D000", "D001"]
+ignore-path = [ "docs/_build" ]
+ignore = [ "D000", "D001" ]
 
 [tool.rstcheck]
-ignore_directives = ["tabs"]
-ignore_messages = ["ERROR/3", "INFO/1"]
+ignore_directives = [ "tabs" ]
+ignore_messages = [ "ERROR/3", "INFO/1" ]

requirements.txt

-# pulid related
-insightface
-opencv-python
-facexlib
-onnxruntime
-# ip-adapter
-timm
-diffusers==0.35

tests/requirements.txt

-# additional requirements for testing
-pytest
-datasets<4
-torchmetrics
-mediapipe
-controlnet_aux
-peft
-git+https://github.com/asomoza/image_gen_aux.git
-insightface
-opencv-python
-facexlib
-onnxruntime
-pytest-rerunfailures

tests/utils.py

@@ -20,14 +20,16 @@ def hash_str_to_int(s: str) -> int:
     return hash_int
 
 
-def already_generate(save_dir: str | PathLike[str], num_images) -> bool:
+def already_generate(save_dir: str | PathLike[str], num_images: int | None = None) -> bool:
     if isinstance(save_dir, str):
         save_dir = Path(save_dir)
     assert isinstance(save_dir, Path)
     if save_dir.exists():
+        if num_images is None:
+            return True
         images = list(save_dir.iterdir())
         images = [_ for _ in images if _.name.endswith(".png")]
-        if len(images) == num_images:
+        if len(images) >= num_images:
             return True
     return False