Skip to content

fix(flux2-vae): support FLUX.2 small-decoder VAE variant#9032

Merged
lstein merged 8 commits intoinvoke-ai:mainfrom
Pfannkuchensack:feat/flux2vae_smaller
Apr 21, 2026
Merged

fix(flux2-vae): support FLUX.2 small-decoder VAE variant#9032
lstein merged 8 commits intoinvoke-ai:mainfrom
Pfannkuchensack:feat/flux2vae_smaller

Conversation

@Pfannkuchensack
Copy link
Copy Markdown
Collaborator

Summary

Since AutoencoderKLFlux2 only exposes a single block_out_channels for both encoder and decoder, the loader now:

  1. Reads encoder.conv_in.weight / encoder.conv_norm_out.weight to derive the encoder channels.
  2. Reads decoder.conv_in.weight / decoder.conv_norm_out.weight to derive the decoder channels.
  3. Builds the model with the encoder's channels.
  4. If the decoder differs, replaces model.decoder with a fresh Decoder instance using the smaller channel widths before load_state_dict is called.

The standard FLUX.2 VAE remains unaffected — when encoder and decoder match, no rebuild happens.

Not supported

The small_decoder.safetensors file from the same repository is not supported by this PR. It only contains the decoder (no encoder) and uses bare BFL keys without an encoder./decoder. prefix, so it neither passes the VAE probe heuristics nor can be loaded into a full AutoencoderKLFlux2 instance. Use full_encoder_small_decoder.safetensors instead, which bundles the original full encoder together with the small decoder.

Related Issues / Discussions

QA Instructions

  1. Download full_encoder_small_decoder.safetensors from black-forest-labs/FLUX.2-small-decoder.
  2. Install it as a FLUX.2 VAE via the model manager.
  3. Run a FLUX.2 generation using this VAE and verify there is no size mismatch / expected shape error and the decoded image looks correct.
  4. Regression check: load the standard FLUX.2 VAE and confirm it still works unchanged.

Merge Plan

Normal merge — change is isolated to Flux2VAELoader._load_model.

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
  • Documentation added / updated (if applicable)
  • Updated What's New copy (if doing a release after this PR)

Infer encoder and decoder block_out_channels independently from the
state dict and rebuild the decoder submodule when its channel widths
differ from the encoder, so the asymmetric full_encoder_small_decoder
checkpoint from black-forest-labs/FLUX.2-small-decoder loads correctly.
@github-actions github-actions Bot added python PRs that change python files backend PRs that change backend files labels Apr 9, 2026
@lstein lstein self-assigned this Apr 14, 2026
@lstein lstein added the v6.13.x label Apr 14, 2026
@lstein lstein moved this to 6.13.x Theme: MODELS in Invoke - Community Roadmap Apr 14, 2026
Copy link
Copy Markdown
Collaborator

@lstein lstein left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works as advertised.

@lstein lstein merged commit c83f293 into invoke-ai:main Apr 21, 2026
16 checks passed
@Pfannkuchensack Pfannkuchensack deleted the feat/flux2vae_smaller branch April 21, 2026 12:08
@Pfannkuchensack Pfannkuchensack restored the feat/flux2vae_smaller branch April 26, 2026 01:57
@Pfannkuchensack Pfannkuchensack deleted the feat/flux2vae_smaller branch April 26, 2026 01:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend PRs that change backend files python PRs that change python files v6.13.x

Projects

Status: 6.13.x Theme: MODELS

Development

Successfully merging this pull request may close these issues.

2 participants