kevinzilin-ComfyUI-Krea2-VisualRef/VALIDATION.md

Krea2 VisualRef 验收记录

本文档把可自动完成的开发检查，和必须进入 ComfyUI、加载真实 Krea2 checkpoint 与 Qwen3-VL 文本编码器后才能完成的人工验收分开记录。

当前版本的核心行为：Krea2 Visual Reference Encode 默认使用 style_text_mode=auto_style_text_only，也就是先把 batched style_image 拆成任意数量的单张参考图，再由 Qwen3-VL 按固定字段逐张提取可迁移的风格描述，并计算每张图的调色、明暗、饱和度和对比度提示；如果有多张参考图，会再进行一次纯文本融合，生成带主次层级和近似权重配方的 TRANSFERABLE STYLE LOCK，优先保留每张参考里有辨识度且兼容的非主体风格要素，避免被平均成泛化的中性描述。auto_style_text_and_visual 会同时保留风格文本和最终视觉 token，并在 batch 多图时传入多张视觉参考；visual_only 只返回视觉 token conditioning，主要用于对照高视觉权重行为。

自动检查

在插件目录中运行：

E:\ComfyUI_windows_portable\python_embeded\python.exe -B -m pytest -q --assert=plain

预期结果：

22 passed

这些测试会验证：

• ComfyUI 节点映射可以加载。
• 节点接口只暴露必要控制：strength、placement、style_text_mode，不再暴露 reference_intent、max_style_tokens、style_seed。
• 未连接 style_image 时，Encode 节点会走原生 clip.tokenize(prompt) 文本编码路径。
• strength=0.0 时，即使连接了图片，也会回落到原生文本路径。style_image 已连接且 strength>0 时，prompt 不能为空；参考图只作为风格来源，空 prompt 会让模型只依赖参考图内容和自身先验。
• style_text_mode=visual_only 时，Encode 节点会把原始 style_image 作为 images=[style_image] 传给 clip.tokenize，并只返回这一条视觉 token conditioning；不会再额外合并一条原生文本 conditioning。
• 默认 style_text_mode=auto_style_text_only 时，会先把 batch 拆成单张图，逐张用 clip.generate(...) 生成固定字段风格文本，再追加算法计算的 palette_hint；多图时会额外调用一次纯文本 clip.generate(...)，把这些参考合成为一段带层级和权重配方的统一 style lock，然后只用增强后的 prompt 做文本 conditioning，不再把参考图放进最终视觉 token conditioning。auto_style_text_and_visual 会同时使用统一风格文本和视觉 token，并在 batch 多图时为每张拆分后的参考图插入一个视觉占位。
• strength 使用 ComfyUI conditioning metadata 控制视觉参考条件强度。visual_only 使用 2.5 次方响应曲线：effective_strength = strength^2.5，因此 strength=1.0 的实际权重仍是 1.0，strength=0.75 约为 0.487，strength=0.5 约为 0.177。auto_style_text_and_visual 的文本条件保持 strength=1.0，视觉条件使用用户填写的直接 strength，避免在混合模式里被二次削弱。
• 视觉模板使用固定的风格参考指导语；visual_only 改用只描述风格迁移的 system prompt，不再复用 Krea2 原生“描述颜色、形状、数量、空间关系和背景”的图像描述 system prompt，也不再枚举 cartoon/anime/comic/manga 等风格词，避免写实参考图被模板文本本身带向动漫、插画或背景/构图复制。高 strength 时模板会额外强调强视觉参考；照片参考会额外要求 real-camera photographic realism、natural optics、material realism 和 physically plausible light，并在 prompt 没要求人物时要求不要从参考图带入人物。
• 自动风格文本 prompt 使用固定字段：medium、signature_cues、line_shape、palette、lighting、shading_rendering、texture_surface、detail_density、mood、negative_subjects。最终 conditioning prompt 会写成 TRANSFERABLE STYLE LOCK，明确要求把风格作为渲染规范执行，而不是只把风格词弱弱追加到 prompt 后面。
• 对真实 ComfyUI 图片 tensor，节点会写入 palette_hint，用于补充参考图的整体暖冷、明暗、饱和度、对比度和平均色。
• batch 中有多张参考图时，自动风格文本路径会写入 style_image_count、style_text_raw_items、palette_hint_items，用于确认每张图都被逐张提取；style_text_fusion 会显示是否经过模型二次融合，最终 style_text 应是一段统一风格描述，而不是 reference 列表。
• Debug 节点会报告 sequence length、Krea2 feature width 和插件写入的 metadata。
• 真实 ComfyUI Krea2Tokenizer 会把 <|image_pad|> 替换为 image token，并且该 token 位于 Krea2 prefix stripping 边界之后，不会被裁掉；多图混合模式应能保留多个 image token。

自动测试不会加载真实 Qwen3-VL-4B 模型，也不证明生成质量或最终出图行为。

手动 ComfyUI 验收

日期：

ComfyUI commit 或构建版本：

Krea2 checkpoint：

Qwen3-VL 文本编码器文件：

VAE：

采样设置：

• Prompt：
• Seed：
• Steps：
• CFG：
• Resolution：
• Sampler：
• Scheduler：
• Strength：
• style_text_mode：

测试 1：图像 Token 与风格文本存在性

注意：style_image 是可选输入。未连接图片时，节点应直接走原生 clip.tokenize(prompt) 文本编码路径；连接图片且 strength>0 时，才进入 VisualRef 路径。

