docs: collapse less important README sections for cleaner reading
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 4.6
parent
3654098561
commit
5f1fbbd8d8
@@ -25,10 +25,13 @@ A ComfyUI node that **automatically analyzes your LoRA stack** and selects the b
|
||||
|
||||
---
|
||||
|
||||
### Should I Merge This LoRA?
|
||||
<details>
|
||||
<summary><b>Should I Merge This LoRA?</b></summary>
|
||||
|
||||
<p align="center"><img src="assets/merge-use-cases.png" width="720" alt="Should I merge this LoRA? Decision guide"></p>
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Nodes
|
||||
@@ -72,7 +75,8 @@ Peak memory is ~one prefix at a time (~260MB) regardless of LoRA count or model
|
||||
|
||||
<p align="center"><img src="assets/optimizer-pipeline.svg" alt="Optimizer Pipeline" width="100%"></p>
|
||||
|
||||
#### What It Analyzes
|
||||
<details>
|
||||
<summary><b>What It Analyzes</b></summary>
|
||||
|
||||
- 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
|
||||
|
||||
</details>
|
||||
|
||||
#### 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
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Important notes & limitations</b></summary>
|
||||
|
||||
> **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.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### Save Merged LoRA
|
||||
<details>
|
||||
<summary><b>Save Merged LoRA</b></summary>
|
||||
|
||||
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)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### Merged LoRA to Hook
|
||||
<details>
|
||||
<summary><b>Merged LoRA to Hook</b></summary>
|
||||
|
||||
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`
|
||||
|
||||
<details>
|
||||
<summary><b>When to use this</b></summary>
|
||||
|
||||
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
|
||||
<details>
|
||||
<summary><b>WanVideo LoRA Optimizer</b></summary>
|
||||
|
||||
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)
|
||||
|
||||
<details>
|
||||
<summary><b>Workflow and usage</b></summary>
|
||||
|
||||
**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
|
||||
<details>
|
||||
<summary><b>Manual install</b></summary>
|
||||
|
||||
```bash
|
||||
cd ComfyUI/custom_nodes/
|
||||
git clone https://github.com/ethanfel/ComfyUI-LoRA-Optimizer.git
|
||||
```
|
||||
Restart ComfyUI. Nodes appear under the `loaders` category.
|
||||
|
||||
## Compatibility
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Compatibility</b></summary>
|
||||
|
||||
- **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
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Credits</b></summary>
|
||||
|
||||
- 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
|
||||
|
||||
</details>
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user