Card: declare the diffusers-layout source and Lightricks/LTX-2.5 as base models

2e1b2c2 verified 2 months ago

6.12 kB

---
license: other
license_name: ltx-2-community-license-agreement
license_link: https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md
base_model:
  - Lightricks/LTX-2.5-Diffusers
  - Lightricks/LTX-2.5
base_model_relation: quantized
library_name: diffusers
pipeline_tag: image-to-video
tags:
  - ltx-2.5
  - nvfp4
  - 4-bit
  - quantized
  - dgx-spark
  - gb10
  - blackwell
extra_gated_prompt: >-
  These are quantized derivatives of LTX-2.5 and are distributed under the LTX-2
  Community License Agreement, a complete copy of which is included in this
  repository as LICENSE.md. By requesting access you confirm you have read and
  accepted it, including the use restrictions in Section 4 and Attachment A.
  IMPORTANT: under Section 2.1, entities with annual revenues of at least
  $10,000,000 must obtain a paid Commercial Use Agreement from Lightricks
  (ltxv-licensing@lightricks.com) before ANY use other than a Non-Commercial
  Purpose as defined in Section 2.2. This applies to these derivative weights
  exactly as it applies to the originals.
extra_gated_fields:
  Name: text
  Organization: text
  I have read and accept the LTX-2 Community License Agreement: checkbox
  My organization has annual revenue under 10M USD, or already holds a Commercial Use Agreement with Lightricks: checkbox
---
# LTX-2.5 (distilled) — weight-only NVFP4

