🛠️ Easy LoRA Merger Suite

Complexity Made Simple — Merge Anything

The Easy LoRA Merger Suite gives you a complete toolkit to merge, convert, extract, bake, and audit LoRAs and checkpoints — without worrying about tensor dimensions, sparsity mismatches, or arcane scaling math.

Every node is built with the same philosophy: powerful defaults when you need simplicity, full control when you need precision.

---

🔍 All Nodes at a Glance

The complete node suite — drag, connect, and merge.

---

📦 Node Catalog

Node	Display Name	Purpose
🎨	Easy LoRA Merger	Merge 2–3 LoRAs with 15+ methods, auto‑format detection, smart defaults, and forensic reports. The core workhorse.
🛡️	Easy LoRA Studio	Universal LoRA analyzer and converter. Transforms between Standard WebUI, Comfy Native, and Forge‑Optimized formats. SVD compression, TE scaling, weight adjustment.
🛡️	Easy Checkpoint Studio	Precision surgery for full checkpoints — precision casting FP8/BF16/FP32, component stripping VAE/TE/CLIP, SVD compression, and structural remapping.
🎨	Easy Checkpoint Merger	Merge 2–3 full model checkpoints with Weight Block Map component‑wise scaling. Streaming engine for low RAM usage.
🔬	Easy LoRA Extractor	Extract a LoRA from the delta between a base and fine‑tuned checkpoint. SVD decomposition with auto‑energy rank selection.
🔧	Easy Component Extractor	Split a checkpoint into its building blocks — extract UNet, CLIP, or VAE as separate files with precision control.
🧩	Easy Component Combiner	Reassemble extracted UNet + CLIP + VAE components back into a single full checkpoint.
🧩	Easy Component Merger	Merge 2–3 component state dicts (e.g., two different CLIP sets or UNets) using the full merge method suite.
🔥	Easy LoRA Baker	Bake a LoRA (or merged LoRA) directly into a full checkpoint at the tensor level. Produces MODEL+CLIP+VAE with RAM Guard fallback.

---

🎯 Merge Methods

Method	Best for	Works on Checkpoints?
linear	Simple weighted average — the safe starting point for any merge	✅ Yes
cross	Blending with a cross‑magnitude interaction term for richer mixes	✅ Yes
ties_strict	Conflicting styles — only keeps weights where both sources agree	⚠️ Limited (all-positive weights reduce effect)
ties_gentle	Softer version of TIES — applies only to strong disagreements	⚠️ Limited (all-positive weights reduce effect)
ties_contrast	Amplify differences between two sources, mute agreements	⚠️ Limited (best on LoRA deltas)
dare_lite	Random dropout — creates sparse, stochastic blends	❌ LoRA only (risky on checkpoint weights)
dare_rescale	Random dropout with rescaling — preserves magnitude distribution	❌ LoRA only (risky on checkpoint weights)
magnitude	Keep the stronger signal per-element from either source	✅ Yes
subtract	Remove unwanted features by subtracting one source from another	✅ Yes
feature_mix	Preserve unique features from each source — great for style + character	✅ Yes
slerp	Smooth spherical interpolation between two vectors	✅ Yes (2‑way only)
svd_preserve	SVD‑based rank reduction — keeps core structure while reducing noise	✅ Yes
block_swap	Swap blocks between sources using a seeded random pattern	✅ Yes
noise_aware	Suppress small noise values before merging for cleaner results	✅ Yes
gradient_alignment	Weight contributions by directional similarity between sources	✅ Yes

💡 Tip: When in doubt, start with linear or magnitude — they're the most versatile and work well across LoRAs and checkpoints alike.

---

🧠 Smart Diagnostics

Every merge node outputs a detailed forensic report with:

• ✅ Alignment verification — cross‑architecture key matching stats
• 📊 Layer‑by‑layer statistics — energy distribution, sparsity, component breakdown
• ⚠️ Clear warnings — mismatched trainers, conflicting trigger words, density risks
• 🔍 Sparsity + scaling reports — magnitude distribution per layer

Console output keeps you informed at every step without overwhelming.

---

🏗️ Supported Architectures (aspirational — not all fully tested)

Architecture	Status
Flux.1‑Dev / Flux.1‑S	Tested
Flux Klein 4B / 9B	Tested
Z‑Image Turbo / Base	Tested
SDXL	Tested
SD1.5	Tested
Anima	Early support
Lumina 2	Early support
SD3	Experimental

---

🚀 Get Started

• Download: github.com/Terpentinas/EasyLoRAMerger
• Install: Drop into ComfyUI/custom_nodes/ and restart ComfyUI.
• Explore: Drag assets/nodes.png into the workflow area to see the suite in action.
• Experiment: Connect a Easy LoRA Merger → Easy LoRA Baker pipeline, or use Easy Checkpoint Studio to shrink a 12GB checkpoint to FP8.
• Optional — GGUF export: Install pip install gguf to enable GGUF output format in Easy Checkpoint Studio. GGUF files are loaded with the ComfyUI-GGUF custom node. All other Easy LoRA Merger nodes work without either dependency.
• Feedback: Open an issue on GitHub — contributions and ideas welcome.

---

⚙️ Precision Options

Different nodes expose different precision tiers depending on their capabilities:

Standard Tier — all float formats

Used by: Easy LoRA Merger, Easy LoRA Studio

