Ltx23 GGUF VAE Companion

LTX-2.3 VAE + vocoder companion — for GGUF runs

A 9 GB stand-in for the 43 GB checkpoint, for when your DiT comes from a GGUF. Same VAEs, byte for byte. Cuts peak system RAM from ~60 GB to ~11 GB.

If you run a GGUF DiT on a 64 GB machine and ComfyUI dies while loading with Windows fatal exception: access violation, this is the fix.

The problem

When you put a GGUF in model_file, the JoyAI-Echo loader takes the transformer from the GGUF — but checkpoint_path is still required, because it supplies the VAEs, the vocoder and the text-embedding projection.

The catch: the loader materialises that whole checkpoint in system RAM as owned copies, not memory-mapped. Against a 43 GB bf16 build that is roughly 60 GB at peak. It has to be owned copies — a tensor left aliasing the safetensors mmap dangles once the file closes, and the next load faults natively on Windows.

So on a 64 GB box you are ~4 GB from the wall before Windows, ComfyUI and the Gemma encoder take their share. It usually falls over, and it looks like a VRAM problem even though the GPU is sitting idle — the crash lands in create_vae_wrappers, right after the DiT loaded perfectly.

What is actually needed

Of a 43 GB checkpoint, a GGUF run touches 9.02 GB - a GGUF carries only the transformer BLOCKS, so everything else must come from checkpoint_path:

kept	size	tensors
model.* (embedding connectors, adaLN singles, patchify/proj)	4.89 GB	316
text_embedding_projection.*	2.31 GB	4
vae.*	1.45 GB	170
vocoder.*	0.26 GB	1227
audio_vae.*	0.11 GB	102
total	9.02 GB	1819

The other ~34 GB is the DiT's transformer blocks - which the GGUF is already providing. You are paying 34 GB of RAM for tensors that get overwritten.

Using it

1. Put this file wherever your checkpoints live.
2. In JoyEcho_ModelLoader: your GGUF in model_file, this file in checkpoint_path.
3. Nothing else changes.

model_file       LTX23-echoVid-ltxAud-Surgical-e50-DiT-Q5_0.gguf
checkpoint_path  ltx23_e50_GGUF-COMPANION.safetensors

Peak system RAM drops to about 11 GB, and load time drops with it.

What it is not

• Not a model. There is no DiT in here. On its own it generates nothing — it is the other half of a GGUF.
• Not quantised. The VAE, vocoder and projection tensors are copied verbatim from the bf16 source, bit for bit. Output is identical.
• Not a substitute for the full checkpoint if you are running a .safetensors DiT. In that case you need the whole file.

Which one do I need?

The VAEs are shared across the LTX-2.3 family, so in practice this companion loads with any LTX-2.3 GGUF. But matching the family it was cut from matters more than it used to: the embedding connectors and adaLN gate tensors ride in this file, and those DIFFER between merge variants (they were merge axes in the echoVid family). This file is cut from the e50 merge - it is the exact match for the e50 GGUFs; with other variants it works but supplies e50's gates. For an exact pairing with a different checkpoint, cut your own with the included script (one command). text_embedding_projection remains the piece that keeps voice and identity conditioning wired up. A GGUF missing those four tensors is the classic cause of robotic voice, the model reading your prompt aloud, and a different face every shot.

Build your own

build_vae_companion.py cuts one from any full LTX-2.3 checkpoint:

python build_vae_companion.py path/to/full_checkpoint.safetensors

It keeps __metadata__ deliberately — the GGUF path calls _full_config(checkpoint_path) to configure the transformer, so a companion stripped of metadata would silently fall back to a stock config. The script refuses to write a file that would.

Verification

Built from ltx23_echoVid-ltxAud_surgical_e50_bf16.safetensors:

• 1819 tensors, all five groups present
• _full_config() returns identically to the 43 GB original — num_layers=48, in_channels=128, positional_embedding_max_pos=[20, 2048, 2048]
• VAE tensor payloads byte-identical to the source (SHA-256 spot checks)

Related

• JoyAI-Echo multishot patch — the node pack this targets
• LTX-2.3 Multishot Lite — core-node workflow
• All models

License

LTX-2 Community License, inherited from the source checkpoint. Non-commercial where the source is non-commercial.

Support

Everything here is free and stays free. If it saved you time, you can sponsor me on GitHub, buy me a coffee, or support me on Liberapay.