Weight-only NVFP4 quantization of [`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers),
made so the model fits and generates on a single NVIDIA GB10 (DGX Spark, `sm_121`)
**alongside other resident models**.

The source is the diffusers-layout repo, so these are the same weights as
[`Lightricks/LTX-2.5`](https://huggingface.co/Lightricks/LTX-2.5) in a different
container: component subdirectories and sharded safetensors rather than the
single-file ComfyUI layout that the GGUF and ComfyUI-NVFP4 builds start from.
If you load LTX-2.5 through `diffusers`, this is the one to take; if you load it
through ComfyUI, it is not.

**68.24 GB → 21.18 GB.**

| component | bf16 | NVFP4 | |
|---|--:|--:|--:|
| `transformer` (distilled DiT) | 37.98 GB | 11.14 GB | 3.41× |
| `text_encoder` (Gemma-4) | 23.92 GB | 8.25 GB | 2.90× |
| `connectors` | 6.34 GB | 1.79 GB | 3.55× |

## NOTICE OF MODIFICATION (LTX-2 Community License §3.3)

**These files have been modified from the originals distributed by Lightricks.**

Every 2-D `.weight` tensor above 2²⁰ elements that is not an embedding or a norm
has been replaced by three tensors — `.weight_packed` (E2M1, two values per byte),
`.weight_scale` (E4M3, one per 16 elements) and `.weight_scale_2` (F32 per-tensor)
— using `torch`'s `to_nvfp4`. Embeddings, norms, positional and register
parameters, and all tensors below the size threshold are carried through
unchanged at their original precision. Activations are **not** quantized. Each
shard carries `{"quant": "nvfp4_weight_only"}` in its safetensors metadata.

No fine-tuning, distillation, or retraining was performed. Only the `transformer`,
`text_encoder` and `connectors` components are included; every other component
(vae, audio_vae, scheduler, tokenizer, vocoder, …) must come from the upstream
repository unmodified.
## Why weight-only and not W4A4
Quantizing activations to 4 bits produced visibly grainy, distorted video in our
testing (0.20 relative error through a stacked FFN). Weight-only delivers the
same ~4× capacity win — which is the entire reason the model fits — without
touching the activation path. If you need W4A4, calibrate and evaluate it
yourself; do not assume this checkpoint's quality carries over.
## Measured on GB10
Image-to-video, 768×768, 97 frames (4.04 s @ 24 fps), the distilled 8-sigma
schedule fully unguided, seed 42:
| stage | time |
|---|--:|
| weight load | 154.9 – 168.6 s |
| denoise + decode | **63.4 / 64.5 / 67.3 s** (three runs) |
| total | 222 – 233 s |
The 67.3 s run had an unrelated 3D pipeline resident at 37.8 GB throughout.
Report load and generation **separately**. Load is bandwidth-bound and dominates
on a chip that is capacity-rich and bandwidth-poor (~273 GB/s); denoise is
compute-bound. A single end-to-end total mostly measures cold weight streaming,
which is why published Spark numbers for the same model rarely agree.
## Usage
Requires `diffusers` 0.40+ and `transformers` 5.15+ (LTX2 classes and the Gemma-4
text encoder). These are *packed* weights: standard `from_pretrained` will not
load them. Use the loader and quantizer from
[spark-nvfp4-bench](https://github.com/kevindowling/spark-nvfp4-bench), which
swaps each `nn.Linear` for a packed-NVFP4 module before assigning tensors.

The shipped `*.index.json` files describe the tensors that are actually here —
`weight_packed` / `weight_scale` / `weight_scale_2` for every quantized layer,
and a `total_size` of the packed footprint — so an index-driven loader resolves
correctly and a preflight download sizing is honest.

Note that the distilled DiT runs a fixed 8-sigma schedule fully unguided; passing
`num_inference_steps` hands it a generic linear schedule and quietly costs quality.

## Reproducing

Nothing here is unreproducible — `quantize_ltx_nvfp4.py` in the repo above takes
the upstream component directory and emits these files. Peak memory is one shard
(~10 GB), not the whole model.

One warning if you adapt it: upstream `transformer/` contains **two shard sets
that are different models** (a 4-shard and an 8-shard, ~38 GB each, sharing one
`config.json`), and only the 4-shard set is referenced by `weight_map`. A
quantizer or loader that globs `*.safetensors` will silently interleave two
distinct 22B checkpoints without raising anything. Drive off the index.

## License

LTX-2 Community License Agreement — full text in `LICENSE.md`, which you must
pass on to anyone you redistribute these files to (§3.2). Use is subject to the
restrictions in Section 4 and Attachment A. See the gated-access notice above
regarding the $10M revenue threshold in §2.1 and the transfer conditions in §3.5.

Not affiliated with or endorsed by Lightricks.

	---
	license: other
	license_name: ltx-2-community-license-agreement
	license_link: https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md
	base_model:
	- Lightricks/LTX-2.5-Diffusers
	- Lightricks/LTX-2.5
	base_model_relation: quantized
	library_name: diffusers
	pipeline_tag: image-to-video
	tags:
	- ltx-2.5
	- nvfp4
	- 4-bit
	- quantized
	- dgx-spark
	- gb10
	- blackwell
	extra_gated_prompt: >-
	These are quantized derivatives of LTX-2.5 and are distributed under the LTX-2
	Community License Agreement, a complete copy of which is included in this
	repository as LICENSE.md. By requesting access you confirm you have read and
	accepted it, including the use restrictions in Section 4 and Attachment A.
	IMPORTANT: under Section 2.1, entities with annual revenues of at least
	$10,000,000 must obtain a paid Commercial Use Agreement from Lightricks
	(ltxv-licensing@lightricks.com) before ANY use other than a Non-Commercial
	Purpose as defined in Section 2.2. This applies to these derivative weights
	exactly as it applies to the originals.
	extra_gated_fields:
	Name: text
	Organization: text
	I have read and accept the LTX-2 Community License Agreement: checkbox
	My organization has annual revenue under 10M USD, or already holds a Commercial Use Agreement with Lightricks: checkbox
	---

	# LTX-2.5 (distilled) — weight-only NVFP4

	Weight-only NVFP4 quantization of [`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers),
	made so the model fits and generates on a single NVIDIA GB10 (DGX Spark, `sm_121`)
	alongside other resident models.

	The source is the diffusers-layout repo, so these are the same weights as
	[`Lightricks/LTX-2.5`](https://huggingface.co/Lightricks/LTX-2.5) in a different
	container: component subdirectories and sharded safetensors rather than the
	single-file ComfyUI layout that the GGUF and ComfyUI-NVFP4 builds start from.
	If you load LTX-2.5 through `diffusers`, this is the one to take; if you load it
	through ComfyUI, it is not.

	68.24 GB → 21.18 GB.

	\| component \| bf16 \| NVFP4 \| \|
	\|---\|--:\|--:\|--:\|
	\| `transformer` (distilled DiT) \| 37.98 GB \| 11.14 GB \| 3.41× \|
	\| `text_encoder` (Gemma-4) \| 23.92 GB \| 8.25 GB \| 2.90× \|
	\| `connectors` \| 6.34 GB \| 1.79 GB \| 3.55× \|

	## NOTICE OF MODIFICATION (LTX-2 Community License §3.3)

	These files have been modified from the originals distributed by Lightricks.

	Every 2-D `.weight` tensor above 2²⁰ elements that is not an embedding or a norm
	has been replaced by three tensors — `.weight_packed` (E2M1, two values per byte),
	`.weight_scale` (E4M3, one per 16 elements) and `.weight_scale_2` (F32 per-tensor)
	— using `torch`'s `to_nvfp4`. Embeddings, norms, positional and register
	parameters, and all tensors below the size threshold are carried through
	unchanged at their original precision. Activations are not quantized. Each
	shard carries `{"quant": "nvfp4_weight_only"}` in its safetensors metadata.

	No fine-tuning, distillation, or retraining was performed. Only the `transformer`,
	`text_encoder` and `connectors` components are included; every other component
	(vae, audio_vae, scheduler, tokenizer, vocoder, …) must come from the upstream
	repository unmodified.

	## Why weight-only and not W4A4

	Quantizing activations to 4 bits produced visibly grainy, distorted video in our
	testing (0.20 relative error through a stacked FFN). Weight-only delivers the
	same ~4× capacity win — which is the entire reason the model fits — without
	touching the activation path. If you need W4A4, calibrate and evaluate it
	yourself; do not assume this checkpoint's quality carries over.

	## Measured on GB10

	Image-to-video, 768×768, 97 frames (4.04 s @ 24 fps), the distilled 8-sigma
	schedule fully unguided, seed 42:

	\| stage \| time \|
	\|---\|--:\|
	\| weight load \| 154.9 – 168.6 s \|
	\| denoise + decode \| 63.4 / 64.5 / 67.3 s (three runs) \|
	\| total \| 222 – 233 s \|

	The 67.3 s run had an unrelated 3D pipeline resident at 37.8 GB throughout.

	Report load and generation separately. Load is bandwidth-bound and dominates
	on a chip that is capacity-rich and bandwidth-poor (~273 GB/s); denoise is
	compute-bound. A single end-to-end total mostly measures cold weight streaming,
	which is why published Spark numbers for the same model rarely agree.

	## Usage

	Requires `diffusers` 0.40+ and `transformers` 5.15+ (LTX2 classes and the Gemma-4
	text encoder). These are packed weights: standard `from_pretrained` will not
	load them. Use the loader and quantizer from
	[spark-nvfp4-bench](https://github.com/kevindowling/spark-nvfp4-bench), which
	swaps each `nn.Linear` for a packed-NVFP4 module before assigning tensors.

	The shipped `*.index.json` files describe the tensors that are actually here —
	`weight_packed` / `weight_scale` / `weight_scale_2` for every quantized layer,
	and a `total_size` of the packed footprint — so an index-driven loader resolves
	correctly and a preflight download sizing is honest.

	Note that the distilled DiT runs a fixed 8-sigma schedule fully unguided; passing
	`num_inference_steps` hands it a generic linear schedule and quietly costs quality.

	## Reproducing

	Nothing here is unreproducible — `quantize_ltx_nvfp4.py` in the repo above takes
	the upstream component directory and emits these files. Peak memory is one shard
	(~10 GB), not the whole model.

	One warning if you adapt it: upstream `transformer/` contains **two shard sets
	that are different models** (a 4-shard and an 8-shard, ~38 GB each, sharing one
	`config.json`), and only the 4-shard set is referenced by `weight_map`. A
	quantizer or loader that globs `*.safetensors` will silently interleave two
	distinct 22B checkpoints without raising anything. Drive off the index.

	## License

	LTX-2 Community License Agreement — full text in `LICENSE.md`, which you must
	pass on to anyone you redistribute these files to (§3.2). Use is subject to the
	restrictions in Section 4 and Attachment A. See the gated-access notice above
	regarding the $10M revenue threshold in §2.1 and the transfer conditions in §3.5.

	Not affiliated with or endorsed by Lightricks.