Qwen-Image-2.1-QIPACK

Qwen-Image-2.1 QIPACK for Apple Silicon and NVIDIA GPUs

Built with Qwen. These are ready-to-map QIPACK transformer files for qwen-image-cplus, a native C+ Qwen-Image-2.1 inference runtime: Metal on Apple Silicon, CUDA on NVIDIA GPUs under Linux.

This repository contains converted transformer weights (FP16 for Apple Silicon, 4-bit for NVIDIA), a Viggle v0.2.1 LoRA, and the unmodified processor, text encoder, and VAE files needed by qwen-image-cplus. The base weights and shared support files come from the pinned upstream Qwen snapshot; the four-step full fine-tune and six-step LoRA come from Viggle. The runtime provides the scheduler.

Files

All packs share processor/vocab.json, processor/merges.txt, four text_encoder/model-*.safetensors shards, and vae/diffusion_pytorch_model.safetensors in this repository's root directory. Their sizes and checksums are recorded in manifest.json. The files remain in those paths when downloaded, so selecting a root-level QIPACK in the GUI also locates its support files. The six-step pack additionally requires its LoRA file beside it. One 14.23 GB pack plus the 18.89 GB shared files requires about 33.12 GB of local storage, or 34.48 GB with the 1.36 GB LoRA. “7B” describes the transformer's parameter count, not the pipeline's size in bytes.

The four-step file is Viggle v0.1's full transformer, not a LoRA. The six-step file contains the original Qwen base transformer with metadata selecting the separate Viggle v0.2.1 LoRA and its six-step schedule.

The three FP16 QIPACK files use QIPACK1 version 1 with policy transformer:all-matrix-f16-v4. All 224 transformer-block matrices are stored as FP16; vectors and the nine global tensors remain BF16. Each pack contains 297 tensors and 7,115,124,736 parameters. The format has fixed little-endian metadata plus per-tensor and payload checksums. The base and four-step packs passed exact round-trip verification against their source tensors.

4-bit packs for NVIDIA GPUs

The two -v6 packs are the four-step Viggle transformer quantized for the CUDA engine. Each keeps the QIPACK1 container and replaces only the 224 transformer-block matrices with 4-bit codes and one FP16 scale per group of 64 inputs; vectors and the nine global tensors are copied unchanged. A pack is about 4 GB, so with the 18.89 GB of shared files one NVIDIA setup needs about 23 GB of storage.

• w4a4-h256-g64-clip (policy transformer:w4a4-h256-g64-v6): signed 4-bit weights rotated by a 256-point Hadamard transform, with activations quantized to 4 bits at run time, and a per-group clipping range chosen to minimize reconstruction error. The faster of the two.
• w4a16-g64 (policy transformer:w4a16-g64-v6): 4-bit weights with an FP16 minimum per group, FP16 activations. Stays closer to the FP16 result.

Measured against the FP16 pack on the same inputs (512x512, 4 steps), both render the reference poster's text exactly. W4A16 keeps the composition closer (21.2 dB PSNR against 19.0 dB for W4A4), and W4A4 is 1.4–1.6x faster end to end. These packs are not used by the Apple Silicon runtime.

Requirements

Apple Silicon (FP16 packs):

• macOS 14 or newer on Apple Silicon
• qwen-image-cplus; the six-step LoRA requires a build with Viggle v0.2.1 support (current main)

NVIDIA (4-bit packs):

• x86_64 Linux with an NVIDIA GPU, Turing (RTX 20xx) or newer, 6 GB of VRAM or more, and the proprietary driver
• qwen-image-cplus with the CUDA engine (the Ubuntu snap, or a build from current main)

The runtime has been tested on an M1 Max with 32 GB unified memory. Lower-memory machines have not yet been validated. Generation at 1024x1024 and the model's native 2048x2048 resolution is supported; 2048x2048 is a high-memory capacity mode on a 32 GB M1 Max.

Download

Install the Hugging Face CLI and read the model license. Download the shared files and the pack you want into one directory. For an NVIDIA GPU, for example:

hf download netdur/Qwen-Image-2.1-QIPACK --local-dir models \
  --include "processor/*" "text_encoder/*" "vae/*" \
  "qwen-image-2.1-viggle-v0.1-4step-w4a4-h256-g64-clip-v6.qipack"

For Apple Silicon, name an FP16 pack instead (and, for the six-step pack, its LoRA file). Leaving out --include downloads everything, about 71 GB.

Use

The command is the same on both platforms; the arguments after the prompt are width, height, and seed. Base model, using the pack's 40-step TaylorSeer defaults:

qwen-image-cplus generate \
  models/qwen-image-2.1-fp16-v4.qipack \
  models \
  output.png \
  "A vintage travel poster for CASABLANCA reading 'MEET ME AT SUNSET'" \
  1024 1024 1301

Four-step distilled model:

qwen-image-cplus generate \
  models/qwen-image-2.1-viggle-v0.1-4step-fp16-v4.qipack \
  models \
  output.png \
  "A vintage travel poster for CASABLANCA reading 'MEET ME AT SUNSET'" \
  1024 1024 1301

Six-step Viggle v0.2.1 LoRA (keep its sidecar safetensors beside the pack):

qwen-image-cplus generate \
  models/qwen-image-2.1-viggle-v0.2.1-lora-fp16-v4.qipack \
  models \
  output.png \
  "A vintage travel poster for CASABLANCA reading 'MEET ME AT SUNSET'" \
  1024 1024 1301

Four-step model on an NVIDIA GPU (use the w4a16 pack for the higher-fidelity mode):

qwen-image-cplus generate \
  models/qwen-image-2.1-viggle-v0.1-4step-w4a4-h256-g64-clip-v6.qipack \
  models \
  output.png \
  "A vintage travel poster for CASABLANCA reading 'MEET ME AT SUNSET'" \
  512 512 1301

The pack metadata selects the correct step count, terminal-shift behavior, and cache policy when those optional CLI arguments are omitted.

Reference performance

On the development M1 Max, the adopted Viggle four-step path generated a 1024x1024 PNG end to end in roughly 38–39 seconds.

On an RTX 2060 (6 GB, PCIe gen3 x8), the four-step packs took, end to end with a warm file cache:

These are single-machine, single-prompt references rather than general performance guarantees. See the versioned benchmark records in the runtime repository for exact conditions and accuracy gates.

License and modifications

The model materials are distributed under the included Qwen Research License Agreement, which permits non-commercial research and evaluation only unless a separate commercial license is obtained from Qwen. Read the agreement before downloading or using the files.

The QIPACK files are modified redistributions: their tensor storage layout and selected matrix dtypes were converted for the runtime, and the -v6 packs quantize the transformer-block matrices to 4 bits. The model architecture and learned values were not retrained by this project. The distilled source model and LoRA were created by Viggle and are attributed in NOTICE.

The runtime source code has its own MIT license; that license does not replace or relax the model license.