Option	Behavior
auto	Auto-select — defaults to BF16 on supported GPUs
float32	Full precision, 4 bytes/param — maximum quality
bfloat16	Half precision, 2 bytes/param — good balance
float16	Half precision, 2 bytes/param — good balance

Extended Tier — adds FP8 support

Used by: Easy Checkpoint Merger, Easy Component Extractor, Easy Component Combiner, Easy Component Merger, Easy LoRA Baker

Option	Behavior
(all Standard options above)
fp8_e4m3fn	FP8 quantization, 1 byte/param — memory efficient
fp8_e5m2	FP8 quantization (wider range) — memory efficient

Studio Tier — full conversion toolkit

Used by: Easy Checkpoint Studio

Option	Behavior
(all Extended options above)
int8	Explicit INT8 quantization, 1 byte/param
int8_convrot	INT8 with convolution rotation handling
svd_only	SVD compression only, no dtype conversion
gguf_q8_0 / gguf_q5_0 / gguf_q4_0	Block‑wise GGUF quantization — requires gguf Python package (pip install gguf). Output loads with ComfyUI-GGUF nodes.

💡 Tip: For everyday use, just leave it on auto. The nodes will pick the best format for your hardware automatically.

⚠️ Note: The gguf package is optional. All nodes work without it — GGUF output is only available in Easy Checkpoint Studio when gguf is installed. If missing, GGUF options are hidden from the dropdown and the Checkpoint Studio loads gracefully without them.

---

📐 Design Philosophy

The suite is engineered for stability and SSD-friendly operation:

• No unnecessary disk writes — intermediate data stays in RAM. Temp files are created only when RAM Guard activates or save_trigger=True.
• Clean resource management — file handles from checkpoint loading are closed immediately after model objects are constructed, preventing stale handles from causing I/O during garbage collection.
• Predictable performance — no background cleanup threads. All file I/O is explicit and happens at known points in the pipeline.
• Memory-efficient streaming — large checkpoints are processed in configurable batch sizes, keeping peak RAM usage under control.

---

💾 Saving Your Merged Models

Every node with save capability exposes three controls: save_trigger, save_folder, and filename.

How save_trigger Works

Toggle	Behavior
False (default)	Preview mode — merge runs, MODEL+CLIP+VAE outputs are returned for testing, but no file is written to disk.
True	Save mode — result is written to a .safetensors file, then loaded from that file (or RAM) for downstream use.

💡 Start with save_trigger=False to test your merge settings. Toggle it to True only when you're happy with the result.

Save Locations

• Checkpoint nodes (Checkpoint Merger, Baker) → ComfyUI/models/checkpoints/
• LoRA nodes (LoRA Merger, LoRA Studio) → ComfyUI/models/loras/

You can override the location with save_folder:

save_folder value	Example	Where it saves
Empty	""	ComfyUI default folder
Relative path	"my_merges"	default/my_merges/merged.safetensors
Absolute path	"D:\\ModelMerges"	D:/ModelMerges/merged.safetensors

Filename & Auto-Increment

The filename parameter sets the output name (.safetensors is appended automatically).

If a file with that name already exists, most nodes auto-increment:

• merged_checkpoint → merged_checkpoint_1 → merged_checkpoint_2 ...
• triple_merged → triple_merged_1 → triple_merged_2 ...

ℹ️ Studio & Converter nodes (Checkpoint Studio, LoRA Studio) add _converted before the extension: name_converted.safetensors, name_converted_1.safetensors.

---

⚖️ Weight Guidance

The global weights (weight_a, weight_b, weight_c) multiply with component weights (weight_unet, weight_clip, weight_vae, weight_te) to determine the effective strength per component.

Key Insight: Checkpoints vs LoRAs

Type	What the weights multiply	Guidance
Checkpoints	Absolute weight values (large, ~1.0 scale)	For linear: weights should sum close to 1.0 (e.g., 0.5 + 0.5, 0.7 + 0.3). With 1.0 + 1.0 the output becomes A + B — doubling magnitudes, resulting in noise.
LoRAs	Small delta values (≈1e‑3 scale)	Weights are independent — feel free to experiment. LoRAs are fast to iterate on.

General Approach

1. Start with equal weights — 0.5 + 0.5 for checkpoints, 1.0 + 1.0 for LoRAs.
2. Use save_trigger=False (preview mode) to test without cluttering your disk.
3. Adjust one weight at a time — small increments (0.05–0.1) and see how the output changes.
4. Different architectures (Flux, SDXL, SD1.5, Z‑Image) may respond differently to the same weights — trust your eyes.

Per-Method Notes

Method	Weight behavior
linear	Direct weighted sum. For checkpoints: result = A×wa + B×wb — sum should be ≈1.0. For LoRAs: any values work.
feature_mix	Preserves unique features per-element. 1.0 + 1.0 is fine — not additive.
magnitude	Takes the larger signal per-element from either source. 1.0 + 1.0 is fine.
slerp	Uses |weight| as interpolation factor. Sign is discarded.
subtract	wa controls source strength, wb controls how much of B to remove.
ties_*	Sign-based. Limited effect on all-positive checkpoint weights.
dare_*	Uses density for sparsification, not weight sum. Risky on checkpoints.

💡 The best weights depend on your models and goal. These are starting points, not rules. The suite is designed for exploration — iterate and find what works for your specific combination.

---

Built because merging different model formats shouldn't require a PhD in tensor math. 💪