LTX-2.5 Gemma 4 12B text encoder with projections — GGUF

Validated Q2_K, Q4_K_M, and Q5_K_M GGUF quantizations of the Gemma 4 12B text encoder bundled with both LTX-2.5 audio/video projection heads from Lightricks/LTX-2.5.

This is an LTX-2.5 conditioning component, not a general-purpose Gemma chat model. The matching quantized transformer is in elix3r/LTX-2.5-22b-distilled-GGUF.

Files

These are mixed quantizations, so their effective BPW is determined by the actual per-tensor qtypes rather than the family name alone. Relative to Q5_K_M, Q4_K_M is 11.56% smaller and Q2_K is 37.39% smaller. See QUANTIZATION.md for exact accounting and measured numerical tradeoffs.

Requirements

• Git, Python, and the Hugging Face hf CLI.
• Access to the gated Lightricks/LTX-2.5 repository for the transformer support models.
• Current ComfyUI core LTX-2.5 nodes plus ComfyUI-GGUF.
• The matching LTX-2.5 distilled transformer; the encoder is not useful by itself for video generation.

The known-good combination used for this audit is:

The end-to-end GPU runs used Python 3.14.4, PyTorch 2.10.0+cu128, an RTX 4070 Ti SUPER with 16 GB VRAM, 32 GB system RAM, and swap. This is a tested configuration, not a universal minimum.

Installation

The commands below use a dedicated ComfyUI virtual environment and pin the two tested source revisions. Set COMFY_DIR to the absolute path where ComfyUI should live.

1. Install or update ComfyUI

Fresh install:

export COMFY_DIR=/absolute/path/to/ComfyUI
git clone https://github.com/comfyanonymous/ComfyUI.git "$COMFY_DIR"
git -C "$COMFY_DIR" checkout 2f35f4a08176d993cded35dac3332be4f7287f41
python3 -m venv "$COMFY_DIR/venv"
"$COMFY_DIR/venv/bin/python" -m pip install -U pip
"$COMFY_DIR/venv/bin/python" -m pip install -r "$COMFY_DIR/requirements.txt"

For an existing clean checkout, inspect git status before changing revisions:

export COMFY_DIR=/absolute/path/to/ComfyUI
git -C "$COMFY_DIR" status --short
git -C "$COMFY_DIR" fetch origin
git -C "$COMFY_DIR" checkout 2f35f4a08176d993cded35dac3332be4f7287f41
"$COMFY_DIR/venv/bin/python" -m pip install -r "$COMFY_DIR/requirements.txt"

Do not discard a dirty worktree to follow these instructions. Preserve or commit your changes first.

2. Install or update ComfyUI-GGUF

Fresh install:

git clone https://github.com/city96/ComfyUI-GGUF.git \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF"
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" checkout \
  6ea2651e7df66d7585f6ffee804b20e92fb38b8a
"$COMFY_DIR/venv/bin/python" -m pip install -r \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF/requirements.txt"

For an existing clean plugin checkout:

git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" status --short
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" fetch origin
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" checkout \
  6ea2651e7df66d7585f6ffee804b20e92fb38b8a
"$COMFY_DIR/venv/bin/python" -m pip install -r \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF/requirements.txt"

3. Download the transformer

"$COMFY_DIR/venv/bin/python" -m pip install -U huggingface_hub
"$COMFY_DIR/venv/bin/hf" auth login
"$COMFY_DIR/venv/bin/hf" download elix3r/LTX-2.5-22b-distilled-GGUF \
  ltx-2.5-22b-distilled-transformer-Q5_K_M.gguf \
  --local-dir "$COMFY_DIR/models/diffusion_models"

4. Download this Gemma 4 LTX encoder

The canonical current ComfyUI directory is models/text_encoders/. models/clip/ remains a legacy alias in current ComfyUI, but it is not the recommended install path.

Choose one of Q2_K, Q4_K_M, or Q5_K_M. Q5_K_M retains the most precision; Q4_K_M and Q2_K trade progressively more precision for smaller files.

export LTX_TEXT_QUANT=Q4_K_M
export LTX_TEXT_ENCODER="gemma4-12b-with-proj-ltx-2.5-${LTX_TEXT_QUANT}.gguf"
"$COMFY_DIR/venv/bin/hf" download elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF \
  "$LTX_TEXT_ENCODER" \
  --local-dir "$COMFY_DIR/models/text_encoders"

Verify both large downloads before loading them:

printf '%s  %s\n' \
  cd82849aec38d2be84805b725c803bad44bc67df9850c23a24ef011a51fd7988 \
  "$COMFY_DIR/models/diffusion_models/ltx-2.5-22b-distilled-transformer-Q5_K_M.gguf" \
  | sha256sum -c -
