feat: t5 encoder gguf support

[Pfannkuchensack]

Summary

Feature: Load GGUF-quantized T5 text encoders, and show/recall the T5 encoder in image metadata.

Adds support for single-file GGUF T5 text encoders (e.g. city96/t5-v1_1-xxl-encoder-gguf, llama.cpp enc.blk.* naming) so users can run FLUX/SD3 with a small quantized T5 instead of the full ~9GB encoder. The GGUF infrastructure already existed (used by FLUX/Qwen3/Z-Image); this wires T5 into it, mirroring the existing Qwen3 GGUF encoder path.

Backend

• New T5Encoder_GGUF_Config (single-file; detects enc.blk.* keys + GGML tensors) registered in the AnyModelConfig union.
• New T5EncoderGGUFModel loader: remaps llama.cpp T5 keys → transformers T5, infers T5Config from tensor shapes, keeps transformer weights as GGMLTensors for the autocast cache, eagerly dequantizes the token/relative-attention-bias embeddings (embedding lookups can't run on quantized tensors) and ties encoder.embed_tokens → shared.
• transformers T5 gotcha: T5DenseGatedActDense.forward casts activations to self.wo.weight.dtype unless it's torch.int8 (a bitsandbytes guard). GGML weights are torch.uint8, which slips past the guard and corrupts the feed-forward output. Worked around by rebinding the FF forward to only cast for floating-point wo weights.
• Made the Qwen3 GGUF/checkpoint configs reject T5 encoders (both carry token_embd.weight; the config factory resolves multi-matches from a set, so they must be mutually exclusive — disambiguated on the enc.blk.* prefix).
• Reuse the T5-XXL tokenizer already vendored in the repo instead of downloading it — moved it out of backend/anima into a neutral shared backend/t5 module used by both Anima and the GGUF loader (updated pyproject.toml package-data accordingly).

Frontend

• FLUX/SD3 images already store the T5 encoder in metadata (t5_encoder), but it wasn't shown in the Recall Parameters tab. Added a T5EncoderModel metadata handler (mirrors Qwen3EncoderModel) and registered it in both the handler registry (for "Recall All") and the metadata viewer's display list, plus an i18n label.

Related Issues / Discussions

https://discord.com/channels/1020123559063990373/1149510134058471514/1521658213836001291
#8421

QA Instructions

1. Download a T5 GGUF encoder (e.g. city96/t5-v1_1-xxl-encoder-Q6_K.gguf) and install it via the Model Manager — it should be detected as a T5 Encoder (GGUF) model.
2. Build a FLUX text-to-image graph using it as the T5 encoder and generate an image; output should be coherent.
3. Confirm a lighter quant (e.g. Q3_K_S) also loads and generates.
4. Open a FLUX/SD3 image's metadata → Recall Parameters tab: a T5 Encoder row appears with a recall button; clicking it (and "Recall All") sets the T5 encoder in the generation settings.

Validated locally on Q3_K_S and Q6_K: unique model classification, correct config inference (T5 v1.1 XXL), finite bf16 forward on CUDA, and cross-quant cosine-similarity 0.94–0.999 on content tokens (confirms the key mapping). Backend config/probe tests and frontend metadata tests pass.

Merge Plan

Standard merge. No DB schema or redux migration changes. pyproject.toml package-data path changed (invokeai.backend.anima → invokeai.backend.t5) — a clean build picks up the vendored tokenizer at its new location.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable)
• ❗Changes to a redux slice have a corresponding migration — N/A (no slice shape changes)
• Documentation added / updated (if applicable) — N/A
• Updated What's New copy (if doing a release after this PR)

[lstein]

Review + merge-to-main update

Brought the branch up to date with main and did a full review of the GGUF T5 encoder support. Summary below.

Merge to main

The only conflict was in the generated invokeai/frontend/web/src/services/api/schema.ts (12 hunks, all the same shape: this branch adds T5Encoder_GGUF_Config, main adds ControlNet_Checkpoint_Anima_Config — both belong in the result). Rather than hand-merge a generated file, I confirmed openapi.json auto-merged correctly with both configs and regenerated schema.ts from it via pnpm typegen. Verified: no conflict markers, both configs present, prettier --check and pnpm lint:tsc clean. The branch is now 0 commits behind main.

Review — overall this is solid

• Detection is correct and defensive. The T5↔Qwen3 GGUF mutual exclusion (enc.blk.* / enc.output_norm.weight) cleanly separates two formats that share token_embd.weight. Existing qwen3 config tests still pass.
• Config inferred from tensor shapes rather than hardcoded, with clear per-field errors.
• Fails loudly on unmapped keys via the meta-tensor check.
• Tokenizer refactor (backend/anima/ → backend/t5/, ANIMA_T5_VOCAB_SIZE → T5_VOCAB_SIZE) is clean — no stale references, pyproject.toml package-data updated.
• Frontend recall handler fills a real gap — t5_encoder is already written to metadata in buildFLUXGraph.ts.

Fixes I pushed (3 commits)

1. Fail-loud guard in _make_feed_forward_gguf_safe. The method patches T5 feed-forward modules matched by exact class-name string to work around the uint8/int8 wo-dtype bug. If a future transformers renames those classes, the patch would silently no-op and silently corrupt encoder output. It now raises a RuntimeError if zero modules are patched, so the mismatch surfaces at load time instead of in generated images.

2. Unit tests (tests/backend/model_manager/load/test_t5_gguf_loader.py, 16 tests) covering the pure, high-risk helpers that previously had no coverage:

• _convert_t5_gguf_to_transformers — key remapping (attn→layer.0, ffn→layer.1, top-level keys, value identity, unknown-component passthrough, non-string keys)
• _infer_t5_config_from_state_dict — correct dims from a synthetic state dict + parametrized "missing required key → ValueError"
• _make_feed_forward_gguf_safe — FFN forward is rebound; a regression test proving the patched forward does not cast activations to a non-floating (uint8) weight dtype; and the new guard raises when no FFN modules match

The tests bypass the cache-dependent constructor via object.__new__, so they run in ~0.1s with no downloads.

3. Small cleanups. Removed the unreachable fallback branch in _shape_of (GGMLTensor.shape already returns the dequantized/logical shape) and inlined it; documented that config inference targets the T5 v1.1 XXL family and that the hardcoded constants (relative_attention_max_distance, layer_norm_epsilon, gated-gelu) are that family's defaults.

Notes (no change made)

• compute_dtype=torch.bfloat16 in _load_from_gguf is left as-is: it's intentional, carries the existing HACK(ryand) comment, and matches the sibling FLUX GGUF main loader. Swapping it for self._torch_dtype would be a real behavior change on the dequantization path.
• The tests surfaced that T5Config ignores the tie_word_embeddings=False the loader passes (forces it back to True). Harmless — T5EncoderModel has no lm_head and the loader re-ties embed_tokens→shared manually — so no fix, just flagging it.

Verification: new tests 16/16 pass, combined with tokenizer + qwen3 config tests 25/25; ruff check/format clean; pnpm lint:tsc clean.

[lstein]

Works as advertised.