Skip to content

[LoRA] support musubi-tuner HunyuanVideo LoRAs - #15346

Merged
sayakpaul merged 5 commits into
huggingface:mainfrom
chsu-amd:fix-hunyuan-musubi-lora
Nov 19, 2026
Merged

sayakpaul merged 5 commits into
huggingface:mainfrom
chsu-amd:fix-hunyuan-musubi-lora

Conversation

@chsu-amd

@chsu-amd chsu-amd commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Fixes #15344

HunyuanVideo LoRAs trained with musubi-tuner (keys like lora_unet_double_blocks_0_img_attn_qkv.lora_down.weight / .lora_up.weight / .alpha, e.g. lucataco/hunyuan-steamboat-willie-10 from the HunyuanVideo docs) were sent to _convert_hunyuan_video_lora_to_diffusers, which calls chunk(3) on the 0-dim .alpha and fails.

This PR adds _convert_musubi_hunyuan_video_lora_to_diffusers, following _convert_musubi_wan_lora_to_diffusers (#11243): it renames the musubi keys to the original HunyuanVideo layout, folds alpha / rank into the weights, and hands the result to the existing converter. HunyuanVideoLoraLoaderMixin.lora_state_dict uses it when a key starts with lora_unet_, the same check as the Wan loader.

With the fix, the snippet from #15344 prints 1040 keys, and every converted key matches the shape of its module in the full-size HunyuanVideoTransformer3DModel (built from the hunyuanvideo-community/HunyuanVideo config on the meta device: 520 modules, 0 missing, 0 shape mismatches).

Tests: per review, no new unit test. tests/pipelines/hunyuan_video/test_hunyuan_video.py + tests/models/transformers/test_models_transformer_hunyuan_video.py pass on CPU (109 passed, 129 skipped, 1 xpassed, with the since-removed musubi test). ruff check / ruff format --check (0.9.10) pass on the changed files.

Self-review notes (the self-review skill's rubric: review-rules.md, code_style.md, testing.md):

Before submitting

Who can review?

@sayakpaul

@chsu-amd
chsu-amd marked this pull request as ready for review November 19, 2026 03:51
@sayakpaul sayakpaul added this to the Release 0.44.0 milestone Nov 19, 2026
class TestHunyuanVideoPipelineLoRA(HunyuanVideoPipelineTesterConfig, LoraTesterMixin):
"""LoRA tests for the HunyuanVideo pipeline."""

def test_lora_musubi_state_dict(self, base_pipe_output):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We can remove this test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Removed in 32f1d52.

@github-actions github-actions Bot removed the tests label Nov 19, 2026
@HuggingFaceDocBuilderDev

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@sayakpaul sayakpaul left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Great!

@sayakpaul
sayakpaul merged commit 3d23f55 into huggingface:main Nov 19, 2026
33 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fixes-issue lora size/M PR with diff < 200 LOC

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HunyuanVideo: lora_state_dict / load_lora_weights crash on musubi-tuner (kohya-style) LoRAs

3 participants