"$COMFY_DIR/venv/bin/hf" download elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF \
  SHA256SUMS --local-dir "$COMFY_DIR/models/text_encoders"
grep "  ${LTX_TEXT_ENCODER}$" "$COMFY_DIR/models/text_encoders/SHA256SUMS" \
  | (cd "$COMFY_DIR/models/text_encoders" && sha256sum -c -)

5. Download the official support models

Accept the upstream LTX-2.5 license first. The convolutional video VAE is the lower-memory choice used by the examples.

"$COMFY_DIR/venv/bin/hf" download Lightricks/LTX-2.5 \
  vae/ltx-2.5-audio-vae-bf16.safetensors \
  vae/ltx-2.5-video-vae-conv-bf16.safetensors \
  --local-dir "$COMFY_DIR/models"

The two-stage example also requires:

"$COMFY_DIR/venv/bin/hf" download Lightricks/LTX-2.5 \
  latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
  --local-dir "$COMFY_DIR/models"

6. Apply the compatibility patch

As of the tested ComfyUI-GGUF revision, stock gguf_clip_loader rejects truthful general.architecture=gemma4. Download and check the included patch before applying it. The audited patch SHA-256 is 1c36aa38fa9c86ec503926bc6b35226e2575b3bfd27b352bff50deccb1cd958e.

export LTX_GGUF_SUPPORT="$COMFY_DIR/.ltx25-gguf-support"
"$COMFY_DIR/venv/bin/hf" download elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF \
  patches/ComfyUI-GGUF-ltx25-gemma4.patch \
  --local-dir "$LTX_GGUF_SUPPORT"
export LTX_GGUF_PATCH="$LTX_GGUF_SUPPORT/patches/ComfyUI-GGUF-ltx25-gemma4.patch"
cd "$COMFY_DIR/custom_nodes/ComfyUI-GGUF"
git apply --check "$LTX_GGUF_PATCH"
git apply "$LTX_GGUF_PATCH"
git diff --check

The patch changes only loader.py:

1. Registers truthful text architecture gemma4 in TXT_ARCH_LIST.
2. Decodes the three named raw BF16 parameters used directly by the companion LTXAV transformer: audio_embeddings_connector.learnable_registers, keyframes_abs_pos_embedding, and video_embeddings_connector.learnable_registers.

It does not add a tokenizer conversion, remap state-dict tensor names, alter the Gemma model implementation, or rewrite GGUF metadata. The encoder already contains ComfyUI-native state-dict names, the complete serialized tokenizer, Hugging Face tokenizer assets, and both projection heads.

If git apply --check fails, check whether it is already applied:

git apply --reverse --check "$LTX_GGUF_PATCH"

If both checks fail, return the plugin to the exact clean tested revision or wait for an updated patch. Do not force the patch, and do not falsify gemma4 as gemma3.

7. Launch ComfyUI

Fully restart ComfyUI after patching:

cd "$COMFY_DIR"
"$COMFY_DIR/venv/bin/python" main.py \
  --lowvram --disable-dynamic-vram --preview-method none

8. Load an example workflow

mkdir -p "$COMFY_DIR/user/default/workflows/LTX25-GGUF"
"$COMFY_DIR/venv/bin/hf" download elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF \
  examples/ltx25-gguf-local-smoke.json \
  examples/ltx25-gguf-local-two-stage-hq.json \
  --local-dir "$COMFY_DIR/user/default/workflows/LTX25-GGUF"

Open LTX25-GGUF/examples/ltx25-gguf-local-smoke.json first. It uses CLIPLoaderGGUF with CLIP type ltxv, local CLIPTextEncode, UnetLoaderGGUF, the official audio and convolutional video VAEs, the distilled eight-step schedule, and synchronized video/audio output. It contains no GemmaAPITextEncode, API prompt enhancer, or ordinary checkpoint loader.

The two-stage example performs native LTX 2× latent spatial upscaling followed by the workflow's four-value refinement sigma schedule and is substantially more memory intensive.

GGUF metadata and tokenizer packaging

Each encoder contains the metadata current ComfyUI needs to identify the component and its projections:

• general.architecture=gemma4
• general.file_type=10, 15, or 17 for Q2_K, Q4_K_M, or Q5_K_M respectively
• general.quantization_version=2
• ltx.text_encoder.version=gemma4-12b-ltx-v1
• dual projection outputs: video 4096, audio 2048, both with bias
• comfy.gguf.tensor_name_layout=comfy_state_dict
• comfy.gguf.requires_gemma4_passthrough=true

