Multi Reference Latent

ComfyUI Multi Reference Latent

中文 | English

把最多 6 张参考图一次性注入 conditioning 的单节点,专为 FLUX.2 dev / klein 这类吃 reference_latents 的图像编辑模型设计。每张图有独立的 strength,strength = 0 就跳过那张图 —— 于是一个静态工作流就能覆盖 0~6 张参考图,不用 bypass、不用动态改线、不用为不同图数准备多个工作流。程序化提交还可用 reference_list 文本(图数=行数,无占位图)。

它解决什么

ComfyUI 原生 ReferenceLatent 一次只喂一张参考图,要多张就得手动把多个 ReferenceLatent 串起来,而且没有逐图强度控制。本节点:

• 一个节点喂多张(≤6 socket,或 reference_list 不限),内部按原生 reference_latents append 语义逐张拼接;
• 每张独立 strength(范围 0 ~ 5),0 = 跳过,1.0 = 原生强度,>1 增强;
• 内置 VAE 编码,直接接 IMAGE,不用每张图外挂一个 VAEEncode;
• 全 optional:一张都不接 → conditioning 原样透传(等于纯文生图)。

安装

• ComfyUI Manager:搜 Multi Reference Latent 安装。
• 手动:git clone https://github.com/lynclee/comfyui_multi_referencelatent 到 ComfyUI/custom_nodes/,重启。

接线

CLIPTextEncode ──conditioning──┐
                               ▼
            ┌──────────────────────────────┐
LoadImage ─►│ image_1   strength_1 = 1.0   │
LoadImage ─►│ image_2   strength_2 = 0.8   │──conditioning──► (接 sampler 的 positive)
            │ image_3   strength_3 = 0  ⟵跳过
            │ ...                          │
VAELoader ─►│ vae                          │
            └──────────────────────────────┘

• conditioning(必填):一般接正向 CLIPTextEncode。
• vae(接了图才需要):接 VAELoader,用来把参考图编码成 latent。
• image_1..image_6(可选):参考图。
• strength_1..strength_6:对应图的强度;留 0 = 该槽不参与,可只接想用的那几张。

一个工作流覆盖 0~6 图

把 6 个图槽留着,想用几张就接几张(或者把不想要的那张 strength 调 0)。提交时不参与的槽不产生任何 latent,云端/本地行为完全一致,无需为不同图数维护多份工作流。

程序化喂图:reference_list(无占位图,图数=行数)

画布手动用 image_N socket;但程序化/API 提交时,socket 会留下"空槽"(要么占位图、要么动态改线)。为此节点提供另一条路 —— reference_list 多行文本:

2.0 iVBORw0KGgoAAAANS...        ← 第 1 张,strength=2.0
iVBORw0KGgoAAAANS...            ← 第 2 张,strength 省略=1.0
0.5 data:image/png;base64,iVBOR... ← 第 3 张,支持 data URI 前缀

• 每行一张图,格式 [strength ]<base64>,strength 可省(=1.0);
• 图数 = 非空行数,完全由你填的文本决定 —— graph 结构恒定,没有空槽、没有占位图、没有动态改线、没有多份 JSON;
• 空行忽略,strength=0 的行跳过;
• 可与 image_N socket 同时用(socket 在前)。

后端只需把 N 张图拼成 N 行塞进这个字段,一个静态工作流适配任意张数。这就是"静态的是 graph,动态的是数据"。

strength 怎么作用(以及它的局限)

reference_latents 在 conditioning 里只是一串 latent,模型对其中每个 latent 没有独立的权重输入。所以在 conditioning 这一层,"调强度"唯一能做的就是缩放这张图自己的 latent 数值。这是近似,不是干净的"影响力旋钮"——缩放会顺带改变 latent 在 VAE 空间的分布:

• 1.0:模型原生行为,最可靠(等于把这张图原样喂进去);
• 0:整张跳过,完全不进 conditioning,可靠;
• 0 < s < 1:弱化,近似,可能伴随轻微的内容呈现变化;
• s > 1:放大,谨慎用,容易过曝/失真。

把它当"开关 + 微调"用最稳:确定要不要某张图(0 / 1.0),需要时再小幅增减。

strength_mode:手动 / 自动归一化

节点上有个 strength_mode 开关:

• manual(默认):每张图各用各自的 strength,行为同上;
• normalize:把所有有效图的 strength 按总和归一化(和=1),保留你设的相对比例。例如三张设 2/1/1 → 0.5/0.25/0.25;全设 1 → 0.333/0.333/0.333(即自动均分)。接几张就自动分几份,不必手动改。

两种模式下 strength=0 都仍表示跳过该图,归一化只在剩下的有效图之间分配。

提醒:归一化让"总权重"恒为 1,但因为 strength 本质是缩放 latent(见上),图越多每张被压得越低,可能整体发灰。normalize 适合"懒得逐个填、要按比例自动分"的场景;追求单图保真时用 manual + 1.0。

