AlperKTS commited on
Commit
d50078f
·
verified ·
1 Parent(s): 3a6277d

Sync docs and code: gallery, troubleshooting, cleanup pass

Browse files
Files changed (50) hide show
  1. .gitattributes +32 -0
  2. BENCHMARKS.md +132 -35
  3. GALLERY.md +250 -0
  4. README.md +245 -564
  5. TROUBLESHOOTING.md +97 -0
  6. diagnose.py +6 -2
  7. examples/fidelity_sheets/sheet_base_01_dense_text.jpg +3 -0
  8. examples/fidelity_sheets/sheet_base_02_curved_text.jpg +3 -0
  9. examples/fidelity_sheets/sheet_base_03_hands_detail.jpg +3 -0
  10. examples/fidelity_sheets/sheet_base_04_crowd_faces.jpg +3 -0
  11. examples/fidelity_sheets/sheet_base_05_symmetry_pattern.jpg +3 -0
  12. examples/fidelity_sheets/sheet_base_06_multi_subject.jpg +3 -0
  13. examples/fidelity_sheets/sheet_base_07_reflections_glass.jpg +3 -0
  14. examples/fidelity_sheets/sheet_base_08_logo_typography.jpg +3 -0
  15. examples/fidelity_sheets/sheet_base_09_counting_objects.jpg +3 -0
  16. examples/fidelity_sheets/sheet_base_10_complex_scene.jpg +3 -0
  17. examples/fidelity_sheets/sheet_base_11_portrait_woman.jpg +3 -0
  18. examples/fidelity_sheets/sheet_base_12_person_holding_sign.jpg +3 -0
  19. examples/fidelity_sheets/sheet_base_13_two_people_interaction.jpg +3 -0
  20. examples/fidelity_sheets/sheet_base_14_hands_and_face.jpg +3 -0
  21. examples/fidelity_sheets/sheet_base_15_full_body_fashion.jpg +3 -0
  22. examples/fidelity_sheets/sheet_base_16_group_selfie.jpg +3 -0
  23. examples/fidelity_sheets/sheet_lora2_01_dense_text.jpg +3 -0
  24. examples/fidelity_sheets/sheet_lora2_02_curved_text.jpg +3 -0
  25. examples/fidelity_sheets/sheet_lora2_03_hands_detail.jpg +3 -0
  26. examples/fidelity_sheets/sheet_lora2_04_crowd_faces.jpg +3 -0
  27. examples/fidelity_sheets/sheet_lora2_05_symmetry_pattern.jpg +3 -0
  28. examples/fidelity_sheets/sheet_lora2_06_multi_subject.jpg +3 -0
  29. examples/fidelity_sheets/sheet_lora2_07_reflections_glass.jpg +3 -0
  30. examples/fidelity_sheets/sheet_lora2_08_logo_typography.jpg +3 -0
  31. examples/fidelity_sheets/sheet_lora2_09_counting_objects.jpg +3 -0
  32. examples/fidelity_sheets/sheet_lora2_10_complex_scene.jpg +3 -0
  33. examples/fidelity_sheets/sheet_lora2_11_portrait_woman.jpg +3 -0
  34. examples/fidelity_sheets/sheet_lora2_12_person_holding_sign.jpg +3 -0
  35. examples/fidelity_sheets/sheet_lora2_13_two_people_interaction.jpg +3 -0
  36. examples/fidelity_sheets/sheet_lora2_14_hands_and_face.jpg +3 -0
  37. examples/fidelity_sheets/sheet_lora2_15_full_body_fashion.jpg +3 -0
  38. examples/fidelity_sheets/sheet_lora2_16_group_selfie.jpg +3 -0
  39. quantize_krea2.py +79 -36
  40. svdquant_capture.py +23 -6
  41. svdquant_diag.py +83 -17
  42. svdquant_lora.py +4 -2
  43. svdquant_quantize.py +41 -9
  44. svdquant_w4a4.py +303 -322
  45. tools/build_workflows.py +92 -32
  46. tools/contact_sheet.py +20 -6
  47. tools/fidelity_bench.py +28 -20
  48. tools/pixel_metrics.py +11 -146
  49. workflows/krea2_base_svdquant_w4a4_t2i_api.json +127 -57
  50. workflows/krea2_turbo_svdquant_w4a4_t2i_api.json +126 -54
.gitattributes CHANGED
@@ -79,3 +79,35 @@ examples/ice_cream_multisubject_test/compare_svdq_r256_00001_.png filter=lfs dif
79
  examples/ice_cream_multisubject_test/compare_svdq_r32_00001_.png filter=lfs diff=lfs merge=lfs -text
80
  examples/ice_cream_multisubject_test/compare_svdq_r64_00001_.png filter=lfs diff=lfs merge=lfs -text
81
  examples/ice_cream_multisubject_test/compare_w4a4_convrot_nolowrank_00001_.png filter=lfs diff=lfs merge=lfs -text
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
79
  examples/ice_cream_multisubject_test/compare_svdq_r32_00001_.png filter=lfs diff=lfs merge=lfs -text
80
  examples/ice_cream_multisubject_test/compare_svdq_r64_00001_.png filter=lfs diff=lfs merge=lfs -text
81
  examples/ice_cream_multisubject_test/compare_w4a4_convrot_nolowrank_00001_.png filter=lfs diff=lfs merge=lfs -text
82
+ examples/fidelity_sheets/sheet_base_01_dense_text.jpg filter=lfs diff=lfs merge=lfs -text
83
+ examples/fidelity_sheets/sheet_base_02_curved_text.jpg filter=lfs diff=lfs merge=lfs -text
84
+ examples/fidelity_sheets/sheet_base_03_hands_detail.jpg filter=lfs diff=lfs merge=lfs -text
85
+ examples/fidelity_sheets/sheet_base_04_crowd_faces.jpg filter=lfs diff=lfs merge=lfs -text
86
+ examples/fidelity_sheets/sheet_base_05_symmetry_pattern.jpg filter=lfs diff=lfs merge=lfs -text
87
+ examples/fidelity_sheets/sheet_base_06_multi_subject.jpg filter=lfs diff=lfs merge=lfs -text
88
+ examples/fidelity_sheets/sheet_base_07_reflections_glass.jpg filter=lfs diff=lfs merge=lfs -text
89
+ examples/fidelity_sheets/sheet_base_08_logo_typography.jpg filter=lfs diff=lfs merge=lfs -text
90
+ examples/fidelity_sheets/sheet_base_09_counting_objects.jpg filter=lfs diff=lfs merge=lfs -text
91
+ examples/fidelity_sheets/sheet_base_10_complex_scene.jpg filter=lfs diff=lfs merge=lfs -text
92
+ examples/fidelity_sheets/sheet_base_11_portrait_woman.jpg filter=lfs diff=lfs merge=lfs -text
93
+ examples/fidelity_sheets/sheet_base_12_person_holding_sign.jpg filter=lfs diff=lfs merge=lfs -text
94
+ examples/fidelity_sheets/sheet_base_13_two_people_interaction.jpg filter=lfs diff=lfs merge=lfs -text
95
+ examples/fidelity_sheets/sheet_base_14_hands_and_face.jpg filter=lfs diff=lfs merge=lfs -text
96
+ examples/fidelity_sheets/sheet_base_15_full_body_fashion.jpg filter=lfs diff=lfs merge=lfs -text
97
+ examples/fidelity_sheets/sheet_base_16_group_selfie.jpg filter=lfs diff=lfs merge=lfs -text
98
+ examples/fidelity_sheets/sheet_lora2_01_dense_text.jpg filter=lfs diff=lfs merge=lfs -text
99
+ examples/fidelity_sheets/sheet_lora2_02_curved_text.jpg filter=lfs diff=lfs merge=lfs -text
100
+ examples/fidelity_sheets/sheet_lora2_03_hands_detail.jpg filter=lfs diff=lfs merge=lfs -text
101
+ examples/fidelity_sheets/sheet_lora2_04_crowd_faces.jpg filter=lfs diff=lfs merge=lfs -text
102
+ examples/fidelity_sheets/sheet_lora2_05_symmetry_pattern.jpg filter=lfs diff=lfs merge=lfs -text
103
+ examples/fidelity_sheets/sheet_lora2_06_multi_subject.jpg filter=lfs diff=lfs merge=lfs -text
104
+ examples/fidelity_sheets/sheet_lora2_07_reflections_glass.jpg filter=lfs diff=lfs merge=lfs -text
105
+ examples/fidelity_sheets/sheet_lora2_08_logo_typography.jpg filter=lfs diff=lfs merge=lfs -text
106
+ examples/fidelity_sheets/sheet_lora2_09_counting_objects.jpg filter=lfs diff=lfs merge=lfs -text
107
+ examples/fidelity_sheets/sheet_lora2_10_complex_scene.jpg filter=lfs diff=lfs merge=lfs -text
108
+ examples/fidelity_sheets/sheet_lora2_11_portrait_woman.jpg filter=lfs diff=lfs merge=lfs -text
109
+ examples/fidelity_sheets/sheet_lora2_12_person_holding_sign.jpg filter=lfs diff=lfs merge=lfs -text
110
+ examples/fidelity_sheets/sheet_lora2_13_two_people_interaction.jpg filter=lfs diff=lfs merge=lfs -text
111
+ examples/fidelity_sheets/sheet_lora2_14_hands_and_face.jpg filter=lfs diff=lfs merge=lfs -text
112
+ examples/fidelity_sheets/sheet_lora2_15_full_body_fashion.jpg filter=lfs diff=lfs merge=lfs -text
113
+ examples/fidelity_sheets/sheet_lora2_16_group_selfie.jpg filter=lfs diff=lfs merge=lfs -text
BENCHMARKS.md CHANGED
@@ -21,11 +21,13 @@ comparable. RTX 3090, cu130 torch build.
21
  reflections, counting, complex composition), same seed, 1024x1024, 8 steps, cfg 1.0.
22
  Checkpoints: BF16 reference, W4A4 with no low-rank branch, and SVDQuant rank 16/32/64/128/256
23
  in both the fast single-shot split (`--refine-iters 0`, "no refine") and the alternating-refit
24
- version (default, "refined") — see the main README's [Low-rank refinement](README.md#low-rank-refinement)
25
  section for what that flag changes.
26
 
27
  [`examples/rank_sweep_t2i_comparison/`](examples/rank_sweep_t2i_comparison/) — one grid PNG
28
- per prompt, all 12 checkpoints side by side with the gemini quality score under each tile.
 
 
29
 
30
  | id | prompt | stresses |
31
  |---|---|---|
@@ -40,16 +42,7 @@ per prompt, all 12 checkpoints side by side with the gemini quality score under
40
  | 09_counting_objects | "A wooden table from directly above with exactly seven red apples arranged in a neat row next to three green pears, soft natural light, flat lay photography" | object counting |
41
  | 10_complex_scene | "A fantasy marketplace street at golden hour, merchant stalls with hanging fabrics and baskets of spices, a dragon perched on a rooftop in the background, dense crowd, painterly digital art" | complex composition |
42
 
43
- ![01_dense_text](examples/rank_sweep_t2i_comparison/grid_01_dense_text.png)
44
- ![02_curved_text](examples/rank_sweep_t2i_comparison/grid_02_curved_text.png)
45
- ![03_hands_detail](examples/rank_sweep_t2i_comparison/grid_03_hands_detail.png)
46
- ![04_crowd_faces](examples/rank_sweep_t2i_comparison/grid_04_crowd_faces.png)
47
- ![05_symmetry_pattern](examples/rank_sweep_t2i_comparison/grid_05_symmetry_pattern.png)
48
- ![06_multi_subject](examples/rank_sweep_t2i_comparison/grid_06_multi_subject.png)
49
- ![07_reflections_glass](examples/rank_sweep_t2i_comparison/grid_07_reflections_glass.png)
50
- ![08_logo_typography](examples/rank_sweep_t2i_comparison/grid_08_logo_typography.png)
51
- ![09_counting_objects](examples/rank_sweep_t2i_comparison/grid_09_counting_objects.png)
52
- ![10_complex_scene](examples/rank_sweep_t2i_comparison/grid_10_complex_scene.png)
53
 
54
  ## Test 2 — krea2edit LoRA (identity-preserving editing)
55
 
@@ -57,17 +50,15 @@ Same rank sweep, this time with the [Krea 2 Identity Edit LoRA](https://github.c
57
  on top, using its `Krea2EditModelPatch` / `Krea2EditGroundedEncode` nodes wired exactly per
58
  the LoRA repo's example workflow (`ref_boost=4`, `fit_mode=fit`, `grounding_px=768`,
59
  10 steps, cfg 1.0). Quantized checkpoints use this repo's **Krea2 SVDQuant LoRA Loader**