Current ComfyUI's LTX Gemma loader consumes a state-dict tensor named tokenizer_json. This artifact embeds that complete 32,169,626-byte tokenizer plus chat_template.jinja, generation_config.json, processor_config.json, and tokenizer_config.json as I16 asset tensors. It intentionally does not use llama.cpp-style tokenizer.ggml.* metadata. For this ComfyUI-specific state-dict layout, the missing tokenizer.ggml.* keys are not missing tokenizer data.

The truthful gemma4 architecture is required to prevent accidental treatment as another text-model family. The current ComfyUI-GGUF architecture allowlist needs the included patch before that value is accepted.

Every file contains the same 686 tensor names, shapes, and 13,147,985,090 logical elements as the source. See QUANTIZATION.md for the exact per-file precision policies.

Validation status

Validated against the exact revisions listed above. Q4_K_M and Q2_K also received a fresh independent structural audit and full 48-layer CPU forward on 2026-09-06:

• Full GGUF header, metadata, non-overlapping range, EOF boundary, qtype byte-math, checksum, name, and logical-shape audit for all three files.
• Patched gguf_clip_loader accepted all 686 tensors from Q5_K_M, Q4_K_M, and Q2_K.
• Current ComfyUI identified GEMMA_4_12B, all 48 layers, and both LTX projection heads for each quantization.
• Full eight-token CPU forwards returned finite [1, 8, 6144] conditioning. Against the same BF16 reference, the published smaller Q4_K_M measured cosine 0.869788 and Q2_K measured cosine 0.881445. These are compatibility/sanity measurements, not perceptual quality benchmarks.
• A real one-token CPU forward traversed all 48 layers and both projections and returned finite [1, 1, 6144] F32 conditioning in 35.94 seconds; peak process RSS was approximately 15.1 GiB.
• End-to-end single-stage and two-stage LTX-2.5 GPU generations completed with Q5_K_M, the matching transformer, and synchronized video/audio. Q4_K_M and Q2_K have loader and full encoder-forward validation but are not claimed here to have completed those end-to-end GPU workflows.
• Both supplied workflows were checked against a live ComfyUI 0.33.0 /object_info response and have also completed real inference.

The shortened forward tests deliberately avoided the normal 1024-token padded short-prompt computation. These checks establish structural and runtime compatibility, not end-to-end quality parity with BF16.

Troubleshooting

Unexpected text model architecture type in GGUF file: 'gemma4'

The compatibility patch is missing from the ComfyUI-GGUF copy actually imported by the server, or ComfyUI was not restarted. Apply the patch to ComfyUI/custom_nodes/ComfyUI-GGUF, run git diff --check, verify there is no duplicate plugin installation, and fully restart. Do not change the file's architecture metadata.

A ComfyUI Manager or manual plugin update can replace the patched loader.py. After updating ComfyUI-GGUF, rerun the forward and reverse git apply --check commands above before launching.

The model does not appear in CLIPLoaderGGUF

Place the file in ComfyUI/models/text_encoders/ and restart ComfyUI. Do not put it in models/diffusion_models/. models/clip/ is a legacy alias, not the canonical path used in these instructions.

The transformer does not appear in UnetLoaderGGUF

Place the companion file in ComfyUI/models/diffusion_models/, verify its exact filename and checksum, and restart ComfyUI.

Value not in list: ckpt_name or a GemmaAPITextEncode error

The workflow is using an API or ordinary-checkpoint node. Load one of the supplied workflows. Use CLIPLoaderGGUF with type ltxv for this encoder and UnetLoaderGGUF for the transformer; do not provide either file as a ckpt_name to GemmaAPITextEncode.

Missing LTX nodes

Check that ComfyUI is at the tested core revision and ComfyUI-GGUF loaded without import errors. The LTX conditioning, latent, sampler, VAE, audio, video, and upscaling nodes in the examples are current ComfyUI core nodes; only CLIPLoaderGGUF and UnetLoaderGGUF come from the plugin.

CUDA out of memory or system-memory pressure

Close other GPU applications, use the convolutional video VAE and tested low-VRAM launch flags, and run the 608×352×49 single-stage workflow before trying two-stage upscaling. The tested two-stage path came close to the 16 GB VRAM limit and used host swap.

CUDA optimization warning

The tested PyTorch CUDA 12.8 build emitted a recommendation for a newer CUDA build but still completed inference. That warning is separate from the gemma4 architecture rejection. Upgrade only to a PyTorch build supported by your GPU, driver, Python version, and current ComfyUI.

Licenses and modification notice

This artifact combines components with two relevant licenses:

• LTX-2.5 and its projection components: LTX-2.x Community License.
• Gemma 4 components: Apache License 2.0.

The LTX license includes redistribution conditions, use restrictions, and a revenue threshold. See NOTICE.md for provenance and prominent modification notices. No endorsement by Google or Lightricks is implied.