Upload folder using huggingface_hub

LICENSE

@@ -0,0 +1,55 @@
+Qwen RESEARCH LICENSE AGREEMENT
+
+Qwen RESEARCH LICENSE AGREEMENT Release Date: September 20, 2026
+
+By clicking to agree or by using or distributing any portion or element of the Qwen Materials, you will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+
+1. Definitions
+    a. This Qwen RESEARCH LICENSE AGREEMENT (this "Agreement") shall mean the terms and conditions for use, reproduction, distribution and modification of the Materials as defined by this Agreement.
+    b. "We" (or "Us") shall mean Hangzhou Tongyi Laboratory Technology Co., Ltd.
+    c. "You" (or "Your") shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Materials for any purpose and in any field of use.
+    d. "Third Parties" shall mean individuals or legal entities that are not under common control with us or you.
+    e. "Qwen" shall mean the large language models, diffusion models, and software and algorithms, consisting of trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing distributed by us.
+    f. "Materials" shall mean, collectively, our proprietary Qwen and Documentation (and any portion thereof) made available under this Agreement.
+    g. "Source" form shall mean the preferred form for making modifications, including but not limited to model source code, documentation source, and configuration files.
+    h. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+    i. "Non-Commercial" shall mean for research or evaluation purposes only.
+
+2. Grant of Rights
+    a. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under our intellectual property or other rights owned by us embodied in the Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the Materials FOR NON-COMMERCIAL PURPOSES ONLY. 
+    b. You shall not use the Materials for any commercial purpose without obtaining a separate commercial license from us. If you wish to use the Materials commercially, you shall request a license from us at model-business@notice.qwencloud.com.
+
+3. Redistribution
+Subject to Section 2 (Grant of Rights), you may distribute copies or make the Materials, or derivative works thereof, available as part of a product or service that contains any of them, with or without modifications, and in Source or Object form, provided that you meet the following conditions:
+    a. You shall give any other recipients of the Materials or derivative works a copy of this Agreement;
+    b. You shall cause any modified files to carry prominent notices stating that you changed the files;
+    c. You shall retain in all copies of the Materials that you distribute the following attribution notices within a "Notice" text file distributed as a part of such copies: "Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou Tongyi Laboratory Technology Co., Ltd. All Rights Reserved."; and
+    d. You may add your own copyright statement to your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of your modifications, or for any such derivative works as a whole, provided your use, reproduction, and distribution of the work otherwise complies with the terms and conditions of this Agreement.
+
+4. Rules of use
+    a. The Materials may be subject to export controls or restrictions in China, the United States or other countries or regions. You shall comply with applicable laws and regulations in your use of the Materials.
+    b. If you use the Materials or any outputs or results therefrom to create, train, fine-tune, or improve an AI model that is distributed or made available, you shall prominently display “Built with Qwen” or “Improved using Qwen” in the related product documentation.
+    c. You shall not use "Qwen" as the primary name or identifier of any derivative works or products; reasonable descriptive use (e.g., "fine-tuned from Qwen Image") is permitted.
+
+5. Intellectual Property
+    a. We retain ownership of all intellectual property rights in and to the Materials and derivatives made by or for us. Conditioned upon compliance with the terms and conditions of this Agreement, with respect to any derivative works and modifications of the Materials that are made by you, you are and will be the owner of such derivative works and modifications.
+    b. No trademark license is granted to use the trade names, trademarks, service marks, or product names of us, except as required to fulfill notice requirements under this Agreement or as required for reasonable and customary use in describing and redistributing the Materials.
+    c. If you commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against us or any entity alleging that the Materials or any output therefrom, or any part of the foregoing, infringe any intellectual property or other right owned or licensable by you, then all licenses granted to you under this Agreement shall terminate as of the date such lawsuit or other proceeding is commenced or brought.
+
+6. Disclaimer of Warranty and Limitation of Liability
+    a. We are not obligated to support, update, provide training for, or develop any further version of the Qwen Materials or to grant any license thereto.
+    b. THE MATERIALS ARE PROVIDED "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY OF ANY KIND INCLUDING WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT, OR FITNESS FOR A PARTICULAR PURPOSE. WE MAKE NO WARRANTY AND ASSUME NO RESPONSIBILITY FOR THE SAFETY OR STABILITY OF THE MATERIALS AND ANY OUTPUT THEREFROM.
+    c. IN NO EVENT SHALL WE BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE MATERIALS OR ANY OUTPUT OF IT, NO MATTER HOW IT’S CAUSED.
+    d. You will defend, indemnify and hold harmless us from and against any claim by any third party arising out of or related to your use or distribution of the Materials.
+
+7. Survival and Termination.
+    a. The term of this Agreement shall commence upon your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+    b. We may terminate this Agreement if you breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, you must delete and cease use of the Materials. Sections 6 and 8 shall survive the termination of this Agreement.
+
+8. Governing Law and Jurisdiction.
+    a. This Agreement and any dispute arising out of or relating to it will be governed by the laws of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+    b. The People's Courts in Hangzhou City shall have exclusive jurisdiction over any dispute arising out of this Agreement.
+
+9. Other Terms and Conditions.
+    a. Any arrangements, understandings, or agreements regarding the Material not stated herein are separate from and independent of the terms and conditions of this Agreement. You shall request a separate license from us, if you use the Materials in ways not expressly agreed to in this Agreement. 
+    b. We shall not be bound by any additional or different terms or conditions communicated by you unless expressly agreed.

