From 5f1fbbd8d80f415b92ae0d3db9ece939efe34e8a Mon Sep 17 00:00:00 2001 From: Ethanfel Date: Wed, 4 Mar 2026 21:51:24 +0100 Subject: [PATCH] docs: collapse less important README sections for cleaner reading Co-Authored-By: Claude Opus 4.6 --- README.md | 48 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 9b2c6bf..9d0a54d 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,13 @@ A ComfyUI node that **automatically analyzes your LoRA stack** and selects the b --- -### Should I Merge This LoRA? +
+Should I Merge This LoRA?

Should I merge this LoRA? Decision guide

+
+ --- ## Nodes @@ -72,7 +75,8 @@ Peak memory is ~one prefix at a time (~260MB) regardless of LoRA count or model

Optimizer Pipeline

-#### What It Analyzes +
+What It Analyzes - Per-LoRA metrics (rank, key count, effective L2 norms) - Pairwise sign conflict ratios per prefix (sampled for efficiency) @@ -80,6 +84,8 @@ Peak memory is ~one prefix at a time (~260MB) regardless of LoRA count or model - Magnitude distribution per prefix - Key overlap between LoRAs +
+ #### Per-Prefix Adaptive Merge The key insight: two LoRAs may overlap in some model blocks but not others. A face LoRA and a style LoRA might only conflict in attention layers 4-7, while the rest of the model is touched by only one of them. @@ -333,13 +339,19 @@ Connect the `STRING` output to a **Show Text** node to see the report in ComfyUI +
+Important notes & limitations + > **Structural & Edit LoRAs:** Do not put distillation LoRAs (LCM, Lightning, Turbo, Hyper), DPO LoRAs, or **edit model LoRAs** (Qwen edit, Klein edit, instruction-editing LoRAs) in the optimizer stack. These LoRAs modify the model's fundamental behavior — their weights are precisely calibrated and merging them with style LoRAs can break their training. Apply them via a standard **Load LoRA** node upstream, then feed only your style/character LoRAs into the optimizer. If you must include an edit LoRA in the stack, use `weighted_sum_only` mode and disable sparsification to avoid weight trimming. > **Limitation:** The optimizer only analyzes LoRAs in its own stack. It cannot see LoRA patches applied by upstream nodes (Load LoRA, etc.) — those stack additively on top of the optimizer's output. Fully baked merges (safetensors checkpoints) are indistinguishable from base weights and cannot be detected. +
+ --- -### Save Merged LoRA +
+Save Merged LoRA Saves the optimizer's merged result as a standalone `.safetensors` file that works with any standard LoRA loader. @@ -353,9 +365,12 @@ Connect the `LORA_DATA` output from LoRA Optimizer to this node. **Outputs:** `STRING` (file path) +
+ --- -### Merged LoRA to Hook +
+Merged LoRA to Hook Wraps the optimizer's merged patches as a **conditioning hook** (`HOOKS`) for per-conditioning LoRA application. Instead of applying the merged LoRA globally to the model, you can attach it to specific conditioning entries using ComfyUI's hook system. @@ -365,9 +380,6 @@ Connect the `LORA_DATA` output from LoRA Optimizer to this node, then connect th **Outputs:** `HOOKS` -
-When to use this - Use this node when you want the merged LoRA to apply **only to specific conditioning** rather than the entire model: - **Per-prompt LoRA:** Apply different merged LoRAs to positive vs negative conditioning @@ -388,7 +400,8 @@ The `prev_hooks` input allows chaining multiple hook sources together. --- -### WanVideo LoRA Optimizer +
+WanVideo LoRA Optimizer Variant of the LoRA Optimizer for **WanVideo models** (via [kijai's WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper)). Accepts `WANVIDEOMODEL` instead of `MODEL`, skips CLIP, and applies merged patches in-memory. @@ -398,9 +411,6 @@ All merging algorithms are inherited — TIES, DARE/DELLA, SVD compression, auto **Outputs:** `WANVIDEOMODEL` (patched), `STRING` (analysis report), `LORA_DATA` (for Save Merged LoRA) -
-Workflow and usage - **Basic workflow:** ``` WanVideoModelLoader → WANVIDEOMODEL → WanVideo LoRA Optimizer → WANVIDEOMODEL → WanVideoSampler @@ -429,14 +439,19 @@ WanVideoLoraSelect → WanVideoModelLoader → WANVIDEOMODEL → WanVideo LoRA O ### ComfyUI Manager Search for "LoRA Optimizer" in ComfyUI Manager and install. -### Manual +
+Manual install + ```bash cd ComfyUI/custom_nodes/ git clone https://github.com/ethanfel/ComfyUI-LoRA-Optimizer.git ``` Restart ComfyUI. Nodes appear under the `loaders` category. -## Compatibility +
+ +
+Compatibility - **Models:** SD 1.5, SDXL, Flux, Z-Image (Lumina2), Wan 2.1/2.2, LTX Video, Qwen-Image, and other architectures supported by ComfyUI - **LoRA formats:** Standard LoRA, LoCon, LyCORIS, diffusers/PEFT formats @@ -445,7 +460,10 @@ Restart ComfyUI. Nodes appear under the `loaders` category. - **Z-Image fused QKV:** Split for per-component analysis, re-fused after merge - **Stack formats:** Native LoRA Stack dicts, plus standard tuples from Efficiency Nodes / Comfyroll -## Credits +
+ +
+Credits - Originally based on [ComfyUI-ZImage-LoRA-Merger](https://github.com/DanrisiUA/ComfyUI-ZImage-LoRA-Merger) by DanrisiUA - Per-prefix adaptive approach inspired by [comfyUI-Realtime-Lora](https://github.com/shootthesound/comfyUI-Realtime-Lora) by shootthesound (per-block LoRA analysis) @@ -454,6 +472,8 @@ Restart ComfyUI. Nodes appear under the `loaders` category. - DARE: [Yu et al., ICML 2024](https://arxiv.org/abs/2311.03099) — Drop And REscale for language model merging - DELLA: [Deep et al., 2024](https://arxiv.org/abs/2406.11617) — magnitude-aware sparsification +
+ ## License MIT License - see [LICENSE](LICENSE).