SnapRef：为 ComfyUI 中的 Anima 打造的缓存 KV 引用适配器

一张引用图像，一个只描述场景的提示词。

Anima 是一个标签提示词模型，所以通常要在提示词中把发型、眼睛和服装一一写出来才能复现一个角色，而且只对模型已经认识的角色有效。引用适配器把这项工作转移到图像上：文本负责姿势、构图和地点，引用负责画的是谁。

这个思路在 Anima 上并不新鲜。Anima Reference Adapter 在 10 月 27 日就这样做过：把引用作为偏移的第二 Latent 帧追加，这样视频式先验就不会把它当作一个镜头继续下去。SnapRef 走了另一条路：它让引用通过模型一次，缓存每一层产生的内容，并在每个采样步骤重新读取该缓存。

引用如何被缓存

适配器文件是两个 LoRA 分支，打包在同一个键 anima_ref_kv/1 下：一个 rank-128 的引用分支，作用于全部 28 个块的自注意力、交叉注意力和两个 MLP 层；另一个 rank-64 的分支作用于目标侧的自注意力。合计 190.8M 参数，bf16 下为 382 MB。

引用只编码一次，并以一组固定的 token 保留，在模型的坐标空间中拥有自己的位置，这样模型读取它是为了获取外观，而不是复制其布局。采样过程中，每一层会关注自己的 token 以及缓存中的引用。目标侧的 LoRA 在每一次目标前向中保持开启，默认只有正向 CFG 分支读取引用；ref_guidance 会把它送入两个分支。由于引用不会在每一步重新编码，模型卡给出的开销约为无引用生成的 15%。

提供了两种模式：cs 同时复制角色与风格，char 只复制角色，以便用画师标签设定风格。另有一条 ref_guidance 路径以约 1.4 倍的时间更强地推向引用，并配合 APG 或 CFG rescale 防止颜色过饱和，这与更早的适配器所需的修正相同。

与其他方案相比的开销

仓库中提供了 comparison_summary.json，这是一张在 A100 上以 832×1216、28 步、各适配器使用自身默认设置测得的同案例计时表：

在身份一致性方面，模型卡报告称，对于训练中留出的角色，使用正确引用的适配器比使用错误引用时对目标的预测更好，在留出集去噪损失上身份差距为 0.0041，逐案例数据见 heldout_loss.json。

训练集中没有的角色。提示词只指明场景；发型、眼睛和服装都来自引用。

训练集之外的引用，经适配器运行。

训练数据由 Anima 自身生成：58,300 张图像，覆盖 2,367 个角色，每个角色都以同一种画师风格绘制在多种场景和姿势中，随后进行了约 120 H100 GPU 小时的运行。第二个检查点 SnapRef v1b 将 LoRA rank 翻倍，更贴近提示词，对角色的保持效果也基本相当。

ComfyUI 方面

节点包位于仓库的 comfyui/snapref/ 下；将其复制到 custom_nodes/，把适配器放入 models/loras/，并用 SnapRef 节点而非 LoRA 加载器加载，因为这两个分支并非普通 LoRA。简单节点接受一到两张图像、一个模式、强度与保真度；高级节点则暴露其余所有参数，包括 ref_in_uncond、ref_megapixels 与 ref_caption。

已包含五个工作流：单角色、双角色、同一角色的多个引用、与其他适配器的并排对比，以及下面的最小工作流。双角色的说明是：用核心 Image Stitch 节点把两张引用拼接起来，并在提示词中描述谁在左、谁在右。推荐采样为 euler 或 er_sde 配合 simple，28 到 30 步，CFG 4.5。

FP8 适配器为 195 MB 而非 382 MB，据报告生成的图像基本一致，包括在 FP8 Anima 基础模型上。节点已于 10 月 31 日更新，将引用编码保持为 fp32：在使用 fp16 检查点、--fp16-unet，或带 fp16 累加的 --fast 时，更早的版本会产生 NaN 和黑色图像。

它在哪些情况下失效

模型卡列出而非隐藏了这些失效模式。耳环、精细花纹和疤痕等非常小的细节可能被简化，深色皮肤的引用可能偏浅，某些户外全身提示词会把画面底部变成纯白地面，除非明确指明地面。场景可能覆盖引用的服装，因此海滩提示词会返回泳装；提高 strength 或指明服装可以保持住。双角色时，引用未清晰展示的属性（例如闭眼）可能在两者之间混淆。