Skip to content

[LoRA] convert Z-Image LoRAs that only carry the fused qkv and bare out attention keys - #14875

Open
christopher5106 wants to merge 1 commit into
huggingface:mainfrom
scenario-labs:fix_zimage_fused_qkv_lora
Open

christopher5106 wants to merge 1 commit into
huggingface:mainfrom
scenario-labs:fix_zimage_fused_qkv_lora

Conversation

@christopher5106

@christopher5106 christopher5106 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Fixes #14876

A LoRA trained on Z-Image's original module names (musubi-tuner and LyCORIS emit lora_unet_<block>_attention_qkv and lora_unet_<block>_attention_out, and nothing else for attention) is currently emptied by _convert_non_diffusers_z_image_lora_to_diffusers: the converter drops the fused qkv key and the bare out key on the assumption that split to.q/k/v and to_out.0 keys are also present (the Anime-Z layout), then raises ValueError: state_dict should be empty on the leftover .alpha keys.

This PR keeps the Anime-Z behaviour (skip the redundant keys when split ones exist) and otherwise:

  • splits the fused qkv LoRA into to_q / to_k / to_v, chunking the up weight along dim 0 like convert_z_image_fused_attention does for base weights and repeating the shared down weight;
  • maps the bare out key to to_out.0, consuming the alpha that normalize_out_key had already renamed.

Two tests in tests/lora/test_lora_conversion_z_image.py: the attention-only layout converts to the expected 16 tensors with the right shapes and the k chunk lands unscaled when alpha equals rank; a state dict that carries both fused and split keys still uses the split ones.

Found by generating synthetic LoRAs from every layout we see in the wild and running them through a deployed Z-Image pipeline; the fused-only layout was the one that failed.

Before submitting

  • Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? Yes, Claude Code.
    • Read the Coding with AI agents guide.
    • Self-review notes, final round:
      • The change is confined to the dotted-key path (.lora.down.weight). The underscore-key path (diffusion_model.*.lora_down.weight, ComfyUI exports) still passes a fused qkv key through unsplit; left alone because I have not seen such a file, so there is nothing to test it against.
      • When a file carries both bare out and to_out.0 keys, normalize_out_key renames the bare alpha to to_out.0.alpha, which can collide with the real one. Pre-existing and unchanged here.
      • Tests use synthetic tensors rather than a checkpoint fixture, matching the existing conversion tests.
  • Did you read the contributor guideline?
  • Was this discussed/approved via a GitHub issue? Z-Image LoRAs with only fused attention_qkv + attention_out keys are dropped, then fail on leftover alpha keys #14876, with a CPU-only reproduction.
  • Did you write any new necessary tests?

Who can review?

@sayakpaul @BenjaminBossan

… `out` attention keys

A LoRA trained on Z-Image's original module names (musubi-tuner, LyCORIS)
has `attention.qkv` and `attention.out` and nothing else. The non-diffusers
converter dropped both on the assumption that split `to.q/k/v` and `to_out.0`
keys are also present (the Anime-Z layout), which emptied such a LoRA and then
raised on its leftover `.alpha` keys. Split the fused key into to_q/to_k/to_v
like the single-file converter does and map bare `out` to `to_out.0` when no
split keys exist; the Anime-Z case keeps skipping the redundant keys.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@github-actions github-actions Bot added lora tests size/M PR with diff < 200 LOC labels Sep 25, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Hi @christopher5106, thanks for the PR! It does not appear to link an issue it fixes. If this PR addresses an existing issue, please add a closing keyword (e.g. Fixes #1234) to the PR description so the issue is linked. See the contribution guide for more details. If this PR intentionally does not fix a tracked issue, a maintainer can add the no-issue-needed label to silence this reminder.

Please note that PRs without a linked issue are likely to be automatically closed 10 days after this notice.

Once the PR links an issue (or gets the no-issue-needed label), you can ignore this message — it stays here as a comment, but it no longer applies.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lora size/M PR with diff < 200 LOC tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Z-Image LoRAs with only fused attention_qkv + attention_out keys are dropped, then fail on leftover alpha keys

1 participant