README.md

@@ -0,0 +1,149 @@
+---
+license: other
+license_name: qwen-research
+license_link: LICENSE
+base_model:
+- Qwen/Qwen-Image-2.1
+tags:
+- quantized
+- nvfp4
+- comfyui
+- qwen-image
+- text-to-image
+---
+
+# Qwen-Image-2.1 DiT — NVFP4 (ComfyUI)
+
+> ⚠️ **ComfyUI format only.** These files use ComfyUI's native quantized-checkpoint
+> layout (`comfy_quant` tensors + `_quantization_metadata`). They will **not** load
+> in `diffusers`, and they need a ComfyUI build with `QwenImage21` support
+> (merged after 2026-09-14). If you want the model for `diffusers`, use the
+> [official bf16 release](https://huggingface.co/Qwen/Qwen-Image-2.1).
+
+> **Not affiliated with, or endorsed by, Alibaba / Qwen.** Community derivative of
+> [`Qwen/Qwen-Image-2.1`](https://huggingface.co/Qwen/Qwen-Image-2.1), redistributed
+> under the **Qwen Research License** (copy included as `LICENSE`, per §3.a).
+> **Non-commercial use only** (§1.i / §2.a); commercial use needs a separate licence
+> from Qwen (`model-business@notice.qwencloud.com`, §2.b).
+
+NVFP4 quantizations of the **diffusion transformer**. Comfy-Org ships `bf16` and
+`int8_convrot`; **there is no official NVFP4 build**, so these are new.
+
+---
+
+## Pick a file
+
+| File | Size | Start here if… |
+|---|---:|---|
+| **`qwen_image_2.1_nvfp4.safetensors`** | **3.91 GB** | **you just want the smallest thing that works — this is the default** |
+| `qwen_image_2.1_nvfp4_T2.safetensors` | 4.29 GB | you see artefacts on hard material and want a little more headroom |
+| `qwen_image_2.1_nvfp4_T3.safetensors` | 4.67 GB | you want the most conservative option in the set |
+
+Source is 13.25 GB bf16, so these are **29.5 % / 32.4 % / 35.2 %** of the original.
+
+### What actually differs between them
+
+The model has **32 transformer blocks**, each with 6 quantizable layers
+(`attn.to_q/k/v/out.0`, `img_mlp.gate_up`, `img_mlp.out`) = 192 layers total.
+The only axis that changes between tiers is **how many blocks at the head and tail
+are kept at 8-bit instead of 4-bit**:
+
+| | 4-bit NVFP4 (group 16) | 8-bit MXFP8 (group 32) | bf16 |
+|---|---|---|---|
+| **T1** (3.91 GB) | all 192 layers | — | 73 tensors |
+| **T2** (4.29 GB) | 168 layers | 24 layers — blocks **0, 1, 30, 31** | 73 tensors |
+| **T3** (4.67 GB) | 144 layers | 48 layers — blocks **0–3, 28–31** | 73 tensors |
+
+The bf16 protection set is **identical in all three** — the tiers differ only in
+that 4-bit ↔ 8-bit trade at the ends of the stack.
+
+### Does the extra size buy anything?
+
+On a like-for-like test — same seed, same prompt, same text encoder — the three
+tiers produced near-identical images: **mean per-pixel difference of 3–4 out of
+255**. The extra 0.4–0.8 GB did not show a visible benefit there.
+
+That was one prompt and one seed, so treat it as a starting point rather than a
+verdict. Faces, small text and dense texture are the places where a difference
+would show up first, so if you work on those, T2/T3 are worth a try.
+
+---
+
+## What is protected, and why
+
+| Layers | Count | Precision |
+|---|---:|---|
+| `attn.to_q/k/v/out`, `img_mlp.gate_up/out` | 192 | NVFP4, or MXFP8 in T2/T3 |
+| `img_in`, `txt_in.in_layer/out_layer` | 3 | **bf16** |
+| `time_text_embed.timestep_embedder.linear_1/2` | 2 | **bf16** |
+| `modulation.1` | 1 | **bf16** |
+| `norm_out.linear`, `proj_out` | 2 | **bf16** |
+| norms / biases (non-2-D) | 65 | bf16 |
+
+98.1 % of parameters are quantized; the protected 1.9 % costs only ~240 MB.
+
+**Why the timestep path stays bf16.** A DiT's `time_text_embed` and modulation decide
+*how far each denoising step moves*. Measurements on a distilled model in this family
+showed that when timestep conditioning is rewritten, the model stops working outside
+the exact schedule it was trained for. Keeping that path in bf16 costs almost nothing
+and removes a whole class of risk.
+
+Every 2-D weight in this model has `in_features` divisible by 16, so **no padding is
+needed anywhere** — the quantization is clean.
+
+## Audit
+
+| Check | Result |
+|---|---|
+| Metadata | `format_version 1.0`, 192 layers declared |
+| Tensor bookkeeping | 0 missing, 0 extra; `comfy_quant` matches metadata for every layer |
+| NVFP4 round-trip error | median **9.44 %**, max 9.49 % (24-layer sample) |
+| MXFP8 round-trip error | median **2.65 %** — 3.6× tighter than NVFP4, as the bit budget predicts |
+| Protected layers | 40/40 sampled are **byte-identical** to the bf16 source |
+| Loads in ComfyUI | ✅ all three, detected as `QwenImage21` |
+| End-to-end | ✅ 1024×1024, 25 steps, **~20–22 s** on a GB10 |
+
+The MXFP8 number matters: had the 8-bit path been written wrong, it would have landed
+at or above the 4-bit error. It didn't.
+
+## Usage
+
+Place in `ComfyUI/models/diffusion_models/`, then use the official
+[Qwen-Image-2.1 text-to-image workflow](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_qwen_image_2_1_t2i.json):
+
+```
+UNETLoader             → (this file)
+CLIPLoader             → qwen3vl_8b_*, type: qwen_image
+TextEncodeQwenImage21
+VAELoader              → qwen_image_2.1_vae_bf16.safetensors
+KSampler               → 25 steps, cfg 1.0, euler, simple
+```
+
+Older ComfyUI builds report `UNSUPPORTED DIFFUSION MODEL` for Qwen-Image-2.1 in
+general — **including the official bf16 files** — so if you see that, update ComfyUI
+rather than suspecting these weights.
+
+## Pitfall worth knowing (T2/T3)
+
+`TensorCoreMXFP8Layout.quantize()` returns its scale as `float8_e8m0`, which
+ComfyUI's safetensors loader cannot parse — `KeyError: 'F8_E8M0'`, and the file simply
+refuses to load. The official checkpoints store that bit pattern as `uint8` and
+reinterpret it at load time; these files do the same.
+
+The all-NVFP4 tier never touches that code path, so **a bug in the MXFP8 route stays
+invisible until you test T2/T3 specifically** — verifying T1 and assuming the rest
+follow is exactly how it gets missed.
+
+## Text encoder
+
+The other half of the pipeline, with refusal behaviour ablated
+(5/100 refusals @ KL 0.0220):
+
+| Repo | Format | Runtime |
+|---|---|---|
+| [`…-Text-Encoder-Heretic`](https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic) | bf16, 16.33 GB | `transformers` / any |
+| [`…-Heretic-NVFP4`](https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-NVFP4) | NVFP4, 5.87 GB | **ComfyUI** |
+| [`…-Heretic-W4A8`](https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-W4A8) | W4A8 INT8, 5.88 GB | **ComfyUI** |
+| [`…-Heretic-GGUF`](https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF) | GGUF Q4_K_M + mmproj, 5.76 GB | **llama.cpp / Mac** |
+
+This DiT + the NVFP4 text encoder is a complete **~9.8 GB** pipeline.

qwen_image_2.1_nvfp4.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c260c7286505f86ded8500664a2fde8522943c6f0bde78ab33ceba85ba50a68
+size 4197590904

qwen_image_2.1_nvfp4_T2.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0534357e7a64add83538f9a5434e851a5f09d82414dcb6ffca84de0a978a23a
+size 4606533160

qwen_image_2.1_nvfp4_T3.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cbe2e6e2ae285bfb7e69270b09d0121425afddc191a4b669bffed68a509b0380
+size 5015475376