Files
ethanfel-ComfyUI-LoRA-Optim…/docs/wiki/Nodes.md
T
EthanfelandClaude Opus 4.8 54fb127f37 docs+chore: document sum_preserve + preserve flag; bump algo 1.11.0, registry 1.8.0
- Merge-Algorithms: new Sum-Preserve section + overview row; weighted_average
  caveat (the /Σw convex-fraction trap) and orthogonal->sum_preserve routing note
- Nodes: preserve toggle on LoRA Stack + LoRA Stack (Dynamic)
- Tips: new 'my style LoRA disappears' troubleshooting entry
- AUTOTUNER_ALGO_VERSION 1.10.2 -> 1.11.0 (orthogonal candidate merges/scores
  change), invalidating stale cached/community rankings
- registry version 1.7.5 -> 1.8.0

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 11:08:20 +02:00

29 KiB
Raw Blame History

Nodes

Complete reference for every node in the LoRA Optimizer suite.


LoRA Stack

Builds a list of LoRAs for the optimizer. Chain multiple Stack nodes to add any number of LoRAs.

Inputs

Input Type Required Description
lora_name COMBO Yes LoRA file selector (.safetensors from your loras folder)
strength FLOAT Yes How much this LoRA contributes (default 1.0)
conflict_mode COMBO Yes Where this LoRA's contributions apply: all, low_conflict, high_conflict
key_filter COMBO Yes Which prefixes this LoRA contributes to: all, shared_only, unique_only, audio_only, no_audio
preserve BOOLEAN Yes Mark as a style LoRA to protect it in conflict merges. When on, it is never trimmed by sparsification and is exempt from TIES sign-election (which otherwise deletes a style's minority-sign direction) — its full contribution is added on top of the conflict-resolved content merge. Turn on when a style LoRA keeps disappearing when merged with a content/character LoRA.
lora_stack LORA_STACK No Previous stack to append to (for chaining)

Outputs

Output Type Description
LORA_STACK LORA_STACK The accumulated LoRA list

LoRA Stack (Dynamic)

Single node with 1–10 adjustable LoRA slots. Replaces chaining multiple Stack nodes.

Parameters

Parameter Options Description
lora_count 1–10 Number of LoRA slots to show
settings_visibility simple, advanced Simple: one strength slider per LoRA. Advanced: separate model/clip strength, conflict mode, key filter
input_mode dropdown, text Dropdown: standard file picker. Text: type a name or path, auto-matched against installed LoRAs
base_model_filter dynamic Filters LoRA list by base model (requires ComfyUI-Lora-Manager)

Per-LoRA Inputs (Simple Mode)

Input Type Description
lora_name_i COMBO/STRING LoRA file
strength_i FLOAT Strength (applies to both model and CLIP)

Per-LoRA Inputs (Advanced Mode)

Input Type Description
lora_name_i COMBO/STRING LoRA file
model_strength_i FLOAT Model patch strength
clip_strength_i FLOAT CLIP patch strength
conflict_mode_i COMBO all, low_conflict, high_conflict
key_filter_i COMBO all, shared_only, unique_only, audio_only, no_audio
preserve_i BOOLEAN Protect LoRA #i as a style LoRA (exempt from sparsification + TIES sign-election; full contribution added on top). See preserve on the LoRA Stack node.

Outputs

Output Type Description
LORA_STACK LORA_STACK The accumulated LoRA list

Optional lora_stack input accepts a previous stack for chaining with other Stack nodes.


LoRA Merge Settings

Shared configuration node for parameters common to both the optimizer and AutoTuner.

Inputs

Input Type Required Default Description
normalize_keys COMBO Yes enabled enabled, disabled — architecture-aware key normalization
architecture_preset COMBO Yes auto auto, sd_unet, dit, acestep_dit, llm — numeric threshold tuning
auto_strength_floor FLOAT Yes -1.0 Minimum auto-strength scale factor for orthogonal LoRAs (-1 = architecture default)
decision_smoothing FLOAT Yes 0.25 Smooth per-prefix decision metrics toward block averages (0 disables)
smooth_slerp_gate BOOLEAN Yes false Use per-prefix cosine similarity for SLERP gate instead of collection average
vram_budget FLOAT Yes 0.0 Fraction of free VRAM for keeping patches on GPU (0.0–1.0)
cache_patches COMBO Yes enabled enabled, disabled — keep merge in RAM for re-execution

Outputs

Output Type Description
merge_settings MERGE_SETTINGS Shared settings for Optimizer Settings or AutoTuner Settings

LoRA Optimizer Settings

Optimizer-specific configuration. Accepts optional Merge Settings input.

Inputs

Input Type Required Default Description
auto_strength COMBO Yes enabled enabled, disabled — interference-aware energy normalization
optimization_mode COMBO Yes per_prefix per_prefix, global, additive
merge_refinement COMBO Yes none none, refine, full
sparsification COMBO Yes disabled disabled, dare, della, dare_conflict, della_conflict
sparsification_density FLOAT Yes 0.7 Fraction of parameters to keep (0.01–1.0)
dare_dampening FLOAT Yes 0.0 DAREx noise reduction (0–1.0, only affects dare/dare_conflict modes)
patch_compression COMBO Yes smart smart, aggressive, disabled
svd_device COMBO Yes gpu gpu, cpu — device for SVD compression
free_vram_between_passes COMBO Yes disabled enabled, disabled — release GPU cache between passes
strategy_set COMBO Yes full full, no_slerp, basic — strategy selection logic

Optional Inputs

Input Type Description
merge_settings MERGE_SETTINGS Shared settings from LoRA Merge Settings node
merge_strategy_override STRING Force a specific merge strategy (connect from Conflict Editor)

Outputs

Output Type Description
settings OPTIMIZER_SETTINGS Connect to LoRA Optimizer's settings input

LoRA AutoTuner Settings

AutoTuner-specific configuration. Accepts optional Merge Settings input.

Inputs

Input Type Required Default Description
top_n INT Yes 3 Number of candidates to merge and score (1–10)
scoring_svd COMBO Yes disabled disabled, merge_quality, lora_rank, full — disabled = fast norm-only; merge_quality = SVD on merged diffs; lora_rank = effective-rank of factors (experimental); full = both
scoring_device COMBO Yes gpu cpu, gpu — device for scoring math (much faster on GPU with SVD modes)
scoring_speed COMBO Yes turbo full, fast, turbo, turbo+ — subsample scoring
scoring_formula COMBO Yes v2 v2 (arch-aware sparsity + energy metrics) or v1 (legacy, fixed 40% sparsity target)
diff_cache_mode COMBO Yes auto disabled, auto, ram, disk
diff_cache_ram_pct FLOAT Yes 0.5 RAM fraction for auto diff cache (0.1–0.9)
community_cache COMBO Yes disabled disabled, upload_only, upload_and_download — community HF cache. upload_only runs locally + uploads without replaying HF hits
memory_mode COMBO Yes auto disabled, auto, auto_ignore_strength, read_only, clear_and_run — persistent tuning result cache across sessions. auto_ignore_strength keys the cache without LoRA strengths
selection INT Yes 1 Which ranked config to replay from memory on a cache hit (1 = top-ranked)
record_dataset COMBO Yes disabled disabled, enabled — append analysis metrics + scored configs to autotuner_dataset.jsonl (only on full sweeps)

Optional Inputs

Input Type Description
merge_settings MERGE_SETTINGS Shared settings from LoRA Merge Settings node
evaluator AUTOTUNER_EVALUATOR External evaluator for prompt/reference scoring

Outputs

Output Type Description
settings OPTIMIZER_SETTINGS Connect to LoRA AutoTuner's settings input

LoRA Optimizer

The simplified auto-optimizer. Sensible defaults, minimal controls. Auto-strength is enabled by default. Accepts optional settings and tuner_data inputs for advanced control without exposing all parameters.

Inputs

Input Type Required Default Description
model MODEL Yes — Base model from checkpoint loader
lora_stack LORA_STACK Yes — Stack of LoRAs to merge
output_strength FLOAT Yes 1.0 Master strength multiplier (-1 to 10). -1 = auto: the optimizer picks the suggested max strength
clip CLIP No — Text encoder (if using CLIP LoRA keys)
clip_strength_multiplier FLOAT No 1.0 CLIP strength relative to model strength (0–10)
tuner_data TUNER_DATA No — AutoTuner result — applies the winning config's settings
settings OPTIMIZER_SETTINGS No — From LoRA Optimizer Settings or LoRA AutoTuner Settings

When no settings node is connected, uses built-in defaults: auto_strength=enabled, optimization_mode=per_prefix, merge_refinement=none, patch_compression=smart, vram_budget=0.0.

Outputs

Output Type Description
MODEL MODEL Patched model ready for sampling
CLIP CLIP Patched text encoder
analysis_report STRING Analysis report with block strategy map
tuner_data TUNER_DATA For Merge Selector or Save Tuner Data
LORA_DATA LORA_DATA Merged patches for downstream nodes

LoRA Optimizer (Legacy)

Deprecated: Superseded by LoRA Optimizer + Settings nodes. Use the Legacy variant only for the AutoTuner ↔ Optimizer bridge workflow (which requires settings_source).

Full-featured optimizer with all parameters on one node.

Inputs

All inputs from the simple variant, plus:

Input Type Default Description
auto_strength COMBO enabled enabled / disabled — interference-aware energy normalization
optimization_mode COMBO per_prefix per_prefix, global, additive
merge_refinement COMBO none none, refine, full
sparsification COMBO disabled disabled, dare, della, dare_conflict, della_conflict
sparsification_density FLOAT 0.7 Fraction of parameters to keep (0.01–1.0)
dare_dampening FLOAT 0.0 DAREx noise reduction (0–1.0, only affects DARE modes)
patch_compression COMBO smart smart, aggressive, disabled
svd_device COMBO gpu gpu, cpu — device for SVD compression
cache_patches COMBO enabled enabled, disabled — keep merge in RAM for re-execution
free_vram_between_passes COMBO disabled enabled, disabled — release GPU cache between passes
normalize_keys COMBO enabled enabled, disabled — architecture-aware key normalization
strategy_set COMBO full full, no_slerp, basic — strategy selection logic
architecture_preset COMBO auto auto, sd_unet, dit, acestep_dit, llm — numeric threshold tuning
auto_strength_floor FLOAT -1.0 Minimum auto-strength scale factor for orthogonal LoRAs (-1 = architecture default)
decision_smoothing FLOAT 0.25 Smooth per-prefix decision metrics toward the surrounding block average (0 disables smoothing)
smooth_slerp_gate BOOLEAN false Use per-prefix cosine similarity for SLERP gate instead of collection average
vram_budget FLOAT 0.0 Fraction of free VRAM for keeping patches on GPU (0.0–1.0)

Optional Inputs

Input Type Description
merge_strategy_override STRING Force a specific merge strategy (connect from Conflict Editor)
tuner_data TUNER_DATA Optional AutoTuner result used when settings_source=from_autotuner or from_tuner_data
settings_source COMBO manual, from_autotuner, or from_tuner_data; controls whether widgets or AutoTuner config drive the node

Outputs

Same as the simple variant: MODEL, CLIP, report (STRING), tuner_data (TUNER_DATA), LORA_DATA.


LoRA AutoTuner

Automated parameter sweep that ranks merge configurations.

Inputs

All inputs from the Legacy optimizer, plus:

Input Type Default Description
top_n INT 3 Number of candidates to actually merge and score (1–10)
scoring_svd COMBO disabled disabled, merge_quality, lora_rank, full — disabled = fast norm-only; merge_quality = SVD on merged diffs; lora_rank = effective-rank (experimental); full = both
scoring_device COMBO gpu cpu, gpu — device for scoring math (GPU much faster with SVD modes)
scoring_speed COMBO turbo full, fast, turbo, turbo+ — subsample scoring for faster sweeps
scoring_formula COMBO v2 v2 (arch-aware sparsity + energy metrics) or v1 (legacy, fixed 40% sparsity target)
output_mode COMBO merge merge, tuning_only — output the top-ranked merged model, or pass the base model through so a downstream optimizer node applies the AutoTuner's settings
auto_strength_floor FLOAT -1.0 Minimum auto-strength scale factor for orthogonal LoRAs
decision_smoothing FLOAT 0.25 Same smoothing control as the optimizer; affects both ranking and final merge
evaluator AUTOTUNER_EVALUATOR — Optional external evaluator hook for prompt/reference scoring
community_cache COMBO disabled disabled, upload_only, upload_and_download — community HF cache (no names shared, content hashes only)
memory_mode COMBO auto disabled, auto, auto_ignore_strength, read_only, clear_and_run — persistent tuning result cache across sessions
selection INT 1 Which ranked config to replay from memory on a cache hit (1 = top-ranked)
record_dataset COMBO disabled disabled, enabled — log analysis metrics + all scored configs to autotuner_dataset.jsonl (full sweeps only)
cache_patches COMBO enabled Cache the final AutoTuner result in RAM for fast re-execution
diff_cache_mode COMBO auto Diff cache mode across candidates: disabled, auto, ram, disk
diff_cache_ram_pct FLOAT 0.5 RAM fraction used before auto diff cache spills to disk
vram_budget FLOAT 0.0 Fraction of free VRAM for patch placement

Outputs

Output Type Description
MODEL MODEL Patched model from the top-ranked config
CLIP CLIP Patched text encoder
report STRING Ranked results with heuristic, internal, and optional external scores
analysis_report STRING Full optimizer analysis report for the top-ranked config
TUNER_DATA TUNER_DATA All ranked configs for Merge Selector
LORA_DATA LORA_DATA Merged patches from the top-ranked config

Marked as OUTPUT_NODE for ComfyUI's re-execution optimization.

See How It Works#appendix-autotuner for details on the two-phase architecture and scoring.


LoRA Merge Estimator

Predicts a merge config via k-NN retrieval over the Hugging Face community cache — skips the full AutoTuner sweep. Runs Phase 1 analysis once, retrieves the nearest cached combos, aggregates their winning configs by inverse-distance weighting, and emits TUNER_DATA.

Inputs

Input Type Required Default Description
model MODEL Yes — Base model (used by Phase 1 analysis)
lora_stack LORA_STACK Yes — Stack to estimate a config for
k INT Yes 5 Number of nearest neighbors to retrieve (1–20)
rebuild_index COMBO Yes auto auto rebuilds when the HF dataset/index schema changes; force always rebuilds; skip never rebuilds (errors if missing)
top_n_output INT Yes 3 How many aggregated candidates to emit in TUNER_DATA (1–10)
clip CLIP No — Optional; only used by Phase 1 analysis

Outputs

Output Type Description
tuner_data TUNER_DATA Aggregated predicted configs — feed into LoRA Optimizer (settings_source=from_tuner_data) or Merge Selector
estimator_report STRING Predicted configs with aggregated scores and neighbor distances (says No neighbors when no family+combo-size match exists)

The first run downloads the community cache and builds a local k-NN index under ComfyUI/models/estimator/ (~30–60s); later runs complete in seconds.


Merge Selector

Applies a specific ranked configuration from AutoTuner results.

Inputs

Input Type Required Default Description
model MODEL Yes — Base model
tuner_data TUNER_DATA Yes — Output from LoRA AutoTuner
selection INT Yes 1 Which ranked config to apply (1 = top-ranked, 2 = next-ranked, etc.)
clip CLIP No — Text encoder
clip_strength_multiplier FLOAT No 1.0 CLIP strength multiplier when replaying the selected config
auto_strength_floor FLOAT No -1.0 Manual override for orthogonal auto-strength floor; -1 reuses tuner setting
decision_smoothing FLOAT No 0.25 Smoothing used when replaying the selected config

Validates that the LoRA stack hasn't changed since the AutoTuner ran (via hash comparison).

Outputs

Output Type Description
MODEL MODEL Patched model from the selected config
CLIP CLIP Patched text encoder
report STRING Analysis report for the selected config
LORA_DATA LORA_DATA Merged patches from the selected config

Marked as OUTPUT_NODE.


LoRA Conflict Editor

Interactive conflict analysis with per-LoRA override controls.

Inputs

Input Type Required Description
lora_stack LORA_STACK Yes Stack to analyze
merge_strategy COMBO Yes auto, ties, consensus, slerp, weighted_average, weighted_sum
conflict_mode_1..10 COMBO Yes Per-slot override: auto (node suggests), all, low_conflict, high_conflict

The 10 per-slot conflict_mode_i widgets are always present; only those matching loaded LoRAs take effect.

Outputs

Output Type Description
LORA_STACK LORA_STACK Enriched stack with conflict mode settings
analysis_report STRING Pairwise conflict analysis
merge_strategy STRING Strategy override string (connect to optimizer's merge_strategy_override)

How It Works

  1. Loads all LoRAs, computes full-rank diffs per prefix
  2. Measures pairwise sign conflict ratios
  3. Auto-suggests per-LoRA conflict modes:
    • < 15% average conflict: all
    • 15–40%: low_conflict
    • > 40%: high_conflict
  4. Allows manual override of each LoRA's conflict mode and the merge strategy
  5. Outputs feed directly into the optimizer

LoRA Merge Formula

Passthrough node that attaches a hierarchical merge order to the stack. Tensors pass through unchanged; only formula metadata is added.

Inputs

Input Type Required Default Description
lora_stack LORA_STACK Yes — Stack to annotate
formula STRING Yes "" Merge order using LoRA positions, +, and parentheses — e.g. (1+2) + 3. Optional weights: (1+2):0.6 + 3:0.4. Empty = flat merge

Outputs

Output Type Description
lora_stack LORA_STACK Same stack with the merge formula attached

The optimizer reads the formula and merges sub-groups before composing them, instead of merging the whole stack flat. Useful for establishing a clean base before layering on a disruptive LoRA.


LoRA Metadata Reader

Passthrough node that extracts embedded metadata from every LoRA in the stack. Works with any .safetensors LoRA, not just ones saved by this pack.

Inputs

Input Type Required Description
lora_stack LORA_STACK Yes Stack to read

Outputs

Output Type Description
lora_stack LORA_STACK Unchanged stack (passthrough)
prompt STRING Training/activation prompt fields, if present
description STRING Description fields, if present
metadata_info STRING Consolidated metadata (source_loras, merge_mode, merge settings, custom fields)

Connect the string outputs to Show Text nodes to inspect downloaded or previously merged LoRAs.


LoRA Extract from Model

Recovers a LoRA baked into a finetuned model by subtracting the base-model weights and SVD-decomposing the per-layer delta.

Inputs

Input Type Required Default Description
base_model MODEL Yes — The clean base model
finetuned_model MODEL Yes — The finetuned model to extract from
rank INT Yes 32 Target rank when rank_mode=fixed (1–512)
rank_mode COMBO Yes auto auto picks rank per layer from energy_threshold; fixed forces rank
energy_threshold FLOAT Yes 0.99 Fraction of singular-value energy to retain in auto mode (0.5–1.0)
strength FLOAT Yes 1.0 Strength baked into the emitted stack entry
base_clip CLIP No — Provide both CLIPs to also extract text-encoder layers
finetuned_clip CLIP No — Finetuned text encoder

Outputs

Output Type Description
lora_stack LORA_STACK Feed directly into the Optimizer / AutoTuner
lora_data LORA_DATA Feed into Save Merged LoRA to write a .safetensors

Save Merged LoRA

Exports merged patches as a standalone .safetensors file usable with any standard LoRA loader.

Inputs

Input Type Required Default Description
lora_data LORA_DATA Yes — From Optimizer, AutoTuner, or Merge Selector
save_folder COMBO Yes first configured LoRA folder Which configured ComfyUI LoRA directory to save into
filename STRING Yes merged_lora File name relative to save_folder. Subdirectories allowed
save_rank INT Yes 0 0 = use existing layer ranks. Non-zero = force this rank via SVD
bake_strength COMBO Yes enabled Bake output_strength so the saved LoRA works at strength 1.0

Outputs

Output Type Description
filepath STRING Full path to the saved .safetensors file

Build AutoTuner Python Evaluator

Builds an AUTOTUNER_EVALUATOR object from a Python module path + callable name.

Inputs

Input Type Required Default Description
module_path STRING Yes — Python file path or importable module
callable_name STRING Yes evaluate_candidate Callable that returns a float score or {score, details}
combine_mode COMBO No blend blend, external_only, multiply
weight FLOAT No 0.5 Blend weight when combine_mode=blend
context_json STRING No {} JSON passed through as context to the evaluator

Outputs

Output Type Description
evaluator AUTOTUNER_EVALUATOR External evaluator spec for LoRA AutoTuner

Save / Load Tuner Data

Persist AutoTuner rankings for reuse across optimizer runs.

Save Tuner Data Inputs

Input Type Required Default Description
tuner_data TUNER_DATA Yes — Ranked AutoTuner results
save_folder COMBO Yes first configured tuner_data folder Which configured tuner_data directory to save into
filename STRING Yes tuner_data File name under save_folder. Subdirectories allowed; .tuner is added automatically unless .json/.tuner is supplied
overwrite BOOLEAN Yes true Overwrite an existing file or append _001, _002, … to avoid clobbering

Load Tuner Data Outputs

Output Type Description
tuner_data TUNER_DATA Loaded AutoTuner results ready for Merge Selector

LoRA Combination Generator

Generates LoRA combinations for AutoTuner dataset collection. Cycles through all 2-/3-way combos with deterministic shuffling and tracks progress in a persistent combo_progress.json, so long collection runs resume without repeating combos. Pair with AutoTuner record_dataset / community_cache to build the shared cache.

Inputs

Input Type Required Default Description
shuffle_order INT Yes 0 Seed for deterministic shuffle ordering
strength FLOAT Yes 1.0 Strength applied to each LoRA in the emitted combo
combo_size COMBO Yes 2_and_3 2, 3, or 2_and_3
folder_filter STRING Yes "" Comma-separated path prefixes to restrict the pool (e.g. zit/,zib/)
rerun_mode BOOLEAN Yes false Re-emit already-processed combos for backfilling enriched configs
rerun_source COMBO Yes shuffle shuffle or original_progress ordering when re-running

Outputs

Output Type Description
lora_stack LORA_STACK One combo at a time
combo_info STRING Human-readable description of the emitted combo + progress

LoRA Compatibility Analyzer

Pre-merge planning node that analyzes overlap, cosine similarity, and conflicts without applying a merge.

Inputs

Input Type Required Default Description
enabled BOOLEAN Yes false Run the analyzer only when explicitly enabled
create_nodes BOOLEAN Yes true When enabled, auto-creates LoraLoader nodes for solo LoRAs and LoRA Stack (Dynamic) nodes for merge groups based on the compatibility analysis
model MODEL Yes — Base model used for target grouping and key mapping
lora_stack LORA_STACK Yes — Stack to analyze
clip CLIP No — Optional CLIP model for text-encoder LoRA keys (also used for CLIP-aware loader selection)

Outputs

Output Type Description
report STRING Human-readable compatibility report with suggested groups
compatibility_map IMAGE Heatmap of pairwise compatibility values

Merged LoRA to Hook

Wraps merged patches as conditioning hooks for per-prompt LoRA application.

Inputs

Input Type Required Description
lora_data LORA_DATA Yes From Optimizer, AutoTuner, or Merge Selector
prev_hooks HOOKS No Chain with existing hooks

Outputs

Output Type Description
HOOKS HOOKS Conditioning hooks for use with Cond Set Props

Use Cases

  • Per-prompt LoRA — different merged LoRAs on positive vs negative conditioning
  • Scheduled application — combine with hook keyframes for step-specific LoRA
  • Regional conditioning — apply LoRA to specific image regions
  • Preserve base model — keep MODEL unpatched, apply LoRA only through conditioning

WanVideo LoRA Optimizer (WIP)

Optimizer variant for WanVideo models via kijai's WanVideoWrapper.

Differences from Standard Optimizer

Aspect Standard WanVideo
Model input MODEL WANVIDEOMODEL
CLIP Supported Not used
normalize_keys default enabled enabled
cache_patches default enabled disabled
architecture_preset default auto dit

All merge algorithms work identically — TIES, DARE/DELLA, SVD compression, auto-strength, quality enhancements, key normalization.

Inputs/Outputs

Same as the Legacy optimizer, but with WANVIDEOMODEL replacing MODEL and no CLIP inputs/outputs. Outputs LORA_DATA for Save Merged LoRA.


Merged LoRA → WanVideo (WIP)

Bridges LORA_DATA to a WanVideo wrapper model.

Inputs

Input Type Required Description
wan_model WANVIDEOMODEL Yes WanVideo model to patch
lora_data LORA_DATA No Merged patches to apply

Outputs

Output Type Description
WANVIDEOMODEL WANVIDEOMODEL Patched WanVideo model

Handles the _orig_mod. key prefix mismatch from torch.compile automatically.