Model card with measured results

README.md

@@ -0,0 +1,153 @@
+---
+license: other
+license_name: ltx-2.5-community
+tags:
+  - quantization
+  - gptq
+  - awq
+  - nvfp4
+  - text-encoder
+  - ltx-video
+  - comfyui
+base_model: Lightricks/LTX-2.5
+---
+
+# LTX-2.5 Text Encoder — nvfp4, portable
+
+The Gemma4-12B text encoder that drives LTX-2.5's DiT, compressed from
+**26.264 GB to 8.46 GB** (3.10x), with **no compute-capability floor**.
+
+Built from the encoder Lightricks published on 2026-08-17
+(`1b92891c`, *"Aligns the published encoders with the LTX-2.5 model
+checkpoints"*) — the revision that matches the released DiT.
+
+## Why this one
+
+Every other public quantization of this encoder needs recent hardware:
+
+| build | size | needs |
+|---|---:|---|
+| Lightricks BF16 | 26.264 GB | — |
+| Lightricks `comfy-int8-convrot` | 15.373 GB | cc 8.9 |
+| DmitryDB `nvfp4` | 11.197 GB | cc 8.9, `comfy_kitchen`, CUDA 13 |
+| joeygambino / Winnougan `w4a8` | 10.604 GB | SM 8.0+ |
+| **this** | **8.46 GB** | **nothing beyond PyTorch** |
+
+Dequantization happens on the CPU at load and the resident model is BF16, so
+there is no kernel requirement to satisfy. Verified running on **Tesla V100
+(cc 7.0)**, **A100 (cc 8.0)** and **RTX 6000 Ada (cc 8.9)**.
+
+It is also the smallest of the set, because it quantizes the three tensors the
+other nvfp4 recipe protects as BF16 "precision islands" — `embed_tokens` and
+both aggregate tables, 4.4 GB of the source.
+
+## Files
+
+| file | build | video relL2 | audio relL2 | `\|\|Q\|\|/\|\|W\|\|` |
+|---|---|---:|---:|---:|
+| `A3.packed.safetensors` | bypass guard + group-bounded AWQ | **0.05204** | **0.04827** | **4.216** |
+| `A0.packed.safetensors` | legacy guard, for comparison | 0.06061 | 0.06095 | 302.654 |
+
+**Use `A3`.** `A0` is published only so the comparison can be checked; it
+carries weights up to 300x their proper norm in near-dead channels, which is
+harmless on this calibration set and fragile by construction.
+
+## Memory
+
+| mode | resident | encode |
+|---|---:|---|
+| `resident` (default) | **7.75 GiB** | dequantizes inside `forward` |
+| `dequantized` | ~26.3 GB | one dense build at load |
+
+The two produce `torch.equal` conditioning, so the choice is footprint against
+speed and never quality. `resident` measured at **8.34 GiB** peak on a 16 GB
+V100 — the encoder fits one consumer card for the first time.
+
+## Use it
+
+### Standalone
+
+```python
+from ltx_packed_codec import load_packed_model
+from transformers import AutoTokenizer
+
+model = load_packed_model("path/to/encoder-hf", "A3.packed.safetensors",
+                          resident=True)
+tokenizer = AutoTokenizer.from_pretrained("path/to/encoder-hf")
+```
+
+`encoder-hf` is a normal HF model directory for this encoder — config,
+tokenizer and the assets that ship inside the original safetensors. Extract it
+with `ltx_extract_encoder_assets.py` from the Lightricks file.
+
+### ComfyUI
+
+`comfy_nodes/ComfyUI-LTXPacked/` provides **LTX Packed Encoder Loader** and
+**LTX Packed Text Encode**, which replace `CLIPTextEncode` and emit a
+CONDITIONING directly.
+
+They do not go through `LTXAVTextEncoderLoader`, and cannot: ComfyUI's LTX CLIP
+path wants a sentencepiece `spiece_model` where this checkpoint carries
+`tokenizer_json`, and its nvfp4 support requires `comfy_kitchen` plus CUDA 13
+plus cc 8.9 — the floor this file exists to avoid. The DiT only ever needed a
+CONDITIONING.
+
+> **Not yet run inside ComfyUI.** The encode path is the same code this
+> project's `ltx_conditioning_dump.py` runs daily and the conditioning wrapper
+> is lifted verbatim from its renderer, so the pieces are exercised — but the
+> nodes themselves have not been loaded in a live ComfyUI, and that is a
+> different claim.
+
+## How it was built
+
+nvfp4 4.5 bpw (E2M1, group 16 with an fp8-e4m3 scale) on 320 projections;
+int8 row-wise on `embed_tokens` and both aggregate tables; norms and asset blobs
+left BF16. Per-tensor AWQ alpha search, then sequential GPTQ error compensation
+(blocksize 128, percdamp 0.01), packed inside the build because the group scales
+cannot be recovered afterwards.
+
+`A3` adds three things the plain recipe lacks:
+
+1. **No weight column is ever zeroed.** Channels are classified by an *absolute*
+   activation RMS, not a threshold relative to `mean(diag(H))` — the relative
+   rule moves with the calibration Hessian's dynamic range, which made the old
+   guard's best setting differ between Volta and Ada.
+2. **The AWQ scale is shaped to the storage grid.** nvfp4 carries one scale per
+   16 input channels and its E2M1 grid spans 12:1; an unshaped per-channel scale
+   spans far wider inside a group and pushes the low channels under the grid
+   floor, where they quantize to exactly zero. Bounding the spread to 12:1 keeps
+   both the smoothing and the channels. The identity
+   `x·diag(1/s) @ Q(W·diag(s))ᵀ` holds for any `s`, so this needs no format
+   change.
+3. **Escalating damping, recorded.** Group shaping removes conditioning that
+   per-channel smoothing was supplying as a side effect; `A3` needed a 10x
+   escalation, written into the artifact metadata so a damped build is never
+   silently compared with an undamped one.
+
+## Measured limits
+
+* **Packing is lossless.** A twin BF16 build plus a full `verify`: all 686
+  tensors value-exact. No drift here is attributable to the format.
+* **GPTQ builds do not reproduce across GPU architectures.** Same code, plan,
+  calibration and guard: V100 0.06879, Ada 0.11210 on the older source. Within
+  one architecture they reproduce to five decimals across separate machines.
+  These files were built on an **A100**; quote that alongside any figure.
+* **No KL or CE ratio is reported.** This artifact carries no LM head, so
+  vocabulary KL and CE ratio are undefined for its deployment path. Measured
+  instead: conditioning relL2/cosine per branch, and a five-prompt render
+  comparison against a BF16 conditioning from the same card, where `A3` is
+  closer on four of five (mean 0.05931 against `A0`'s 0.06571).
+* **Not evaluated**: human listening, native DiT cross-attention KL, or whether
+  the remaining gap to BF16 is visible at all in finished video.
+* Prompts asking for four-legged or wheeled robots still render humans. That
+  happens with the BF16 encoder too — a model limit, not compression damage.
+
+## Provenance
+
+Source `Lightricks/LTX-2.5` revision `1b92891c`+, torch 2.11.0+cu128,
+transformers 5.14.1, plan `r45c`, calibration `calib-large.txt`. Evidence in
+`evidence/`: gate JSON, build logs with per-layer drift and `||Q||/||W||`, the
+A100 BF16 reference, all three conditionings, and fifteen rendered clips.
+
+Earlier builds against the pre-2026-08-17 encoder, and the method results that
+came from them, are at `topabaem/Pacific-LTX-2.5-Encoder-r45d`.