使用相同 prompt 分别运行 text-only baseline 和带 1 张参考图的 Krea2 Visual Reference Encode。把 Krea2 Visual Reference Debug 连接到 visual-reference conditioning。

记录 Debug 输出：

text_only_sequence_length:
visual_ref_sequence_length:
feature_width:
krea2_width_valid:
visual_placeholders:
visual_span:
strength:
effective_strength:
style_text_mode:
style_text:
style_text_raw:
style_text_raw_items:
palette_hint:
palette_hint_items:
style_text_fusion:
style_image_count:

通过标准：

• visual_ref_sequence_length 大于 text_only_sequence_length。
• feature_width 等于 30720。
• krea2_width_valid 为 True。
• auto_style_text_only 时，visual_placeholders 为 0，visual_span 为 None。
• visual_only 时，visual_placeholders 为 1，visual_span 有值；auto_style_text_and_visual 时，单图为 1，batch 多图时应等于拆分后的参考图数量。
• style_text_mode=auto_style_text_only 或 auto_style_text_and_visual 时，Debug 中应出现 style_text 和 style_text_raw。
• 参考图 tensor 可读取时，Debug 中应出现 palette_hint；内容应类似 algorithmic palette hint: warm, mid-tone, high-saturation, low contrast, average color #...。batch 多图时，还应看到 style_image_count 等于参考图数量，style_text_raw_items / palette_hint_items 的条目数与参考图数量一致，且 style_text_fusion 为 model_synthesized。最终 style_text 应是统一描述，不应只是 reference 1 | reference 2 的拼接。
• style_text_raw 应尽量描述媒介、线条、笔触、配色、光照、质感、阴影、细节程度和氛围，而不是参考图主体、物体、文字、logo、姿势或布局。
• auto_style_text_only 时会输出一条带 krea2_visual_ref metadata 的文本 conditioning，顶层 strength=1.0。
• auto_style_text_and_visual 时应有一条原生文本条件 strength=1.0，以及一条带 krea2_visual_ref 的视觉参考条件；该视觉参考条件的顶层 strength 应等于用户填写的 strength。visual_only 时应只有一条带 krea2_visual_ref 的视觉参考条件；该条件的顶层 strength 应等于 strength^2.5 后的 effective_strength。

测试 2：三种 style_text_mode 对照

使用相同 prompt、seed、参考图和采样设置，分别生成：

text_only:
auto_style_text_only_strength_0_5:
auto_style_text_only_strength_0_75:
auto_style_text_and_visual_strength_0_5:
auto_style_text_and_visual_strength_0_75:
visual_only_strength_0_5:
visual_only_strength_0_75:

通过标准：

• auto_style_text_only 相对 text-only 有可见风格变化。
• 如果 style_text 干净但 auto_style_text_and_visual 仍带入参考图主体，而 auto_style_text_only 没有带入，说明泄漏来自最终视觉 token 路径。
• 如果 style_text 自身提到了参考图主体或物体，需要记录，因为这会继续造成内容泄漏。

测试 3：风格影响与主体泄漏检查

Prompt：

a ceramic teapot on a wooden table

参考图建议：

• 漫画或线稿风格图
• 水彩或厚涂插画
• 写实照片
• 抽象纹理或图案

记录观察结果：

reference_image:
style_text:
style_text_raw:
style_text_raw_items:
palette_hint:
palette_hint_items:
style_image_count:
teapot_remains:
style_changes:
reference_medium_similarity:
subject_leakage:
best_strength:
best_placement:
style_text_mode:

通过标准：

• 生成结果仍以 prompt 要求的 teapot 为主体。
• 至少 1 张参考图带来可见风格变化，并记录输出是否尽量贴近参考图的原始媒介与风格。
• 如果出现参考图主体、文字、logo 或构图泄漏，需要明确记录。
• 能找到一个比 strength=1.0 更好保留 prompt 的较低权重时，应记录该值。

测试 4：Strength、Placement 与 Mode 对比

对比：

• strength=0.25 / 0.5 / 0.75 / 1.0
• before_prompt
• after_prompt
• auto_style_text_only / auto_style_text_and_visual / visual_only

记录观察结果：

strength_0_25:
strength_0_5:
strength_0_75:
strength_1_0:
before_prompt:
after_prompt:
auto_style_text_only:
auto_style_text_and_visual:
visual_only:

通过标准：

• 所有设置都能运行，且没有 conditioning width 错误。
• prompt following、style strength、leakage 或上下拼贴/重复面板差异有记录。
• 建议先用 0.5 或 0.75 观察；如果参考图主体压过提示词，再降到 0.25。

v1 就绪标准

只有满足以下条件，才判定插件 v1 验收完成：

• 自动测试通过。
• 重启 ComfyUI 后能加载 Krea2 Visual Reference Encode、Krea2 Style Prompt Encode、Krea2 Visual Reference Debug 三个节点。
• 手动测试 1 通过。
• 至少一组固定 seed 生成对比证明：更换参考图会改变输出。
• 至少一组三模式对比证明：auto_style_text_only、auto_style_text_and_visual、visual_only 在主体泄漏和风格迁移上的差异；如果不能改善，也要记录当前模型上的失败表现。
• 至少一组 strength 对比证明：降低指令强度能减轻参考图压过 prompt、上下拼贴或重复面板问题，或记录该机制在当前模型上无明显效果。
• 已知限制仍以“实验行为”记录，不宣称这是 Krea 官方 style reference，也不承诺稳定风格迁移效果。