显存与分辨率

每张参考图都会被 VAE 编码成 latent 并占用模型上下文,多张高分辨率图会显著增加显存和 token 数。建议在接入前用上游节点把参考图缩到合理尺寸(例如长边 ≤1024),尤其是同时接 4~6 张时。本节点刻意不内置自动缩放,把分辨率决策留给你的工作流。

许可

MIT。基于 ComfyUI 公开的原生 ReferenceLatent 机制独立实现。

---

<a name="english"></a>

ComfyUI Multi Reference Latent (English)

中文 | English

A single node that injects up to 6 reference images into conditioning, built for FLUX.2 dev / klein and other edit models that consume reference_latents. Each image has its own strength, and strength = 0 skips that image — so one static workflow covers 0–6 references without bypass, rewiring, or multiple workflows. For programmatic submission there is also a reference_list text field (image count = number of lines, no placeholder images).

What it solves

Native ReferenceLatent feeds one reference at a time and has no per-image strength. This node:

• Feeds many in one node (≤6 sockets, or unlimited via reference_list), chaining them with the native reference_latents append semantics;
• Per-image strength (range 0–5): 0 = skip, 1.0 = native, >1 stronger;
• Built-in VAE encode — wire IMAGE directly, no per-image VAEEncode;
• All optional — connect nothing and conditioning passes through unchanged (plain text-to-image).

Install

• ComfyUI Manager: search Multi Reference Latent.
• Manual: git clone https://github.com/lynclee/comfyui_multi_referencelatent into ComfyUI/custom_nodes/, restart.

Inputs

• conditioning (required): usually your positive CLIPTextEncode.
• vae (needed only when images are connected): from VAELoader.
• image_1..image_6 (optional): reference images.
• strength_1..strength_6: per-image strength; leave 0 to disable that slot.

One workflow, 0–6 images

Keep all 6 slots; wire as many as you need (or set an unwanted image's strength to 0). Disabled slots produce no latent at all, so behavior is identical locally and on any backend — no need to maintain separate workflows per image count.

Programmatic input: reference_list (no placeholder images)

image_N sockets are for the canvas; but for programmatic / API submission, sockets leave "empty slots" (needing placeholder images or graph rewiring). So the node offers another path — the reference_list multiline text:

2.0 iVBORw0KGgoAAAANS...        ← image 1, strength 2.0
iVBORw0KGgoAAAANS...            ← image 2, strength omitted = 1.0
0.5 data:image/png;base64,iVBOR... ← image 3, data URI prefix supported

• one image per line, format [strength ]<base64>, strength optional (=1.0);
• image count = number of non-empty lines, fully data-driven — the graph structure is fixed: no empty slots, no placeholder images, no rewiring, no multiple JSONs;
• blank lines ignored, lines with strength=0 skipped;
• works alongside image_N sockets (sockets first).

Your backend just joins N images into N lines and fills this field; one static workflow adapts to any count. The graph stays static, the data drives the image count.

How strength works (and its limits)

reference_latents is just a list of latents in the conditioning; the model has no per-latent weight input. So at the conditioning level the only thing "strength" can do is scale that image's own latent values. This is an approximation, not a clean influence knob — scaling also shifts the latent's distribution in VAE space:

• 1.0: native behavior, most reliable (feeds the image as-is);
• 0: the image is skipped entirely, reliable;
• 0 < s < 1: weaker, approximate, may slightly alter how the reference reads;
• s > 1: stronger, use sparingly — prone to over-exposure / artifacts.

Treat it as a switch plus fine-tune: decide whether an image is in (0 / 1.0), then nudge if needed.

strength_mode: manual / auto-normalize

The node has a strength_mode switch:

• manual (default): each image uses its own strength, as above;
• normalize: all active strengths are normalized to sum to 1, keeping your relative ratios. E.g. three images at 2/1/1 → 0.5/0.25/0.25; all 1 → 0.333/0.333/0.333 (auto-equal). Wire any number of images and they auto-split.

In both modes strength=0 still skips that image; normalization only distributes across the remaining active ones.

Note: normalizing keeps total weight at 1, but since strength scales the latent (see above), more images means each is pushed lower and the result may turn flat/grey. Use normalize when you want hands-off proportional splitting; use manual + 1.0 when single-image fidelity matters.

VRAM & resolution

Every reference image is VAE-encoded into a latent that occupies model context, so several high-resolution images noticeably increase VRAM and token count. Resize references upstream to a sane size (e.g. long edge ≤1024) before wiring them in, especially with 4–6 images at once. This node deliberately ships no auto-resize — the resolution decision stays in your workflow.

License

MIT. An independent implementation built on ComfyUI's public native ReferenceLatent mechanism.