$ show kohya-ss/musubi-tuner
Musubi Tuner is a comprehensive LoRA training and inference toolkit for a wide range of diffusion model architectures, including HunyuanVideo, Wan, FramePack, FLUX variants, Qwen-Image, Z-Image, HiDream-O1, Ideogram4, Krea2, and Kandinsky5. It provides a unified pipeline of pre-caching (latents and text encoder outputs), training (LoRA, LoHa, LoKr), and generation, all accessible via CLI scripts and an optional Gradio GUI. The codebase is built on a shared `NetworkTrainer` base class with architecture-specific overrides, and includes advanced memory-saving techniques such as block-swap CPU offloading, FP8 quantization, and gradient checkpointing. While the repository is actively maintained and widely used (2035 stars), it exhibits medium technical drift due to vendored external model code, deprecated diffusers API usage, and a proliferation of near-duplicate architecture-specific scripts. The core reusable componentsβunified attention backend, offloading utilities, FP8 optimization, and LoRA network infrastructureβdemonstrate solid engineering craftsmanship.
The LLM identified 5 files worth highlighting for reuse:
Provides a single `attention()` function that dispatches to multiple backends (torch SDPA, FlashAttention 2/3, SageAttention, xformers) based on a configuration dataclass. Handles GQA, variable-length sequences, and custom masks. This is a self-contained, reusable abstraction that can be extracted into any transformer project needing flexible attention.
Implements `BlockSwapConfig` and `create_offloader()` for CPU offloading of transformer blocks during training/inference. Uses CUDA streams for asynchronous weight transfer. The offloader is generic and can be reused in any large model training pipeline to reduce GPU memory usage.
Provides functions to apply FP8 quantization to linear layers via monkey-patching, supporting scaled and block-wise modes. Includes `load_safetensors_with_fp8_optimization` for loading weights with on-the-fly FP8 conversion. This is a standalone utility that can be adapted for any PyTorch model requiring FP8 memory reduction.
Defines the base `LoRANetwork` class with support for LoRA, LoHa, and LoKr adapters. Handles module replacement, weight merging, optimizer parameter preparation, and max-norm regularization. This is a well-structured, reusable LoRA implementation that can be extracted and used in any PyTorch model fine-tuning project.
Provides common functions for saving and loading latent and text encoder caches as safetensors files. Includes metadata handling, NaN checks, and merging with existing caches. This is a reusable caching layer that can be applied to any diffusion model training pipeline to avoid redundant encoding.