60
- node instead of the stock LoRA loader — the stock loader silently skips the quantized
61
- layers on these models (see the main README's [LoRA](README.md#lora) section).
 
 
62
 
63
  Three real stock photos of different women, resized to 1024x1536 before editing (feeding
64
  multi-thousand-pixel originals straight into VAEEncode wastes VRAM/time for no quality
65
  gain at this model's ~1MP working resolution).
66
 
67
- | woman 1 | woman 2 | woman 3 |
68
- |---|---|---|
69
- | ![woman1](examples/krea2edit_lora_comparison/source_photos/source_woman1.png) | ![woman2](examples/krea2edit_lora_comparison/source_photos/source_woman2.png) | ![woman3](examples/krea2edit_lora_comparison/source_photos/source_woman3.png) |
70
-
71
  | id | source | instruction |
72
  |---|---|---|
73
  | e1_paris_w1 | woman 1 | "Place her in Paris with the Eiffel Tower visible in the background, golden afternoon light, keep her exact face, hair, and outfit unchanged." |
@@ -77,12 +68,7 @@ gain at this model's ~1MP working resolution).
77
  | e5_paris_w3 | woman 3 | "Place her in Paris with the Eiffel Tower visible behind her, keep her exact face, hairstyle, and outfit unchanged." |
78
  | e6_night_lights_off_w3 | woman 3 | "Change the lighting to nighttime with all lights turned off, dark and moody atmosphere, keep her exact face unchanged." |
79
 
80
- ![e1_paris_w1](examples/krea2edit_lora_comparison/grid_e1_paris_w1.png)
81
- ![e2_sunset_sky_w1](examples/krea2edit_lora_comparison/grid_e2_sunset_sky_w1.png)
82
- ![e3_horse_w2](examples/krea2edit_lora_comparison/grid_e3_horse_w2.png)
83
- ![e4_night_lights_off_w2](examples/krea2edit_lora_comparison/grid_e4_night_lights_off_w2.png)
84
- ![e5_paris_w3](examples/krea2edit_lora_comparison/grid_e5_paris_w3.png)
85
- ![e6_night_lights_off_w3](examples/krea2edit_lora_comparison/grid_e6_night_lights_off_w3.png)
86
 
87
  ## Results
88
 
@@ -242,24 +228,135 @@ Without a LoRA the gain is large and unambiguous: LPIPS 0.3378 to **0.2825**, PS
242
  including r256. It also beats `no low-rank` at t=7.86 (2/32) — the widest margin any
243
  checkpoint reaches in this benchmark.
244
 
245
- Under a LoRA the gain shrinks to roughly nothing, and in the `canon` arm it goes slightly
246
- negative. The honest reading: **four of the five arms point the same way and the fifth is
247
- inside the noise** (t=1.67, and its own reseed floor is the lowest of the LoRA arms), so this
248
- is not evidence of a general act-aware/LoRA incompatibility. The plausible mechanism is
249
- calibration mismatch — the statistics were captured with no LoRA loaded, so they describe
250
- activation energy the LoRA then shifts. Recalibrating with the adapter loaded is untested.
 
251
 
252
- `r256-actaware` beats `r64` in every arm (t = 3.44 / 2.69 / 3.49 / 3.06 / 1.89), so nothing
253
- here reverses the Test 3 recommendation.
254
 
255
- **Recommendation: build with `--act-stats` — it is free at runtime, clearly better with no
256
- LoRA, and neutral with one.**
 
257
 
258
  ```bash
259
- python quantize_krea2.py --input turbo.safetensors --format svdq --rank 256 \
260
  --act-stats krea2_act_stats.safetensors
261
  ```
262
 
263
  Ruled out as confounds: `r256` and `r256-actaware` share source, rank, `refine_iters=100`,
264
  `groupsize=256` and all 224 branch sites. The activation weighting is the only variable.
265
  With `act_rms=None` the code path is bit-identical to the old one given the same RNG seed.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
21
  reflections, counting, complex composition), same seed, 1024x1024, 8 steps, cfg 1.0.
22
  Checkpoints: BF16 reference, W4A4 with no low-rank branch, and SVDQuant rank 16/32/64/128/256
23
  in both the fast single-shot split (`--refine-iters 0`, "no refine") and the alternating-refit
24
+ version (default, "refined") — see the main README's [Build your own checkpoint](README.md#build-your-own-checkpoint)
25
  section for what that flag changes.
26
 
27
  [`examples/rank_sweep_t2i_comparison/`](examples/rank_sweep_t2i_comparison/) — one grid PNG
28
+ per prompt, all 12 checkpoints side by side. The tiles have the judge's score printed under
29
+ them; those numbers are the withdrawn ones, baked into the images. Ignore them and look at
30
+ the images.
31
 
32
  | id | prompt | stresses |
33
  |---|---|---|
 
42
  | 09_counting_objects | "A wooden table from directly above with exactly seven red apples arranged in a neat row next to three green pears, soft natural light, flat lay photography" | object counting |
43
  | 10_complex_scene | "A fantasy marketplace street at golden hour, merchant stalls with hanging fabrics and baskets of spices, a dragon perched on a rooftop in the background, dense crowd, painterly digital art" | complex composition |
44
 
45
+ All ten grids: [GALLERY.md](GALLERY.md#rank-sweep-refined-vs-not).
 
 
 
 
 
 
 
 
 
46
 
47
  ## Test 2 — krea2edit LoRA (identity-preserving editing)
48
 
 
50
  on top, using its `Krea2EditModelPatch` / `Krea2EditGroundedEncode` nodes wired exactly per
51
  the LoRA repo's example workflow (`ref_boost=4`, `fit_mode=fit`, `grounding_px=768`,
52
  10 steps, cfg 1.0). Quantized checkpoints use this repo's **Krea2 SVDQuant LoRA Loader**
53
+ node instead of the stock one, which would dequantize the weight to apply the LoRA and then
54
+ requantize both together (see the main README's [LoRA](README.md#lora) section).
55
+
56
+ Source photographs are in [GALLERY.md](GALLERY.md#identity-edit-lora).
57
 
58
  Three real stock photos of different women, resized to 1024x1536 before editing (feeding
59
  multi-thousand-pixel originals straight into VAEEncode wastes VRAM/time for no quality
60
  gain at this model's ~1MP working resolution).
61
 
 
 
 
 
62
  | id | source | instruction |
63
  |---|---|---|
64
  | e1_paris_w1 | woman 1 | "Place her in Paris with the Eiffel Tower visible in the background, golden afternoon light, keep her exact face, hair, and outfit unchanged." |
 
68
  | e5_paris_w3 | woman 3 | "Place her in Paris with the Eiffel Tower visible behind her, keep her exact face, hairstyle, and outfit unchanged." |
69
  | e6_night_lights_off_w3 | woman 3 | "Change the lighting to nighttime with all lights turned off, dark and moody atmosphere, keep her exact face unchanged." |
70
 
71
+ All six edit grids: [GALLERY.md](GALLERY.md#identity-edit-lora).
 
 
 
 
 
72
 
73
  ## Results
74
 
 
228
  including r256. It also beats `no low-rank` at t=7.86 (2/32) — the widest margin any
229
  checkpoint reaches in this benchmark.
230
 
231
+ Under a LoRA the gain shrinks to roughly nothing: three of the four LoRA arms are positive and
232
+ one (`canon`) is slightly negative at t=1.67 — inside the noise, and the only arm of the five
233
+ pointing that way. **Four of five agree, so this is not evidence of an act-aware/LoRA
234
+ incompatibility**, and nothing here says avoid it with a LoRA. The plausible mechanism for the
235
+ shrinkage is calibration mismatch: the statistics were captured with no LoRA loaded, so they
236
+ describe activation energy the adapter then shifts. Recalibrating with the adapter loaded is
237
+ untested, and is the obvious next experiment for anyone picking this up.
238
 
239
+ `r256-actaware` also beats `r64` in every arm (t = 3.44 / 2.69 / 3.49 / 3.06 / 1.89), so
240
+ nothing here reverses the Test 3 recommendation either.
241
 
242
+ **Recommendation: build with `--act-stats`, whether or not you use LoRAs.** Free at runtime,
243
+ the largest fidelity gain measured in this repo without one, no worse with one — there is no
244
+ configuration in which the plain objective is the better choice.
245
 
246
  ```bash
247
+ python quantize_krea2.py turbo.safetensors --format svdq --rank 256 \
248
  --act-stats krea2_act_stats.safetensors
249
  ```
250
 
251
  Ruled out as confounds: `r256` and `r256-actaware` share source, rank, `refine_iters=100`,
252
  `groupsize=256` and all 224 branch sites. The activation weighting is the only variable.
253
  With `act_rms=None` the code path is bit-identical to the old one given the same RNG seed.
254
+
255
+ ## Speed and per-layer accuracy
256
+
257
+ All numbers measured on an **RTX 3090 24GB**, 1024x1024, 8-step Euler/simple sampling,
258
+ `cfg=1.0` (Krea 2 Turbo distilled schedule), from the same BF16 source checkpoint, on a
259
+ **cu130 torch build** (see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — on an older build every
260
+ one of these numbers gets worse, and the ordering inverts).
261
+
262
+ These are Turbo numbers. The base model at ~50 steps with CFG does roughly 12x the
263
+ sampling work per image, so the absolute seconds do not transfer; the *ratios* between
264
+ formats do, since they come from the same per-layer kernels.
265
+
266
+ #### End to end, per image
267
+
268
+ Two numbers matter and are easy to conflate: **first run after switching checkpoints**
269
+ (pays disk-to-VRAM load time, ~9-15s here) and **warm run** (model already resident,
270
+ what you get generating multiple images back to back). ComfyUI's own progress bar
271
+ ("`8/8 [00:07<00:00, 1.09it/s]`") only covers the KSampler loop; "`Prompt executed in
272
+ X seconds`" is CLIP load/encode + model staging + sampling + VAE decode + save combined
273
+ — the two numbers can differ by 2x on a cold run.
274
+
275
+ | checkpoint | size | first run (cold) | warm run | vs. BF16 |
276
+ |---|---|---|---|---|
277
+ | BF16 (unquantized reference) | 24.48 GB | 25.3 s | 21.3 s | 1.0x |
278
+ | FP8 e4m3, scaled (emulated on Ampere) | 12.24 GB | 22.2 s | 19.2 s | 1.1x |
279
+ | INT8 tensorwise + convrot (not in this upload) | 13.16 GB | 13.3 s | 10.4 s | 2.0x |
280
+ | **W4A4 + convrot, no low-rank branch** | 7.50 GB | 10.3 s | **10.1 s** | 2.1x |
281
+ | **W4A4 + SVDQuant low-rank, rank 16/64/128** | 7.6-8.3 GB | ~19.3 s | **10.1-10.2 s** | 2.1x |
282
+
283
+ Rank does not measurably change warm speed — CLIP text-encode (Qwen3-VL 4B) and VAE
284
+ decode overhead dominate a single 1024x1024/8-step/batch-1 image and mask the low-rank
285
+ branch's cost. Add a **TorchCompileModel** node (backend `inductor`) after the loader
286
+ for a further ~20-25% cut on the sampling portion specifically (see profiling below);
287
+ that number does not show up in the table above since it isn't included in this
288
+ upload's default workflow.
289
+
290
+ **FP8 is not faster than BF16 on Ampere** — there are no FP8 tensor cores on this
291
+ architecture, so ComfyUI casts to bf16 and calls cuBLAS. It's included here because it's
292
+ the most common recommendation online for "quantizing Krea 2," and the numbers show why
293
+ that advice doesn't hold on 30-series cards. **INT8 is the fastest *accurate* option**
294
+ measured, but is not part of this upload (available via `quantize_krea2.py --format
295
+ int8` on your own BF16 checkpoint).
296
+
297
+ #### Per-layer accuracy (cosine similarity / relative error vs. BF16 original)
298
+
299
+ Measured on real captured activations from a Krea 2 Turbo forward pass (not synthetic
300
+ noise), across representative attention and MLP layers:
301
+
302
+ | format | cosine | relative error | per-layer time |
303
+ |---|---|---|---|
304
+ | bf16 (reference) | 1.00000 | - | 1.22 - 3.48 ms |
305
+ | **int8 + convrot (Hadamard rotation)** | 0.99999 | 0.35 - 0.63% | 0.39 - 1.09 ms |
306
+ | int8 per-channel (no rotation) | 0.99993 | 0.45 - 1.47% | 0.35 - 1.01 ms |
307
+ | fp8 e4m3, scaled | 0.99996 | 0.39 - 1.28% | 1.95 - 5.14 ms |
308
+ | nvfp4 | 0.99968 | 0.74 - 4.00% | 1.49 - 3.93 ms |
309
+ | w4a4 + convrot, rank-64 low-rank branch | 0.99933 - 0.99997 | 0.72 - 8.38% | 0.39 - 1.09 ms |
310
+ | w4a4 + convrot, no low-rank branch | 0.99569 - 0.99908 | 1.49 - 9.29% | 0.23 - 0.67 ms |
311
+
312
+ The Hadamard rotation used by `convrot` already does most of what SVDQuant's low-rank
313
+ branch does (both are outlier-mitigation strategies), so on top of `convrot_w4a4` the
314
+ low-rank branch buys noticeably less than in the original SVDQuant paper — it roughly
315
+ halves the error rather than eliminating it. **`int8` is the more accurate choice if
316
+ quality matters more than raw speed; `svdq` is the faster, smaller choice.**
317
+
318
+ #### Rank sweep
319
+
320
+ `--format svdq --rank N` was run for N = 16, 32, 64, 128, 256. Checkpoint sizes:
321
+
322
+ | rank | size |
323
+ |---|---|
324
+ | 16 | 7.60 GB |
325
+ | 32 | 7.70 GB |
326
+ | 64 | 7.90 GB |
327
+ | 128 | 8.30 GB |
328
+ | 256 | 9.10 GB |
329
+
330
+ This is an experimental project — the rank sweep is deliberately shipped so people can
331
+ try the tradeoff themselves rather than take one number on faith. If you benchmark other
332
+ ranks or find a case where one clearly wins, open a discussion on this repo.
333
+
334
+ To measure any of this yourself against a BF16 reference:
335
+
336
+ ```bash
337
+ python tools/fidelity_bench.py generate --output-dir <ComfyUI/output>
338
+ python tools/fidelity_bench.py score --output-dir <ComfyUI/output>
339
+ python tools/contact_sheet.py --output-dir <ComfyUI/output> --jpeg 90
340
+ ```
341
+
342
+ `generate` is idempotent, so it can be grown one `--seeds` or `--checkpoints` at a time.
343
+ `score` prints the reseed floor next to every result, which is the number that decides whether
344
+ a difference is claimable. `contact_sheet` builds the sheets in [GALLERY.md](GALLERY.md) --
345
+ the numbers rank, the sheets adjudicate.
346
+
347
+ #### Where the remaining time goes (profiled, `svdq r64`, single denoise step, 175.7 ms)
348
+
349
+ | component | share |
350
+ |---|---|
351
+ | W4A4 GEMM (native `comfy_kitchen` cutlass kernel) | 37% |
352
+ | elementwise / norm / RoPE / dtype casts | 34% |
353
+ | attention (cuDNN flash) | 9% |
354
+ | low-rank branch (2 bf16 GEMMs per quantized layer) | 9% |
355
+ | W4A4 activation quantization | 8% |
356
+
357
+ A third of a step is small elementwise kernels, which is why `torch.compile` (backend
358
+ `inductor`) helps: add a **TorchCompileModel** node after the loader. Stock ComfyUI
359
+ quantized tensors normally break `torch.compile` (Dynamo can't trace into the
360
+ `comfy_kitchen` kernel); the W4A4 loader here works around that by marking those calls as
361
+ graph breaks so inductor still fuses everything around them. First run after loading pays
362
+ ~50s of compilation; subsequent runs are warm.
GALLERY.md ADDED
@@ -0,0 +1,250 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Gallery
2
+
3
+ Every comparison image in this repo, kept out of the README so that page stays short. Nothing
4
+ here is a measurement -- those live in [BENCHMARKS.md](BENCHMARKS.md). These exist because
5
+ LPIPS answers "how far did it move", not "is it worse", and the two come apart: W4A4 shifts
6
+ the sampling trajectory, so a checkpoint can score a large distance and still look fine, or a
7
+ small one and mangle a line of text.
8
+
9
+ * [Fidelity sheets, no LoRA](#fidelity-sheets-no-lora) -- 16 prompts x 7 checkpoints x 2 seeds
10
+ * [Fidelity sheets, with a LoRA](#fidelity-sheets-with-a-lora) -- the same, under `bloomgirls-ultrarealism`
11
+ * [Rank sweep, refined vs not](#rank-sweep-refined-vs-not)
12
+ * [Identity-edit LoRA](#identity-edit-lora)
13
+ * [Single-prompt stress tests](#single-prompt-stress-tests)
14
+
15
+ **How to read the sheets.** They are wide -- open one full size, they are unreadable at page
16
+ width. Columns run left to right in accuracy order: **BF16 reference** first, then no
17
+ low-rank branch, then rising rank, ending with the activation-aware build. Rows are two
18
+ seeds. So anything that differs between the two rows of a *single* column is sampling
19
+ variance, not a property of the checkpoint -- and if a difference between columns is smaller
20
+ than the difference between rows, it is not a difference.
21
+
22
+
23
+ ## Fidelity sheets, no LoRA
24
+
25
+ Built with `tools/contact_sheet.py` from the same renders `tools/fidelity_bench.py score` measures, so every image here has a number behind it in
26
+ [Test 3 and Test 4](BENCHMARKS.md#test-3--paired-lpips-fidelity-with-and-without-a-lora).
27
+
28
+ **01_dense_text** -- Three lines of small chalkboard text. The hardest cell in the set: read the prices.
29
+
30
+ ![01_dense_text](examples/fidelity_sheets/sheet_base_01_dense_text.jpg)
31
+
32
+ **02_curved_text** -- Two large words wrapped around a cup. Every checkpoint gets this; it is the easy control.
33
+
34
+ ![02_curved_text](examples/fidelity_sheets/sheet_base_02_curved_text.jpg)
35
+
36
+ **03_hands_detail** -- Finger placement on the strings, and whether the motion-blurred bow holds together.
37
+
38
+ ![03_hands_detail](examples/fidelity_sheets/sheet_base_03_hands_detail.jpg)
39
+
40
+ **04_crowd_faces** -- Dozens of small faces. Look for melted or duplicated ones rather than at the whole frame.
41
+
42
+ ![04_crowd_faces](examples/fidelity_sheets/sheet_base_04_crowd_faces.jpg)
43
+
44
+ **05_symmetry_pattern** -- Repeating geometry. Breaks in the tiling are far easier to see than colour drift.
45
+
46
+ ![05_symmetry_pattern](examples/fidelity_sheets/sheet_base_05_symmetry_pattern.jpg)
47
+
48
+ **06_multi_subject** -- Two people acting at once -- tweezers in one pair of hands, sauce in the other.
49
+
50
+ ![06_multi_subject](examples/fidelity_sheets/sheet_base_06_multi_subject.jpg)
51
+
52
+ **07_reflections_glass** -- Condensation and bokeh reflected through liquid. High frequency, little structure.
53
+
54
+ ![07_reflections_glass](examples/fidelity_sheets/sheet_base_07_reflections_glass.jpg)
55
+
56
+ **08_logo_typography** -- Serif signage on curved chrome: text and specular highlight in the same place.
57
+
58
+ ![08_logo_typography](examples/fidelity_sheets/sheet_base_08_logo_typography.jpg)
59
+
60
+ **09_counting_objects** -- Seven apples, three pears. Miscounting is a structural failure, not a detail one.
61
+
62
+ ![09_counting_objects](examples/fidelity_sheets/sheet_base_09_counting_objects.jpg)
63
+
64
+ **10_complex_scene** -- Dense painterly scene. Composition should be identical; brushwork will not be.
65
+
66
+ ![10_complex_scene](examples/fidelity_sheets/sheet_base_10_complex_scene.jpg)
67
+
68
+ **11_portrait_woman** -- Skin texture, freckles, catchlights. Where a photographic LoRA earns its keep.
69
+
70
+ ![11_portrait_woman](examples/fidelity_sheets/sheet_base_11_portrait_woman.jpg)
71
+
72
+ **12_person_holding_sign** -- Handwritten marker text on cardboard at arm's length -- text plus a full body.
73
+
74
+ ![12_person_holding_sign](examples/fidelity_sheets/sheet_base_12_person_holding_sign.jpg)
75
+
76
+ **13_two_people_interaction** -- Two faces mid-expression, and the hand-off between them.
77
+
78
+ ![13_two_people_interaction](examples/fidelity_sheets/sheet_base_13_two_people_interaction.jpg)
79
+
80
+ **14_hands_and_face** -- Hands, lips and a reflected eye in one frame at extreme close-up.
81
+
82
+ ![14_hands_and_face](examples/fidelity_sheets/sheet_base_14_hands_and_face.jpg)
83
+
84
+ **15_full_body_fashion** -- Fabric folds under hard side light, and whether the stride survives.
85
+
86
+ ![15_full_body_fashion](examples/fidelity_sheets/sheet_base_15_full_body_fashion.jpg)
87
+
88
+ **16_group_selfie** -- Four faces at once, plus the arm geometry of whoever is holding the phone.
89
+
90
+ ![16_group_selfie](examples/fidelity_sheets/sheet_base_16_group_selfie.jpg)
91
+
92
+
93
+ ## Fidelity sheets, with a LoRA
94
+
95
+ The same 16 prompts and seeds with `bloomgirls-ultrarealism-krea2_4k` at strength 1.0,
96
+ applied through this repo's LoRA node. The BF16 column carries the LoRA too -- the
97
+ comparison is quantized+LoRA against BF16+LoRA, which is the question the repo's earlier
98
+ LoRA benchmark never asked.
99
+
100
+ **01_dense_text** -- Three lines of small chalkboard text. The hardest cell in the set: read the prices.
101
+
102
+ ![01_dense_text](examples/fidelity_sheets/sheet_lora2_01_dense_text.jpg)
103
+
104
+ **02_curved_text** -- Two large words wrapped around a cup. Every checkpoint gets this; it is the easy control.
105
+
106
+ ![02_curved_text](examples/fidelity_sheets/sheet_lora2_02_curved_text.jpg)
107
+
108
+ **03_hands_detail** -- Finger placement on the strings, and whether the motion-blurred bow holds together.
109
+
110
+ ![03_hands_detail](examples/fidelity_sheets/sheet_lora2_03_hands_detail.jpg)
111
+
112
+ **04_crowd_faces** -- Dozens of small faces. Look for melted or duplicated ones rather than at the whole frame.
113
+
114
+ ![04_crowd_faces](examples/fidelity_sheets/sheet_lora2_04_crowd_faces.jpg)
115
+
116
+ **05_symmetry_pattern** -- Repeating geometry. Breaks in the tiling are far easier to see than colour drift.
117
+
118
+ ![05_symmetry_pattern](examples/fidelity_sheets/sheet_lora2_05_symmetry_pattern.jpg)
119
+
120
+ **06_multi_subject** -- Two people acting at once -- tweezers in one pair of hands, sauce in the other.
121
+
122
+ ![06_multi_subject](examples/fidelity_sheets/sheet_lora2_06_multi_subject.jpg)
123
+
124
+ **07_reflections_glass** -- Condensation and bokeh reflected through liquid. High frequency, little structure.
125
+
126
+ ![07_reflections_glass](examples/fidelity_sheets/sheet_lora2_07_reflections_glass.jpg)
127
+
128
+ **08_logo_typography** -- Serif signage on curved chrome: text and specular highlight in the same place.
129
+
130
+ ![08_logo_typography](examples/fidelity_sheets/sheet_lora2_08_logo_typography.jpg)
131
+
132
+ **09_counting_objects** -- Seven apples, three pears. Miscounting is a structural failure, not a detail one.
133
+
134
+ ![09_counting_objects](examples/fidelity_sheets/sheet_lora2_09_counting_objects.jpg)
135
+
136
+ **10_complex_scene** -- Dense painterly scene. Composition should be identical; brushwork will not be.
137
+
138
+ ![10_complex_scene](examples/fidelity_sheets/sheet_lora2_10_complex_scene.jpg)
139
+
140
+ **11_portrait_woman** -- Skin texture, freckles, catchlights. Where a photographic LoRA earns its keep.
141
+
142
+ ![11_portrait_woman](examples/fidelity_sheets/sheet_lora2_11_portrait_woman.jpg)
143
+
144
+ **12_person_holding_sign** -- Handwritten marker text on cardboard at arm's length -- text plus a full body.
145
+
146
+ ![12_person_holding_sign](examples/fidelity_sheets/sheet_lora2_12_person_holding_sign.jpg)
147
+
148
+ **13_two_people_interaction** -- Two faces mid-expression, and the hand-off between them.
149
+
150
+ ![13_two_people_interaction](examples/fidelity_sheets/sheet_lora2_13_two_people_interaction.jpg)
151
+
152
+ **14_hands_and_face** -- Hands, lips and a reflected eye in one frame at extreme close-up.
153
+
154
+ ![14_hands_and_face](examples/fidelity_sheets/sheet_lora2_14_hands_and_face.jpg)
155
+
156
+ **15_full_body_fashion** -- Fabric folds under hard side light, and whether the stride survives.
157
+
158
+ ![15_full_body_fashion](examples/fidelity_sheets/sheet_lora2_15_full_body_fashion.jpg)
159
+
160
+ **16_group_selfie** -- Four faces at once, plus the arm geometry of whoever is holding the phone.
161
+
162
+ ![16_group_selfie](examples/fidelity_sheets/sheet_lora2_16_group_selfie.jpg)
163
+
164
+
165
+ ## Rank sweep, refined vs not
166
+
167
+ Ten prompts across rank 16 through 256, refined and non-refined, from the sweep documented in
168
+ [Test 1](BENCHMARKS.md#test-1--text-to-image-rank-sweep). Speed tables and the prompts
169
+ themselves are there; these are the images.
170
+
171
+ ![01_dense_text](examples/rank_sweep_t2i_comparison/grid_01_dense_text.png)
172
+ ![02_curved_text](examples/rank_sweep_t2i_comparison/grid_02_curved_text.png)
173
+ ![03_hands_detail](examples/rank_sweep_t2i_comparison/grid_03_hands_detail.png)
174
+ ![04_crowd_faces](examples/rank_sweep_t2i_comparison/grid_04_crowd_faces.png)
175
+ ![05_symmetry_pattern](examples/rank_sweep_t2i_comparison/grid_05_symmetry_pattern.png)
176
+ ![06_multi_subject](examples/rank_sweep_t2i_comparison/grid_06_multi_subject.png)
177
+ ![07_reflections_glass](examples/rank_sweep_t2i_comparison/grid_07_reflections_glass.png)
178
+ ![08_logo_typography](examples/rank_sweep_t2i_comparison/grid_08_logo_typography.png)
179
+ ![09_counting_objects](examples/rank_sweep_t2i_comparison/grid_09_counting_objects.png)
180
+ ![10_complex_scene](examples/rank_sweep_t2i_comparison/grid_10_complex_scene.png)
181
+
182
+ ## Identity-edit LoRA
183
+
184
+ Six edits on three real photographs through the
185
+ [Krea 2 Identity Edit LoRA](https://github.com/lbouaraba/comfyui-krea2edit), same rank sweep.
186
+ Details in [Test 2](BENCHMARKS.md#test-2--krea2edit-lora-identity-preserving-editing).
187
+
188
+ | woman 1 | woman 2 | woman 3 |
189
+ |---|---|---|
190
+ | ![woman1](examples/krea2edit_lora_comparison/source_photos/source_woman1.png) | ![woman2](examples/krea2edit_lora_comparison/source_photos/source_woman2.png) | ![woman3](examples/krea2edit_lora_comparison/source_photos/source_woman3.png) |
191
+
192
+ ![e1_paris_w1](examples/krea2edit_lora_comparison/grid_e1_paris_w1.png)
193
+ ![e2_sunset_sky_w1](examples/krea2edit_lora_comparison/grid_e2_sunset_sky_w1.png)
194
+ ![e3_horse_w2](examples/krea2edit_lora_comparison/grid_e3_horse_w2.png)
195
+ ![e4_night_lights_off_w2](examples/krea2edit_lora_comparison/grid_e4_night_lights_off_w2.png)
196
+ ![e5_paris_w3](examples/krea2edit_lora_comparison/grid_e5_paris_w3.png)
197
+ ![e6_night_lights_off_w3](examples/krea2edit_lora_comparison/grid_e6_night_lights_off_w3.png)
198
+
199
+ ## Single-prompt stress tests
200
+
201
+ The two early comparisons, one seed each, across all nine formats tried during development
202
+ (FP8, INT8 and rank 32 are here for reference; they were never uploaded). One seed is not a
203
+ ranking -- read these as "what does this format do to this image", not "which is best".
204
+
205
+ ### Hard case: dense multi-line text
206
+
207
+ A rainy neon diner sign with a three-line handwritten chalkboard menu.
208
+
209
+ | BF16 (reference) | INT8 + convrot |
210
+ |---|---|
211
+ | ![bf16](examples/neon_sign_text_test/compare_bf16_reference_00001_.png) | ![int8](examples/neon_sign_text_test/compare_int8_convrot_00001_.png) |
212
+
213
+ | W4A4, no low-rank branch | SVDQuant rank 128 |
214
+ |---|---|
215
+ | ![w4a4](examples/neon_sign_text_test/compare_w4a4_convrot_nolowrank_00001_.png) | ![r128](examples/neon_sign_text_test/compare_svdq_r128_00001_.png) |
216
+
217
+ What happened at this one seed: BF16, FP8 and INT8 render the menu correctly; W4A4 with no
218
+ branch duplicates a word; rank 16 is correct but shifts a nearby sign's colour; rank 32
219
+ duplicates a line; rank 64 gets a digit wrong; rank 128 lands closest to BF16; rank 256 swaps
220
+ two digits. That is not a rank ordering -- it is seed sensitivity, which is precisely why the
221
+ paired multi-seed sheets above exist.
222
+
223
+ <details>
224
+ <summary>All nine variants for this prompt</summary>
225
+
226
+ [`examples/neon_sign_text_test/`](examples/neon_sign_text_test) -- file names match the config
227
+ names used in the benchmark tables.
228
+
229
+ </details>
230
+
231
+ ### Easy case: large text, two subjects, low angle
232
+
233
+ Two people, a low camera angle, and two words of large curved text on a held object. Every
234
+ checkpoint renders the text correctly here, down to W4A4 with no branch; only fine composition
235
+ details vary.
236
+
237
+ | BF16 (reference) | SVDQuant rank 64 |
238
+ |---|---|
239
+ | ![bf16](examples/ice_cream_multisubject_test/compare_bf16_reference_00001_.png) | ![r64](examples/ice_cream_multisubject_test/compare_svdq_r64_00001_.png) |
240
+
241
+ <details>
242
+ <summary>All nine variants for this prompt</summary>
243
+
244
+ [`examples/ice_cream_multisubject_test/`](examples/ice_cream_multisubject_test)
245
+
246
+ </details>
247
+
248
+ **Across both:** for large signage text or no text, any checkpoint here works. For dense small
249
+ text the low-rank branch helps and does not fully close the gap to INT8 -- `quantize_krea2.py
250
+ --format int8` is the better choice if that is your main use case.
README.md CHANGED
@@ -21,459 +21,312 @@ pipeline_tag: text-to-image
21
 
22
  # Krea 2 SVDQuant W4A4 for ComfyUI
23
 
24
- Quantized **Krea 2** checkpoints for ComfyUI — about **2x faster** and **a third the
25
- size** of the usual FP8 version, with no calibration dataset needed, on both **Krea 2
26
- Turbo** (distilled, 8 steps) and the **base** release (~50 steps with real CFG; the
27
- conversion is identical, only the sampler settings differ). This is an experimental,
28
- built-from-scratch project — the quantization script, loader node, and LoRA node were
29
- all written for this repo against ComfyUI's own quantization backend, and are fully
30
- reproducible (`quantize_krea2.py` regenerates any checkpoint here from a BF16 source in
31
- 40-100 seconds, or ~6 minutes with low-rank refinement, the default for `--format svdq`).
32
-
33
- Works on **any modern NVIDIA GPU** — INT8/W4A4 tensor cores go back to Turing (RTX
34
- 20-series and up). Benchmarked on an RTX 3090 (Ampere, sm_86), which is the case most
35
- existing Krea 2 quantization writeups don't cover, since that generation has no FP8 or
36
- NVFP4 tensor cores at all.
37
 
38
  > **Requires a cu130 (CUDA 13) or newer PyTorch build.** ComfyUI disables `comfy_kitchen`'s
39
- > CUDA backend entirely on older torch builds, which silently drops every quantized
40
- > checkpoint onto a pure-Python fallback that is *slower than bf16*. If these checkpoints
41
- > are slower than FP8 for you, this is almost certainly why — see
42
- > [Troubleshooting](#troubleshooting).
43
 
44
- This is a community-produced modification of Krea 2, not an official Krea product —
45
- license and attribution details are at the [bottom of this README](#attribution); read
46
- them before using these weights, in particular the revenue threshold on commercial use.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
47
 
48
  ## Quick start
49
 
50
- 1. **Install the custom nodes.** Open a terminal in your ComfyUI folder and run:
51
  ```bash
52
  git clone https://github.com/alperktt/Krea-2-SVDQuant-ComfyUI custom_nodes/krea2-svdquant
53
  ```
54
- (No git? Just download this repo as a ZIP and unzip it into `ComfyUI/custom_nodes/`.)
55
- Restart ComfyUI.
56
 
57
- 2. **Download one checkpoint** from the *Files* tab of this page (`Krea2-Turbo-...
58
- .safetensors`, pick one — see the table below) and put it in
59
  `ComfyUI/models/diffusion_models/`.
60
 
61
- 3. **Download the text encoder and VAE** (same ones any Krea 2 Turbo workflow needs,
62
- not specific to this repo):
63
  - [`qwen3vl_4b_fp8_scaled.safetensors`](https://huggingface.co/Comfy-Org/Krea-2/resolve/main/text_encoders/qwen3vl_4b_fp8_scaled.safetensors) → `ComfyUI/models/text_encoders/`
64
  - [`qwen_image_vae.safetensors`](https://huggingface.co/Comfy-Org/Krea-2/resolve/main/vae/qwen_image_vae.safetensors) → `ComfyUI/models/vae/`
65
 
66
- 4. **Load a workflow.** Drag one of these from the `workflows/` folder into ComfyUI, pick
67
- your checkpoint in the loader node, and generate. Each one opens with a **READ ME FIRST**
68
- note covering the settings that matter.
69
-
70
  - `krea2_turbo_svdquant_w4a4_t2i.json` → **Turbo**: 8 steps, `cfg 1.0`, zeroed negative.
71
- - `krea2_base_svdquant_w4a4_t2i.json` → **base**: 50 steps, `cfg 3.5`, real negative
72
- prompt. Treat those as a starting point and tune them.
73
-
74
- The matching `*_api.json` files are for POSTing to `/prompt` from a script — don't drag
75
- those in, they carry no layout.
76
 
77
- - `Krea2-Turbo-W4A4-noLowRank.safetensors` → use the normal **UNETLoader** node.
78
- - Any `SVDQuant-W4A4-rank*` checkpoint → use the **Krea2 SVDQuant W4A4 Loader**
79
- node from this repo instead (it's what shows up after step 1).
80
 
81
- That's it. Everything below is background on *why* it's faster and *how accurate* each
82
- option is, for people who want the details.
83
 
84
- ## Why this exists
 
 
 
85
 
86
- The usual advice for making Krea 2 cheaper to run is FP8. That only pays off if your GPU
87
- has FP8 tensor cores — Ada, Hopper, Blackwell. On anything older, FP8 weights get cast
88
- back to bf16 before the matmul and run through cuBLAS, so you save VRAM but gain no
89
- speed. Measured on an RTX 3090, FP8 was *slower* than plain bf16.
90
 
91
- The same trap catches weight-only 4-bit quantization (W4A16): if activations stay 16-bit,
92
- the matmul still runs on bf16 tensor cores at bf16 speed. 4-bit weights only reduce
93
- memory bandwidth, which isn't the bottleneck at typical resolutions and batch sizes.
94
 
95
- What actually moves the needle is quantizing **activations too**, onto hardware that has
96
- the units for it. **INT8 and W4A4 tensor cores go back to Turing (RTX 20-series)** — far
97
- wider support than FP8. So this repo quantizes Krea 2 Turbo from BF16 straight into
98
- formats ComfyUI already ships native kernels for (`int8_tensorwise` and `convrot_w4a4`
99
- in `comfy_kitchen`), and adds an SVDQuant-style low-rank correction branch on top of the
100
- native W4A4 kernel to claw back accuracy at 4 bits.
101
 
102
- No calibration dataset is needed — the `convrot` (group-wise Hadamard rotation) step
103
- spreads outliers analytically, and activations are quantized by the kernel at run time.
104
- Everything here was built from scratch against ComfyUI's own quantization backend.
105
 
106
- ## Included checkpoints
107
 
108
- | file | format | rank | size |
109
- |---|---|---|---|
110
- | `Krea2-Turbo-W4A4-noLowRank.safetensors` | native `convrot_w4a4`, no accuracy branch | - | 7.50 GB |
111
- | `Krea2-Turbo-SVDQuant-W4A4-rank16.safetensors` | `convrot_w4a4` + low-rank branch | 16 | 7.60 GB |
112
- | `Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors` | `convrot_w4a4` + low-rank branch | 64 | 7.90 GB |
113
- | `Krea2-Turbo-SVDQuant-W4A4-rank128.safetensors` | `convrot_w4a4` + low-rank branch | 128 | 8.30 GB |
114
 
115
- The no-low-rank file loads with the stock ComfyUI **UNETLoader**. The three `svdq`
116
- checkpoints need the **Krea2 SVDQuant W4A4 Loader** node from this repo (they carry extra
117
- `*.svdq_l1` / `*.svdq_l2` tensors the stock loader doesn't know about).
118
 
119
- Higher rank = larger low-rank correction branch = lower weight reconstruction error. Over
120
- four sampled layers: 0.127 at rank 16, 0.098 at rank 64, 0.080 at rank 128. All are built
121
- with `refine_iters=100`, which is what makes rank worth spending at all.
 
 
122
 
123
- **Which one to download.** Lower reconstruction error stops translating into visibly closer
124
- *images* past rank 64 — unless you load a LoRA, and then it keeps paying up to 256. Measured
125
- paired over 16 prompts x 2 seeds; details and the numbers are in
126
- [BENCHMARKS.md](BENCHMARKS.md#test-3--paired-lpips-fidelity-with-and-without-a-lora).
 
127
 
128
- | you | pick |
129
- |---|---|
130
- | never use LoRAs | **rank 64** — 128 and 256 measure the same, so the extra GB is wasted |
131
- | use LoRAs | **rank 256** — rank 64 loses most of its advantage under one |
132
- | want the smallest/fastest and can accept the drop | no-low-rank, or rank 16 |
133
 
134
- Each file records how it was built in its safetensors metadata (`krea2_svdquant_rank`,
135
- `krea2_svdquant_refine_iters`, tool version, source file), so you can check what you
136
- downloaded rather than trusting this table:
137
 
138
- ```python
139
- from safetensors import safe_open
140
- with safe_open("Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors", framework="pt") as f:
141
- print(f.metadata())
142
- ```
143
-
144
- > The test that matters is `f.metadata() is None`, not the date: an early batch (published
145
- > before 2026-07-26) was built without refinement and carries no metadata at all. If yours
146
- > returns `None`, re-download — at rank 128 the unrefined build measures 0.095 against the
147
- > refined 0.080, and the whole rank ladder is flat without refinement.
148
-
149
- Rank 32 and 256 were also produced and benchmarked during development but are not included
150
- in this upload; `quantize_krea2.py` reproduces them exactly (`--rank 32` / `--rank 256`).
151
-
152
- ## What's in this repo
153
-
154
- | file | what it is |
155
- |---|---|
156
- | `quantize_krea2.py` | Converts a BF16 Krea 2 checkpoint to int8, w4a4, or w4a4 + low-rank (svdq) |
157
- | `svdquant_w4a4.py` | The **Krea2 SVDQuant W4A4 Loader** node — loads `--format svdq` checkpoints (self-contained, no base model needed) |
158
- | `svdquant_lora.py` | The **Krea2 SVDQuant LoRA Loader** node — applies LoRAs as a parallel branch so the 4-bit weight is never dequantized |
159
- | `svdquant_quantize.py` | The **Krea2 SVDQuant Quantize** node — the quantizer above, run from inside ComfyUI instead of a terminal |
160
- | `svdquant_capture.py` | The **Krea2 SVDQuant Capture Start/Save** nodes — record per-channel activation RMS for `--act-stats` |
161
- | `svdquant_diag.py` | The **Krea2 SVDQuant Diagnostics** and **Krea2 SVDQuant Env Check** nodes — which kernel actually runs, plus memory accounting and per-layer timings |
162
- | `diagnose.py` | The same reports from a terminal, without starting ComfyUI |
163
- | `tools/build_workflows.py` | Regenerates `workflows/*.json`. Edit this, not the JSON |
164
- | `tools/pixel_metrics.py` | LPIPS/PSNR/SSIM against a BF16 reference — see [Benchmarks](#benchmarks) |
165
- | `tools/fidelity_bench.py` | Paired multi-seed multi-LoRA LPIPS harness — every fidelity claim here comes from it |
166
- | `tools/contact_sheet.py` | Per-prompt contact sheets (checkpoints x seeds) for looking at, not scoring |
167
- | `workflows/*.json` | Example workflows — see the format note below |
168
-
169
- Installing this adds seven nodes, all under the **Krea2/SVDQuant** category:
170
 
171
  | node | what it is for |
172
  |---|---|
173
  | **Krea2 SVDQuant W4A4 Loader** | Loads an `svdq` checkpoint. Its `status` output names the kernel that will actually run — read it first if generation is slow |
174
- | **Krea2 SVDQuant LoRA Loader** | LoRAs and LoKrs on quantized blocks |
175
- | **Krea2 SVDQuant Quantize** | Builds a quantized checkpoint without leaving ComfyUI. Blocks the queue while it runs (54 s to ~6 min) and writes ~8 GB |
176
  | **Krea2 SVDQuant Diagnostics** | Backend dispatch, memory accounting, per-layer timings, profiler table |
177
  | **Krea2 SVDQuant Env Check** | Is the int4 kernel available at all? Needs no model, so you can ask before downloading 8 GB |
178
- | **Krea2 SVDQuant Capture Start** / **Capture Save** | Record activation statistics for an activation-aware build — see [`--act-stats`](#activation-aware-branch---act-stats) |
179
 
180
- ### Two workflow formats, and why
181
-
182
- ComfyUI has two JSON dialects and mixing them up is a bad first five minutes:
183
 
184
- - `workflows/krea2_*_t2i.json` — **UI format.** Drag these into the ComfyUI canvas. They
185
- carry layout, node titles, colours, and a **READ ME FIRST** note with the settings that
186
- matter and the slow-generation checklist.
187
- - `workflows/krea2_*_t2i_api.json` — **API format.** What you POST to `/prompt` from a
188
- script. No layout; dragging one in gives you a pile of untitled nodes.
 
 
 
 
 
 
 
 
 
 
 
 
189
 
190
- Regenerate the UI ones with `python tools/build_workflows.py` rather than editing the JSON.
191
 
192
- ### Quantize your own checkpoint
193
 
194
- Either from a terminal:
195
 
196
  ```bash
197
  cd ComfyUI/custom_nodes/krea2-svdquant
198
- python quantize_krea2.py /path/to/krea2_bf16.safetensors --format int8
199
- python quantize_krea2.py /path/to/krea2_bf16.safetensors --format w4a4
200
- python quantize_krea2.py /path/to/krea2_bf16.safetensors --format svdq --rank 64
201
  ```
202
 
203
- …or with the **Krea2 SVDQuant Quantize** node, which calls the same code with no terminal
204
- involved: drop the source checkpoint in `models/diffusion_models/`, pick it in the node, and
205
- queue. Three things to know before you do:
206
-
207
- - **It blocks the queue** for the whole run — 54 s for a single-shot split, ~5.7 min with
208
- `refine_iters=100`, measured on a 3090. Nothing else generates meanwhile.
209
- - **It takes the GPU.** Any loaded model is unloaded first, so your next generation pays a
210
- reload.
211
- - **It writes ~8 GB**, and refuses rather than overwriting unless you tick `overwrite`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
212
 
213
- **`rank` and `refine_iters` are one lever, not two.** With refinement off, a rank sweep is
214
- flat — rank 16 and rank 256 land within noise of each other (0.337 vs 0.340), so the extra
215
- 1.5 GB buys nothing. Raising rank without `refine_iters > 0` is wasted file size; if you want
216
- the cheap build, lower the rank rather than skipping refinement.
217
-
218
- **How much rank you need depends on whether you load a LoRA.** Measured paired over 16 prompts
219
- x 2 seeds, refinement on ([BENCHMARKS.md](BENCHMARKS.md#test-3--paired-lpips-fidelity-with-and-without-a-lora)):
220
 
221
- | | no LoRA | with a LoRA |
222
- |---|---|---|
223
- | best rank | 64 (128 and 256 tie with it) | **256** |
224
- | r256 vs r64 | t=0.39, wins 16/32 — a coin flip | t=2.8-3.5, wins 23-26/32 |
225
- | r64 vs no branch at all | t=4.45, clearly better | t=0.73-1.72, barely better |
226
 
227
- So a rank-64 branch saturates on plain t2i and then largely stops earning its keep once a
228
- LoRA is loaded on top, while rank 256 holds its advantage in both cases. **Rank 256 if you
229
- use LoRAs, rank 64 if you never do.**
 
 
230
 
231
  <details>
232
- <summary>An earlier version of this section claimed LPIPS falls monotonically with rank — that was wrong</summary>
233
-
234
- It read: *"with refinement on, LPIPS falls monotonically with rank across all five ranks
235
- tested (16 → 256), and higher rank helps in 10 of 10 prompts individually."*
236
 
237
- That came from 10 prompts at a **single seed**, compared as marginal per-checkpoint means,
238
- and using `wan21-vae` rather than this repo's own `qwen_image_vae`. Re-measured properly —
239
- paired differences, two seeds, 16 prompts, correct VAE — rank 64, 128 and 256 are statistically
240
- indistinguishable without a LoRA (`r128 vs r64` t=0.01 at 16/32). Monotonicity was an artifact
241
- of the weaker measurement, not a property of the checkpoints.
242
-
243
- Kept visible rather than quietly deleted: the mistake is the same one the `--rank-alloc`
244
- section below documents, and the fix in both cases was a better statistic, not more data.
 
 
 
 
 
245
 
246
  </details>
247
 
248
- ### `--rank-alloc`: where the rank goes, and why it doesn't matter
 
249
 
250
  Rank is uniform across all 224 layers by default, and that is measurably not the efficient
251
- choice. At rank 64, error removed per million branch parameters spans **6.9x** across the eight
252
- projection types — `attn.wk` returns 0.0992 against `mlp.up`'s 0.0143. The cause is GQA: Krea 2
253
- has 12 kv heads against 48 query heads, so `wk`/`wv` are 1536-wide and their branch costs a
254
- third of an MLP branch while absorbing twice as much error.
255
 
256
  `--rank-alloc gqa` spends the same bytes accordingly (`wk` 360, `wv` 256, `wq` 72, `wo` 64,
257
- `gate` 56, MLP 8 — 0.02% smaller than uniform rank 64, same speed at 7.1 s/image). **It
258
- does not improve the images** — measured, not assumed; `uniform` stays the default.
259
-
260
- <details>
261
- <summary>Why it's kept despite not helping (measured LPIPS, what the greedy solve got wrong)</summary>
262
-
263
- LPIPS 0.3523 against uniform's 0.3403, better on 5 of 10 prompts, paired t = +0.55 on 9 df
264
- — no effect in either direction. The greedy solve predicted 6% less weight error and that
265
- did not translate. It does halve the spread across prompts (variance ratio 4.64, F-test
266
- p = 0.032) and improve the worst prompt, 0.4975 → 0.4470, which is worth someone
267
- re-testing at more than 10 images but is not a reason to change the default.
268
 
269
  Kept because the mechanism is sound and the option is cheap to leave in. The transferable
270
- result is negative: weight reconstruction error is a poor predictor of image outcome on
271
- this model — three separate attempts to optimise against it (the refinement objective,
272
- per-block depth allocation, this) have failed to move LPIPS in the predicted direction.
273
-
274
- </details>
275
-
276
- Add `--variant turbo` or `--variant base` to get a checkpoint name you'll still recognise
277
- later (`Krea2-Base-SVDQuant-W4A4-rank64.safetensors`) and to record which release it came
278
- from in the file's metadata. It does not change the quantization: the layer selection keys
279
- off block naming, which Turbo and base share, so both produce the same 224-layer split.
280
-
281
- Only the 224 transformer-block linears (attention + MLP) are quantized; norms,
282
- modulation, the text-fusion stack, and the final layer stay at full precision — they are
283
- small and disproportionately sensitive to quantization noise. Expect a line like
284
- `quantized 224 layers; 206 tensors passed through; 896 tensors created ...` for either
285
- variant — 224 is the whole target set, and a run that reports **0** quantized layers now
286
- fails loudly with the leaf names it actually found instead of writing a useless file.
287
-
288
- An FP8 checkpoint works as a source too — it is reconstructed back to BF16 first. INT8
289
- and W4A4 sources are rejected, since unpacking those needs layer dimensions the file
290
- alone doesn't carry; use the original BF16 (or FP16) release for those.
291
-
292
- #### Low-rank refinement
293
-
294
- For `--format svdq`, a single SVD of `W` is only a first guess: it finds the directions
295
- that are largest in `W`, which are not the same as the directions the quantizer handles
296
- worst. So the branch is refit against the *current* quantization error and requantized,
297
- repeatedly, keeping the best — the same alternating scheme DeepCompressor uses. On Krea 2
298
- Turbo at rank 64 this cuts reconstruction error by **9.4%**, with all 224 layers
299
- improving.
300
-
301
- Because iteration one is exactly the plain single-shot split and the best result is kept,
302
- refining can never do worse. It costs conversion time: roughly **6 minutes** instead of
303
- 40-100 seconds. To skip it:
304
-
305
- ```bash
306
- python quantize_krea2.py model.safetensors --format svdq --rank 64 --refine-iters 0
307
- ```
308
-
309
- <details>
310
- <summary>What the objective is, and the remaining gap to DeepCompressor</summary>
311
-
312
- The default objective here is weight reconstruction error, which needs no calibration data
313
- — it is the true output error under the assumption that the input covariance is identity,
314
- and spreading outliers with the convrot rotation is what makes that assumption reasonable.
315
- `--act-stats` (below) relaxes that assumption to a measured per-channel diagonal; the full
316
- covariance, which is what makes DeepCompressor's conversions take hours, is still not
317
- modelled.
318
 
319
  </details>
320
 
321
- #### Activation-aware branch (`--act-stats`)
322
-
323
- Identity input covariance is an approximation, and a measurable one. Capture the real
324
- per-input-channel activation RMS on a calibration pass, then fit the branch against
325
- `||(W - (Q + L1 L2)) * d||_F` instead — the branch spends its rank where the activations
326
- actually are. `d` is normalised to mean 1 and floor-clamped at 0.05 so a near-dead channel
327
- cannot dominate the fit.
328
-
329
- **This costs nothing at inference.** Same shapes, same format, same kernels — only the
330
- values inside `svdq_l1`/`svdq_l2` change.
331
-
332
- Two nodes capture the statistics (they hook all 224 branched linears on a BF16 model):
333
-
334
- 1. **Krea2 SVDQuant Capture Start** — between your model loader and the sampler.
335
- 2. **Krea2 SVDQuant Capture Save** — takes the sampler's `LATENT` so it runs after
336
- denoising; set `keep_capturing` on every prompt but the last so several prompts
337
- accumulate into one file. Writes to `models/krea2_act_stats/`.
338
-
339
- Use prompts that are *not* the ones you plan to judge the checkpoint with, then:
340
-
341
- ```bash
342
- python quantize_krea2.py model.safetensors --format svdq --rank 256 \
343
- --act-stats krea2_act_stats.safetensors
344
- ```
345
-
346
- The output filename gains an `-actaware` tag and the file records which stats built it in
347
- `krea2_svdquant_act_stats`. Missing stats for any branched layer is a hard error rather
348
- than a silent fallback. Measured effect: without a LoRA, LPIPS to BF16 drops 0.3378 to
349
- **0.2825** (t=4.68, 27/32 prompts), beating every other checkpoint in the sweep; with a
350
- LoRA it is neutral across four adapters. See
351
- [Test 4 in BENCHMARKS.md](BENCHMARKS.md#test-4--activation-aware-low-rank-objective).
352
-
353
- ## Benchmarks
354
-
355
- > **Community rank sweep + krea2edit LoRA test:** a full rank-16-through-256 comparison
356
- > (refined and non-refined) across 10 stress-test prompts, plus the same sweep run through
357
- > the [Krea 2 Identity Edit LoRA](https://github.com/lbouaraba/comfyui-krea2edit) on 3 real
358
- > photos (Paris/horse/night edits). Grids, prompts, and speed+quality tables:
359
- > [BENCHMARKS.md](BENCHMARKS.md).
360
-
361
- All numbers measured on an **RTX 3090 24GB**, 1024x1024, 8-step Euler/simple sampling,
362
- `cfg=1.0` (Krea 2 Turbo distilled schedule), from the same BF16 source checkpoint, on a
363
- **cu130 torch build** (see [Troubleshooting](#troubleshooting) — on an older build every
364
- one of these numbers gets worse, and the ordering inverts).
365
-
366
- These are Turbo numbers. The base model at ~50 steps with CFG does roughly 12x the
367
- sampling work per image, so the absolute seconds do not transfer; the *ratios* between
368
- formats do, since they come from the same per-layer kernels.
369
-
370
- ### End to end, per image
371
-
372
- Two numbers matter and are easy to conflate: **first run after switching checkpoints**
373
- (pays disk-to-VRAM load time, ~9-15s here) and **warm run** (model already resident,
374
- what you get generating multiple images back to back). ComfyUI's own progress bar
375
- ("`8/8 [00:07<00:00, 1.09it/s]`") only covers the KSampler loop; "`Prompt executed in
376
- X seconds`" is CLIP load/encode + model staging + sampling + VAE decode + save combined
377
- — the two numbers can differ by 2x on a cold run.
378
-
379
- | checkpoint | size | first run (cold) | warm run | vs. BF16 |
380
- |---|---|---|---|---|
381
- | BF16 (unquantized reference) | 24.48 GB | 25.3 s | 21.3 s | 1.0x |
382
- | FP8 e4m3, scaled (emulated on Ampere) | 12.24 GB | 22.2 s | 19.2 s | 1.1x |
383
- | INT8 tensorwise + convrot (not in this upload) | 13.16 GB | 13.3 s | 10.4 s | 2.0x |
384
- | **W4A4 + convrot, no low-rank branch** | 7.50 GB | 10.3 s | **10.1 s** | 2.1x |
385
- | **W4A4 + SVDQuant low-rank, rank 16/64/128** | 7.6-8.3 GB | ~19.3 s | **10.1-10.2 s** | 2.1x |
386
-
387
- Rank does not measurably change warm speed — CLIP text-encode (Qwen3-VL 4B) and VAE
388
- decode overhead dominate a single 1024x1024/8-step/batch-1 image and mask the low-rank
389
- branch's cost. Add a **TorchCompileModel** node (backend `inductor`) after the loader
390
- for a further ~20-25% cut on the sampling portion specifically (see profiling below);
391
- that number does not show up in the table above since it isn't included in this
392
- upload's default workflow.
393
-
394
- **FP8 is not faster than BF16 on Ampere** — there are no FP8 tensor cores on this
395
- architecture, so ComfyUI casts to bf16 and calls cuBLAS. It's included here because it's
396
- the most common recommendation online for "quantizing Krea 2," and the numbers show why
397
- that advice doesn't hold on 30-series cards. **INT8 is the fastest *accurate* option**
398
- measured, but is not part of this upload (available via `quantize_krea2.py --format
399
- int8` on your own BF16 checkpoint).
400
-
401
- ### Per-layer accuracy (cosine similarity / relative error vs. BF16 original)
402
-
403
- Measured on real captured activations from a Krea 2 Turbo forward pass (not synthetic
404
- noise), across representative attention and MLP layers:
405
-
406
- | format | cosine | relative error | per-layer time |
407
- |---|---|---|---|
408
- | bf16 (reference) | 1.00000 | - | 1.22 - 3.48 ms |
409
- | **int8 + convrot (Hadamard rotation)** | 0.99999 | 0.35 - 0.63% | 0.39 - 1.09 ms |
410
- | int8 per-channel (no rotation) | 0.99993 | 0.45 - 1.47% | 0.35 - 1.01 ms |
411
- | fp8 e4m3, scaled | 0.99996 | 0.39 - 1.28% | 1.95 - 5.14 ms |
412
- | nvfp4 | 0.99968 | 0.74 - 4.00% | 1.49 - 3.93 ms |
413
- | w4a4 + convrot, rank-64 low-rank branch | 0.99933 - 0.99997 | 0.72 - 8.38% | 0.39 - 1.09 ms |
414
- | w4a4 + convrot, no low-rank branch | 0.99569 - 0.99908 | 1.49 - 9.29% | 0.23 - 0.67 ms |
415
-
416
- The Hadamard rotation used by `convrot` already does most of what SVDQuant's low-rank
417
- branch does (both are outlier-mitigation strategies), so on top of `convrot_w4a4` the
418
- low-rank branch buys noticeably less than in the original SVDQuant paper — it roughly
419
- halves the error rather than eliminating it. **`int8` is the more accurate choice if
420
- quality matters more than raw speed; `svdq` is the faster, smaller choice.**
421
-
422
- ### Rank sweep
423
-
424
- `--format svdq --rank N` was run for N = 16, 32, 64, 128, 256. Checkpoint sizes:
425
-
426
- | rank | size |
427
- |---|---|
428
- | 16 | 7.60 GB |
429
- | 32 | 7.70 GB |
430
- | 64 | 7.90 GB |
431
- | 128 | 8.30 GB |
432
- | 256 | 9.10 GB |
433
 
434
- This is an experimental project — the rank sweep is deliberately shipped so people can
435
- try the tradeoff themselves rather than take one number on faith. If you benchmark other
436
- ranks or find a case where one clearly wins, open a discussion on this repo.
437
 
438
- To measure it yourself against a BF16 reference: generate matching prompts across
439
- checkpoints into one output folder, then `python tools/pixel_metrics.py --dir
440
- <output-dir>` — it pairs files by name (`bench_<checkpoint>_<prompt>_00001_.png`),
441
- reports LPIPS/PSNR/SSIM per checkpoint, and `--noise-floor` gives you the reseed
442
- distance to judge drift against (see the tool's own docstring for details).
443
-
444
- ### Where the remaining time goes (profiled, `svdq r64`, single denoise step, 175.7 ms)
445
-
446
- | component | share |
447
- |---|---|
448
- | W4A4 GEMM (native `comfy_kitchen` cutlass kernel) | 37% |
449
- | elementwise / norm / RoPE / dtype casts | 34% |
450
- | attention (cuDNN flash) | 9% |
451
- | low-rank branch (2 bf16 GEMMs per quantized layer) | 9% |
452
- | W4A4 activation quantization | 8% |
453
-
454
- A third of a step is small elementwise kernels, which is why `torch.compile` (backend
455
- `inductor`) helps: add a **TorchCompileModel** node after the loader. Stock ComfyUI
456
- quantized tensors normally break `torch.compile` (Dynamo can't trace into the
457
- `comfy_kitchen` kernel); the W4A4 loader here works around that by marking those calls as
458
- graph breaks so inductor still fuses everything around them. First run after loading pays
459
- ~50s of compilation; subsequent runs are warm.
460
 
461
  ## LoRA
462
 
463
  Use **Krea2 SVDQuant LoRA Loader**, not the stock `LoraLoaderModelOnly`. The stock loader
464
  patches `weight += down @ up`, but on these models `.weight` is a `QuantizedTensor`, so
465
  applying it that way means dequantize → add → requantize: the branch's whole point, keeping
466
- the 4-bit weight untouched, is lost, and the LoRA delta is re-quantized to 4 bits along
467
- with it.
 
 
 
 
 
 
 
 
 
 
468
 
469
  <details>
470
- <summary>Does the stock loader silently skip the quantized layers? Measured: no longer</summary>
471
 
472
- This was documented here as "it matches only the ~32 non-quantized layers out of ~256 and
473
- misses all 224 transformer-block layers, with no error." Re-tested against ComfyUI **0.28.0**
474
- (commit `f966a2b3`) on both `W4A4-convrot` and `SVDQuant-W4A4-rank256`, by patching the same
475
- checkpoint at LoRA strength 1.0 and 4.0 and diffing every weight — a layer that was skipped
476
- would be bit-identical between the two:
477
 
478
  ```
479
  key map offers 224/224 of the quantized layers
@@ -481,208 +334,36 @@ load_lora produced 256 patches; add_patches accepted 256 keys
481
  strength 1.0 vs 4.0: quantized 224/224 differ, plain 32/32 differ
482
  ```
483
 
484
- All 224 do move, so the coverage claim does not hold on current ComfyUI. We have not
485
- bisected when that changed. The reason to use this repo's node is the requantization above,
486
- not missing coverage.
487
 
488
  </details>
489
 
490
- The included loader instead attaches the LoRA as a parallel low-rank branch, which is
491
- mathematically identical for a linear layer (`(W + BA)x == Wx + B(Ax)`) and leaves the
492
- quantized weight untouched. Chain multiple nodes to stack LoRAs. Check the console — it
493
- reports what it matched, e.g. `224 quantized layers, 32 normal layers`.
494
-
495
- The branch is installed as a ComfyUI *object patch*, so it belongs to that one model
496
- branch: two LoRA loader nodes hanging off the same checkpoint loader no longer contaminate
497
- each other, and nothing survives past the sampling run. A stack of N LoRAs on one layer is
498
- folded into a single pair of GEMMs rather than N pairs, and LoRA files are cached by
499
- mtime, so changing a strength no longer re-reads them from disk.
500
-
501
  ## Troubleshooting
502
 
503
- Start with the **Krea2 SVDQuant Diagnostics** node (drop it between the loader and the
504
- KSampler, `mode=dispatch`), or from a terminal:
 
 
505
 
506
- ```bash
507
- python diagnose.py --no-load
508
- ```
509
-
510
- ### "It's slower than FP8 / slower than BF16"
511
-
512
- Almost always this: **ComfyUI disables `comfy_kitchen`'s CUDA backend when torch was built
513
- against CUDA < 13**, in `comfy/quant_ops.py`:
514
-
515
- ```python
516
- if cuda_version < (13,):
517
- ck.registry.disable("cuda")
518
- logging.warning("WARNING: You need pytorch with cu130 or higher to use optimized CUDA operations.")
519
- ```
520
-
521
- `convrot_w4a4_linear` resolves its backend per call, so with `cuda` disabled it falls
522
- through to the eager implementation — which unpacks int4 to bf16 in Python and runs an
523
- ordinary matmul. That is strictly slower than just running bf16, and the more aggressive
524
- the format the worse it gets. The tell is that the ordering **inverts**: fp8 fastest, int8
525
- middling, w4a4/svdq slowest, the exact opposite of the benchmark table above.
526
-
527
- Check with:
528
 
529
  ```bash
530
- python -c "import torch; print(torch.__version__, torch.version.cuda)"
531
  ```
532
 
533
- If that prints anything below `13.0`, install a cu130+ torch build. The loader now prints
534
- the resolved backend on every load and shouts if it isn't `cuda`.
535
-
536
- ### "No speedup at all on my RTX 20-series" (Turing)
537
-
538
- Different problem, and this one has no fix on our side. The backend resolves to `cuda`, the
539
- kernel runs, nothing is misconfigured — int4 is simply not much faster than int8 on Turing:
540
-
541
- - The instruction the fast path is built around, `mma.m16n8k64` (s4×s4→s32), is **Ampere and
542
- newer**. `comfy_kitchen`'s default convrot path targets `Sm89` and gates that instruction
543
- behind `__CUDA_ARCH__ >= 800`.
544
- - SM 7.5 is served by separate kernels (`turing_int4.cu`, `turing_int8.cu`) built on a
545
- smaller MMA tile — `GemmShape<8, 8, 32>` versus the default int8 path's
546
- `GemmShape<16, 8, 32>` — and without `cp.async` prefetch, which is also SM80+.
547
-
548
- Both formats run weaker kernels there, so switching to int8 does not dodge it either.
549
- Rebuilding `comfy_kitchen` yourself will not change it: the SM75 kernels are what you get.
550
-
551
- The int4 checkpoint is still worth downloading on these cards for the **smaller VRAM
552
- footprint** — just do not expect the speed column of the benchmark table.
553
-
554
- The diagnostics node and `diagnose.py --no-load` now say this explicitly when they detect a
555
- compute-capability-7.x device, so you can tell "my setup is broken" apart from "my card
556
- predates the instruction". Those kernels live in
557
- [comfy-kitchen](https://github.com/Comfy-Org/comfy-kitchen), not here — this repo ships no
558
- CUDA build pipeline, and we have no Turing hardware to validate a replacement against, so
559
- the honest answer is to report it upstream rather than have us ship an untested kernel.
560
-
561
- ### "Pin error." in the console
562
-
563
- Harmless. It comes from ComfyUI core (`comfy/model_management.py`), not from this repo,
564
- and means a weight could not be page-locked so a normal (unpinned) host copy was used
565
- instead. Results are identical; you lose a little load/offload bandwidth. Windows caps
566
- locked pages aggressively — `MAX_PINNED_MEMORY` there is 40% of system RAM — so it fires
567
- routinely with a model this size. It is not specific to `svdq`; INT8 checkpoints trigger it
568
- too. The diagnostics node prints your pinned-memory budget under `mode=env`.
569
-
570
- ### Out of memory on a small card (and int8 works fine)
571
-
572
- Fixed. The low-rank factors were attached as non-persistent buffers, which ComfyUI's
573
- `module_size()` — the basis of every VRAM decision, including the lowvram split — could
574
- not see, while `.to(device)` moved them anyway. Worse, the old branch cached its own
575
- device move back onto the module, so once ComfyUI offloaded a layer the factors quietly
576
- came back to the GPU and stayed there, outside all accounting. About 645 MB at rank 64,
577
- which is the difference between fitting and not on an 8 GB card. INT8 checkpoints carry no
578
- branch, so they were never affected.
579
-
580
- They are now published into `state_dict()` under their own `svdq_l1` / `svdq_l2` keys and
581
- staged per call via `comfy.model_management.cast_to`, so they are budgeted and offloaded
582
- like any other weight. `mode=env` on the diagnostics node reports the factor devices — under
583
- lowvram they should sit on `cpu` between steps, not `cuda`.
584
-
585
- One gap remains and it is upstream, not here: `QuantizedTensor.nbytes` reports only the
586
- packed weight, so the W4A4 `weight_scale` (~3 MB/layer) is still invisible to ComfyUI's
587
- accounting for *any* w4a4 checkpoint, branch or no branch.
588
-
589
- ### A re-saved checkpoint logs "left over keys in diffusion model"
590
-
591
- Expected. Saving the model out of ComfyUI now includes the `svdq_l1` / `svdq_l2` keys, which
592
- is what lets the file round-trip back into this loader — but the stock `UNETLoader` doesn't
593
- know them and says so. Harmless.
594
-
595
- ## Accuracy vs. the base model, qualitatively
596
-
597
- Same seed and prompt against the BF16 reference produces the same composition throughout
598
- this quantization sweep — differences are in surface detail, not structure. Two stress
599
- tests, same seed across all checkpoints:
600
-
601
- **Multi-line small text** (a chalkboard menu board with 3 lines of prices) is the harder
602
- case and is where the checkpoints separate:
603
-
604
- | checkpoint | result |
605
- |---|---|
606
- | BF16, FP8 | correct |
607
- | INT8 + convrot (not in this upload) | correct |
608
- | W4A4, no low-rank | one digit/word duplicated |
609
- | SVDQuant rank 16 | correct, but a nearby sign's color shifted |
610
- | SVDQuant rank 32 | one line duplicated |
611
- | SVDQuant rank 64 | one digit wrong |
612
- | SVDQuant rank 128 | correct, closest of the SVDQuant series to BF16 |
613
- | SVDQuant rank 256 | two digits swapped |
614
-
615
- Rank does not improve monotonically in a single-seed test like this — it reflects
616
- noise sensitivity at that particular seed, not a reliable ranking. **Rank 128 was the
617
- best performer here**, which is part of why it's included in this upload alongside 16
618
- (smallest) and 64 (a common middle ground).
619
-
620
- **Large, short text on a curved surface** (2 words on a hand-held cup) was solved by
621
- every checkpoint including W4A4 with no low-rank branch — legible text and object
622
- counts held up across the board; only fine composition details (a person's pose, an
623
- extra utensil) varied, which is normal sampling variance, not a quantization artifact.
624
-
625
- **Takeaway:** if your use case is large signage-style text or no text, any checkpoint in
626
- this repo works. If you're rendering dense small text (menus, labels, documents), the
627
- low-rank branch helps but doesn't fully close the gap to INT8/FP8 — reach for
628
- `quantize_krea2.py --format int8` if that's your primary use case.
629
-
630
- ## Example comparisons
631
-
632
- Same seed, same prompt, across all 9 checkpoints tested during development (only 4 are
633
- included in this upload; BF16/FP8/INT8/rank-32/rank-256 are shown for reference since
634
- they're discussed in the benchmarks above).
635
-
636
- ### Hard case: dense multi-line text
637
-
638
- A rainy neon diner sign with a 3-line handwritten chalkboard menu. This is where the
639
- checkpoints visibly separate — see the accuracy table above for the full breakdown.
640
-
641
- | BF16 (reference) | INT8 + convrot (not in this upload) |
642
- |---|---|
643
- | ![bf16](examples/neon_sign_text_test/compare_bf16_reference_00001_.png) | ![int8](examples/neon_sign_text_test/compare_int8_convrot_00001_.png) |
644
-
645
- | W4A4, no low-rank branch | SVDQuant rank 128 (best of the included ranks) |
646
- |---|---|
647
- | ![w4a4](examples/neon_sign_text_test/compare_w4a4_convrot_nolowrank_00001_.png) | ![r128](examples/neon_sign_text_test/compare_svdq_r128_00001_.png) |
648
-
649
- <details>
650
- <summary>All 9 variants for this prompt (BF16, FP8, INT8, W4A4, rank 16/32/64/128/256)</summary>
651
-
652
- [`examples/neon_sign_text_test/`](examples/neon_sign_text_test) — file names match the
653
- config names used in the benchmark tables.
654
-
655
- </details>
656
-
657
- ### Easy case: large text, two subjects, low angle
658
-
659
- Two people in varied clothing, a low camera angle, and 2 words of large curved text on
660
- a held object. Every checkpoint renders the text correctly here — only fine composition
661
- details vary, which is normal sampling variance, not a quantization artifact.
662
-
663
- | BF16 (reference) | SVDQuant rank 64 |
664
- |---|---|
665
- | ![bf16](examples/ice_cream_multisubject_test/compare_bf16_reference_00001_.png) | ![r64](examples/ice_cream_multisubject_test/compare_svdq_r64_00001_.png) |
666
-
667
- <details>
668
- <summary>All 9 variants for this prompt</summary>
669
-
670
- [`examples/ice_cream_multisubject_test/`](examples/ice_cream_multisubject_test)
671
-
672
- </details>
673
-
674
  ## Attribution
675
 
676
- Krea 2 is developed by [Krea AI](https://www.krea.ai). This repository contains
677
- derivative, modified weights and is licensed under the same [Krea 2 Community License
678
  Agreement](https://www.krea.ai/krea-2-licensing) as the base model — see
679
  [LICENSE.md](LICENSE.md) for the full terms and how they apply to the code here. It is a
680
  community contribution, not an official Krea product, and is not endorsed by Krea.
681
 
682
  The quantization kernels used here (`int8_tensorwise`, `convrot_w4a4`) are native to
683
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI)'s `comfy_kitchen` backend. The
684
- low-rank branch construction follows the method described in the [SVDQuant
685
  paper](https://arxiv.org/abs/2411.05007) (Li et al., MIT Han Lab), implemented here from
686
- scratch on top of ComfyUI's native kernel rather than the paper's own Nunchaku engine,
687
- which has no
688
- Krea 2 architecture support.
 
21
 
22
  # Krea 2 SVDQuant W4A4 for ComfyUI
23
 
24
+ Quantized **Krea 2** checkpoints for ComfyUI — about **2x faster** and **a third the size**
25
+ of the usual FP8 version, with no calibration dataset needed, on both **Krea 2 Turbo**
26
+ (distilled, 8 steps) and the **base** release. This repo holds the custom nodes and the
27
+ `quantize_krea2.py` conversion script; the `.safetensors` files (7.5-9.1 GB each) live on
28
+ Hugging Face.
29
+
30
+ Works on **any modern NVIDIA GPU** — INT8/W4A4 tensor cores go back to Turing (RTX 20-series).
31
+ Benchmarked on an RTX 3090 (Ampere), the case most Krea 2 quantization writeups skip, since
32
+ that generation has no FP8 or NVFP4 tensor cores at all. Everything here was built from
33
+ scratch against ComfyUI's own quantization backend and is reproducible: `quantize_krea2.py`
34
+ regenerates any checkpoint from a BF16 source in 40-100 seconds, or ~6 minutes with the
35
+ default low-rank refinement.
 
36
 
37
  > **Requires a cu130 (CUDA 13) or newer PyTorch build.** ComfyUI disables `comfy_kitchen`'s
38
+ > CUDA backend on older torch builds, which silently drops every quantized checkpoint onto a
39
+ > pure-Python fallback that is *slower than bf16*. If these checkpoints are slower than FP8
40
+ > for you, this is almost certainly why — see
41
+ > [TROUBLESHOOTING.md](TROUBLESHOOTING.md#its-slower-than-fp8--slower-than-bf16).
42
 
43
+ This is a community-produced modification of Krea 2, not an official Krea product — license
44
+ and attribution are at the [bottom of this page](#attribution). Read them before using these
45
+ weights, in particular the revenue threshold on commercial use.
46
+
47
+ > **Moved 2026-07-27.** The checkpoints now live under `checkpoints/`, with superseded
48
+ > builds in `checkpoints/legacy/`. Direct links to the old repository-root paths will 404 --
49
+ > the root had ten loose 8 GB files with no indication which one to take.
50
+
51
+ ## Which checkpoint to download
52
+
53
+ Everything lives under `checkpoints/` on Hugging Face.
54
+
55
+ | file | rank | size | when |
56
+ |---|---|---|---|
57
+ | **`Krea2-Turbo-SVDQuant-W4A4-rank256-actaware.safetensors`** | 256 | 9.10 GB | **Start here.** Closest to BF16 of anything measured, same speed as any other rank-256 build |
58
+ | `Krea2-Turbo-SVDQuant-W4A4-rank256.safetensors` | 256 | 9.10 GB | The same without the activation weighting |
59
+ | `Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors` | 64 | 7.90 GB | 1.2 GB smaller, and identical to rank 256 *if you never load a LoRA* |
60
+ | `Krea2-Turbo-W4A4-noLowRank.safetensors` | — | 7.50 GB | Smallest and ~9% faster per step; loads with the stock **UNETLoader** |
61
+ | `checkpoints/legacy/` | 16, 128 | — | Superseded, kept because BENCHMARKS.md cites measurements from them |
62
+
63
+ The `actaware` file is the same format, size and speed as plain rank 256 — the low-rank branch
64
+ was just fitted against measured per-channel activation energy instead of assuming it is
65
+ uniform ([`--act-stats`](#activation-aware-branch---act-stats)). Without a LoRA that moves
66
+ LPIPS-to-BF16 from 0.3378 to **0.2825** (t=4.68 over 32 paired cells); with a LoRA it measures
67
+ no worse. There is no case where the plain build is the better pick. The calibration file it
68
+ was built from is in `calibration/`, so the build is reproducible.
69
+
70
+ **Rank only matters if you load LoRAs.** Without one, ranks 64 / 128 / 256 are statistically
71
+ indistinguishable. With one, rank 256 wins clearly and rank 64 loses most of its advantage
72
+ over having no branch at all
73
+ ([Test 3](BENCHMARKS.md#test-3--paired-lpips-fidelity-with-and-without-a-lora)).
74
+
75
+ Every file records how it was built in its safetensors metadata, so you can check what you
76
+ downloaded rather than trusting this table:
77
+
78
+ ```python
79
+ from safetensors import safe_open
80
+ with safe_open("Krea2-Turbo-SVDQuant-W4A4-rank256-actaware.safetensors", framework="pt") as f:
81
+ print(f.metadata())
82
+ ```
83
+
84
+ > The test that matters is `f.metadata() is None`, not the date: an early batch (published
85
+ > before 2026-07-26) was built without refinement and carries no metadata at all. If yours
86
+ > returns `None`, re-download — the whole rank ladder is flat without refinement.
87
 
88
  ## Quick start
89
 
90
+ 1. **Install the nodes.** In your ComfyUI folder:
91
  ```bash
92
  git clone https://github.com/alperktt/Krea-2-SVDQuant-ComfyUI custom_nodes/krea2-svdquant
93
  ```
94
+ (No git? Download the repo as a ZIP and unzip it into `ComfyUI/custom_nodes/`.) Restart
95
+ ComfyUI.
96
 
97
+ 2. **Download one checkpoint** from `checkpoints/` on Hugging Face into
 
98
  `ComfyUI/models/diffusion_models/`.
99
 
100
+ 3. **Download the text encoder and VAE** — the same ones any Krea 2 Turbo workflow needs:
 
101
  - [`qwen3vl_4b_fp8_scaled.safetensors`](https://huggingface.co/Comfy-Org/Krea-2/resolve/main/text_encoders/qwen3vl_4b_fp8_scaled.safetensors) → `ComfyUI/models/text_encoders/`
102
  - [`qwen_image_vae.safetensors`](https://huggingface.co/Comfy-Org/Krea-2/resolve/main/vae/qwen_image_vae.safetensors) → `ComfyUI/models/vae/`
103
 
104
+ 4. **Drag in a workflow** from `workflows/`. Each opens with a **READ ME FIRST** note covering
105
+ the settings that matter.
 
 
106
  - `krea2_turbo_svdquant_w4a4_t2i.json` → **Turbo**: 8 steps, `cfg 1.0`, zeroed negative.
107
+ - `krea2_base_svdquant_w4a4_t2i.json` → **base**: 50 steps, `cfg 3.5`, real negative prompt.
 
 
 
 
108
 
109
+ Any `SVDQuant-W4A4-rank*` file needs the **Krea2 SVDQuant W4A4 Loader** node from this repo;
110
+ `noLowRank` uses the stock **UNETLoader**. The `*_api.json` files are for POSTing to
111
+ `/prompt` from a script — don't drag those in, they carry no layout.
112
 
113
+ ## See it
 
114
 
115
+ Full comparison sheets — 16 prompts x 7 checkpoints x 2 seeds, with and without a LoRA — are
116
+ in **[GALLERY.md](GALLERY.md)**. Three of them here. Columns run BF16 reference, no branch,
117
+ then rising rank, ending with the activation-aware build; the two rows are two seeds, so
118
+ anything that changes between rows is sampling variance rather than the checkpoint.
119
 
120
+ Dense small text, the hardest case in the set:
 
 
 
121
 
122
+ ![01_dense_text](examples/fidelity_sheets/sheet_base_01_dense_text.jpg)
 
 
123
 
124
+ A portrait — skin texture and catchlights, where quantization is most visible to a viewer:
 
 
 
 
 
125
 
126
+ ![11_portrait_woman](examples/fidelity_sheets/sheet_base_11_portrait_woman.jpg)
 
 
127
 
128
+ The same portrait prompt with a realism LoRA loaded on top, BF16 column included:
129
 
130
+ ![11_portrait_woman_lora](examples/fidelity_sheets/sheet_lora2_11_portrait_woman.jpg)
 
 
 
 
 
131
 
132
+ ## Why this exists
 
 
133
 
134
+ The usual advice for making Krea 2 cheaper is FP8. That only pays off if your GPU has FP8
135
+ tensor cores — Ada, Hopper, Blackwell. On anything older, FP8 weights get cast back to bf16
136
+ before the matmul, so you save VRAM and gain no speed; on an RTX 3090, FP8 measured *slower*
137
+ than plain bf16. The same trap catches weight-only 4-bit (W4A16): if activations stay 16-bit,
138
+ the matmul still runs at bf16 speed.
139
 
140
+ What moves the needle is quantizing **activations too**, on hardware that has the units for
141
+ it — and INT8/W4A4 tensor cores go back to Turing, far wider support than FP8. So this repo
142
+ quantizes Krea 2 into formats ComfyUI already ships native kernels for (`int8_tensorwise` and
143
+ `convrot_w4a4` in `comfy_kitchen`) and adds an SVDQuant-style low-rank correction branch on
144
+ top of the native W4A4 kernel to claw back accuracy at 4 bits.
145
 
146
+ No calibration dataset is required: the `convrot` group-wise Hadamard rotation spreads
147
+ outliers analytically, and the kernel quantizes activations at run time. `--act-stats` can use
148
+ a calibration pass if you have one, but the default path needs nothing.
 
 
149
 
150
+ ## The nodes
 
 
151
 
152
+ Installing this adds seven nodes, all under **Krea2/SVDQuant**:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
153
 
154
  | node | what it is for |
155
  |---|---|
156
  | **Krea2 SVDQuant W4A4 Loader** | Loads an `svdq` checkpoint. Its `status` output names the kernel that will actually run — read it first if generation is slow |
157
+ | **Krea2 SVDQuant LoRA Loader** | LoRAs and LoKrs on quantized blocks — see [LoRA](#lora) |
158
+ | **Krea2 SVDQuant Quantize** | Builds a quantized checkpoint without leaving ComfyUI. Blocks the queue (54 s to ~6 min) and writes ~8 GB |
159
  | **Krea2 SVDQuant Diagnostics** | Backend dispatch, memory accounting, per-layer timings, profiler table |
160
  | **Krea2 SVDQuant Env Check** | Is the int4 kernel available at all? Needs no model, so you can ask before downloading 8 GB |
161
+ | **Krea2 SVDQuant Capture Start** / **Capture Save** | Record activation statistics for an activation-aware build |
162
 
163
+ <details>
164
+ <summary>Which file is which</summary>
 
165
 
166
+ | file | what it is |
167
+ |---|---|
168
+ | `quantize_krea2.py` | Converts a BF16 Krea 2 checkpoint to int8, w4a4, or w4a4 + low-rank (svdq). Also the CLI |
169
+ | `svdquant_w4a4.py` | The **W4A4 Loader** node — loads `--format svdq` checkpoints (self-contained, no base model needed) |
170
+ | `svdquant_lora.py` | The **LoRA Loader** node — applies LoRAs as a parallel branch so the 4-bit weight is never dequantized |
171
+ | `svdquant_quantize.py` | The **Quantize** node — the quantizer above, from inside ComfyUI |
172
+ | `svdquant_capture.py` | The **Capture Start/Save** nodes — record per-channel activation RMS for `--act-stats` |
173
+ | `svdquant_diag.py` | The **Diagnostics** and **Env Check** nodes |
174
+ | `diagnose.py` | The same reports from a terminal, without starting ComfyUI (`--mode all` for everything) |
175
+ | `tools/fidelity_bench.py` | Paired multi-seed multi-LoRA LPIPS harness. Every fidelity claim in this repo comes from it |
176
+ | `tools/contact_sheet.py` | Builds the contact sheets in [GALLERY.md](GALLERY.md) — for looking at, not scoring |
177
+ | `tools/pixel_metrics.py` | The shared LPIPS/PSNR/SSIM implementation `fidelity_bench` imports. Not a CLI |
178
+ | `tools/build_workflows.py` | Regenerates `workflows/*.json`, both dialects. Edit this, not the JSON |
179
+
180
+ ComfyUI has two JSON dialects and mixing them up is a bad first five minutes: the plain names
181
+ are **UI format** (drag into the canvas — layout, titles, the READ ME note), and `*_api.json`
182
+ is **API format** (POST to `/prompt`, no layout). Both come out of `build_workflows.py`.
183
 
184
+ </details>
185
 
186
+ ## Build your own checkpoint
187
 
188
+ From a terminal:
189
 
190
  ```bash
191
  cd ComfyUI/custom_nodes/krea2-svdquant
192
+ python quantize_krea2.py /path/to/krea2_bf16.safetensors --format svdq --rank 256 \
193
+ --act-stats krea2_act_stats.safetensors
 
194
  ```
195
 
196
+ `--format int8` and `--format w4a4` also work (`int8` is the most faithful option and still
197
+ ~2x FP8 on Ampere; `w4a4` is the fastest and smallest). Add `--variant turbo` or
198
+ `--variant base` for a filename you will recognise later and to record the source release in
199
+ the metadata — it does not change the quantization, since layer selection keys off block
200
+ naming that Turbo and base share.
201
+
202
+ Or use the **Krea2 SVDQuant Quantize** node, which calls the same code. Three things first: it
203
+ blocks the queue for the whole run, it unloads any resident model to take the GPU, and it
204
+ writes ~8 GB (refusing rather than overwriting unless you tick `overwrite`).
205
+
206
+ **`rank` and `refine_iters` are one lever, not two.** With refinement off a rank sweep is flat
207
+ — rank 16 and rank 256 land within noise of each other — so raising rank without
208
+ `refine_iters > 0` is wasted file size. If you want a cheap build, lower the rank instead of
209
+ skipping refinement.
210
+
211
+ Only the 224 transformer-block linears (attention + MLP) are quantized; norms, modulation, the
212
+ text-fusion stack and the final layer stay at full precision, being small and
213
+ disproportionately sensitive. Expect `quantized 224 layers; 206 tensors passed through; ...`
214
+ — a run reporting **0** fails loudly with the leaf names it actually found rather than writing
215
+ a useless file. An FP8 source works too (it is reconstructed to BF16 first); INT8 and W4A4
216
+ sources are rejected, because unpacking those needs layer dimensions the file alone lacks.
217
+
218
+ ### Activation-aware branch (`--act-stats`)
219
+
220
+ The branch is normally fitted by minimising `||W - (Q + L1 L2)||`, which treats every input
221
+ channel as carrying the same activation energy. It does not. `--act-stats` weights the
222
+ objective by measured per-input-channel activation RMS instead, so the branch spends its rank
223
+ where the activations actually are. `d` is normalised to mean 1 and floor-clamped at 0.05 so a
224
+ near-dead channel cannot dominate the fit.
225
+
226
+ **This costs nothing at inference** — same shapes, same format, same kernels; only the values
227
+ inside `svdq_l1`/`svdq_l2` change. It is the largest fidelity gain measured in this repo
228
+ ([Test 4](BENCHMARKS.md#test-4--activation-aware-low-rank-objective)), so it is worth the
229
+ extra calibration pass whether or not you use LoRAs.
230
 
231
+ Two nodes capture the statistics (they hook all 224 branched linears on a BF16 model):
 
 
 
 
 
 
232
 
233
+ 1. **Krea2 SVDQuant Capture Start** — between your model loader and the sampler.
234
+ 2. **Krea2 SVDQuant Capture Save** — takes the sampler's `LATENT`, so it runs after denoising.
235
+ Leave `keep_capturing` on for every prompt but the last, and several prompts accumulate
236
+ into one file under `ComfyUI/output/`.
 
237
 
238
+ Use prompts that are *not* the ones you plan to judge the checkpoint with, then pass the file
239
+ to `--act-stats` (or to the Quantize node's `act_stats` input). The output filename gains an
240
+ `-actaware` tag and records which statistics built it in `krea2_svdquant_act_stats`. Stats
241
+ missing for any branched layer is a hard error, checked before any GPU work rather than
242
+ silently falling back.
243
 
244
  <details>
245
+ <summary>Low-rank refinement, and what the objective actually is</summary>
 
 
 
246
 
247
+ For `--format svdq`, a single SVD of `W` is only a first guess: it finds the directions
248
+ largest in `W`, which are not the directions the quantizer handles worst. So the branch is
249
+ refit against the *current* quantization error and requantized, repeatedly, keeping the best —
250
+ the alternating scheme DeepCompressor uses. On Krea 2 Turbo at rank 64 this cuts
251
+ reconstruction error by **9.4%**, with all 224 layers improving. Because iteration one is
252
+ exactly the plain single-shot split and the best result is kept, refining can never do worse.
253
+ It costs conversion time: ~6 minutes instead of 40-100 seconds. `--refine-iters 0` skips it.
254
+
255
+ The default objective is weight reconstruction error, which needs no calibration data — it is
256
+ the true output error under the assumption that the input covariance is identity, and
257
+ spreading outliers with the convrot rotation is what makes that assumption reasonable.
258
+ `--act-stats` relaxes it to a measured per-channel diagonal. The full covariance, which is
259
+ what makes DeepCompressor's conversions take hours, is still not modelled.
260
 
261
  </details>
262
 
263
+ <details>
264
+ <summary><code>--rank-alloc</code>: where the rank goes, and why it does not matter</summary>
265
 
266
  Rank is uniform across all 224 layers by default, and that is measurably not the efficient
267
+ choice. At rank 64, error removed per million branch parameters spans **6.9x** across the
268
+ eight projection types — `attn.wk` returns 0.0992 against `mlp.up`'s 0.0143. The cause is GQA:
269
+ Krea 2 has 12 kv heads against 48 query heads, so `wk`/`wv` are 1536-wide and their branch
270
+ costs a third of an MLP branch while absorbing twice the error.
271
 
272
  `--rank-alloc gqa` spends the same bytes accordingly (`wk` 360, `wv` 256, `wq` 72, `wo` 64,
273
+ `gate` 56, MLP 8 — 0.02% smaller than uniform rank 64, same speed). **It does not improve the
274
+ images:** LPIPS 0.3523 against uniform's 0.3403, better on 5 of 10 prompts, paired t = +0.55 —
275
+ no effect in either direction. It does halve the spread across prompts (variance ratio 4.64,
276
+ F-test p = 0.032) and improve the worst prompt, 0.4975 → 0.4470, which someone could re-test
277
+ at more than 10 images. `uniform` stays the default.
 
 
 
 
 
 
278
 
279
  Kept because the mechanism is sound and the option is cheap to leave in. The transferable
280
+ result is negative: weight reconstruction error is a poor predictor of image outcome on this
281
+ model. Three attempts to optimise against it — the refinement objective, per-block depth
282
+ allocation, and this — failed to move LPIPS in the predicted direction. `--act-stats` is the
283
+ one that worked, and it optimises against something else.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
284
 
285
  </details>
286
 
287
+ ## What was measured
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
288
 
289
+ Full tables, methodology and caveats: **[BENCHMARKS.md](BENCHMARKS.md)**. Images:
290
+ **[GALLERY.md](GALLERY.md)**. In short, on an RTX 3090 at 1024x1024 / 8 steps / cfg 1.0:
 
291
 
292
+ * **Speed.** W4A4 with no branch is ~2.9x BF16; the low-rank branch costs ~9-10% of step time
293
+ and barely varies with rank, so rank 256 is only ~4% slower than rank 16. FP8 is *slower*
294
+ than BF16 on Ampere. INT8 is the fastest accurate option.
295
+ * **Fidelity.** Every claim comes from `tools/fidelity_bench.py`: 16 prompts x 2 seeds x 5 LoRA
296
+ arms, LPIPS against a BF16 reference generated in the *same* arm, compared as paired
297
+ differences with a reseed noise floor printed beside every result. Two findings:
298
+ **branch rank only matters under a LoRA**, and **the activation-aware objective beats every
299
+ other checkpoint here without one**.
300
+ * **What was withdrawn.** An earlier quality ranking came from an LLM judge that had
301
+ saturated (9 of 12 rows a flat 10.00/10) and a rank claim came from one seed compared as
302
+ marginal means. Both are struck through in place with the reason, rather than deleted.
 
 
 
 
 
 
 
 
 
 
 
303
 
304
  ## LoRA
305
 
306
  Use **Krea2 SVDQuant LoRA Loader**, not the stock `LoraLoaderModelOnly`. The stock loader
307
  patches `weight += down @ up`, but on these models `.weight` is a `QuantizedTensor`, so
308
  applying it that way means dequantize → add → requantize: the branch's whole point, keeping
309
+ the 4-bit weight untouched, is lost, and the LoRA delta gets quantized to 4 bits along with it.
310
+
311
+ This loader instead attaches the LoRA as a parallel low-rank branch, which is mathematically
312
+ identical for a linear layer (`(W + BA)x == Wx + B(Ax)`) and leaves the quantized weight alone.
313
+ Chain multiple nodes to stack LoRAs; the console reports what matched, e.g. `224 quantized
314
+ layers, 32 normal layers`.
315
+
316
+ The branch is installed as a ComfyUI *object patch*, so it belongs to that one model branch:
317
+ two LoRA loader nodes on the same checkpoint loader do not contaminate each other, and nothing
318
+ survives past the sampling run. A stack of N LoRAs on one layer folds into a single pair of
319
+ GEMMs rather than N pairs, and LoRA files are cached by mtime, so changing a strength does not
320
+ re-read them from disk.
321
 
322
  <details>
323
+ <summary>Does the stock loader silently skip the quantized layers? Measured: not any more</summary>
324
 
325
+ This page used to claim "it matches only the ~32 non-quantized layers out of ~256 and misses
326
+ all 224 transformer-block layers, with no error." Re-tested against ComfyUI **0.28.0** (commit
327
+ `f966a2b3`) on both `W4A4-convrot` and `SVDQuant-W4A4-rank256`, by patching the same checkpoint
328
+ at LoRA strength 1.0 and 4.0 and diffing every weight — a skipped layer would be bit-identical
329
+ between the two:
330
 
331
  ```
332
  key map offers 224/224 of the quantized layers
 
334
  strength 1.0 vs 4.0: quantized 224/224 differ, plain 32/32 differ
335
  ```
336
 
337
+ All 224 move, so the coverage claim does not hold on current ComfyUI, and we have not bisected
338
+ when that changed. The reason to use this repo's node is the requantization above, not missing
339
+ coverage.
340
 
341
  </details>
342
 
 
 
 
 
 
 
 
 
 
 
 
343
  ## Troubleshooting
344
 
345
+ **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** covers the five things that actually go wrong:
346
+ generation slower than FP8 (nearly always a pre-cu130 torch build), no speedup at all on
347
+ RTX 20-series, `Pin error.` in the console, out-of-memory on a small card, and "left over keys
348
+ in diffusion model" after re-saving.
349
 
350
+ Start with the **Krea2 SVDQuant Diagnostics** node between the loader and the KSampler, or:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
351
 
352
  ```bash
353
+ python diagnose.py --no-load
354
  ```
355
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
356
  ## Attribution
357
 
358
+ Krea 2 is developed by [Krea AI](https://www.krea.ai). This repository contains derivative,
359
+ modified weights and is licensed under the same [Krea 2 Community License
360
  Agreement](https://www.krea.ai/krea-2-licensing) as the base model — see
361
  [LICENSE.md](LICENSE.md) for the full terms and how they apply to the code here. It is a
362
  community contribution, not an official Krea product, and is not endorsed by Krea.
363
 
364
  The quantization kernels used here (`int8_tensorwise`, `convrot_w4a4`) are native to
365
+ [ComfyUI](https://github.com/comfyanonymous/ComfyUI)'s `comfy_kitchen` backend. The low-rank
366
+ branch construction follows the method described in the [SVDQuant
367
  paper](https://arxiv.org/abs/2411.05007) (Li et al., MIT Han Lab), implemented here from
368
+ scratch on top of ComfyUI's native kernel rather than the paper's own Nunchaku engine, which
369
+ has no Krea 2 architecture support.
 
TROUBLESHOOTING.md ADDED
@@ -0,0 +1,97 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Troubleshooting
2
+
3
+ Split out of the README so the getting-started page stays short. Start with the **Krea2
4
+ SVDQuant Diagnostics** node (drop it between the loader and the KSampler, `mode=dispatch`),
5
+ or from a terminal:
6
+
7
+ ```bash
8
+ python diagnose.py --no-load
9
+ ```
10
+
11
+ `--mode all` adds the memory, dispatch, benchmark and profile tables in one go, which is
12
+ what to paste into a bug report.
13
+
14
+ ## "It's slower than FP8 / slower than BF16"
15
+
16
+ Almost always this: **ComfyUI disables `comfy_kitchen`'s CUDA backend when torch was built
17
+ against CUDA < 13**, in `comfy/quant_ops.py`:
18
+
19
+ ```python
20
+ if cuda_version < (13,):
21
+ ck.registry.disable("cuda")
22
+ logging.warning("WARNING: You need pytorch with cu130 or higher to use optimized CUDA operations.")
23
+ ```
24
+
25
+ `convrot_w4a4_linear` resolves its backend per call, so with `cuda` disabled it falls
26
+ through to the eager implementation — which unpacks int4 to bf16 in Python and runs an
27
+ ordinary matmul. That is strictly slower than just running bf16, and the more aggressive
28
+ the format the worse it gets. The tell is that the ordering **inverts**: fp8 fastest, int8
29
+ middling, w4a4/svdq slowest, the exact opposite of the benchmark table above.
30
+
31
+ Check with:
32
+
33
+ ```bash
34
+ python -c "import torch; print(torch.__version__, torch.version.cuda)"
35
+ ```
36
+
37
+ If that prints anything below `13.0`, install a cu130+ torch build. The loader now prints
38
+ the resolved backend on every load and shouts if it isn't `cuda`.
39
+
40
+ ## "No speedup at all on my RTX 20-series" (Turing)
41
+
42
+ Different problem, and this one has no fix on our side. The backend resolves to `cuda`, the
43
+ kernel runs, nothing is misconfigured — int4 is simply not much faster than int8 on Turing:
44
+
45
+ - The instruction the fast path is built around, `mma.m16n8k64` (s4×s4→s32), is **Ampere and
46
+ newer**. `comfy_kitchen`'s default convrot path targets `Sm89` and gates that instruction
47
+ behind `__CUDA_ARCH__ >= 800`.
48
+ - SM 7.5 is served by separate kernels (`turing_int4.cu`, `turing_int8.cu`) built on a
49
+ smaller MMA tile — `GemmShape<8, 8, 32>` versus the default int8 path's
50
+ `GemmShape<16, 8, 32>` — and without `cp.async` prefetch, which is also SM80+.
51
+
52
+ Both formats run weaker kernels there, so switching to int8 does not dodge it either.
53
+ Rebuilding `comfy_kitchen` yourself will not change it: the SM75 kernels are what you get.
54
+
55
+ The int4 checkpoint is still worth downloading on these cards for the **smaller VRAM
56
+ footprint** — just do not expect the speed column of the benchmark table.
57
+
58
+ The diagnostics node and `diagnose.py --no-load` now say this explicitly when they detect a
59
+ compute-capability-7.x device, so you can tell "my setup is broken" apart from "my card
60
+ predates the instruction". Those kernels live in
61
+ [comfy-kitchen](https://github.com/Comfy-Org/comfy-kitchen), not here — this repo ships no
62
+ CUDA build pipeline, and we have no Turing hardware to validate a replacement against, so
63
+ the honest answer is to report it upstream rather than have us ship an untested kernel.
64
+
65
+ ## "Pin error." in the console
66
+
67
+ Harmless. It comes from ComfyUI core (`comfy/model_management.py`), not from this repo,
68
+ and means a weight could not be page-locked so a normal (unpinned) host copy was used
69
+ instead. Results are identical; you lose a little load/offload bandwidth. Windows caps
70
+ locked pages aggressively — `MAX_PINNED_MEMORY` there is 40% of system RAM — so it fires
71
+ routinely with a model this size. It is not specific to `svdq`; INT8 checkpoints trigger it
72
+ too. The diagnostics node prints your pinned-memory budget under `mode=env`.
73
+
74
+ ## Out of memory on a small card (and int8 works fine)
75
+
76
+ Fixed. The low-rank factors were attached as non-persistent buffers, which ComfyUI's
77
+ `module_size()` — the basis of every VRAM decision, including the lowvram split — could
78
+ not see, while `.to(device)` moved them anyway. Worse, the old branch cached its own
79
+ device move back onto the module, so once ComfyUI offloaded a layer the factors quietly
80
+ came back to the GPU and stayed there, outside all accounting. About 645 MB at rank 64,
81
+ which is the difference between fitting and not on an 8 GB card. INT8 checkpoints carry no
82
+ branch, so they were never affected.
83
+
84
+ They are now published into `state_dict()` under their own `svdq_l1` / `svdq_l2` keys and
85
+ staged per call via `comfy.model_management.cast_to`, so they are budgeted and offloaded
86
+ like any other weight. `mode=env` on the diagnostics node reports the factor devices — under
87
+ lowvram they should sit on `cpu` between steps, not `cuda`.
88
+
89
+ One gap remains and it is upstream, not here: `QuantizedTensor.nbytes` reports only the
90
+ packed weight, so the W4A4 `weight_scale` (~3 MB/layer) is still invisible to ComfyUI's
91
+ accounting for *any* w4a4 checkpoint, branch or no branch.
92
+
93
+ ## A re-saved checkpoint logs "left over keys in diffusion model"
94
+
95
+ Expected. Saving the model out of ComfyUI now includes the `svdq_l1` / `svdq_l2` keys, which
96
+ is what lets the file round-trip back into this loader — but the stock `UNETLoader` doesn't
97
+ know them and says so. Harmless.
diagnose.py CHANGED
@@ -49,7 +49,8 @@ def main() -> int:
49
  help="path to a --format svdq checkpoint (or a name under "
50
  "models/diffusion_models)")
51
  parser.add_argument("--mode", default="dispatch",
52
- choices=["dispatch", "env", "bench", "profile", "all"])
 
53
  parser.add_argument("--tokens", type=int, default=None,
54
  help="sequence length to probe with; 4096 = 1024x1024")
55
  parser.add_argument("--no-load", action="store_true",
@@ -78,7 +79,10 @@ def main() -> int:
78
  print("loading {} ...".format(path), flush=True)
79
  patcher = loader.load_svdquant_w4a4(path)
80
 
81
- modes = ["env", "dispatch", "bench"] if args.mode == "all" else [args.mode]
 
 
 
82
  for mode in modes:
83
  print()
84
  print(diag.run_report(patcher, mode, tokens), flush=True)
 
49
  help="path to a --format svdq checkpoint (or a name under "
50
  "models/diffusion_models)")
51
  parser.add_argument("--mode", default="dispatch",
52
+ choices=["dispatch", "env", "bench", "profile", "all"],
53
+ help="'all' runs env, dispatch, bench and profile in that order")
54
  parser.add_argument("--tokens", type=int, default=None,
55
  help="sequence length to probe with; 4096 = 1024x1024")
56
  parser.add_argument("--no-load", action="store_true",
 
79
  print("loading {} ...".format(path), flush=True)
80
  patcher = loader.load_svdquant_w4a4(path)
81
 
82
+ # Driven off REPORTS rather than a hand-written list, which had drifted: `profile` was
83
+ # added to the choices and to REPORTS but never to `all`, so `--mode all` quietly meant
84
+ # "all but the profile table" and nobody pasting its output would have known.
85
+ modes = list(diag.REPORTS) if args.mode == "all" else [args.mode]
86
  for mode in modes:
87
  print()
88
  print(diag.run_report(patcher, mode, tokens), flush=True)
examples/fidelity_sheets/sheet_base_01_dense_text.jpg ADDED

Git LFS Details

  • SHA256: f1879662de3b04e182bd32b65f71dfa52e5520b2fea215cbea01c7cbdb1ebd57
  • Pointer size: 132 Bytes
  • Size of remote file: 1.49 MB
examples/fidelity_sheets/sheet_base_02_curved_text.jpg ADDED

Git LFS Details

  • SHA256: 8b3be907db006e4b64f627829d7df58f6de3ff327663942ad1c14c7970ba9dee
  • Pointer size: 131 Bytes
  • Size of remote file: 951 kB
examples/fidelity_sheets/sheet_base_03_hands_detail.jpg ADDED

Git LFS Details

  • SHA256: 16f8cc61ea6e77bbb05ea4b951685279029615e8f1bbd1aaa96b5289676fa1ce
  • Pointer size: 132 Bytes
  • Size of remote file: 1.14 MB
examples/fidelity_sheets/sheet_base_04_crowd_faces.jpg ADDED

Git LFS Details

  • SHA256: d7c3347d40d042018dd6fbd0e11c5a263a7cdcc9f74d00c532ae192dd5c2f93b
  • Pointer size: 132 Bytes
  • Size of remote file: 1.81 MB
examples/fidelity_sheets/sheet_base_05_symmetry_pattern.jpg ADDED

Git LFS Details

  • SHA256: c277672dfd353ce7e67f36077726869996264763f22afb654f84b5c31fc5cb9b
  • Pointer size: 132 Bytes
  • Size of remote file: 3.19 MB
examples/fidelity_sheets/sheet_base_06_multi_subject.jpg ADDED

Git LFS Details

  • SHA256: 8bc4b2157c61e07a1f42260a8b11fb7f29851a4f817fe28a3ab78557c9a98fee
  • Pointer size: 132 Bytes
  • Size of remote file: 1.24 MB
examples/fidelity_sheets/sheet_base_07_reflections_glass.jpg ADDED

Git LFS Details

  • SHA256: 8f26ba17f59b5137419a3a3378e1ebce0678757c38ba2397ccc1c251b76e488b
  • Pointer size: 132 Bytes
  • Size of remote file: 1.42 MB
examples/fidelity_sheets/sheet_base_08_logo_typography.jpg ADDED

Git LFS Details

  • SHA256: 9f1070dc076d4ade5cccd631137d39d00c19b8853e9bdb1044b17acfb6f08008
  • Pointer size: 132 Bytes
  • Size of remote file: 1.72 MB
examples/fidelity_sheets/sheet_base_09_counting_objects.jpg ADDED

Git LFS Details

  • SHA256: 0d51ebf684610c6bd33e3cbe6c7c158ac9cf9c432af17b54db969c90f59a170b
  • Pointer size: 132 Bytes
  • Size of remote file: 1.14 MB
examples/fidelity_sheets/sheet_base_10_complex_scene.jpg ADDED

Git LFS Details

  • SHA256: d4d2beee2a3f1c53a59664c14682bdb143369b610a113c89898127e0aabc62d4
  • Pointer size: 132 Bytes
  • Size of remote file: 1.64 MB
examples/fidelity_sheets/sheet_base_11_portrait_woman.jpg ADDED

Git LFS Details

  • SHA256: 461a829c3a6d91c2b38809cf1f9c7d3605d07ae8d443a9b49af85f06b1bd6072
  • Pointer size: 132 Bytes
  • Size of remote file: 1.22 MB
examples/fidelity_sheets/sheet_base_12_person_holding_sign.jpg ADDED

Git LFS Details

  • SHA256: 4c9c6eb6ac8cea138fb83a157b95bd875457e9044ba976f3d8405379f15ba2bc
  • Pointer size: 132 Bytes
  • Size of remote file: 1.34 MB
examples/fidelity_sheets/sheet_base_13_two_people_interaction.jpg ADDED

Git LFS Details

  • SHA256: 861aa8c20b59d1781bff1111981732771e8db39b9e6e4b26881a33e9970add16
  • Pointer size: 132 Bytes
  • Size of remote file: 1.16 MB
examples/fidelity_sheets/sheet_base_14_hands_and_face.jpg ADDED

Git LFS Details

  • SHA256: ac74e820d4dc04eb1fe02007407474b385c21ed5dca2fc43ee2052b442dac855
  • Pointer size: 131 Bytes
  • Size of remote file: 973 kB
examples/fidelity_sheets/sheet_base_15_full_body_fashion.jpg ADDED

Git LFS Details

  • SHA256: 79d415bd158231a45061af1ba1b4df2921d4ac6fa33fece1a4ea741301306197
  • Pointer size: 132 Bytes
  • Size of remote file: 1.24 MB
examples/fidelity_sheets/sheet_base_16_group_selfie.jpg ADDED

Git LFS Details

  • SHA256: ad42f16c245b49d71c487ebda002af375edb9848553a0ad367808829428cebda
  • Pointer size: 132 Bytes
  • Size of remote file: 1.45 MB
examples/fidelity_sheets/sheet_lora2_01_dense_text.jpg ADDED

Git LFS Details

  • SHA256: 1a9efed0a272e894f8b4a8c8f3f055f7fb362444d734319e9ebb8428f686a8dc
  • Pointer size: 132 Bytes
  • Size of remote file: 1.46 MB
examples/fidelity_sheets/sheet_lora2_02_curved_text.jpg ADDED

Git LFS Details

  • SHA256: 56354057f1603731c47a10262adb83afc3dec91a4c56b9c54fc010d5241bd89d
  • Pointer size: 131 Bytes
  • Size of remote file: 934 kB
examples/fidelity_sheets/sheet_lora2_03_hands_detail.jpg ADDED

Git LFS Details

  • SHA256: 3ea53575281cba068068982b4818e0bc4aa414d9586b655c95c14c608589b1c6
  • Pointer size: 132 Bytes
  • Size of remote file: 1.13 MB
examples/fidelity_sheets/sheet_lora2_04_crowd_faces.jpg ADDED

Git LFS Details

  • SHA256: e6fc7714f9d48dc4d30167dbae179b5fa58d5d126132e72693ae59ac0dd4d483
  • Pointer size: 132 Bytes
  • Size of remote file: 1.79 MB
examples/fidelity_sheets/sheet_lora2_05_symmetry_pattern.jpg ADDED

Git LFS Details

  • SHA256: 3c0726ddb21a2df1e5ac89d3d44011b385576705c92810c47dd9c2f56fb8ae14
  • Pointer size: 132 Bytes
  • Size of remote file: 3.19 MB
examples/fidelity_sheets/sheet_lora2_06_multi_subject.jpg ADDED

Git LFS Details

  • SHA256: f0a34c8de32f7926456804718cf1dd405f060237e232e651dc82b65843b6b0a2
  • Pointer size: 132 Bytes
  • Size of remote file: 1.26 MB
examples/fidelity_sheets/sheet_lora2_07_reflections_glass.jpg ADDED

Git LFS Details

  • SHA256: 7edf114bebf428a321063289dfdcc0520faac3a87be992d66720b9751d501e65
  • Pointer size: 132 Bytes
  • Size of remote file: 1.4 MB
examples/fidelity_sheets/sheet_lora2_08_logo_typography.jpg ADDED

Git LFS Details

  • SHA256: 985558fa1163960e834b13fc92fe4d487f502f9328e960459322b7c8cbaecbf0
  • Pointer size: 132 Bytes
  • Size of remote file: 1.69 MB
examples/fidelity_sheets/sheet_lora2_09_counting_objects.jpg ADDED

Git LFS Details

  • SHA256: 9a93e1b9582e9a8a8d1a7c5dd694a4c1df3c9d527289b816ea6004f20266a101
  • Pointer size: 132 Bytes
  • Size of remote file: 1.11 MB
examples/fidelity_sheets/sheet_lora2_10_complex_scene.jpg ADDED

Git LFS Details

  • SHA256: d6ac85792ca41319f7e3e81458a0de514011e5931b638b7efb4469efc5e03f28
  • Pointer size: 132 Bytes
  • Size of remote file: 1.66 MB
examples/fidelity_sheets/sheet_lora2_11_portrait_woman.jpg ADDED

Git LFS Details

  • SHA256: 9629bbd0e6b959ae0f06021c18b42f13247b40335724f9b46f34855beed7f77b
  • Pointer size: 132 Bytes
  • Size of remote file: 1.27 MB
examples/fidelity_sheets/sheet_lora2_12_person_holding_sign.jpg ADDED

Git LFS Details

  • SHA256: f2592e07a348a815701c35947ecf68018824e8eb2f345db4f1218a44d38d02c2
  • Pointer size: 132 Bytes
  • Size of remote file: 1.39 MB
examples/fidelity_sheets/sheet_lora2_13_two_people_interaction.jpg ADDED

Git LFS Details

  • SHA256: 3360e9ee5c72ae83bfe278227ebde74fcf057e296b4d345056ff4557340b6900
  • Pointer size: 132 Bytes
  • Size of remote file: 1.2 MB
examples/fidelity_sheets/sheet_lora2_14_hands_and_face.jpg ADDED

Git LFS Details

  • SHA256: 9129745ffb219f117616711db6aa6b5c5922fc1b70488e43bd1b1ad7233c42a9
  • Pointer size: 131 Bytes
  • Size of remote file: 932 kB
examples/fidelity_sheets/sheet_lora2_15_full_body_fashion.jpg ADDED

Git LFS Details

  • SHA256: e1f8202e400b8a1e0384770e38d02360441a46a63a553bff235594505c46b1a0
  • Pointer size: 132 Bytes
  • Size of remote file: 1.32 MB
examples/fidelity_sheets/sheet_lora2_16_group_selfie.jpg ADDED

Git LFS Details

  • SHA256: 66c7320cb2faf5ab84c7ab585c64380de7b599ec86221a35a2612f22f1e7152d
  • Pointer size: 132 Bytes
  • Size of remote file: 1.48 MB
quantize_krea2.py CHANGED
@@ -38,6 +38,7 @@ from __future__ import annotations
38
 
39
  import argparse
40
  import gc
 
41
  import json
42
  import math
43
  import os
@@ -50,11 +51,14 @@ import torch
50
  from safetensors import safe_open
51
  from safetensors.torch import save_file
52
 
53
- def _find_comfyui_root() -> str:
54
  """Locate the ComfyUI root so `comfy.*` imports work regardless of cwd.
55
 
56
  Preference order: $COMFYUI_PATH, then walking up from this file (this script
57
- lives in ComfyUI/custom_nodes/<pkg>/, so comfy/ is two levels up), then cwd.
 
 
 
58
  """
59
  env = os.environ.get("COMFYUI_PATH")
60
  if env and os.path.isdir(os.path.join(env, "comfy")):
@@ -63,19 +67,32 @@ def _find_comfyui_root() -> str:
63
  candidate = os.path.abspath(os.path.join(here, "..", ".."))
64
  if os.path.isdir(os.path.join(candidate, "comfy")):
65
  return candidate
66
- return "."
67
-
68
-
69
- sys.path.insert(0, _find_comfyui_root())
70
-
71
- from comfy.quant_ops import QUANT_ALGOS, get_layout_class # noqa: E402
 
 
 
 
 
 
 
 
 
 
 
 
 
72
 
73
  _QUANT_SUFFIXES = ("attn.wq", "attn.wk", "attn.wv", "attn.gate", "attn.wo",
74
  "mlp.gate", "mlp.up", "mlp.down")
75
 
76
 
77
  # Checkpoints ship either bare ("blocks.0...") or prefixed ("model.diffusion_model.blocks.0...").
78
- _PREFIXES = ("model.diffusion_model.", "diffusion_model.", "")
79
 
80
  # Formats we know how to reconstruct back to BF16 from disk alone. FP8 storage is one
81
  # byte per element with no packing or pre-rotation, so `qdata * scale` recovers the
@@ -85,15 +102,22 @@ _PREFIXES = ("model.diffusion_model.", "diffusion_model.", "")
85
  # in/out feature counts from the live nn.Linear, which isn't recoverable from the
86
  # checkpoint alone, so those are rejected instead.
87
  _DEQUANTIZABLE_FORMATS = ("float8_e4m3fn", "float8_e5m2")
88
- _UNSCALED_FP8_DTYPES = ("F8_E4M3", "F8_E5M2")
89
 
90
 
91
- def detect_prefix(keys) -> str:
92
- """Return the prefix the transformer blocks live under, or raise if not found."""
93
- for prefix in _PREFIXES:
 
 
 
 
 
 
94
  if any(k.startswith("{}blocks.".format(prefix)) for k in keys):
95
  return prefix
96
- raise SystemExit(
 
 
97
  "Could not find transformer blocks in this checkpoint. Expected keys like\n"
98
  " blocks.0.attn.wq.weight or model.diffusion_model.blocks.0.attn.wq.weight\n"
99
  "This does not look like a Krea 2 diffusion model."
@@ -114,7 +138,7 @@ def check_requantizable(handle, keys, prefix: str) -> None:
114
  conf = json.loads(bytes(handle.get_tensor(key).tolist()))
115
  fmt = conf.get("format")
116
  if fmt not in _DEQUANTIZABLE_FORMATS:
117
- raise SystemExit(
118
  "Layer {} is already quantized as '{}'. Only FP8-quantized layers can be "
119
  "automatically reconstructed and re-quantized; for INT8/W4A4 sources, use "
120
  "the original BF16 (or FP16) release of the model instead.".format(layer, fmt)
@@ -429,8 +453,6 @@ def conf_tensor(conf: dict) -> torch.Tensor:
429
 
430
  def load_act_stats(path: str) -> dict[str, torch.Tensor]:
431
  """Read the file the capture nodes write: {layer name: per-input-channel RMS}."""
432
- from safetensors import safe_open
433
-
434
  stats = {}
435
  with safe_open(path, framework="pt", device="cpu") as handle:
436
  for key in handle.keys():
@@ -440,6 +462,42 @@ def load_act_stats(path: str) -> dict[str, torch.Tensor]:
440
  return stats
441
 
442
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
443
  def convert(src: str, dst: str, fmt: str, groupsize: int, device: str = "cuda", rank: int = 0,
444
  refine_iters: int = 100, variant: str = "unknown", progress_cb=None,
445
  rank_alloc: str = "uniform", act_stats: str | None = None):
@@ -463,14 +521,14 @@ def convert(src: str, dst: str, fmt: str, groupsize: int, device: str = "cuda",
463
  used_ranks: set[int] = set()
464
  clamped: dict[str, int] = {}
465
  stats = load_act_stats(act_stats) if act_stats else {}
466
- stats_used = 0
467
- stats_missing: list[str] = []
468
  t0 = time.time()
469
 
470
  with safe_open(src, framework="pt", device="cpu") as handle:
471
  keys = list(handle.keys())
472
  prefix = detect_prefix(keys)
473
  check_requantizable(handle, keys, prefix)
 
 
474
 
475
  # Companion keys (old scales/markers) for target layers get regenerated fresh
476
  # when we process the ".weight" key below -- skip the stale copies on disk,
@@ -501,12 +559,9 @@ def convert(src: str, dst: str, fmt: str, groupsize: int, device: str = "cuda",
501
  if leaf_rank > 0:
502
  # Stats are keyed by module path (`blocks.0.attn.wq`); checkpoint
503
  # keys may carry a prefix, so strip it to look them up.
 
 
504
  act = stats.get(layer[len(prefix):] if prefix else layer)
505
- if stats:
506
- if act is None:
507
- stats_missing.append(layer)
508
- else:
509
- stats_used += 1
510
  split = svdquant_split(w, leaf_rank, fmt, groupsize, refine_iters,
511
  act_rms=act)
512
  if split is None:
@@ -556,18 +611,6 @@ def convert(src: str, dst: str, fmt: str, groupsize: int, device: str = "cuda",
556
  ", ".join(sorted(observed_leaves)) or "none")
557
  )
558
 
559
- # Partial statistics are the quiet-wrongness case this file hard-fails on elsewhere: the
560
- # covered layers would get an activation-aware split and the rest a plain one, producing a
561
- # checkpoint that is neither, and no measurement of it would mean anything.
562
- if stats and stats_missing:
563
- raise RuntimeError(
564
- "activation stats cover {} of {} branched layers; {} are missing, e.g. {}.\n"
565
- "The capture run did not see every layer -- usually because sampling was "
566
- "interrupted, or the statistics came from a different model. Re-capture rather "
567
- "than building a checkpoint that is activation-aware in some layers and not "
568
- "others.".format(stats_used, stats_used + len(stats_missing), len(stats_missing),
569
- ", ".join(stats_missing[:3])))
570
-
571
  # A leaf can only be clamped when the allocation asked for more rank than the weight is
572
  # wide, which means part of the budget went unspent and the file is *smaller* than the
573
  # uniform one -- so a comparison against uniform at this budget is no longer like-for-like.
 
38
 
39
  import argparse
40
  import gc
41
+ import importlib.util
42
  import json
43
  import math
44
  import os
 
51
  from safetensors import safe_open
52
  from safetensors.torch import save_file
53
 
54
+ def _find_comfyui_root() -> str | None:
55
  """Locate the ComfyUI root so `comfy.*` imports work regardless of cwd.
56
 
57
  Preference order: $COMFYUI_PATH, then walking up from this file (this script
58
+ lives in ComfyUI/custom_nodes/<pkg>/, so comfy/ is two levels up). None if
59
+ neither resolves -- deliberately *not* cwd. This module is imported by the
60
+ Quantize node inside ComfyUI's own process, and putting cwd at sys.path[0]
61
+ there lets any file in the working directory shadow a real import.
62
  """
63
  env = os.environ.get("COMFYUI_PATH")
64
  if env and os.path.isdir(os.path.join(env, "comfy")):
 
67
  candidate = os.path.abspath(os.path.join(here, "..", ".."))
68
  if os.path.isdir(os.path.join(candidate, "comfy")):
69
  return candidate
70
+ return None
71
+
72
+
73
+ # Running inside ComfyUI, `comfy` already imports and the path needs no help.
74
+ if importlib.util.find_spec("comfy") is None:
75
+ _root = _find_comfyui_root()
76
+ if _root is not None:
77
+ sys.path.insert(0, _root)
78
+
79
+ # Guarded because __init__.py imports this module transitively: an unguarded failure
80
+ # here would deregister every node in the pack, including Env Check, whose whole job is
81
+ # diagnosing a broken quantization backend. Degrade to "no formats available" instead.
82
+ QUANT_UNAVAILABLE = ""
83
+ try:
84
+ from comfy.quant_ops import QUANT_ALGOS, get_layout_class # noqa: E402
85
+ except Exception as exc: # pragma: no cover - depends on the ComfyUI build
86
+ QUANT_ALGOS = {}
87
+ get_layout_class = None
88
+ QUANT_UNAVAILABLE = "{}: {}".format(type(exc).__name__, exc)
89
 
90
  _QUANT_SUFFIXES = ("attn.wq", "attn.wk", "attn.wv", "attn.gate", "attn.wo",
91
  "mlp.gate", "mlp.up", "mlp.down")
92
 
93
 
94
  # Checkpoints ship either bare ("blocks.0...") or prefixed ("model.diffusion_model.blocks.0...").
95
+ LAYER_PREFIXES = ("model.diffusion_model.", "diffusion_model.", "")
96
 
97
  # Formats we know how to reconstruct back to BF16 from disk alone. FP8 storage is one
98
  # byte per element with no packing or pre-rotation, so `qdata * scale` recovers the
 
102
  # in/out feature counts from the live nn.Linear, which isn't recoverable from the
103
  # checkpoint alone, so those are rejected instead.
104
  _DEQUANTIZABLE_FORMATS = ("float8_e4m3fn", "float8_e5m2")
 
105
 
106
 
107
+ def detect_prefix(keys, default: str | None = None) -> str:
108
+ """Return the prefix the transformer blocks live under.
109
+
110
+ Raises `RuntimeError` if no prefix matches and no `default` was given. Not
111
+ `SystemExit`: that is a `BaseException`, and `convert()` runs inside ComfyUI's
112
+ executor via the Quantize node, where a BaseException escapes error handling
113
+ entirely. `main()` catches RuntimeError and prints it as a clean CLI line.
114
+ """
115
+ for prefix in LAYER_PREFIXES:
116
  if any(k.startswith("{}blocks.".format(prefix)) for k in keys):
117
  return prefix
118
+ if default is not None:
119
+ return default
120
+ raise RuntimeError(
121
  "Could not find transformer blocks in this checkpoint. Expected keys like\n"
122
  " blocks.0.attn.wq.weight or model.diffusion_model.blocks.0.attn.wq.weight\n"
123
  "This does not look like a Krea 2 diffusion model."
 
138
  conf = json.loads(bytes(handle.get_tensor(key).tolist()))
139
  fmt = conf.get("format")
140
  if fmt not in _DEQUANTIZABLE_FORMATS:
141
+ raise RuntimeError(
142
  "Layer {} is already quantized as '{}'. Only FP8-quantized layers can be "
143
  "automatically reconstructed and re-quantized; for INT8/W4A4 sources, use "
144
  "the original BF16 (or FP16) release of the model instead.".format(layer, fmt)
 
453
 
454
  def load_act_stats(path: str) -> dict[str, torch.Tensor]:
455
  """Read the file the capture nodes write: {layer name: per-input-channel RMS}."""
 
 
456
  stats = {}
457
  with safe_open(path, framework="pt", device="cpu") as handle:
458
  for key in handle.keys():
 
462
  return stats
463
 
464
 
465
+ def check_act_stats_coverage(stats: dict, keys, prefix: str, ranks: dict) -> None:
466
+ """Fail before any GPU work if the statistics don't cover every layer that will branch.
467
+
468
+ Partial statistics are the quiet-wrongness case: the covered layers would get an
469
+ activation-aware split and the rest a plain one, producing a checkpoint that is neither,
470
+ and no measurement of it would mean anything.
471
+
472
+ Deliberately key-only. Which layers branch depends on `is_target` plus a positive
473
+ `rank_for_leaf`, both of which read the layer *name*; the one weight-dependent step in
474
+ the loop (`min(wanted, min(w.shape))`) can only lower a rank, never raise a zero above
475
+ it, so this pre-pass sees exactly the set the loop will branch. Doing it here instead of
476
+ after the loop turns a ~6 minute mistake into a two-second one.
477
+ """
478
+ covered, missing = 0, []
479
+ for key in keys:
480
+ if not key.endswith(".weight"):
481
+ continue
482
+ layer = key[: -len(".weight")]
483
+ if not is_target(layer, prefix):
484
+ continue
485
+ if rank_for_leaf(ranks, leaf_name(layer, prefix)) <= 0:
486
+ continue
487
+ if stats.get(layer[len(prefix):] if prefix else layer) is None:
488
+ missing.append(layer)
489
+ else:
490
+ covered += 1
491
+ if missing:
492
+ raise RuntimeError(
493
+ "activation stats cover {} of {} branched layers; {} are missing, e.g. {}.\n"
494
+ "The capture run did not see every layer -- usually because sampling was "
495
+ "interrupted, or the statistics came from a different model. Re-capture rather "
496
+ "than building a checkpoint that is activation-aware in some layers and not "
497
+ "others.".format(covered, covered + len(missing), len(missing),
498
+ ", ".join(missing[:3])))
499
+
500
+
501
  def convert(src: str, dst: str, fmt: str, groupsize: int, device: str = "cuda", rank: int = 0,
502
  refine_iters: int = 100, variant: str = "unknown", progress_cb=None,
503
  rank_alloc: str = "uniform", act_stats: str | None = None):
 
521
  used_ranks: set[int] = set()
522
  clamped: dict[str, int] = {}
523
  stats = load_act_stats(act_stats) if act_stats else {}
 
 
524
  t0 = time.time()
525
 
526
  with safe_open(src, framework="pt", device="cpu") as handle:
527
  keys = list(handle.keys())
528
  prefix = detect_prefix(keys)
529
  check_requantizable(handle, keys, prefix)
530
+ if stats:
531
+ check_act_stats_coverage(stats, keys, prefix, ranks)
532
 
533
  # Companion keys (old scales/markers) for target layers get regenerated fresh
534
  # when we process the ".weight" key below -- skip the stale copies on disk,
 
559
  if leaf_rank > 0:
560
  # Stats are keyed by module path (`blocks.0.attn.wq`); checkpoint
561
  # keys may carry a prefix, so strip it to look them up.
562
+ # Coverage was already proven complete before the loop started, so
563
+ # a None here cannot happen for a branched layer.
564
  act = stats.get(layer[len(prefix):] if prefix else layer)
 
 
 
 
 
565
  split = svdquant_split(w, leaf_rank, fmt, groupsize, refine_iters,
566
  act_rms=act)
567
  if split is None:
 
611
  ", ".join(sorted(observed_leaves)) or "none")
612
  )
613
 
 
 
 
 
 
 
 
 
 
 
 
 
614
  # A leaf can only be clamped when the allocation asked for more rank than the weight is
615
  # wide, which means part of the budget went unspent and the file is *smaller* than the
616
  # uniform one -- so a comparison against uniform at this budget is no longer like-for-like.
svdquant_capture.py CHANGED
@@ -23,7 +23,6 @@ and each ComfyUI run is a separate execution. `Start` with `reset=True` on the f
23
 
24
  from __future__ import annotations
25
 
26
- import json
27
  import logging
28
  import os
29
 
@@ -37,13 +36,18 @@ from .svdquant_diag import _CATEGORY
37
  # layer name -> {"sumsq": float64 [in_features] on cpu, "count": int}
38
  _STATS: dict[str, dict] = {}
39
  _HANDLES: list = []
 
 
 
 
 
40
 
41
  FILE_VERSION = 1
42
 
43
 
44
  def _hook(name: str):
45
  def pre_hook(module, args):
46
- if not args:
47
  return
48
  x = args[0]
49
  if not isinstance(x, torch.Tensor) or x.ndim < 2:
@@ -77,25 +81,39 @@ def is_target(name: str) -> bool:
77
 
78
 
79
  def attach(diffusion_model) -> int:
 
80
  detach()
81
  count = 0
82
  for name, module in diffusion_model.named_modules():
83
  if is_target(name) and getattr(module, "weight", None) is not None:
84
  _HANDLES.append(module.register_forward_pre_hook(_hook(name)))
85
  count += 1
 
86
  return count
87
 
88
 
89
  def detach() -> None:
 
 
 
 
 
 
 
 
 
 
90
  for handle in _HANDLES:
91
  try:
92
  handle.remove()
93
  except Exception:
94
- logging.debug("[krea2-svdquant] could not remove a capture hook", exc_info=True)
95
- _HANDLES.clear()
 
 
96
 
97
 
98
- def write(path: str, meta: dict | None = None) -> dict:
99
  """RMS per input channel, as a safetensors file keyed by layer name."""
100
  from safetensors.torch import save_file
101
 
@@ -117,7 +135,6 @@ def write(path: str, meta: dict | None = None) -> dict:
117
  "krea2_actstats_min_tokens": str(min(counts)),
118
  "krea2_actstats_max_tokens": str(max(counts)),
119
  }
120
- metadata.update({k: str(v) for k, v in (meta or {}).items()})
121
 
122
  os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
123
  save_file(tensors, path, metadata=metadata)
 
23
 
24
  from __future__ import annotations
25
 
 
26
  import logging
27
  import os
28
 
 
36
  # layer name -> {"sumsq": float64 [in_features] on cpu, "count": int}
37
  _STATS: dict[str, dict] = {}
38
  _HANDLES: list = []
39
+ # Checked first inside every hook, so a hook that outlives its handle is inert rather than
40
+ # quietly accumulating. A leaked hook is the worst failure this module has: it would keep
41
+ # adding activations from later, unrelated generations into _STATS, and the next calibration
42
+ # file would be contaminated with no sign of it.
43
+ _ACTIVE = False
44
 
45
  FILE_VERSION = 1
46
 
47
 
48
  def _hook(name: str):
49
  def pre_hook(module, args):
50
+ if not _ACTIVE or not args:
51
  return
52
  x = args[0]
53
  if not isinstance(x, torch.Tensor) or x.ndim < 2:
 
81
 
82
 
83
  def attach(diffusion_model) -> int:
84
+ global _ACTIVE
85
  detach()
86
  count = 0
87
  for name, module in diffusion_model.named_modules():
88
  if is_target(name) and getattr(module, "weight", None) is not None:
89
  _HANDLES.append(module.register_forward_pre_hook(_hook(name)))
90
  count += 1
91
+ _ACTIVE = True
92
  return count
93
 
94
 
95
  def detach() -> None:
96
+ """Stop capturing, then remove the hooks.
97
+
98
+ `_ACTIVE` goes down first so capture stops even for a hook whose handle refuses to
99
+ detach. A failed handle is kept in `_HANDLES` so the next `detach()` retries it, and the
100
+ failure is logged at warning -- at DEBUG (ComfyUI's default is INFO) nobody would ever
101
+ see the one condition that can silently corrupt a calibration file.
102
+ """
103
+ global _ACTIVE
104
+ _ACTIVE = False
105
+ kept = []
106
  for handle in _HANDLES:
107
  try:
108
  handle.remove()
109
  except Exception:
110
+ logging.warning("[krea2-svdquant] could not remove a capture hook; capture is "
111
+ "off but the hook is still installed", exc_info=True)
112
+ kept.append(handle)
113
+ _HANDLES[:] = kept
114
 
115
 
116
+ def write(path: str) -> dict:
117
  """RMS per input channel, as a safetensors file keyed by layer name."""
118
  from safetensors.torch import save_file
119
 
 
135
  "krea2_actstats_min_tokens": str(min(counts)),
136
  "krea2_actstats_max_tokens": str(max(counts)),
137
  }
 
138
 
139
  os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
140
  save_file(tensors, path, metadata=metadata)
svdquant_diag.py CHANGED
@@ -32,15 +32,28 @@ import comfy.model_management as mm
32
  # `ck.registry.disable("cuda")` it performs when torch was built against CUDA < 13.
33
  # Without it we would query a registry ComfyUI has not finished configuring and happily
34
  # report a CUDA backend that never runs in practice.
35
- import comfy.quant_ops # noqa: F401
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
 
37
  _CK_IMPORT_ERROR = None
38
  try:
39
- import comfy_kitchen as ck
40
  from comfy_kitchen.registry import registry as ck_registry
41
  from comfy_kitchen.tensor.convrot_w4a4 import TensorCoreConvRotW4A4Layout
42
  except Exception as exc: # pragma: no cover - depends on the install
43
- ck = None
44
  ck_registry = None
45
  TensorCoreConvRotW4A4Layout = None
46
  _CK_IMPORT_ERROR = "{}: {}".format(type(exc).__name__, exc)
@@ -75,12 +88,28 @@ def quantized_linears(diffusion_model):
75
 
76
 
77
  def branch_buffers(module):
78
- """(name, tensor) for the low-rank factors attached to a module, in any naming."""
 
 
 
 
79
  for name, buf in module.named_buffers(recurse=False):
80
- if buf is not None and (name.startswith("svdq_l") or name.startswith("_br_l")):
81
  yield name, buf
82
 
83
 
 
 
 
 
 
 
 
 
 
 
 
 
84
  def _probe_kwargs(module, tokens: int, device) -> dict:
85
  """Kwargs shaped exactly like a real `convrot_w4a4_linear` call, for validation.
86
 
@@ -255,6 +284,11 @@ def report_backend_status() -> str:
255
  --no-load` and the env-check node come through here.
256
  """
257
  lines = ["torch {} (cuda build {})".format(torch.__version__, torch.version.cuda), ""]
 
 
 
 
 
258
  if ck_registry is None:
259
  lines.append("comfy_kitchen unavailable: {}".format(_CK_IMPORT_ERROR))
260
  return "\n".join(lines)
@@ -421,8 +455,13 @@ def report_dispatch(patcher, tokens: int) -> list[str]:
421
  return lines
422
 
423
 
424
- def _timed(fn, reps: int = 20, warmup: int = 3) -> float:
425
- """Milliseconds per call, CUDA-synchronised. Returns nan if the call raises."""
 
 
 
 
 
426
  try:
427
  for _ in range(warmup):
428
  fn()
@@ -435,7 +474,10 @@ def _timed(fn, reps: int = 20, warmup: int = 3) -> float:
435
  torch.cuda.synchronize()
436
  return (time.perf_counter() - start) * 1000.0 / reps
437
  except Exception as exc:
438
- logging.debug("[krea2-svdquant] bench call failed: %s", exc, exc_info=True)
 
 
 
439
  return float("nan")
440
 
441
 
@@ -458,6 +500,7 @@ def report_bench(patcher, tokens: int) -> list[str]:
458
  lines.append("{:<44} {:>9} {:>9} {:>9} {:>9}".format(
459
  "layer [in -> out]", "quant ms", "branch ms", "bf16 ms", "quant/bf16"))
460
 
 
461
  for shape, (name, module) in sorted(_distinct_shapes(patcher.model.diffusion_model).items()):
462
  out_features, in_features = int(shape[0]), int(shape[1])
463
  dtype = module.weight._params.orig_dtype
@@ -465,21 +508,31 @@ def report_bench(patcher, tokens: int) -> list[str]:
465
  dtype = torch.bfloat16
466
  x = torch.randn((tokens, in_features), dtype=dtype, device=device)
467
 
468
- quant_ms = _timed(lambda: F.linear(x, module.weight))
 
469
 
470
- factors = [buf for _n, buf in branch_buffers(module)]
471
- if len(factors) >= 2:
472
- a1, a2 = factors[0].to(device=device, dtype=dtype), factors[1].to(device=device, dtype=dtype)
473
- branch_ms = _timed(lambda: F.linear(F.linear(x, a2), a1))
474
- del a1, a2
475
- else:
476
  branch_ms = float("nan")
 
 
 
 
 
 
 
 
477
 
478
  try:
479
  dense = module.weight.dequantize().to(dtype)
480
- bf16_ms = _timed(lambda: F.linear(x, dense))
 
481
  del dense
482
- except Exception:
 
 
 
 
483
  bf16_ms = float("nan")
484
 
485
  ratio = quant_ms / bf16_ms if bf16_ms == bf16_ms and bf16_ms > 0 else float("nan")
@@ -493,6 +546,13 @@ def report_bench(patcher, tokens: int) -> list[str]:
493
  lines.append("")
494
  lines.append("quant/bf16 < 1.0 means the int4 kernel is winning. Above 1.0 means the "
495
  "quantized path is being emulated -- check mode=dispatch.")
 
 
 
 
 
 
 
496
  return lines
497
 
498
 
@@ -562,6 +622,12 @@ class Krea2SVDQuantDiagnostics:
562
  }
563
  }
564
 
 
 
 
 
 
 
565
  RETURN_TYPES = ("MODEL", "STRING")
566
  RETURN_NAMES = ("model", "report")
567
  OUTPUT_TOOLTIPS = ("The model, unchanged - wire it on to your sampler.",
 
32
  # `ck.registry.disable("cuda")` it performs when torch was built against CUDA < 13.
33
  # Without it we would query a registry ComfyUI has not finished configuring and happily
34
  # report a CUDA backend that never runs in practice.
35
+ _QUANT_OPS_ERROR = None
36
+ try:
37
+ import comfy.quant_ops # noqa: F401
38
+ except Exception as exc: # pragma: no cover - depends on the ComfyUI build
39
+ # Guarded so a build without quant_ops still gets *this* module, and therefore still gets
40
+ # Env Check -- the one node whose entire job is explaining a missing quantization backend.
41
+ # Unguarded, the ImportError would propagate through __init__.py and remove all seven.
42
+ _QUANT_OPS_ERROR = "{}: {}".format(type(exc).__name__, exc)
43
+
44
+ # Buffer names for the low-rank factors, chosen to match the on-disk keys exactly: a buffer
45
+ # called ``svdq_l1`` on ``blocks.0.attn.wq`` produces the state-dict key
46
+ # ``blocks.0.attn.wq.svdq_l1``, byte-identical to what quantize_krea2.py writes. So a model
47
+ # re-saved out of ComfyUI round-trips straight back into the loader. Defined here because
48
+ # svdquant_w4a4 imports this module (not the other way round) and both need them.
49
+ BUF_L1 = "svdq_l1"
50
+ BUF_L2 = "svdq_l2"
51
 
52
  _CK_IMPORT_ERROR = None
53
  try:
 
54
  from comfy_kitchen.registry import registry as ck_registry
55
  from comfy_kitchen.tensor.convrot_w4a4 import TensorCoreConvRotW4A4Layout
56
  except Exception as exc: # pragma: no cover - depends on the install
 
57
  ck_registry = None
58
  TensorCoreConvRotW4A4Layout = None
59
  _CK_IMPORT_ERROR = "{}: {}".format(type(exc).__name__, exc)
 
88
 
89
 
90
  def branch_buffers(module):
91
+ """(name, tensor) for every low-rank factor buffer on a module, for summing bytes.
92
+
93
+ Use `branch_factors` when you need l1 and l2 individually -- these come back in
94
+ registration order, which is not something to index positionally.
95
+ """
96
  for name, buf in module.named_buffers(recurse=False):
97
+ if buf is not None and name.startswith("svdq_l"):
98
  yield name, buf
99
 
100
 
101
+ def branch_factors(module):
102
+ """The (l1, l2) pair attached to a module, or None if it has no branch.
103
+
104
+ Keyed by name deliberately. Reading `list(branch_buffers(module))[0]` as l1 happens to
105
+ work today only because the loader registers l1 first; a third factor or a reordering
106
+ would silently swap the two and every derived number would look plausible and be wrong.
107
+ """
108
+ bufs = getattr(module, "_buffers", {})
109
+ l1, l2 = bufs.get(BUF_L1), bufs.get(BUF_L2)
110
+ return None if l1 is None or l2 is None else (l1, l2)
111
+
112
+
113
  def _probe_kwargs(module, tokens: int, device) -> dict:
114
  """Kwargs shaped exactly like a real `convrot_w4a4_linear` call, for validation.
115
 
 
284
  --no-load` and the env-check node come through here.
285
  """
286
  lines = ["torch {} (cuda build {})".format(torch.__version__, torch.version.cuda), ""]
287
+ if _QUANT_OPS_ERROR:
288
+ lines.append("comfy.quant_ops failed to import: {}".format(_QUANT_OPS_ERROR))
289
+ lines.append("No quantized checkpoint can load on this build, and this repo's "
290
+ "quantizer has no formats available. Update ComfyUI.")
291
+ lines.append("")
292
  if ck_registry is None:
293
  lines.append("comfy_kitchen unavailable: {}".format(_CK_IMPORT_ERROR))
294
  return "\n".join(lines)
 
455
  return lines
456
 
457
 
458
+ def _timed(fn, reps: int = 20, warmup: int = 3, label: str = "", failures: list | None = None):
459
+ """Milliseconds per call, CUDA-synchronised. Returns nan if the call raises.
460
+
461
+ A failure is logged at *warning* and recorded in `failures`, not swallowed to DEBUG:
462
+ ComfyUI logs at INFO by default, so a row of bare `nan`s used to arrive with its reason
463
+ discarded -- the opposite of what a diagnostics tool is for.
464
+ """
465
  try:
466
  for _ in range(warmup):
467
  fn()
 
474
  torch.cuda.synchronize()
475
  return (time.perf_counter() - start) * 1000.0 / reps
476
  except Exception as exc:
477
+ logging.warning("[krea2-svdquant] bench call failed (%s): %s", label or "?", exc,
478
+ exc_info=True)
479
+ if failures is not None:
480
+ failures.append((label, "{}: {}".format(type(exc).__name__, exc)))
481
  return float("nan")
482
 
483
 
 
500
  lines.append("{:<44} {:>9} {:>9} {:>9} {:>9}".format(
501
  "layer [in -> out]", "quant ms", "branch ms", "bf16 ms", "quant/bf16"))
502
 
503
+ failures: list[tuple[str, str]] = []
504
  for shape, (name, module) in sorted(_distinct_shapes(patcher.model.diffusion_model).items()):
505
  out_features, in_features = int(shape[0]), int(shape[1])
506
  dtype = module.weight._params.orig_dtype
 
508
  dtype = torch.bfloat16
509
  x = torch.randn((tokens, in_features), dtype=dtype, device=device)
510
 
511
+ quant_ms = _timed(lambda: F.linear(x, module.weight),
512
+ label="{} quant".format(name), failures=failures)
513
 
514
+ factors = branch_factors(module)
515
+ if factors is None:
 
 
 
 
516
  branch_ms = float("nan")
517
+ failures.append(("{} branch".format(name), "no svdq_l1/svdq_l2 on this module"))
518
+ else:
519
+ l1, l2 = factors
520
+ a1 = l1.to(device=device, dtype=dtype)
521
+ a2 = l2.to(device=device, dtype=dtype)
522
+ branch_ms = _timed(lambda: F.linear(F.linear(x, a2), a1),
523
+ label="{} branch".format(name), failures=failures)
524
+ del a1, a2
525
 
526
  try:
527
  dense = module.weight.dequantize().to(dtype)
528
+ bf16_ms = _timed(lambda: F.linear(x, dense),
529
+ label="{} bf16".format(name), failures=failures)
530
  del dense
531
+ except Exception as exc:
532
+ logging.warning("[krea2-svdquant] could not dequantize %s for the bf16 reference: %s",
533
+ name, exc, exc_info=True)
534
+ failures.append(("{} bf16".format(name),
535
+ "dequantize failed: {}: {}".format(type(exc).__name__, exc)))
536
  bf16_ms = float("nan")
537
 
538
  ratio = quant_ms / bf16_ms if bf16_ms == bf16_ms and bf16_ms > 0 else float("nan")
 
546
  lines.append("")
547
  lines.append("quant/bf16 < 1.0 means the int4 kernel is winning. Above 1.0 means the "
548
  "quantized path is being emulated -- check mode=dispatch.")
549
+ if failures:
550
+ # Every nan above has to be accountable here. A bench table pasted into an issue is
551
+ # useless if a column of nans carries no reason with it.
552
+ lines.append("")
553
+ lines.append("failed measurements ({}):".format(len(failures)))
554
+ for label, reason in failures:
555
+ lines.append(" {:<40} {}".format(label[:40], reason))
556
  return lines
557
 
558
 
 
622
  }
623
  }
624
 
625
+ @classmethod
626
+ def IS_CHANGED(cls, *args, **kwargs):
627
+ # Same reasoning as Env Check: this measures the live process (mode=bench times real
628
+ # kernels), so a cached report would be a report about a previous run.
629
+ return float("nan")
630
+
631
  RETURN_TYPES = ("MODEL", "STRING")
632
  RETURN_NAMES = ("model", "report")
633
  OUTPUT_TOOLTIPS = ("The model, unchanged - wire it on to your sampler.",
svdquant_lora.py CHANGED
@@ -202,8 +202,10 @@ class Krea2SVDQuantLoraLoader:
202
  FUNCTION = "load_lora"
203
  CATEGORY = _CATEGORY
204
  TITLE = "Krea2 SVDQuant LoRA Loader"
205
- DESCRIPTION = ("Applies a LoRA to a Krea2 W4A4 quantized model. The standard LoRA "
206
- "loader silently skips the quantized layers on these models.")
 
 
207
 
208
  def load_lora(self, model, lora_name, strength):
209
  if strength == 0:
 
202
  FUNCTION = "load_lora"
203
  CATEGORY = _CATEGORY
204
  TITLE = "Krea2 SVDQuant LoRA Loader"
205
+ DESCRIPTION = ("Applies a LoRA to a Krea2 W4A4 quantized model as a parallel low-rank "
206
+ "branch, leaving the 4-bit weight untouched. The stock loader has to "
207
+ "dequantize, add and requantize, which puts the LoRA delta through 4-bit "
208
+ "quantization along with the weight.")
209
 
210
  def load_lora(self, model, lora_name, strength):
211
  if strength == 0:
svdquant_quantize.py CHANGED
@@ -60,9 +60,9 @@ class Krea2SVDQuantQuantize:
60
  "rank": ("INT", {
61
  "default": 64, "min": 8, "max": 1024, "step": 8,
62
  "tooltip": "svdq only: size of the low-rank branch. Only pays off with "
63
- "refine_iters > 0 - measured LPIPS falls monotonically with "
64
- "rank when refining and is flat without it. Each doubling buys "
65
- "about 0.013 LPIPS.",
66
  }),
67
  "rank_alloc": (["uniform", "gqa"], {
68
  "default": "uniform",
@@ -104,9 +104,28 @@ class Krea2SVDQuantQuantize:
104
  "tooltip": "Off means an existing file of the same name is an error "
105
  "rather than 8 GB written over your last run.",
106
  }),
107
- }
 
 
 
 
 
 
 
 
 
 
 
 
108
  }
109
 
 
 
 
 
 
 
 
110
  RETURN_TYPES = ("STRING",)
111
  RETURN_NAMES = ("summary",)
112
  OUTPUT_TOOLTIPS = ("Where the checkpoint was written, and what went into it.",)
@@ -120,7 +139,7 @@ class Krea2SVDQuantQuantize:
120
  "Krea2 SVDQuant W4A4 Loader (svdq) or the stock UNETLoader (w4a4/int8/fp8).")
121
 
122
  def run(self, source_model, format, rank, rank_alloc, refine_iters, groupsize, variant,
123
- output_name, overwrite):
124
  src = folder_paths.get_full_path_or_raise("diffusion_models", source_model)
125
 
126
  # `rank` always carries a value from the widget, so "was it set?" cannot be inferred
@@ -128,13 +147,25 @@ class Krea2SVDQuantQuantize:
128
  # erroring, which is the friendlier reading of a dropdown the user cannot un-set.
129
  fmt, rank = resolve_format(format, rank, rank_was_set=False)
130
 
 
 
 
 
 
 
 
 
 
 
 
 
131
  if output_name.strip():
132
  name = output_name.strip()
133
  if not name.endswith(".safetensors"):
134
  name += ".safetensors"
135
  dst = os.path.join(os.path.dirname(src), name)
136
  else:
137
- dst, note = derive_out_path(src, format, rank, variant, rank_alloc)
138
  if note:
139
  logging.info("[krea2-svdquant] %s", note)
140
 
@@ -165,11 +196,12 @@ class Krea2SVDQuantQuantize:
165
  pbar.update_absolute(done, total)
166
 
167
  logging.info("[krea2-svdquant] quantizing %s -> %s (format %s, rank %s/%s, "
168
- "refine_iters %s)", src, dst, fmt, rank, rank_alloc,
169
- refine_iters if rank else 0)
170
  summary = convert(src, dst, fmt, groupsize, "cuda", rank, refine_iters,
171
  variant=variant, progress_cb=progress,
172
- rank_alloc=rank_alloc if rank else "uniform")
 
173
 
174
  hint = SAMPLER_HINTS.get(variant)
175
  loader = ("Krea2 SVDQuant W4A4 Loader" if rank else "the stock UNETLoader")
 
60
  "rank": ("INT", {
61
  "default": 64, "min": 8, "max": 1024, "step": 8,
62
  "tooltip": "svdq only: size of the low-rank branch. Only pays off with "
63
+ "refine_iters > 0. Without a LoRA, 64 / 128 / 256 measure the "
64
+ "same, so 64 is enough. With a LoRA loaded, 256 wins clearly "
65
+ "and 64 loses most of its advantage - so 256 if you use LoRAs.",
66
  }),
67
  "rank_alloc": (["uniform", "gqa"], {
68
  "default": "uniform",
 
104
  "tooltip": "Off means an existing file of the same name is an error "
105
  "rather than 8 GB written over your last run.",
106
  }),
107
+ },
108
+ # Optional so workflows saved before this input existed keep validating.
109
+ "optional": {
110
+ "act_stats": ("STRING", {
111
+ "default": "",
112
+ "tooltip": "svdq only: an activation-statistics file from the Capture "
113
+ "nodes (a bare filename is looked up in ComfyUI/output/). "
114
+ "Fits the low-rank branch against measured per-channel "
115
+ "activation energy instead of assuming it is uniform. Free at "
116
+ "inference and the best-measured setting here - LPIPS to BF16 "
117
+ "0.3378 to 0.2825 with no LoRA. Empty means the plain objective.",
118
+ }),
119
+ },
120
  }
121
 
122
+ @classmethod
123
+ def IS_CHANGED(cls, *args, **kwargs):
124
+ # Writes an ~8 GB file as its side effect, so a cached summary would claim a file
125
+ # exists that the user may have since deleted. Re-queueing is cheap to refuse
126
+ # (overwrite=False still fails fast) and expensive to get wrong.
127
+ return float("nan")
128
+
129
  RETURN_TYPES = ("STRING",)
130
  RETURN_NAMES = ("summary",)
131
  OUTPUT_TOOLTIPS = ("Where the checkpoint was written, and what went into it.",)
 
139
  "Krea2 SVDQuant W4A4 Loader (svdq) or the stock UNETLoader (w4a4/int8/fp8).")
140
 
141
  def run(self, source_model, format, rank, rank_alloc, refine_iters, groupsize, variant,
142
+ output_name, overwrite, act_stats=""):
143
  src = folder_paths.get_full_path_or_raise("diffusion_models", source_model)
144
 
145
  # `rank` always carries a value from the widget, so "was it set?" cannot be inferred
 
147
  # erroring, which is the friendlier reading of a dropdown the user cannot un-set.
148
  fmt, rank = resolve_format(format, rank, rank_was_set=False)
149
 
150
+ # Same validation the CLI does for --act-stats: a typed path that silently did nothing
151
+ # would produce a checkpoint indistinguishable from a plain one.
152
+ stats_path = act_stats.strip() or None
153
+ if stats_path is not None:
154
+ if format != "svdq":
155
+ raise RuntimeError("act_stats only applies to format 'svdq': it weights the "
156
+ "low-rank branch, and the other formats have no branch.")
157
+ if not os.path.isabs(stats_path):
158
+ stats_path = os.path.join(folder_paths.get_output_directory(), stats_path)
159
+ if not os.path.isfile(stats_path):
160
+ raise RuntimeError("act_stats file not found: {}".format(stats_path))
161
+
162
  if output_name.strip():
163
  name = output_name.strip()
164
  if not name.endswith(".safetensors"):
165
  name += ".safetensors"
166
  dst = os.path.join(os.path.dirname(src), name)
167
  else:
168
+ dst, note = derive_out_path(src, format, rank, variant, rank_alloc, stats_path)
169
  if note:
170
  logging.info("[krea2-svdquant] %s", note)
171
 
 
196
  pbar.update_absolute(done, total)
197
 
198
  logging.info("[krea2-svdquant] quantizing %s -> %s (format %s, rank %s/%s, "
199
+ "refine_iters %s, act_stats %s)", src, dst, fmt, rank, rank_alloc,
200
+ refine_iters if rank else 0, stats_path or "none")
201
  summary = convert(src, dst, fmt, groupsize, "cuda", rank, refine_iters,
202
  variant=variant, progress_cb=progress,
203
+ rank_alloc=rank_alloc if rank else "uniform",
204
+ act_stats=stats_path)
205
 
206
  hint = SAMPLER_HINTS.get(variant)
207
  loader = ("Krea2 SVDQuant W4A4 Loader" if rank else "the stock UNETLoader")
svdquant_w4a4.py CHANGED
@@ -1,322 +1,303 @@
1
- """Loader for SVDQuant-on-native-W4A4 checkpoints (built by ``quantize_krea2.py``).
2
-
3
- This is SVDQuant's mechanism (low-rank bf16 branch + 4-bit residual) running on ComfyUI's
4
- own ``convrot_w4a4`` kernel. Because the *activations* are 4-bit here too, the matmul runs
5
- on hardware that is genuinely faster than bf16 -- weight-only 4-bit schemes keep 16-bit
6
- activations and therefore still run at bf16 tensor-core speed.
7
-
8
- The checkpoint is self-contained - it carries the quantized blocks *and* the untouched
9
- high-precision layers - so no separate base file is needed. Everything except the 224
10
- block linears loads through ComfyUI's normal path; only those 224 get a low-rank branch
11
- attached on top of the native quantized Linear.
12
- """
13
-
14
- from __future__ import annotations
15
-
16
- import logging
17
-
18
- import torch
19
- import torch.nn.functional as F
20
-
21
- import comfy.model_management
22
- import comfy.sd
23
- import comfy.utils
24
- import folder_paths
25
-
26
- from .svdquant_diag import _CATEGORY, log_dispatch
27
-
28
- _L1 = ".svdq_l1"
29
- _L2 = ".svdq_l2"
30
-
31
- # Buffer names, chosen to match the on-disk keys exactly: a buffer called ``svdq_l1`` on
32
- # ``blocks.0.attn.wq`` produces the state-dict key ``blocks.0.attn.wq.svdq_l1``, which is
33
- # byte-identical to what quantize_krea2.py writes. So a model re-saved out of ComfyUI
34
- # round-trips straight back into this loader.
35
- _BUF_L1 = "svdq_l1"
36
- _BUF_L2 = "svdq_l2"
37
-
38
- # Checkpoints ship either bare ("blocks.0...") or prefixed ("model.diffusion_model.blocks.0...").
39
- # `comfy.sd.load_diffusion_model_state_dict` strips this prefix internally when it builds the
40
- # module tree, but we walk that tree ourselves to attach branches, so we have to strip it too.
41
- _LAYER_PREFIXES = ("model.diffusion_model.", "diffusion_model.", "")
42
-
43
-
44
- def _detect_layer_prefix(keys) -> str:
45
- for prefix in _LAYER_PREFIXES:
46
- if any(k.startswith("{}blocks.".format(prefix)) for k in keys):
47
- return prefix
48
- return ""
49
-
50
-
51
- def has_branch(module: torch.nn.Module) -> bool:
52
- """True once this module carries a low-rank branch (i.e. it is a quantized linear)."""
53
- return _BUF_L1 in getattr(module, "_buffers", {})
54
-
55
-
56
- def branch_factors(module: torch.nn.Module):
57
- """The (l1, l2) pair attached to a module, or None."""
58
- bufs = getattr(module, "_buffers", {})
59
- l1, l2 = bufs.get(_BUF_L1), bufs.get(_BUF_L2)
60
- return None if l1 is None or l2 is None else (l1, l2)
61
-
62
-
63
- def add_low_rank(y: torch.Tensor, x: torch.Tensor, l1: torch.Tensor, l2: torch.Tensor):
64
- """``y + (x @ l2.T) @ l1.T``, with l1/l2 moved to x's device and dtype as needed.
65
-
66
- `comfy.model_management.cast_to` returns the tensor untouched when it is already in
67
- the right place, so this is free on a fully-resident model. When ComfyUI has offloaded
68
- the layer, it performs the same kind of per-call staging copy that ComfyUI itself does
69
- for the quantized weight -- crucially *without* caching the result back onto the
70
- module, which would strand the factors on the GPU behind ComfyUI's back.
71
- """
72
- a1 = comfy.model_management.cast_to(l1, x.dtype, x.device)
73
- a2 = comfy.model_management.cast_to(l2, x.dtype, x.device)
74
- return y + F.linear(F.linear(x, a2), a1)
75
-
76
-
77
- def _publish_in_state_dict(module: torch.nn.Module) -> None:
78
- """Make the branch buffers visible to ``state_dict()`` on a quantized Linear.
79
-
80
- Registering them as persistent buffers is not enough. ComfyUI's quantized Linear
81
- (``comfy.ops.mixed_precision_ops``) replaces ``state_dict`` wholesale with a body that
82
- emits weight/scale/marker/bias and nothing else -- buffers never reach it. That
83
- matters because ``model_management.module_size()`` sums ``state_dict()``, and every
84
- per-module VRAM decision ComfyUI makes (the lowvram split in particular) is derived
85
- from that number. Left alone, ~2.9 MB per layer and ~645 MB across the 224 blocks
86
- would sit on the GPU while the budget believed it was free -- which is exactly how an
87
- 8 GB card OOMs on this checkpoint but not on the branch-free int8 one.
88
-
89
- Emitting them under their own names also means a model saved out of ComfyUI carries
90
- the same ``<layer>.svdq_l1`` keys quantize_krea2.py writes, so it round-trips.
91
- """
92
- if getattr(module, "_krea2_state_dict_patched", False):
93
- return
94
- inner = module.state_dict
95
-
96
- def state_dict(*args, destination=None, prefix="", **kwargs):
97
- sd = inner(*args, destination=destination, prefix=prefix, **kwargs)
98
- for name in (_BUF_L1, _BUF_L2):
99
- buf = module._buffers.get(name)
100
- if buf is not None:
101
- sd["{}{}".format(prefix, name)] = buf
102
- return sd
103
-
104
- module.state_dict = state_dict
105
- module._krea2_state_dict_patched = True
106
-
107
-
108
- def attach_branch(module: torch.nn.Module, l1: torch.Tensor, l2: torch.Tensor,
109
- scale: float = 1.0) -> None:
110
- """Add ``+ (x @ l2.T) @ l1.T * scale`` to a module's output, in place.
111
-
112
- The module is *not* replaced: swapping it for a wrapper would push its weight down a
113
- level in the state dict (``blocks.0.attn.wq.base.weight``), and every LoRA key map in
114
- ComfyUI expects ``blocks.0.attn.wq.weight``. Keeping the module identity keeps those
115
- paths - and therefore the rest of the ecosystem - intact.
116
-
117
- The factors are registered as persistent buffers *and* published into ``state_dict()``
118
- by `_publish_in_state_dict` -- on these modules persistence alone is not enough, see
119
- that function for why. Both steps are needed to get them counted by
120
- ``model_management.module_size()``, which is what every VRAM decision (full load, the
121
- lowvram split, how much to free) is derived from. Uncounted, they are roughly 2.9 MB
122
- per layer and 645 MB across the 224 blocks: the difference between fitting and OOMing
123
- on an 8 GB card.
124
-
125
- `scale` is folded into l2 at attach time rather than applied to the output every step:
126
- l2 is [rank, in_features] while the output is [tokens, out_features], so this is about
127
- three orders of magnitude less work and one fewer full-size allocation per call.
128
- """
129
- if has_branch(module):
130
- raise RuntimeError("module already carries a low-rank branch")
131
-
132
- if scale != 1.0:
133
- l2 = l2 * scale
134
- module.register_buffer(_BUF_L1, l1.contiguous(), persistent=True)
135
- module.register_buffer(_BUF_L2, l2.contiguous(), persistent=True)
136
- _publish_in_state_dict(module)
137
-
138
- original = module.forward
139
-
140
- def forward(x, *args, **kwargs):
141
- y = original(x, *args, **kwargs)
142
- factors = branch_factors(module)
143
- if factors is None:
144
- return y
145
- return add_low_rank(y, x, *factors)
146
-
147
- module.forward = forward
148
- # Kept as a stable handle so a LoRA can build on top of "quantized weight + svdq
149
- # branch" without having to trust whatever is currently in `module.forward` -- which
150
- # ComfyUI's object-patch machinery swaps in and out around sampling.
151
- module._krea2_forward = forward
152
-
153
-
154
- def _get_submodule(root: torch.nn.Module, dotted: str) -> torch.nn.Module:
155
- """Walk a dotted path, reporting the layer name rather than the raw attribute error.
156
-
157
- Left to `getattr`/`__getitem__` this surfaces as a bare ``AttributeError: 'ModuleList'
158
- object has no attribute 'nope'`` or ``IndexError: index 999 is out of range``, which says
159
- nothing about which checkpoint key failed to map.
160
- """
161
- module = root
162
- for i, p in enumerate(dotted.split(".")):
163
- try:
164
- module = module[int(p)] if p.isdigit() else getattr(module, p)
165
- except (AttributeError, IndexError, KeyError) as exc:
166
- raise RuntimeError(
167
- "checkpoint refers to layer {!r}, which this model does not have "
168
- "(failed at {!r}): {}".format(dotted, ".".join(dotted.split(".")[:i + 1]), exc)
169
- ) from exc
170
- return module
171
-
172
-
173
- def _shield_from_dynamo(module: torch.nn.Module) -> None:
174
- """Let torch.compile skip the quantized kernel instead of failing on it.
175
-
176
- Dynamo cannot trace ``F.linear(x, QuantizedTensor)`` -- the comfy_kitchen kernel is
177
- not registered as an opaque custom op, so fake-tensor tracing raises. Marking the
178
- call as a graph break lets inductor still fuse everything around it (norms,
179
- modulation, RoPE), which is a third of the step time.
180
-
181
- Call order matters and is easy to get backwards: this must run *before*
182
- `attach_branch`, so that what gets wrapped is the real `nn.Linear.forward` and the
183
- branch closure installed on top of it stays traceable. Dynamo then breaks at the
184
- kernel call and still compiles the two low-rank GEMMs around it. Shielding after
185
- `attach_branch` would wrap the branch as well and hand inductor nothing.
186
- """
187
- try:
188
- module.forward = torch._dynamo.disable(module.forward)
189
- except Exception as exc:
190
- # Not fatal on its own -- the model runs fine uncompiled. But if this silently
191
- # no-ops, a later TorchCompileModel dies inside the comfy_kitchen kernel with a
192
- # fake-tensor error that points nowhere near here, so leave a trail.
193
- logging.debug("[krea2-svdquant] could not shield %s from dynamo: %s",
194
- type(module).__name__, exc)
195
-
196
-
197
- def load_svdquant_w4a4(path: str, model_options: dict | None = None,
198
- compile_safe: bool = True):
199
- sd, metadata = comfy.utils.load_torch_file(path, return_metadata=True)
200
- layer_prefix = _detect_layer_prefix(sd.keys())
201
-
202
- branches: dict[str, dict[str, torch.Tensor]] = {}
203
- for key in list(sd.keys()):
204
- for suffix, slot in ((_L1, "l1"), (_L2, "l2")):
205
- if key.endswith(suffix):
206
- branches.setdefault(key[: -len(suffix)], {})[slot] = sd.pop(key)
207
- break
208
- if not branches:
209
- raise ValueError(
210
- "{} carries no svdq_l1/svdq_l2 tensors - it is a plain quantized checkpoint, "
211
- "load it with UNETLoader instead".format(path)
212
- )
213
-
214
- # `disable_dynamic=True` pins this to the classic ModelPatcher. On current ComfyUI
215
- # that is a no-op (`CoreModelPatcher is ModelPatcher`), but when upstream flips it to
216
- # ModelPatcherDynamic the streaming patcher takes ownership of the weights via
217
- # `load_model_weights(..., assign=patcher.is_dynamic())`, which we have not validated
218
- # against the branch buffers. Keep it pinned until that path is tested; the
219
- # diagnostics node reports which patcher is actually in use.
220
- patcher = comfy.sd.load_diffusion_model_state_dict(
221
- sd, model_options=model_options or {}, metadata=metadata, disable_dynamic=True
222
- )
223
- if patcher is None:
224
- raise RuntimeError("could not detect a model in {}".format(path))
225
-
226
- diffusion_model = patcher.model.diffusion_model
227
- attached = 0
228
- ranks: set[int] = set()
229
- incomplete = []
230
- for layer, parts in branches.items():
231
- if "l1" not in parts or "l2" not in parts:
232
- incomplete.append(layer)
233
- continue
234
- submodule_path = layer[len(layer_prefix):] if layer_prefix else layer
235
- base = _get_submodule(diffusion_model, submodule_path)
236
- if compile_safe:
237
- _shield_from_dynamo(base)
238
- attach_branch(base, parts["l1"], parts["l2"])
239
- # Collected per layer rather than read once off the first branch, so a checkpoint
240
- # with a non-uniform rank budget reports honestly instead of quoting layer zero.
241
- ranks.add(int(parts["l1"].shape[1]))
242
- attached += 1
243
-
244
- # Silently returning a patcher with no branches would hand back a plain quantized model
245
- # dressed as an SVDQuant one -- same class of failure quantize_krea2.py hard-fails on.
246
- if attached == 0:
247
- raise RuntimeError(
248
- "{}: found {} svdq_l1/svdq_l2 key pairs but attached none of them"
249
- "{}. The checkpoint's layer names do not line up with this model "
250
- "(detected prefix {!r}).".format(
251
- path, len(branches),
252
- "; {} were missing their other half".format(len(incomplete))
253
- if incomplete else "",
254
- layer_prefix)
255
- )
256
-
257
- # The branch buffers were registered after the patcher computed (and cached) its size,
258
- # so drop the cache and let `model_size()` re-derive it from the state dict.
259
- patcher.size = 0
260
-
261
- # Metadata is a newer addition; checkpoints published before it still load, with the
262
- # rank recovered from the factor shape exactly as before. The shapes are the ground
263
- # truth, so they win over a metadata value that disagrees with them.
264
- meta = metadata or {}
265
- rank_desc = (str(next(iter(ranks))) if len(ranks) == 1
266
- else "{}-{} mixed".format(min(ranks), max(ranks)))
267
- meta_rank = meta.get("krea2_svdquant_rank")
268
- if meta_rank and len(ranks) == 1 and int(meta_rank) != next(iter(ranks)):
269
- logging.warning("[krea2-svdquant] metadata says rank %s but the factors are rank %s; "
270
- "trusting the factors", meta_rank, rank_desc)
271
- variant = meta.get("krea2_svdquant_variant", "unknown")
272
- summary = ("w4a4 + low-rank: attached {} branches (rank {}, variant {}), "
273
- "model_size {:.2f} GiB".format(
274
- attached, rank_desc, variant, patcher.model_size() / 1024 ** 3))
275
- logging.info("[krea2-svdquant] %s", summary)
276
-
277
- dispatch = log_dispatch(diffusion_model)
278
-
279
- # Stashed rather than returned so callers that just want the model (diagnose.py, the
280
- # head-to-head scripts) keep working unchanged. The node surfaces it in the UI, which
281
- # matters most for the dispatch warning: buried in the console, the people who most need
282
- # to read it are exactly the ones who never see it.
283
- patcher.krea2_load_summary = "\n".join(x for x in (summary, dispatch) if x)
284
- return patcher
285
-
286
-
287
- class Krea2SVDQuantW4A4Loader:
288
- @classmethod
289
- def INPUT_TYPES(cls):
290
- return {
291
- "required": {
292
- "model_name": (folder_paths.get_filename_list("diffusion_models"), {
293
- "tooltip": "A checkpoint from quantize_krea2.py --format svdq (it carries "
294
- "*.svdq_l1/*.svdq_l2 tensors). The --format w4a4 / int8 / fp8 "
295
- "checkpoints have no branch and load with the stock UNETLoader "
296
- "instead.",
297
- }),
298
- }
299
- }
300
-
301
- RETURN_TYPES = ("MODEL", "STRING")
302
- RETURN_NAMES = ("model", "status")
303
- OUTPUT_TOOLTIPS = ("Wire this to a KSampler.",
304
- "Rank, variant, size and which kernel the quantized layers will "
305
- "actually dispatch to. Read this if generation is slow.")
306
- OUTPUT_NODE = True
307
- FUNCTION = "load"
308
- CATEGORY = _CATEGORY
309
- TITLE = "Krea2 SVDQuant W4A4 Loader"
310
- DESCRIPTION = ("Loads a W4A4 + low-rank (SVDQuant) Krea2 checkpoint. Self-contained: "
311
- "no separate base model needed. The status output tells you whether the "
312
- "fast int4 kernel is in play.")
313
-
314
- def load(self, model_name):
315
- path = folder_paths.get_full_path_or_raise("diffusion_models", model_name)
316
- patcher = load_svdquant_w4a4(path)
317
- status = getattr(patcher, "krea2_load_summary", "")
318
- return {"ui": {"text": [status]}, "result": (patcher, status)}
319
-
320
-
321
- NODE_CLASS_MAPPINGS = {"Krea2SVDQuantW4A4Loader": Krea2SVDQuantW4A4Loader}
322
- NODE_DISPLAY_NAME_MAPPINGS = {"Krea2SVDQuantW4A4Loader": "Krea2 SVDQuant W4A4 Loader"}
 
1
+ """Loader for SVDQuant-on-native-W4A4 checkpoints (built by ``quantize_krea2.py``).
2
+
3
+ This is SVDQuant's mechanism (low-rank bf16 branch + 4-bit residual) running on ComfyUI's
4
+ own ``convrot_w4a4`` kernel. Because the *activations* are 4-bit here too, the matmul runs
5
+ on hardware that is genuinely faster than bf16 -- weight-only 4-bit schemes keep 16-bit
6
+ activations and therefore still run at bf16 tensor-core speed.
7
+
8
+ The checkpoint is self-contained - it carries the quantized blocks *and* the untouched
9
+ high-precision layers - so no separate base file is needed. Everything except the 224
10
+ block linears loads through ComfyUI's normal path; only those 224 get a low-rank branch
11
+ attached on top of the native quantized Linear.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import logging
17
+
18
+ import torch
19
+ import torch.nn.functional as F
20
+
21
+ import comfy.model_management
22
+ import comfy.sd
23
+ import comfy.utils
24
+ import folder_paths
25
+
26
+ from .quantize_krea2 import detect_prefix
27
+ from .svdquant_diag import BUF_L1, BUF_L2, _CATEGORY, branch_factors, log_dispatch # noqa: F401
28
+
29
+ # The checkpoint keys are the buffer names with a dot in front -- derived rather than
30
+ # retyped, because the two being identical is the property the round-trip depends on.
31
+ _L1 = "." + BUF_L1
32
+ _L2 = "." + BUF_L2
33
+
34
+
35
+ def has_branch(module: torch.nn.Module) -> bool:
36
+ """True once this module carries a low-rank branch (i.e. it is a quantized linear)."""
37
+ return BUF_L1 in getattr(module, "_buffers", {})
38
+
39
+
40
+ def add_low_rank(y: torch.Tensor, x: torch.Tensor, l1: torch.Tensor, l2: torch.Tensor):
41
+ """``y + (x @ l2.T) @ l1.T``, with l1/l2 moved to x's device and dtype as needed.
42
+
43
+ `comfy.model_management.cast_to` returns the tensor untouched when it is already in
44
+ the right place, so this is free on a fully-resident model. When ComfyUI has offloaded
45
+ the layer, it performs the same kind of per-call staging copy that ComfyUI itself does
46
+ for the quantized weight -- crucially *without* caching the result back onto the
47
+ module, which would strand the factors on the GPU behind ComfyUI's back.
48
+ """
49
+ a1 = comfy.model_management.cast_to(l1, x.dtype, x.device)
50
+ a2 = comfy.model_management.cast_to(l2, x.dtype, x.device)
51
+ return y + F.linear(F.linear(x, a2), a1)
52
+
53
+
54
+ def _publish_in_state_dict(module: torch.nn.Module) -> None:
55
+ """Make the branch buffers visible to ``state_dict()`` on a quantized Linear.
56
+
57
+ Registering them as persistent buffers is not enough. ComfyUI's quantized Linear
58
+ (``comfy.ops.mixed_precision_ops``) replaces ``state_dict`` wholesale with a body that
59
+ emits weight/scale/marker/bias and nothing else -- buffers never reach it. That
60
+ matters because ``model_management.module_size()`` sums ``state_dict()``, and every
61
+ per-module VRAM decision ComfyUI makes (the lowvram split in particular) is derived
62
+ from that number. Left alone, ~2.9 MB per layer and ~645 MB across the 224 blocks
63
+ would sit on the GPU while the budget believed it was free -- which is exactly how an
64
+ 8 GB card OOMs on this checkpoint but not on the branch-free int8 one.
65
+
66
+ Emitting them under their own names also means a model saved out of ComfyUI carries
67
+ the same ``<layer>.svdq_l1`` keys quantize_krea2.py writes, so it round-trips.
68
+ """
69
+ if getattr(module, "_krea2_state_dict_patched", False):
70
+ return
71
+ inner = module.state_dict
72
+
73
+ def state_dict(*args, destination=None, prefix="", **kwargs):
74
+ sd = inner(*args, destination=destination, prefix=prefix, **kwargs)
75
+ for name in (BUF_L1, BUF_L2):
76
+ buf = module._buffers.get(name)
77
+ if buf is not None:
78
+ sd["{}{}".format(prefix, name)] = buf
79
+ return sd
80
+
81
+ module.state_dict = state_dict
82
+ module._krea2_state_dict_patched = True
83
+
84
+
85
+ def attach_branch(module: torch.nn.Module, l1: torch.Tensor, l2: torch.Tensor,
86
+ scale: float = 1.0) -> None:
87
+ """Add ``+ (x @ l2.T) @ l1.T * scale`` to a module's output, in place.
88
+
89
+ The module is *not* replaced: swapping it for a wrapper would push its weight down a
90
+ level in the state dict (``blocks.0.attn.wq.base.weight``), and every LoRA key map in
91
+ ComfyUI expects ``blocks.0.attn.wq.weight``. Keeping the module identity keeps those
92
+ paths - and therefore the rest of the ecosystem - intact.
93
+
94
+ The factors are registered as persistent buffers *and* published into ``state_dict()``
95
+ by `_publish_in_state_dict` -- on these modules persistence alone is not enough, see
96
+ that function for why. Both steps are needed to get them counted by
97
+ ``model_management.module_size()``, which is what every VRAM decision (full load, the
98
+ lowvram split, how much to free) is derived from. Uncounted, they are roughly 2.9 MB
99
+ per layer and 645 MB across the 224 blocks: the difference between fitting and OOMing
100
+ on an 8 GB card.
101
+
102
+ `scale` is folded into l2 at attach time rather than applied to the output every step:
103
+ l2 is [rank, in_features] while the output is [tokens, out_features], so this is about
104
+ three orders of magnitude less work and one fewer full-size allocation per call.
105
+ """
106
+ if has_branch(module):
107
+ raise RuntimeError("module already carries a low-rank branch")
108
+
109
+ if scale != 1.0:
110
+ l2 = l2 * scale
111
+ module.register_buffer(BUF_L1, l1.contiguous(), persistent=True)
112
+ module.register_buffer(BUF_L2, l2.contiguous(), persistent=True)
113
+ _publish_in_state_dict(module)
114
+
115
+ original = module.forward
116
+
117
+ def forward(x, *args, **kwargs):
118
+ y = original(x, *args, **kwargs)
119
+ factors = branch_factors(module)
120
+ if factors is None:
121
+ return y
122
+ return add_low_rank(y, x, *factors)
123
+
124
+ module.forward = forward
125
+ # Kept as a stable handle so a LoRA can build on top of "quantized weight + svdq
126
+ # branch" without having to trust whatever is currently in `module.forward` -- which
127
+ # ComfyUI's object-patch machinery swaps in and out around sampling.
128
+ module._krea2_forward = forward
129
+
130
+
131
+ def _get_submodule(root: torch.nn.Module, dotted: str) -> torch.nn.Module:
132
+ """Walk a dotted path, reporting the layer name rather than the raw attribute error.
133
+
134
+ Left to `getattr`/`__getitem__` this surfaces as a bare ``AttributeError: 'ModuleList'
135
+ object has no attribute 'nope'`` or ``IndexError: index 999 is out of range``, which says
136
+ nothing about which checkpoint key failed to map.
137
+ """
138
+ module = root
139
+ for i, p in enumerate(dotted.split(".")):
140
+ try:
141
+ module = module[int(p)] if p.isdigit() else getattr(module, p)
142
+ except (AttributeError, IndexError, KeyError) as exc:
143
+ raise RuntimeError(
144
+ "checkpoint refers to layer {!r}, which this model does not have "
145
+ "(failed at {!r}): {}".format(dotted, ".".join(dotted.split(".")[:i + 1]), exc)
146
+ ) from exc
147
+ return module
148
+
149
+
150
+ def _shield_from_dynamo(module: torch.nn.Module) -> None:
151
+ """Let torch.compile skip the quantized kernel instead of failing on it.
152
+
153
+ Dynamo cannot trace ``F.linear(x, QuantizedTensor)`` -- the comfy_kitchen kernel is
154
+ not registered as an opaque custom op, so fake-tensor tracing raises. Marking the
155
+ call as a graph break lets inductor still fuse everything around it (norms,
156
+ modulation, RoPE), which is a third of the step time.
157
+
158
+ Call order matters and is easy to get backwards: this must run *before*
159
+ `attach_branch`, so that what gets wrapped is the real `nn.Linear.forward` and the
160
+ branch closure installed on top of it stays traceable. Dynamo then breaks at the
161
+ kernel call and still compiles the two low-rank GEMMs around it. Shielding after
162
+ `attach_branch` would wrap the branch as well and hand inductor nothing.
163
+ """
164
+ try:
165
+ module.forward = torch._dynamo.disable(module.forward)
166
+ except Exception as exc:
167
+ # Not fatal on its own -- the model runs fine uncompiled. But if this silently
168
+ # no-ops, a later TorchCompileModel dies inside the comfy_kitchen kernel with a
169
+ # fake-tensor error that points nowhere near here, so leave a trail.
170
+ logging.debug("[krea2-svdquant] could not shield %s from dynamo: %s",
171
+ type(module).__name__, exc)
172
+
173
+
174
+ def load_svdquant_w4a4(path: str, model_options: dict | None = None,
175
+ compile_safe: bool = True):
176
+ sd, metadata = comfy.utils.load_torch_file(path, return_metadata=True)
177
+ # `comfy.sd.load_diffusion_model_state_dict` strips this prefix internally when it builds
178
+ # the module tree, but we walk that tree ourselves to attach branches, so we strip it too.
179
+ # `default=""` rather than raising: a loader must not blow up on a checkpoint with no
180
+ # blocks, and the "found no branches" error below says far more about what went wrong.
181
+ layer_prefix = detect_prefix(sd.keys(), default="")
182
+
183
+ branches: dict[str, dict[str, torch.Tensor]] = {}
184
+ for key in list(sd.keys()):
185
+ for suffix, slot in ((_L1, "l1"), (_L2, "l2")):
186
+ if key.endswith(suffix):
187
+ branches.setdefault(key[: -len(suffix)], {})[slot] = sd.pop(key)
188
+ break
189
+ if not branches:
190
+ raise ValueError(
191
+ "{} carries no svdq_l1/svdq_l2 tensors - it is a plain quantized checkpoint, "
192
+ "load it with UNETLoader instead".format(path)
193
+ )
194
+
195
+ # `disable_dynamic=True` pins this to the classic ModelPatcher. On current ComfyUI
196
+ # that is a no-op (`CoreModelPatcher is ModelPatcher`), but when upstream flips it to
197
+ # ModelPatcherDynamic the streaming patcher takes ownership of the weights via
198
+ # `load_model_weights(..., assign=patcher.is_dynamic())`, which we have not validated
199
+ # against the branch buffers. Keep it pinned until that path is tested; the
200
+ # diagnostics node reports which patcher is actually in use.
201
+ patcher = comfy.sd.load_diffusion_model_state_dict(
202
+ sd, model_options=model_options or {}, metadata=metadata, disable_dynamic=True
203
+ )
204
+ if patcher is None:
205
+ raise RuntimeError("could not detect a model in {}".format(path))
206
+
207
+ diffusion_model = patcher.model.diffusion_model
208
+ attached = 0
209
+ ranks: set[int] = set()
210
+ incomplete = []
211
+ for layer, parts in branches.items():
212
+ if "l1" not in parts or "l2" not in parts:
213
+ incomplete.append(layer)
214
+ continue
215
+ submodule_path = layer[len(layer_prefix):] if layer_prefix else layer
216
+ base = _get_submodule(diffusion_model, submodule_path)
217
+ if compile_safe:
218
+ _shield_from_dynamo(base)
219
+ attach_branch(base, parts["l1"], parts["l2"])
220
+ # Collected per layer rather than read once off the first branch, so a checkpoint
221
+ # with a non-uniform rank budget reports honestly instead of quoting layer zero.
222
+ ranks.add(int(parts["l1"].shape[1]))
223
+ attached += 1
224
+
225
+ # Silently returning a patcher with no branches would hand back a plain quantized model
226
+ # dressed as an SVDQuant one -- same class of failure quantize_krea2.py hard-fails on.
227
+ if attached == 0:
228
+ raise RuntimeError(
229
+ "{}: found {} svdq_l1/svdq_l2 key pairs but attached none of them"
230
+ "{}. The checkpoint's layer names do not line up with this model "
231
+ "(detected prefix {!r}).".format(
232
+ path, len(branches),
233
+ "; {} were missing their other half".format(len(incomplete))
234
+ if incomplete else "",
235
+ layer_prefix)
236
+ )
237
+
238
+ # The branch buffers were registered after the patcher computed (and cached) its size,
239
+ # so drop the cache and let `model_size()` re-derive it from the state dict.
240
+ patcher.size = 0
241
+
242
+ # Metadata is a newer addition; checkpoints published before it still load, with the
243
+ # rank recovered from the factor shape exactly as before. The shapes are the ground
244
+ # truth, so they win over a metadata value that disagrees with them.
245
+ meta = metadata or {}
246
+ rank_desc = (str(next(iter(ranks))) if len(ranks) == 1
247
+ else "{}-{} mixed".format(min(ranks), max(ranks)))
248
+ meta_rank = meta.get("krea2_svdquant_rank")
249
+ if meta_rank and len(ranks) == 1 and int(meta_rank) != next(iter(ranks)):
250
+ logging.warning("[krea2-svdquant] metadata says rank %s but the factors are rank %s; "
251
+ "trusting the factors", meta_rank, rank_desc)
252
+ variant = meta.get("krea2_svdquant_variant", "unknown")
253
+ summary = ("w4a4 + low-rank: attached {} branches (rank {}, variant {}), "
254
+ "model_size {:.2f} GiB".format(
255
+ attached, rank_desc, variant, patcher.model_size() / 1024 ** 3))
256
+ logging.info("[krea2-svdquant] %s", summary)
257
+
258
+ dispatch = log_dispatch(diffusion_model)
259
+
260
+ # Stashed rather than returned so callers that just want the model (diagnose.py, the
261
+ # head-to-head scripts) keep working unchanged. The node surfaces it in the UI, which
262
+ # matters most for the dispatch warning: buried in the console, the people who most need
263
+ # to read it are exactly the ones who never see it.
264
+ patcher.krea2_load_summary = "\n".join(x for x in (summary, dispatch) if x)
265
+ return patcher
266
+
267
+
268
+ class Krea2SVDQuantW4A4Loader:
269
+ @classmethod
270
+ def INPUT_TYPES(cls):
271
+ return {
272
+ "required": {
273
+ "model_name": (folder_paths.get_filename_list("diffusion_models"), {
274
+ "tooltip": "A checkpoint from quantize_krea2.py --format svdq (it carries "
275
+ "*.svdq_l1/*.svdq_l2 tensors). The --format w4a4 / int8 / fp8 "
276
+ "checkpoints have no branch and load with the stock UNETLoader "
277
+ "instead.",
278
+ }),
279
+ }
280
+ }
281
+
282
+ RETURN_TYPES = ("MODEL", "STRING")
283
+ RETURN_NAMES = ("model", "status")
284
+ OUTPUT_TOOLTIPS = ("Wire this to a KSampler.",
285
+ "Rank, variant, size and which kernel the quantized layers will "
286
+ "actually dispatch to. Read this if generation is slow.")
287
+ OUTPUT_NODE = True
288
+ FUNCTION = "load"
289
+ CATEGORY = _CATEGORY
290
+ TITLE = "Krea2 SVDQuant W4A4 Loader"
291
+ DESCRIPTION = ("Loads a W4A4 + low-rank (SVDQuant) Krea2 checkpoint. Self-contained: "
292
+ "no separate base model needed. The status output tells you whether the "
293
+ "fast int4 kernel is in play.")
294
+
295
+ def load(self, model_name):
296
+ path = folder_paths.get_full_path_or_raise("diffusion_models", model_name)
297
+ patcher = load_svdquant_w4a4(path)
298
+ status = getattr(patcher, "krea2_load_summary", "")
299
+ return {"ui": {"text": [status]}, "result": (patcher, status)}
300
+
301
+
302
+ NODE_CLASS_MAPPINGS = {"Krea2SVDQuantW4A4Loader": Krea2SVDQuantW4A4Loader}
303
+ NODE_DISPLAY_NAME_MAPPINGS = {"Krea2SVDQuantW4A4Loader": "Krea2 SVDQuant W4A4 Loader"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
tools/build_workflows.py CHANGED
@@ -13,7 +13,9 @@ ComfyUI has two JSON dialects and they are not interchangeable.
13
 
14
  The repo used to ship only API format while the README told people to drag the file in, so
15
  every new user's first experience was a pile of untitled nodes stacked on the origin. Both
16
- dialects are emitted now: ``*_api.json`` for scripting, the plain name for the editor.
 
 
17
 
18
  Positions are computed from a column/row grid rather than written by hand, so adding a node
19
  does not mean renumbering everything below it.
@@ -51,13 +53,25 @@ class Graph:
51
  self._next_node = 1
52
  self._next_link = 1
53
  self._slots = {} # node_id -> {"in": {name: idx}, "out": {name: idx}}
 
54
 
55
  def add(self, class_type, col, row, inputs=None, outputs=None, widgets=None,
56
- title=None, colour=None, size=None, order=None):
 
 
 
 
 
 
 
 
 
 
57
  nid = self._next_node
58
  self._next_node += 1
59
  inputs = inputs or []
60
  outputs = outputs or []
 
61
  self._slots[nid] = {
62
  "in": {name: i for i, (name, _) in enumerate(inputs)},
63
  "out": {name: i for i, (name, _) in enumerate(outputs)},
@@ -68,19 +82,21 @@ class Graph:
68
  "pos": [60 + col * COL, 60 + row * ROW],
69
  "size": size or [380, 100],
70
  "flags": {},
71
- "order": self._next_node - 2 if order is None else order,
72
  "mode": 0,
73
  "inputs": [{"name": n, "type": t, "link": None} for n, t in inputs],
74
  "outputs": [{"name": n, "type": t, "links": [], "slot_index": i}
75
  for i, (n, t) in enumerate(outputs)],
76
  "properties": {"Node name for S&R": class_type},
77
- "widgets_values": widgets if widgets is not None else [],
78
  }
79
  if title:
80
  node["title"] = title
81
  if colour:
82
  node["color"], node["bgcolor"] = colour
83
  self.nodes.append(node)
 
 
84
  return nid
85
 
86
  def link(self, src_node, src_name, dst_node, dst_name):
@@ -99,8 +115,8 @@ class Graph:
99
 
100
  def note(self, text, col, row, size=(400, 260), title="READ ME"):
101
  """A built-in Note node. Its text lives in widgets_values[0]."""
102
- return self.add("Note", col, row, widgets=[text], title=title, colour=YELLOW,
103
- size=list(size))
104
 
105
  def group(self, title, bounding, colour="#3f789e"):
106
  return {"title": title, "bounding": list(bounding), "color": colour,
@@ -120,6 +136,34 @@ class Graph:
120
  "version": 0.4,
121
  }
122
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
123
 
124
  TURBO_NOTE = """KREA 2 TURBO - SVDQuant W4A4
125
 
@@ -190,44 +234,48 @@ def build_turbo():
190
 
191
  loader = g.add("Krea2SVDQuantW4A4Loader", 1, 0,
192
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
193
- widgets=["Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors"],
194
  title="Krea2 SVDQuant W4A4 Loader", colour=TEAL, size=[400, 120])
195
  clip = g.add("CLIPLoader", 1, 1,
196
  outputs=[("CLIP", "CLIP")],
197
- widgets=["qwen3vl_4b_fp8_scaled.safetensors", "krea2", "default"],
 
198
  title="Text encoder (Qwen3-VL 4B)", colour=TEAL, size=[400, 120])
199
  vae = g.add("VAELoader", 1, 2, outputs=[("VAE", "VAE")],
200
- widgets=["qwen_image_vae.safetensors"], title="VAE", colour=TEAL,
201
  size=[400, 80])
202
 
203
  pos = g.add("CLIPTextEncode", 2, 0, inputs=[("clip", "CLIP")],
204
- outputs=[("CONDITIONING", "CONDITIONING")], widgets=[PROMPT],
205
  title="Prompt", colour=GREEN, size=[400, 220])
206
  neg = g.add("ConditioningZeroOut", 2, 1.4, inputs=[("conditioning", "CONDITIONING")],
207
  outputs=[("CONDITIONING", "CONDITIONING")],
208
  title="Negative (zeroed - required at cfg 1.0)", colour=GREEN,
209
  size=[400, 60])
210
  latent = g.add("EmptySD3LatentImage", 2, 2.2, outputs=[("LATENT", "LATENT")],
211
- widgets=[1024, 1024, 1], title="Latent 1024x1024", colour=GREEN,
 
212
  size=[400, 120])
213
 
214
  sampler = g.add("KSampler", 3, 0,
215
  inputs=[("model", "MODEL"), ("positive", "CONDITIONING"),
216
  ("negative", "CONDITIONING"), ("latent_image", "LATENT")],
217
  outputs=[("LATENT", "LATENT")],
218
- widgets=[987654321, "randomize", 8, 1.0, "euler", "simple", 1.0],
 
 
219
  title="KSampler - 8 steps, cfg 1.0", colour=PURPLE, size=[400, 280])
220
  decode = g.add("VAEDecode", 4, 0, inputs=[("samples", "LATENT"), ("vae", "VAE")],
221
  outputs=[("IMAGE", "IMAGE")], title="VAE Decode", colour=PURPLE,
222
  size=[300, 60])
223
  save = g.add("SaveImage", 4, 0.7, inputs=[("images", "IMAGE")],
224
- widgets=["krea2_turbo_svdq"], title="Save", colour=PURPLE, size=[400, 300])
225
 
226
  diag = g.add("Krea2SVDQuantDiagnostics", 3, 2.4, inputs=[("model", "MODEL")],
227
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
228
- widgets=["dispatch", 4096],
229
  title="Diagnostics (optional - run if slow)", colour=YELLOW,
230
- size=[400, 130])
231
 
232
  g.link(loader, "MODEL", sampler, "model")
233
  g.link(clip, "CLIP", pos, "clip")
@@ -245,7 +293,7 @@ def build_turbo():
245
  g.group("Prompt", (940, 20, 420, 620)),
246
  g.group("Sample", (1360, 20, 420, 640), colour="#8a4"),
247
  ]
248
- return g.serialize(groups)
249
 
250
 
251
  def build_base():
@@ -254,37 +302,41 @@ def build_base():
254
 
255
  loader = g.add("Krea2SVDQuantW4A4Loader", 1, 0,
256
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
257
- widgets=["Krea2-Base-SVDQuant-W4A4-rank64.safetensors"],
258
  title="Krea2 SVDQuant W4A4 Loader (base)", colour=TEAL, size=[400, 120])
259
  clip = g.add("CLIPLoader", 1, 1, outputs=[("CLIP", "CLIP")],
260
- widgets=["qwen3vl_4b_fp8_scaled.safetensors", "krea2", "default"],
 
261
  title="Text encoder (Qwen3-VL 4B)", colour=TEAL, size=[400, 120])
262
  vae = g.add("VAELoader", 1, 2, outputs=[("VAE", "VAE")],
263
- widgets=["qwen_image_vae.safetensors"], title="VAE", colour=TEAL,
264
  size=[400, 80])
265
 
266
  pos = g.add("CLIPTextEncode", 2, 0, inputs=[("clip", "CLIP")],
267
- outputs=[("CONDITIONING", "CONDITIONING")], widgets=[PROMPT],
268
  title="Positive prompt", colour=GREEN, size=[400, 200])
269
  neg = g.add("CLIPTextEncode", 2, 1.3, inputs=[("clip", "CLIP")],
270
- outputs=[("CONDITIONING", "CONDITIONING")], widgets=[NEGATIVE],
271
  title="Negative prompt (base uses real CFG)", colour=GREEN,
272
  size=[400, 140])
273
  latent = g.add("EmptySD3LatentImage", 2, 2.3, outputs=[("LATENT", "LATENT")],
274
- widgets=[1024, 1024, 1], title="Latent 1024x1024", colour=GREEN,
 
275
  size=[400, 120])
276
 
277
  sampler = g.add("KSampler", 3, 0,
278
  inputs=[("model", "MODEL"), ("positive", "CONDITIONING"),
279
  ("negative", "CONDITIONING"), ("latent_image", "LATENT")],
280
  outputs=[("LATENT", "LATENT")],
281
- widgets=[987654321, "randomize", 50, 3.5, "euler", "simple", 1.0],
 
 
282
  title="KSampler - 50 steps, cfg 3.5", colour=PURPLE, size=[400, 280])
283
  decode = g.add("VAEDecode", 4, 0, inputs=[("samples", "LATENT"), ("vae", "VAE")],
284
  outputs=[("IMAGE", "IMAGE")], title="VAE Decode", colour=PURPLE,
285
  size=[300, 60])
286
  save = g.add("SaveImage", 4, 0.7, inputs=[("images", "IMAGE")],
287
- widgets=["krea2_base_svdq"], title="Save", colour=PURPLE, size=[400, 300])
288
 
289
  g.link(loader, "MODEL", sampler, "model")
290
  g.link(clip, "CLIP", pos, "clip")
@@ -301,19 +353,27 @@ def build_base():
301
  g.group("Prompt", (940, 20, 420, 620)),
302
  g.group("Sample", (1360, 20, 420, 640), colour="#8a4"),
303
  ]
304
- return g.serialize(groups)
 
 
 
 
 
 
305
 
306
 
307
  def main():
308
  os.makedirs(OUT_DIR, exist_ok=True)
309
- for name, graph in (("krea2_turbo_svdquant_w4a4_t2i", build_turbo()),
310
- ("krea2_base_svdquant_w4a4_t2i", build_base())):
311
- path = os.path.join(OUT_DIR, name + ".json")
312
- with open(path, "w", encoding="utf-8", newline="\n") as fh:
313
- json.dump(graph, fh, indent=2, ensure_ascii=False)
314
- fh.write("\n")
 
315
  print("wrote {} ({} nodes, {} links)".format(
316
- path, len(graph["nodes"]), len(graph["links"])))
 
317
 
318
 
319
  if __name__ == "__main__":
 
13
 
14
  The repo used to ship only API format while the README told people to drag the file in, so
15
  every new user's first experience was a pile of untitled nodes stacked on the origin. Both
16
+ dialects come out of this script now -- ``*_api.json`` for scripting, the plain name for the
17
+ editor -- from one graph definition, so they cannot drift apart. They previously could, and
18
+ did: the committed API files carried titles the generator had never produced.
19
 
20
  Positions are computed from a column/row grid rather than written by hand, so adding a node
21
  does not mean renumbering everything below it.
 
53
  self._next_node = 1
54
  self._next_link = 1
55
  self._slots = {} # node_id -> {"in": {name: idx}, "out": {name: idx}}
56
+ self._api = {} # node_id -> what the API dialect needs about that node
57
 
58
  def add(self, class_type, col, row, inputs=None, outputs=None, widgets=None,
59
+ title=None, colour=None, size=None, api=True):
60
+ """`widgets` is a list of (input_name, value).
61
+
62
+ The name is what the API dialect needs and the UI dialect ignores; `None` marks a
63
+ UI-only widget (`control_after_generate` has no API input). Keeping them as pairs is
64
+ what lets one graph definition emit both dialects, instead of a hand-written API file
65
+ drifting away from the generator -- which is exactly what had happened.
66
+
67
+ `api=False` drops the node from the API output: Notes and the optional Diagnostics
68
+ node are editor furniture with nothing to execute.
69
+ """
70
  nid = self._next_node
71
  self._next_node += 1
72
  inputs = inputs or []
73
  outputs = outputs or []
74
+ widgets = widgets or []
75
  self._slots[nid] = {
76
  "in": {name: i for i, (name, _) in enumerate(inputs)},
77
  "out": {name: i for i, (name, _) in enumerate(outputs)},
 
82
  "pos": [60 + col * COL, 60 + row * ROW],
83
  "size": size or [380, 100],
84
  "flags": {},
85
+ "order": self._next_node - 2,
86
  "mode": 0,
87
  "inputs": [{"name": n, "type": t, "link": None} for n, t in inputs],
88
  "outputs": [{"name": n, "type": t, "links": [], "slot_index": i}
89
  for i, (n, t) in enumerate(outputs)],
90
  "properties": {"Node name for S&R": class_type},
91
+ "widgets_values": [v for _name, v in widgets],
92
  }
93
  if title:
94
  node["title"] = title
95
  if colour:
96
  node["color"], node["bgcolor"] = colour
97
  self.nodes.append(node)
98
+ self._api[nid] = {"class_type": class_type, "title": title, "api": api,
99
+ "widgets": [(n, v) for n, v in widgets if n is not None]}
100
  return nid
101
 
102
  def link(self, src_node, src_name, dst_node, dst_name):
 
115
 
116
  def note(self, text, col, row, size=(400, 260), title="READ ME"):
117
  """A built-in Note node. Its text lives in widgets_values[0]."""
118
+ return self.add("Note", col, row, widgets=[(None, text)], title=title, colour=YELLOW,
119
+ size=list(size), api=False)
120
 
121
  def group(self, title, bounding, colour="#3f789e"):
122
  return {"title": title, "bounding": list(bounding), "color": colour,
 
136
  "version": 0.4,
137
  }
138
 
139
+ def serialize_api(self):
140
+ """The same graph in API dialect: {"1": {"class_type", "inputs", "_meta"}, ...}.
141
+
142
+ Ids are reassigned sequentially over the executable nodes, so dropping the Note (which
143
+ is always added first) leaves the remaining nodes numbered from 1 with no gaps.
144
+ """
145
+ keep = [n["id"] for n in self.nodes if self._api[n["id"]]["api"]]
146
+ renum = {old: str(i + 1) for i, old in enumerate(keep)}
147
+
148
+ # dst_node -> {input_name: [src_id, src_slot]}
149
+ wired: dict[int, dict] = {}
150
+ for _lid, src, src_slot, dst, dst_slot, _type in self.links:
151
+ if src not in renum or dst not in renum:
152
+ continue
153
+ name = next(n for n, i in self._slots[dst]["in"].items() if i == dst_slot)
154
+ wired.setdefault(dst, {})[name] = [renum[src], src_slot]
155
+
156
+ out = {}
157
+ for old in keep:
158
+ meta = self._api[old]
159
+ inputs = {name: value for name, value in meta["widgets"]}
160
+ inputs.update(wired.get(old, {}))
161
+ entry = {"class_type": meta["class_type"], "inputs": inputs}
162
+ if meta["title"]:
163
+ entry["_meta"] = {"title": meta["title"]}
164
+ out[renum[old]] = entry
165
+ return out
166
+
167
 
168
  TURBO_NOTE = """KREA 2 TURBO - SVDQuant W4A4
169
 
 
234
 
235
  loader = g.add("Krea2SVDQuantW4A4Loader", 1, 0,
236
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
237
+ widgets=[("model_name", "Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors")],
238
  title="Krea2 SVDQuant W4A4 Loader", colour=TEAL, size=[400, 120])
239
  clip = g.add("CLIPLoader", 1, 1,
240
  outputs=[("CLIP", "CLIP")],
241
+ widgets=[("clip_name", "qwen3vl_4b_fp8_scaled.safetensors"), ("type", "krea2"),
242
+ ("device", "default")],
243
  title="Text encoder (Qwen3-VL 4B)", colour=TEAL, size=[400, 120])
244
  vae = g.add("VAELoader", 1, 2, outputs=[("VAE", "VAE")],
245
+ widgets=[("vae_name", "qwen_image_vae.safetensors")], title="VAE", colour=TEAL,
246
  size=[400, 80])
247
 
248
  pos = g.add("CLIPTextEncode", 2, 0, inputs=[("clip", "CLIP")],
249
+ outputs=[("CONDITIONING", "CONDITIONING")], widgets=[("text", PROMPT)],
250
  title="Prompt", colour=GREEN, size=[400, 220])
251
  neg = g.add("ConditioningZeroOut", 2, 1.4, inputs=[("conditioning", "CONDITIONING")],
252
  outputs=[("CONDITIONING", "CONDITIONING")],
253
  title="Negative (zeroed - required at cfg 1.0)", colour=GREEN,
254
  size=[400, 60])
255
  latent = g.add("EmptySD3LatentImage", 2, 2.2, outputs=[("LATENT", "LATENT")],
256
+ widgets=[("width", 1024), ("height", 1024), ("batch_size", 1)],
257
+ title="Latent 1024x1024", colour=GREEN,
258
  size=[400, 120])
259
 
260
  sampler = g.add("KSampler", 3, 0,
261
  inputs=[("model", "MODEL"), ("positive", "CONDITIONING"),
262
  ("negative", "CONDITIONING"), ("latent_image", "LATENT")],
263
  outputs=[("LATENT", "LATENT")],
264
+ widgets=[("seed", 987654321), (None, "randomize"), ("steps", 8), ("cfg", 1.0),
265
+ ("sampler_name", "euler"), ("scheduler", "simple"),
266
+ ("denoise", 1.0)],
267
  title="KSampler - 8 steps, cfg 1.0", colour=PURPLE, size=[400, 280])
268
  decode = g.add("VAEDecode", 4, 0, inputs=[("samples", "LATENT"), ("vae", "VAE")],
269
  outputs=[("IMAGE", "IMAGE")], title="VAE Decode", colour=PURPLE,
270
  size=[300, 60])
271
  save = g.add("SaveImage", 4, 0.7, inputs=[("images", "IMAGE")],
272
+ widgets=[("filename_prefix", "krea2_turbo_svdq")], title="Save", colour=PURPLE, size=[400, 300])
273
 
274
  diag = g.add("Krea2SVDQuantDiagnostics", 3, 2.4, inputs=[("model", "MODEL")],
275
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
276
+ widgets=[("mode", "dispatch"), ("tokens", 4096)],
277
  title="Diagnostics (optional - run if slow)", colour=YELLOW,
278
+ size=[400, 130], api=False)
279
 
280
  g.link(loader, "MODEL", sampler, "model")
281
  g.link(clip, "CLIP", pos, "clip")
 
293
  g.group("Prompt", (940, 20, 420, 620)),
294
  g.group("Sample", (1360, 20, 420, 640), colour="#8a4"),
295
  ]
296
+ return g.serialize(groups), g.serialize_api()
297
 
298
 
299
  def build_base():
 
302
 
303
  loader = g.add("Krea2SVDQuantW4A4Loader", 1, 0,
304
  outputs=[("MODEL", "MODEL"), ("STRING", "STRING")],
305
+ widgets=[("model_name", "Krea2-Base-SVDQuant-W4A4-rank64.safetensors")],
306
  title="Krea2 SVDQuant W4A4 Loader (base)", colour=TEAL, size=[400, 120])
307
  clip = g.add("CLIPLoader", 1, 1, outputs=[("CLIP", "CLIP")],
308
+ widgets=[("clip_name", "qwen3vl_4b_fp8_scaled.safetensors"), ("type", "krea2"),
309
+ ("device", "default")],
310
  title="Text encoder (Qwen3-VL 4B)", colour=TEAL, size=[400, 120])
311
  vae = g.add("VAELoader", 1, 2, outputs=[("VAE", "VAE")],
312
+ widgets=[("vae_name", "qwen_image_vae.safetensors")], title="VAE", colour=TEAL,
313
  size=[400, 80])
314
 
315
  pos = g.add("CLIPTextEncode", 2, 0, inputs=[("clip", "CLIP")],
316
+ outputs=[("CONDITIONING", "CONDITIONING")], widgets=[("text", PROMPT)],
317
  title="Positive prompt", colour=GREEN, size=[400, 200])
318
  neg = g.add("CLIPTextEncode", 2, 1.3, inputs=[("clip", "CLIP")],
319
+ outputs=[("CONDITIONING", "CONDITIONING")], widgets=[("text", NEGATIVE)],
320
  title="Negative prompt (base uses real CFG)", colour=GREEN,
321
  size=[400, 140])
322
  latent = g.add("EmptySD3LatentImage", 2, 2.3, outputs=[("LATENT", "LATENT")],
323
+ widgets=[("width", 1024), ("height", 1024), ("batch_size", 1)],
324
+ title="Latent 1024x1024", colour=GREEN,
325
  size=[400, 120])
326
 
327
  sampler = g.add("KSampler", 3, 0,
328
  inputs=[("model", "MODEL"), ("positive", "CONDITIONING"),
329
  ("negative", "CONDITIONING"), ("latent_image", "LATENT")],
330
  outputs=[("LATENT", "LATENT")],
331
+ widgets=[("seed", 987654321), (None, "randomize"), ("steps", 50), ("cfg", 3.5),
332
+ ("sampler_name", "euler"), ("scheduler", "simple"),
333
+ ("denoise", 1.0)],
334
  title="KSampler - 50 steps, cfg 3.5", colour=PURPLE, size=[400, 280])
335
  decode = g.add("VAEDecode", 4, 0, inputs=[("samples", "LATENT"), ("vae", "VAE")],
336
  outputs=[("IMAGE", "IMAGE")], title="VAE Decode", colour=PURPLE,
337
  size=[300, 60])
338
  save = g.add("SaveImage", 4, 0.7, inputs=[("images", "IMAGE")],
339
+ widgets=[("filename_prefix", "krea2_base_svdq")], title="Save", colour=PURPLE, size=[400, 300])
340
 
341
  g.link(loader, "MODEL", sampler, "model")
342
  g.link(clip, "CLIP", pos, "clip")
 
353
  g.group("Prompt", (940, 20, 420, 620)),
354
  g.group("Sample", (1360, 20, 420, 640), colour="#8a4"),
355
  ]
356
+ return g.serialize(groups), g.serialize_api()
357
+
358
+
359
+ def _write(path, payload):
360
+ with open(path, "w", encoding="utf-8", newline="\n") as fh:
361
+ json.dump(payload, fh, indent=2, ensure_ascii=False)
362
+ fh.write("\n")
363
 
364
 
365
  def main():
366
  os.makedirs(OUT_DIR, exist_ok=True)
367
+ for name, build in (("krea2_turbo_svdquant_w4a4_t2i", build_turbo),
368
+ ("krea2_base_svdquant_w4a4_t2i", build_base)):
369
+ graph, api = build()
370
+ ui_path = os.path.join(OUT_DIR, name + ".json")
371
+ api_path = os.path.join(OUT_DIR, name + "_api.json")
372
+ _write(ui_path, graph)
373
+ _write(api_path, api)
374
  print("wrote {} ({} nodes, {} links)".format(
375
+ ui_path, len(graph["nodes"]), len(graph["links"])))
376
+ print("wrote {} ({} nodes)".format(api_path, len(api)))
377
 
378
 
379
  if __name__ == "__main__":
tools/contact_sheet.py CHANGED
@@ -79,10 +79,17 @@ def main() -> int:
79
  formatter_class=argparse.RawDescriptionHelpFormatter)
80
  ap.add_argument("--output-dir", required=True,
81
  help="the ComfyUI output directory (reads its fb/ subfolder)")
82
- ap.add_argument("--arm", default=None, choices=["base", "lora"],
83
  help="default: one set of sheets per arm present")
84
  ap.add_argument("--cell", type=int, default=640, help="tile size in px")
85
  ap.add_argument("--dest", default=None, help="default: <output-dir>/fb/sheets")
 
 
 
 
 
 
 
86
  args = ap.parse_args()
87
 
88
  out_root = os.path.join(args.output_dir, fb.SUBDIR)
@@ -96,9 +103,12 @@ def main() -> int:
96
  arms = [args.arm] if args.arm else sorted({a for a, _ in images})
97
  written = 0
98
  for arm in arms:
99
- ckpts = sorted(c for a, c in images if a == arm)
100
- # Reference first, then whatever order the rest come in -- a moving anchor makes
101
- # side-by-side comparison much harder than it needs to be.
 
 
 
102
  if fb.REFERENCE in ckpts:
103
  ckpts = [fb.REFERENCE] + [c for c in ckpts if c != fb.REFERENCE]
104
 
@@ -118,8 +128,12 @@ def main() -> int:
118
  cells[(ckpt, seed)] = path
119
  sheet = build_sheet(cells, ckpts, sorted(seeds), args.cell,
120
  "{} [{}]".format(pid, arm))
121
- path = os.path.join(dest, "sheet_{}_{}.png".format(arm, pid))
122
- sheet.save(path)
 
 
 
 
123
  written += 1
124
  print("wrote {}".format(path))
125
 
 
79
  formatter_class=argparse.RawDescriptionHelpFormatter)
80
  ap.add_argument("--output-dir", required=True,
81
  help="the ComfyUI output directory (reads its fb/ subfolder)")
82
+ ap.add_argument("--arm", default=None, choices=sorted(fb.ARM_LORA),
83
  help="default: one set of sheets per arm present")
84
  ap.add_argument("--cell", type=int, default=640, help="tile size in px")
85
  ap.add_argument("--dest", default=None, help="default: <output-dir>/fb/sheets")
86
+ ap.add_argument("--optimize", action="store_true",
87
+ help="slower PNG encode, roughly 20%% smaller")
88
+ # A 7-column sheet is ~4000x1200 px. As PNG that is ~5.7 MB each, so 32 of them is 184 MB
89
+ # of repository -- JPEG at q90 is ~20x smaller and the artifacts are nowhere near the
90
+ # scale of the differences these sheets exist to show.
91
+ ap.add_argument("--jpeg", type=int, default=None, metavar="QUALITY",
92
+ help="write .jpg at this quality instead of .png (90 is a good default)")
93
  args = ap.parse_args()
94
 
95
  out_root = os.path.join(args.output_dir, fb.SUBDIR)
 
103
  arms = [args.arm] if args.arm else sorted({a for a, _ in images})
104
  written = 0
105
  for arm in arms:
106
+ present = {c for a, c in images if a == arm}
107
+ # Reference first, then fb.CHECKPOINTS order -- that is the accuracy ladder
108
+ # (no branch, then rising rank), so the sheet reads left to right. Alphabetical
109
+ # would put r128 before r16, and a moving anchor makes comparison much harder.
110
+ ckpts = [c for c in fb.CHECKPOINTS if c in present]
111
+ ckpts += sorted(present - set(ckpts))
112
  if fb.REFERENCE in ckpts:
113
  ckpts = [fb.REFERENCE] + [c for c in ckpts if c != fb.REFERENCE]
114
 
 
128
  cells[(ckpt, seed)] = path
129
  sheet = build_sheet(cells, ckpts, sorted(seeds), args.cell,
130
  "{} [{}]".format(pid, arm))
131
+ ext = "jpg" if args.jpeg else "png"
132
+ path = os.path.join(dest, "sheet_{}_{}.{}".format(arm, pid, ext))
133
+ if args.jpeg:
134
+ sheet.save(path, quality=args.jpeg, optimize=True, subsampling=0)
135
+ else:
136
+ sheet.save(path, optimize=args.optimize)
137
  written += 1
138
  print("wrote {}".format(path))
139
 
tools/fidelity_bench.py CHANGED
@@ -3,8 +3,8 @@
3
  python tools/fidelity_bench.py generate --output-dir <ComfyUI/output> [--seeds 4]
4
  python tools/fidelity_bench.py score --output-dir <ComfyUI/output>
5
 
6
- Why this exists rather than `tools/pixel_metrics.py` alone. That script scores one seed per
7
- prompt and reports each checkpoint's *marginal* mean. Two things go wrong with that:
8
 
9
  * **One seed cannot resolve the differences we care about.** Re-analysing its own 130-pair
10
  output as paired differences: `rank256 vs nolowrank` is a clean t=-4.73 (10/10 prompts),
@@ -54,6 +54,8 @@ sys.path.insert(0, HERE)
54
 
55
  # The metric implementations are shared rather than reimplemented -- two copies of SSIM in
56
  # one repo is two chances to have a different window or a different epsilon.
 
 
57
  import pixel_metrics # noqa: E402
58
 
59
  SUBDIR = "fb"
@@ -90,9 +92,9 @@ ARM_LORA = {
90
  }
91
 
92
  # Loader choice is a property of the file, so it lives with the file rather than being
93
- # guessed from the name at call time. `quantized` drives the *LoRA* node choice: the stock
94
- # loader cannot patch a quantized weight and silently skips those blocks, which is the whole
95
- # reason this repo ships its own LoRA node.
96
  CHECKPOINTS = {
97
  "bf16": {"file": "turbo.safetensors", "loader": "unet", "quantized": False},
98
  "nolowrank": {"file": "Krea2-Turbo-W4A4-convrot.safetensors", "loader": "unet", "quantized": True},
@@ -105,9 +107,9 @@ CHECKPOINTS = {
105
  "r256aa": {"file": "Krea2-Turbo-SVDQuant-W4A4-rank256-actaware.safetensors", "loader": "svdq", "quantized": True},
106
  }
107
 
108
- # The repo's established prompt set (the same ids BENCHMARKS.md and pixel_metrics.csv use),
109
- # kept verbatim so new numbers stay comparable with the old ones.
110
- PROMPTS = [
111
  ("01_dense_text", "A rain-soaked neon diner sign at night, below it a handwritten chalkboard menu with three lines of text reading 'SOUP $4 / PIE $6 / COFFEE $2', reflections on wet asphalt, cinematic"),
112
  ("02_curved_text", "Close-up of a person holding a paper coffee cup with large bold curved text 'STAY WARM' printed around the cup, soft morning light, shallow depth of field"),
113
  ("03_hands_detail", "A violinist's hands mid-performance, fingers pressed on the strings, bow in motion with visible blur, studio lighting, extreme close-up, photorealistic"),
@@ -134,7 +136,7 @@ PROMPTS_PEOPLE = [
134
  ("16_group_selfie", "Four friends of different ethnicities crowded around a restaurant table taking a group selfie, one holding the phone at arm's length, another leaning in making a peace sign, plates of pasta and half-full wine glasses on the table, warm indoor lighting, natural candid expressions"),
135
  ]
136
 
137
- PROMPTS = PROMPTS + PROMPTS_PEOPLE
138
 
139
  # Fixed rather than random so a re-run reproduces the same dataset. The first is the seed the
140
  # older single-seed benchmarks used, which keeps those results inside this one.
@@ -312,7 +314,6 @@ def score(args) -> int:
312
  import lpips
313
  except ImportError:
314
  raise SystemExit("pip install lpips")
315
- import torch
316
 
317
  out_root = os.path.join(args.output_dir, SUBDIR)
318
  images = index(out_root)
@@ -333,7 +334,7 @@ def score(args) -> int:
333
  # touches a tile mosaic but rewrites skin and hair -- so they are separable.
334
  if args.group:
335
  wanted = {p for p, _ in (PROMPTS_PEOPLE if args.group == "people"
336
- else PROMPTS[:len(PROMPTS) - len(PROMPTS_PEOPLE)])}
337
  images = {k: {c: p for c, p in cells.items() if c[0] in wanted}
338
  for k, cells in images.items()}
339
  images = {k: cells for k, cells in images.items() if cells}
@@ -352,7 +353,7 @@ def score(args) -> int:
352
  def load(path):
353
  if path in cache:
354
  return cache[path]
355
- tensor = pixel_metrics._load(path, device)
356
  if path in ref_paths:
357
  cache[path] = tensor
358
  return tensor
@@ -440,21 +441,26 @@ def score(args) -> int:
440
  label, st["mean"], st["se"], st["t"], st["a_wins"], st["n"], mark))
441
  summary.append(dict(arm=arm, a=a_ck, b=b_ck, **st))
442
 
443
- # The reason the LoRA arm exists: same checkpoint, same cells, LoRA vs no LoRA. A
444
  # positive mean means the LoRA made that checkpoint drift further from its own
445
- # reference, i.e. LoRAs amplify quantization error.
446
- both = sorted({c for a, c in lpips_by if a == "lora"} & {c for a, c in lpips_by if a == "base"})
447
- if both:
448
- print("\nLoRA amplification (lora - base, same checkpoint/prompt/seed)")
 
 
 
 
 
449
  print("{:<40} {:>9} {:>8} {:>7} {:>9}".format("checkpoint", "mean", "se", "t", "worse"))
450
  for ckpt in both:
451
- st = paired(lpips_by[("lora", ckpt)], lpips_by[("base", ckpt)])
452
  if st is None:
453
  continue
454
  mark = " ***" if abs(st["t"]) > 3 else (" *" if abs(st["t"]) > 2 else "")
455
  print("{:<40} {:>+9.4f} {:>8.4f} {:>7.2f} {:>5}/{}{}".format(
456
  ckpt, st["mean"], st["se"], st["t"], st["n"] - st["a_wins"], st["n"], mark))
457
- summary.append(dict(arm="amplification", a=ckpt, b=ckpt, **st))
458
 
459
  json_path = os.path.splitext(out_csv)[0] + "_summary.json"
460
  with open(json_path, "w", encoding="utf-8") as fh:
@@ -498,7 +504,9 @@ def main() -> int:
498
 
499
  sc = sub.choices["score"]
500
  sc.add_argument("--out", default=None)
501
- sc.add_argument("--device", default="cuda")
 
 
502
  sc.add_argument("--seeds", type=int, default=None,
503
  help="analyse only the first N fixed seeds, so a half-finished generate "
504
  "does not make the cell grid ragged")
 
3
  python tools/fidelity_bench.py generate --output-dir <ComfyUI/output> [--seeds 4]
4
  python tools/fidelity_bench.py score --output-dir <ComfyUI/output>
5
 
6
+ Why this exists. The measurement it replaced scored one seed per prompt and reported each
7
+ checkpoint's *marginal* mean. Two things go wrong with that:
8
 
9
  * **One seed cannot resolve the differences we care about.** Re-analysing its own 130-pair
10
  output as paired differences: `rank256 vs nolowrank` is a clean t=-4.73 (10/10 prompts),
 
54
 
55
  # The metric implementations are shared rather than reimplemented -- two copies of SSIM in
56
  # one repo is two chances to have a different window or a different epsilon.
57
+ import torch # noqa: E402
58
+
59
  import pixel_metrics # noqa: E402
60
 
61
  SUBDIR = "fb"
 
92
  }
93
 
94
  # Loader choice is a property of the file, so it lives with the file rather than being
95
+ # guessed from the name at call time. `quantized` drives the *LoRA* node choice: applying a
96
+ # LoRA to a quantized weight through the stock path means dequantize -> add -> requantize,
97
+ # which re-quantizes the LoRA delta to 4 bits, so quantized files go through this repo's node.
98
  CHECKPOINTS = {
99
  "bf16": {"file": "turbo.safetensors", "loader": "unet", "quantized": False},
100
  "nolowrank": {"file": "Krea2-Turbo-W4A4-convrot.safetensors", "loader": "unet", "quantized": True},
 
107
  "r256aa": {"file": "Krea2-Turbo-SVDQuant-W4A4-rank256-actaware.safetensors", "loader": "svdq", "quantized": True},
108
  }
109
 
110
+ # The repo's established prompt set (the same ids BENCHMARKS.md uses), kept verbatim so new
111
+ # numbers stay comparable with the old ones.
112
+ PROMPTS_OBJECTS = [
113
  ("01_dense_text", "A rain-soaked neon diner sign at night, below it a handwritten chalkboard menu with three lines of text reading 'SOUP $4 / PIE $6 / COFFEE $2', reflections on wet asphalt, cinematic"),
114
  ("02_curved_text", "Close-up of a person holding a paper coffee cup with large bold curved text 'STAY WARM' printed around the cup, soft morning light, shallow depth of field"),
115
  ("03_hands_detail", "A violinist's hands mid-performance, fingers pressed on the strings, bow in motion with visible blur, studio lighting, extreme close-up, photorealistic"),
 
136
  ("16_group_selfie", "Four friends of different ethnicities crowded around a restaurant table taking a group selfie, one holding the phone at arm's length, another leaning in making a peace sign, plates of pasta and half-full wine glasses on the table, warm indoor lighting, natural candid expressions"),
137
  ]
138
 
139
+ PROMPTS = PROMPTS_OBJECTS + PROMPTS_PEOPLE
140
 
141
  # Fixed rather than random so a re-run reproduces the same dataset. The first is the seed the
142
  # older single-seed benchmarks used, which keeps those results inside this one.
 
314
  import lpips
315
  except ImportError:
316
  raise SystemExit("pip install lpips")
 
317
 
318
  out_root = os.path.join(args.output_dir, SUBDIR)
319
  images = index(out_root)
 
334
  # touches a tile mosaic but rewrites skin and hair -- so they are separable.
335
  if args.group:
336
  wanted = {p for p, _ in (PROMPTS_PEOPLE if args.group == "people"
337
+ else PROMPTS_OBJECTS)}
338
  images = {k: {c: p for c, p in cells.items() if c[0] in wanted}
339
  for k, cells in images.items()}
340
  images = {k: cells for k, cells in images.items() if cells}
 
353
  def load(path):
354
  if path in cache:
355
  return cache[path]
356
+ tensor = pixel_metrics.load_image(path, device)
357
  if path in ref_paths:
358
  cache[path] = tensor
359
  return tensor
 
441
  label, st["mean"], st["se"], st["t"], st["a_wins"], st["n"], mark))
442
  summary.append(dict(arm=arm, a=a_ck, b=b_ck, **st))
443
 
444
+ # The reason the LoRA arms exist: same checkpoint, same cells, LoRA vs no LoRA. A
445
  # positive mean means the LoRA made that checkpoint drift further from its own
446
+ # reference, i.e. LoRAs amplify quantization error. One block per LoRA arm present --
447
+ # this used to be hardcoded to "lora", so extra arms were generated and then silently
448
+ # left out of the analysis.
449
+ base_ckpts = {c for a, c in lpips_by if a == "base"}
450
+ for arm in sorted({a for a, _ in lpips_by} - {"base"}):
451
+ both = sorted({c for a, c in lpips_by if a == arm} & base_ckpts)
452
+ if not both:
453
+ continue
454
+ print("\nLoRA amplification ({} - base, same checkpoint/prompt/seed)".format(arm))
455
  print("{:<40} {:>9} {:>8} {:>7} {:>9}".format("checkpoint", "mean", "se", "t", "worse"))
456
  for ckpt in both:
457
+ st = paired(lpips_by[(arm, ckpt)], lpips_by[("base", ckpt)])
458
  if st is None:
459
  continue
460
  mark = " ***" if abs(st["t"]) > 3 else (" *" if abs(st["t"]) > 2 else "")
461
  print("{:<40} {:>+9.4f} {:>8.4f} {:>7.2f} {:>5}/{}{}".format(
462
  ckpt, st["mean"], st["se"], st["t"], st["n"] - st["a_wins"], st["n"], mark))
463
+ summary.append(dict(arm="amplification:" + arm, a=ckpt, b=ckpt, **st))
464
 
465
  json_path = os.path.splitext(out_csv)[0] + "_summary.json"
466
  with open(json_path, "w", encoding="utf-8") as fh:
 
504
 
505
  sc = sub.choices["score"]
506
  sc.add_argument("--out", default=None)
507
+ # Scoring is LPIPS over already-rendered PNGs -- it has no GPU requirement of its own,
508
+ # so it must not fail on a machine that only has the images.
509
+ sc.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
510
  sc.add_argument("--seeds", type=int, default=None,
511
  help="analyse only the first N fixed seeds, so a half-finished generate "
512
  "does not make the cell grid ragged")
tools/pixel_metrics.py CHANGED
@@ -1,48 +1,31 @@
1
- """LPIPS / PSNR / SSIM for quantized checkpoints against a BF16 reference.
2
 
3
- python tools/pixel_metrics.py --dir <output-dir> [--out scores.csv]
 
 
 
 
4
 
5
- Images are paired by filename: ``bench_<checkpoint>_<prompt_id>_00001_.png``, matched against
6
- ``bench_turbo_bf16_reference_<prompt_id>_00001_.png``.
7
-
8
- Why this exists: the earlier sweep of these same images scored them with a vision model and
9
- produced a ranking that cannot be defended. One seed per cell, and 71 of 110 cells came back a
10
- flat 10/10 -- the judge had no discrimination left, so checkpoint means differed by 0.45 on a
11
- 10-point scale from single samples. LPIPS is deterministic and continuous, so it can separate
12
- things a saturated judge cannot.
13
-
14
- Read the output with two cautions:
15
 
16
  * **A number is only meaningful against a noise floor.** Two BF16 runs at different seeds are
17
  not identical images either. Until that distance is measured, "LPIPS 0.27" does not tell you
18
- whether a checkpoint drifted or merely rolled different dice. Pass ``--noise-floor`` a pair
19
- of same-checkpoint / different-seed renders to print it alongside.
20
  * **LPIPS measures divergence, not damage.** W4A4 shifts the sampling trajectory: the image
21
  lands somewhere else, which is not the same as landing somewhere worse. High LPIPS with
22
  intact aesthetics means drift. Do not read it as quality loss on its own.
23
 
24
- Needs `lpips` (`pip install lpips`). SSIM is computed here rather than pulled from
25
- scikit-image to keep the dependency list to one.
26
  """
27
 
28
  from __future__ import annotations
29
 
30
- import argparse
31
- import csv
32
- import json
33
- import os
34
- import re
35
- import statistics
36
- import sys
37
-
38
  import torch
39
  import torch.nn.functional as F
40
 
41
- REFERENCE = "turbo_bf16_reference"
42
- _NAME_RE = re.compile(r"^bench_(?P<ckpt>.+?)_(?P<prompt>\d{2}_[a-z_]+)_\d+_\.png$")
43
 
44
-
45
- def _load(path: str, device) -> torch.Tensor:
46
  """PNG -> [1,3,H,W] in [-1,1], which is what LPIPS expects."""
47
  from PIL import Image
48
 
@@ -77,121 +60,3 @@ def ssim(a: torch.Tensor, b: torch.Tensor) -> float:
77
  c1, c2 = 0.01 ** 2, 0.03 ** 2
78
  s = ((2 * mu_xy + c1) * (2 * sigma_xy + c2)) / ((mu_x2 + mu_y2 + c1) * (sigma_x + sigma_y + c2))
79
  return s.mean().item()
80
-
81
-
82
- def index_images(directory: str) -> dict[str, dict[str, str]]:
83
- """{checkpoint: {prompt_id: path}} for every bench_*.png in `directory`."""
84
- found: dict[str, dict[str, str]] = {}
85
- for name in sorted(os.listdir(directory)):
86
- m = _NAME_RE.match(name)
87
- if m:
88
- found.setdefault(m["ckpt"], {})[m["prompt"]] = os.path.join(directory, name)
89
- return found
90
-
91
-
92
- def main():
93
- ap = argparse.ArgumentParser()
94
- ap.add_argument("--dir", required=True, help="directory holding the bench_*.png renders")
95
- ap.add_argument("--out", default=None, help="CSV to write (default: <dir>/pixel_metrics.csv)")
96
- ap.add_argument("--reference", default=REFERENCE, help="checkpoint name to treat as truth")
97
- ap.add_argument("--net", default="alex", choices=["alex", "vgg", "squeeze"],
98
- help="LPIPS backbone. alex matches what most published tables use")
99
- ap.add_argument("--noise-floor", nargs=2, metavar=("IMG_A", "IMG_B"),
100
- help="two renders of the same checkpoint at different seeds; their "
101
- "distance is the threshold any result below is indistinguishable from")
102
- ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
103
- args = ap.parse_args()
104
-
105
- try:
106
- import lpips
107
- except ImportError:
108
- raise SystemExit("pip install lpips")
109
-
110
- images = index_images(args.dir)
111
- if args.reference not in images:
112
- raise SystemExit("no reference renders named {!r} in {}; found: {}".format(
113
- args.reference, args.dir, ", ".join(sorted(images)) or "nothing"))
114
- refs = images[args.reference]
115
- device = torch.device(args.device)
116
- net = lpips.LPIPS(net=args.net).to(device).eval()
117
-
118
- floor = None
119
- if args.noise_floor:
120
- with torch.no_grad():
121
- a, b = (_load(p, device) for p in args.noise_floor)
122
- floor = {"lpips": net(a, b).item(), "psnr": psnr(a, b), "ssim": ssim(a, b)}
123
- print("noise floor (same checkpoint, different seed): LPIPS {lpips:.3f} "
124
- "PSNR {psnr:.1f} SSIM {ssim:.3f}\n".format(**floor))
125
- else:
126
- print("no --noise-floor given: the numbers below have no threshold to be compared "
127
- "against. Two BF16 runs at different seeds already differ.\n")
128
-
129
- rows = []
130
- per_ckpt: dict[str, list[float]] = {}
131
- with torch.no_grad():
132
- for ckpt in sorted(images):
133
- if ckpt == args.reference:
134
- continue
135
- for prompt_id, cand_path in sorted(images[ckpt].items()):
136
- ref_path = refs.get(prompt_id)
137
- if ref_path is None:
138
- print(" skipping {} / {}: no reference render".format(ckpt, prompt_id))
139
- continue
140
- a, b = _load(ref_path, device), _load(cand_path, device)
141
- if a.shape != b.shape:
142
- print(" skipping {} / {}: {} vs {}".format(
143
- ckpt, prompt_id, tuple(a.shape), tuple(b.shape)))
144
- continue
145
- row = {"checkpoint": ckpt, "prompt_id": prompt_id,
146
- "lpips": round(net(a, b).item(), 5),
147
- "psnr": round(psnr(a, b), 3),
148
- "ssim": round(ssim(a, b), 5)}
149
- rows.append(row)
150
- per_ckpt.setdefault(ckpt, []).append(row["lpips"])
151
- del a, b
152
-
153
- # sanity check: the reference against itself must be 0
154
- with torch.no_grad():
155
- first = next(iter(refs.values()))
156
- same = _load(first, device)
157
- self_lpips = net(same, same.clone()).item()
158
- print("sanity: reference vs itself LPIPS = {:.6f} (should be ~0)\n".format(self_lpips))
159
-
160
- out_path = args.out or os.path.join(args.dir, "pixel_metrics.csv")
161
- with open(out_path, "w", encoding="utf-8", newline="") as fh:
162
- w = csv.DictWriter(fh, fieldnames=["checkpoint", "prompt_id", "lpips", "psnr", "ssim"])
163
- w.writeheader()
164
- w.writerows(rows)
165
-
166
- print("{:<32} {:>8} {:>8} {:>8} {:>8} {:>4}".format(
167
- "checkpoint", "LPIPS", "+-sd", "PSNR", "SSIM", "n"))
168
- summary = []
169
- for ckpt in sorted(per_ckpt, key=lambda c: statistics.mean(per_ckpt[c])):
170
- sub = [r for r in rows if r["checkpoint"] == ckpt]
171
- mean_l = statistics.mean(r["lpips"] for r in sub)
172
- sd = statistics.stdev([r["lpips"] for r in sub]) if len(sub) > 1 else 0.0
173
- mean_p = statistics.mean(r["psnr"] for r in sub if r["psnr"] != float("inf"))
174
- mean_s = statistics.mean(r["ssim"] for r in sub)
175
- flag = ""
176
- if floor and mean_l <= floor["lpips"]:
177
- flag = " <- within seed noise"
178
- print("{:<32} {:>8.4f} {:>8.4f} {:>8.2f} {:>8.4f} {:>4}{}".format(
179
- ckpt, mean_l, sd, mean_p, mean_s, len(sub), flag))
180
- summary.append({"checkpoint": ckpt, "lpips": round(mean_l, 5), "lpips_sd": round(sd, 5),
181
- "psnr": round(mean_p, 3), "ssim": round(mean_s, 5), "n": len(sub)})
182
-
183
- print("\nper prompt, mean LPIPS across checkpoints (higher = harder for W4A4):")
184
- for prompt_id in sorted({r["prompt_id"] for r in rows}):
185
- sub = [r["lpips"] for r in rows if r["prompt_id"] == prompt_id]
186
- print(" {:<24} {:.4f}".format(prompt_id, statistics.mean(sub)))
187
-
188
- json_path = os.path.splitext(out_path)[0] + "_summary.json"
189
- with open(json_path, "w", encoding="utf-8") as fh:
190
- json.dump({"reference": args.reference, "net": args.net, "noise_floor": floor,
191
- "reference_self_lpips": self_lpips, "checkpoints": summary}, fh, indent=2)
192
- print("\nwrote {}\n {}".format(out_path, json_path))
193
- return 0
194
-
195
-
196
- if __name__ == "__main__":
197
- sys.exit(main())
 
1
+ """LPIPS / PSNR / SSIM implementations, shared by `fidelity_bench.py`.
2
 
3
+ Not a command-line tool. It used to be, scoring renders named
4
+ ``bench_<checkpoint>_<prompt_id>_00001_.png`` -- a naming scheme nothing in this repo
5
+ produces any more, which made the CLI undriveable, and a methodology `fidelity_bench.py`
6
+ argues against in its own docstring (one seed per cell, marginal means). The measurement
7
+ code was worth keeping; the entry point was not.
8
 
9
+ Read any of these numbers with two cautions:
 
 
 
 
 
 
 
 
 
10
 
11
  * **A number is only meaningful against a noise floor.** Two BF16 runs at different seeds are
12
  not identical images either. Until that distance is measured, "LPIPS 0.27" does not tell you
13
+ whether a checkpoint drifted or merely rolled different dice. `fidelity_bench score` prints
14
+ the floor per arm for exactly this reason.
15
  * **LPIPS measures divergence, not damage.** W4A4 shifts the sampling trajectory: the image
16
  lands somewhere else, which is not the same as landing somewhere worse. High LPIPS with
17
  intact aesthetics means drift. Do not read it as quality loss on its own.
18
 
19
+ SSIM is computed here rather than pulled from scikit-image to keep the dependency list short.
 
20
  """
21
 
22
  from __future__ import annotations
23
 
 
 
 
 
 
 
 
 
24
  import torch
25
  import torch.nn.functional as F
26
 
 
 
27
 
28
+ def load_image(path: str, device) -> torch.Tensor:
 
29
  """PNG -> [1,3,H,W] in [-1,1], which is what LPIPS expects."""
30
  from PIL import Image
31
 
 
60
  c1, c2 = 0.01 ** 2, 0.03 ** 2
61
  s = ((2 * mu_xy + c1) * (2 * sigma_xy + c2)) / ((mu_x2 + mu_y2 + c1) * (sigma_x + sigma_y + c2))
62
  return s.mean().item()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
workflows/krea2_base_svdquant_w4a4_t2i_api.json CHANGED
@@ -1,57 +1,127 @@
1
- {
2
- "1": {
3
- "class_type": "Krea2SVDQuantW4A4Loader",
4
- "_meta": {"title": "Krea2 Base SVDQuant W4A4 (rank 64)"},
5
- "inputs": {"model_name": "Krea2-Base-SVDQuant-W4A4-rank64.safetensors"}
6
- },
7
- "2": {
8
- "class_type": "CLIPLoader",
9
- "_meta": {"title": "Text encoder (Qwen3-VL 4B)"},
10
- "inputs": {"clip_name": "qwen3vl_4b_fp8_scaled.safetensors", "type": "krea2", "device": "default"}
11
- },
12
- "3": {
13
- "class_type": "VAELoader",
14
- "_meta": {"title": "VAE"},
15
- "inputs": {"vae_name": "qwen_image_vae.safetensors"}
16
- },
17
- "4": {
18
- "class_type": "CLIPTextEncode",
19
- "_meta": {"title": "Positive prompt"},
20
- "inputs": {
21
- "text": "A photorealistic portrait of a snow leopard resting on a mossy rock in a misty alpine forest at dawn, golden rim light, shallow depth of field, 85mm lens, ultra detailed fur",
22
- "clip": ["2", 0]
23
- }
24
- },
25
- "5": {
26
- "class_type": "CLIPTextEncode",
27
- "_meta": {"title": "Negative prompt (base model uses real CFG)"},
28
- "inputs": {
29
- "text": "blurry, low resolution, jpeg artifacts, watermark, text, deformed, extra limbs",
30
- "clip": ["2", 0]
31
- }
32
- },
33
- "6": {
34
- "class_type": "EmptySD3LatentImage",
35
- "_meta": {"title": "Latent 1024x1024"},
36
- "inputs": {"width": 1024, "height": 1024, "batch_size": 1}
37
- },
38
- "7": {
39
- "class_type": "KSampler",
40
- "_meta": {"title": "KSampler (base: 50 steps, cfg 3.5)"},
41
- "inputs": {
42
- "seed": 987654321, "steps": 50, "cfg": 3.5, "sampler_name": "euler",
43
- "scheduler": "simple", "denoise": 1.0,
44
- "model": ["1", 0], "positive": ["4", 0], "negative": ["5", 0], "latent_image": ["6", 0]
45
- }
46
- },
47
- "8": {
48
- "class_type": "VAEDecode",
49
- "_meta": {"title": "VAE Decode"},
50
- "inputs": {"samples": ["7", 0], "vae": ["3", 0]}
51
- },
52
- "9": {
53
- "class_type": "SaveImage",
54
- "_meta": {"title": "Save"},
55
- "inputs": {"images": ["8", 0], "filename_prefix": "krea2_base_svdq_w4a4"}
56
- }
57
- }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "1": {
3
+ "class_type": "Krea2SVDQuantW4A4Loader",
4
+ "inputs": {
5
+ "model_name": "Krea2-Base-SVDQuant-W4A4-rank64.safetensors"
6
+ },
7
+ "_meta": {
8
+ "title": "Krea2 SVDQuant W4A4 Loader (base)"
9
+ }
10
+ },
11
+ "2": {
12
+ "class_type": "CLIPLoader",
13
+ "inputs": {
14
+ "clip_name": "qwen3vl_4b_fp8_scaled.safetensors",
15
+ "type": "krea2",
16
+ "device": "default"
17
+ },
18
+ "_meta": {
19
+ "title": "Text encoder (Qwen3-VL 4B)"
20
+ }
21
+ },
22
+ "3": {
23
+ "class_type": "VAELoader",
24
+ "inputs": {
25
+ "vae_name": "qwen_image_vae.safetensors"
26
+ },
27
+ "_meta": {
28
+ "title": "VAE"
29
+ }
30
+ },
31
+ "4": {
32
+ "class_type": "CLIPTextEncode",
33
+ "inputs": {
34
+ "text": "A cluttered antique clockmaker's workshop seen through a cracked magnifying glass, brass gears laid out in a spiral on the workbench, a ginger cat asleep on a stack of leather-bound books, warm afternoon light with visible dust motes, photorealistic, 85mm lens, shallow depth of field",
35
+ "clip": [
36
+ "2",
37
+ 0
38
+ ]
39
+ },
40
+ "_meta": {
41
+ "title": "Positive prompt"
42
+ }
43
+ },
44
+ "5": {
45
+ "class_type": "CLIPTextEncode",
46
+ "inputs": {
47
+ "text": "blurry, low resolution, jpeg artifacts, watermark, deformed, extra limbs",
48
+ "clip": [
49
+ "2",
50
+ 0
51
+ ]
52
+ },
53
+ "_meta": {
54
+ "title": "Negative prompt (base uses real CFG)"
55
+ }
56
+ },
57
+ "6": {
58
+ "class_type": "EmptySD3LatentImage",
59
+ "inputs": {
60
+ "width": 1024,
61
+ "height": 1024,
62
+ "batch_size": 1
63
+ },
64
+ "_meta": {
65
+ "title": "Latent 1024x1024"
66
+ }
67
+ },
68
+ "7": {
69
+ "class_type": "KSampler",
70
+ "inputs": {
71
+ "seed": 987654321,
72
+ "steps": 50,
73
+ "cfg": 3.5,
74
+ "sampler_name": "euler",
75
+ "scheduler": "simple",
76
+ "denoise": 1.0,
77
+ "model": [
78
+ "1",
79
+ 0
80
+ ],
81
+ "positive": [
82
+ "4",
83
+ 0
84
+ ],
85
+ "negative": [
86
+ "5",
87
+ 0
88
+ ],
89
+ "latent_image": [
90
+ "6",
91
+ 0
92
+ ]
93
+ },
94
+ "_meta": {
95
+ "title": "KSampler - 50 steps, cfg 3.5"
96
+ }
97
+ },
98
+ "8": {
99
+ "class_type": "VAEDecode",
100
+ "inputs": {
101
+ "samples": [
102
+ "7",
103
+ 0
104
+ ],
105
+ "vae": [
106
+ "3",
107
+ 0
108
+ ]
109
+ },
110
+ "_meta": {
111
+ "title": "VAE Decode"
112
+ }
113
+ },
114
+ "9": {
115
+ "class_type": "SaveImage",
116
+ "inputs": {
117
+ "filename_prefix": "krea2_base_svdq",
118
+ "images": [
119
+ "8",
120
+ 0
121
+ ]
122
+ },
123
+ "_meta": {
124
+ "title": "Save"
125
+ }
126
+ }
127
+ }
workflows/krea2_turbo_svdquant_w4a4_t2i_api.json CHANGED
@@ -1,54 +1,126 @@
1
- {
2
- "1": {
3
- "class_type": "Krea2SVDQuantW4A4Loader",
4
- "_meta": {"title": "Krea2 SVDQuant W4A4 (rank 64)"},
5
- "inputs": {"model_name": "Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors"}
6
- },
7
- "2": {
8
- "class_type": "CLIPLoader",
9
- "_meta": {"title": "Text encoder (Qwen3-VL 4B)"},
10
- "inputs": {"clip_name": "qwen3vl_4b_fp8_scaled.safetensors", "type": "krea2", "device": "default"}
11
- },
12
- "3": {
13
- "class_type": "VAELoader",
14
- "_meta": {"title": "VAE"},
15
- "inputs": {"vae_name": "qwen_image_vae.safetensors"}
16
- },
17
- "4": {
18
- "class_type": "CLIPTextEncode",
19
- "_meta": {"title": "Prompt"},
20
- "inputs": {
21
- "text": "A photorealistic portrait of a snow leopard resting on a mossy rock in a misty alpine forest at dawn, golden rim light, shallow depth of field, 85mm lens, ultra detailed fur",
22
- "clip": ["2", 0]
23
- }
24
- },
25
- "5": {
26
- "class_type": "ConditioningZeroOut",
27
- "_meta": {"title": "Negative (zeroed, cfg=1)"},
28
- "inputs": {"conditioning": ["4", 0]}
29
- },
30
- "6": {
31
- "class_type": "EmptySD3LatentImage",
32
- "_meta": {"title": "Latent 1024x1024"},
33
- "inputs": {"width": 1024, "height": 1024, "batch_size": 1}
34
- },
35
- "7": {
36
- "class_type": "KSampler",
37
- "_meta": {"title": "KSampler (turbo: 8 steps, cfg 1)"},
38
- "inputs": {
39
- "seed": 987654321, "steps": 8, "cfg": 1.0, "sampler_name": "euler",
40
- "scheduler": "simple", "denoise": 1.0,
41
- "model": ["1", 0], "positive": ["4", 0], "negative": ["5", 0], "latent_image": ["6", 0]
42
- }
43
- },
44
- "8": {
45
- "class_type": "VAEDecode",
46
- "_meta": {"title": "VAE Decode"},
47
- "inputs": {"samples": ["7", 0], "vae": ["3", 0]}
48
- },
49
- "9": {
50
- "class_type": "SaveImage",
51
- "_meta": {"title": "Save"},
52
- "inputs": {"images": ["8", 0], "filename_prefix": "krea2_svdq_w4a4"}
53
- }
54
- }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "1": {
3
+ "class_type": "Krea2SVDQuantW4A4Loader",
4
+ "inputs": {
5
+ "model_name": "Krea2-Turbo-SVDQuant-W4A4-rank64.safetensors"
6
+ },
7
+ "_meta": {
8
+ "title": "Krea2 SVDQuant W4A4 Loader"
9
+ }
10
+ },
11
+ "2": {
12
+ "class_type": "CLIPLoader",
13
+ "inputs": {
14
+ "clip_name": "qwen3vl_4b_fp8_scaled.safetensors",
15
+ "type": "krea2",
16
+ "device": "default"
17
+ },
18
+ "_meta": {
19
+ "title": "Text encoder (Qwen3-VL 4B)"
20
+ }
21
+ },
22
+ "3": {
23
+ "class_type": "VAELoader",
24
+ "inputs": {
25
+ "vae_name": "qwen_image_vae.safetensors"
26
+ },
27
+ "_meta": {
28
+ "title": "VAE"
29
+ }
30
+ },
31
+ "4": {
32
+ "class_type": "CLIPTextEncode",
33
+ "inputs": {
34
+ "text": "A cluttered antique clockmaker's workshop seen through a cracked magnifying glass, brass gears laid out in a spiral on the workbench, a ginger cat asleep on a stack of leather-bound books, warm afternoon light with visible dust motes, photorealistic, 85mm lens, shallow depth of field",
35
+ "clip": [
36
+ "2",
37
+ 0
38
+ ]
39
+ },
40
+ "_meta": {
41
+ "title": "Prompt"
42
+ }
43
+ },
44
+ "5": {
45
+ "class_type": "ConditioningZeroOut",
46
+ "inputs": {
47
+ "conditioning": [
48
+ "4",
49
+ 0
50
+ ]
51
+ },
52
+ "_meta": {
53
+ "title": "Negative (zeroed - required at cfg 1.0)"
54
+ }
55
+ },
56
+ "6": {
57
+ "class_type": "EmptySD3LatentImage",
58
+ "inputs": {
59
+ "width": 1024,
60
+ "height": 1024,
61
+ "batch_size": 1
62
+ },
63
+ "_meta": {
64
+ "title": "Latent 1024x1024"
65
+ }
66
+ },
67
+ "7": {
68
+ "class_type": "KSampler",
69
+ "inputs": {
70
+ "seed": 987654321,
71
+ "steps": 8,
72
+ "cfg": 1.0,
73
+ "sampler_name": "euler",
74
+ "scheduler": "simple",
75
+ "denoise": 1.0,
76
+ "model": [
77
+ "1",
78
+ 0
79
+ ],
80
+ "positive": [
81
+ "4",
82
+ 0
83
+ ],
84
+ "negative": [
85
+ "5",
86
+ 0
87
+ ],
88
+ "latent_image": [
89
+ "6",
90
+ 0
91
+ ]
92
+ },
93
+ "_meta": {
94
+ "title": "KSampler - 8 steps, cfg 1.0"
95
+ }
96
+ },
97
+ "8": {
98
+ "class_type": "VAEDecode",
99
+ "inputs": {
100
+ "samples": [
101
+ "7",
102
+ 0
103
+ ],
104
+ "vae": [
105
+ "3",
106
+ 0
107
+ ]
108
+ },
109
+ "_meta": {
110
+ "title": "VAE Decode"
111
+ }
112
+ },
113
+ "9": {
114
+ "class_type": "SaveImage",
115
+ "inputs": {
116
+ "filename_prefix": "krea2_turbo_svdq",
117
+ "images": [
118
+ "8",
119
+ 0
120
+ ]
121
+ },
122
+ "_meta": {
123
+ "title": "Save"
124
+ }
125
+ }
126
+ }