ComfyUI-EmbeddingQuery：基于 EmbeddingGemma 2 的语义搜索节点，实现图文混合检索与实时索引

ComfyUI-EmbeddingQuery 是一个专为 ComfyUI 设计的语义搜索工具，利用谷歌的 EmbeddingGemma 2 模型对 input/ 和 output/ 目录下的文件进行向量化索引。由于文本和图像共享同一个嵌入空间，该节点支持文本搜图、以图搜图、文本搜文以及图文混合查询等多种交互模式。其核心优势在于零依赖安装、实时非阻塞索引以及高度集成的 ZenKit UI 体验。

GitHub：https://github.com/Nynxz/ComfyUI-EmbeddingQuery
模型：https://huggingface.co/google/embeddinggemma-2

ComfyUI-EmbeddingQuery：基于 EmbeddingGemma 2 的语义搜索节点，实现图文混合检索与实时索引

核心功能与交互逻辑

该插件以单个节点 Embedding Search 的形式存在，所有操作界面均集成在节点主体内（需配合 ZenKit nodekit 使用效果最佳）。

1. 文件夹管理与索引

自动扫描：节点会自动列出 input/ 和 output/ 下的所有文件夹。每个文件夹行代表其整个子树。
状态汇总：显示索引状态（如 ✓ 全部已索引 或 3/7 部分）。打开未索引的文件夹会自动触发后台索引进程。
精准搜索：Ctrl/Cmd-点击文件夹圆点可限定仅搜索该文件夹及其子内容；再次点击可恢复全局搜索。
增量更新：索引存储在用户目录下的 embeddingquery/indexes/<model>/ 中，不会污染工作目录。系统通过文件大小和修改时间判断是否需重新嵌入，实现高效的增量更新。

2. 多模态查询

实时响应：输入文本即触发实时搜索，无需加入生成队列。
混合输入：支持将图像拖放到节点上进行“以图搜图”；Shift-拖放可将多张图像添加为查询集合。
相似性扩展：点击结果中的“查找相似”可直接利用该文件的存储嵌入进行搜索，无需重新运行模型；Shift-点击多个结果可按文件组进行联合搜索。

3. 结果输出与工作流集成

可视化网格：搜索结果以带相似度分数的网格形式展示。
灵活输出：
- 手动固定：点击某个结果将其固定为节点输出。
- 自动最佳匹配：若未固定，节点默认输出得分最高的命中项。
- 拖拽使用：可直接将图像结果拖入 Load Image 节点或画布中使用。

标准输出接口：作为输出节点，它可在图中途工作，提供以下输出：

输出端口	值说明
`image`	命中的图像文件；若是文本文件，则尝试加载同名图像，否则为 64×64 空白图。
`text`	命中文本文件的内容；若是图像，则尝试加载同名 `.txt` 或 `.caption` 文件，否则为空字符串。

4. 高级设置与 ZenKit 集成

查询组合策略（齿轮设置）：
- mean (默认)：计算查询向量的归一化质心，寻找共同点。
- any：取每个文件在查询中的最佳匹配（OR 逻辑），寻找任一特征相符的内容。
- joint：将图像和文本作为序列输入模型（最多 16 张图像），实现特征交互（如“这个姿势配这套服装”）。
ZenKit 弹出窗口：安装 ZenKit 后，节点标题栏会出现按钮，点击可在独立窗口中打开搜索界面，方便在编辑其他工作流时随时检索和拖拽结果。

技术架构与模型细节

模型基础：使用 nynxz/embeddinggemma-2，这是 Google EmbeddingGemma 2 (Apache 2.0) 的单文件重打包版本。包含文本和视觉塔，丢弃了音频组件。
ComfyUI 适配：基于 ComfyUI 原生的 Gemma 4 实现 (comfy.text_encoders.gemma4)，通过对称滑动窗口实现双向注意力，并采用 EmbeddingGemma 2 特有的逐层投影输入和 768 维均值池化头。
精度与性能：
- 以 bf16 加载（不支持 bf16 时回退至 fp32，fp16 会溢出）。
- 与 Hugging Face Transformers 库的 EmbeddingGemma2Model 保持高度一致（文本余弦相似度 1.0000，图像 0.9999）。
- 图像细节控制：支持每张图像 280、140 或 70 token 的嵌入粒度。较低粒度可显著提升索引速度（测试中分别快约 3 倍和 8 倍），但会牺牲少量匹配精度。
- Matryoshka 截断：支持使用 512/256/128 维嵌入进行排名，进一步优化检索效率。

安装指南

1. 安装节点包

无需额外 Python 依赖，前端资源已预构建。

cd ComfyUI/custom_nodes
git clone https://github.com/Nynxz/ComfyUI-EmbeddingQuery

注意：需要 ComfyUI 版本支持 Gemma 4（已在 v0.41.0 上测试通过）。

2. 下载模型

从 Hugging Face 下载 embeddinggemma_2_bf16.safetensors (约 0.9 GB) 并放置于：

ComfyUI/models/text_encoders/embeddinggemma_2_bf16.safetensors

3. 启动与使用

重启 ComfyUI，在节点菜单中找到 EmbeddingQuery 类别下的 Embedding Search 节点。首次使用时，展开文件夹列表并点击想要索引的目录，等待后台索引完成后即可输入查询。

常见问题与技巧

如何搜索外部库？ 将外部文件夹符号链接到 input/ 目录下，节点会自动跟随符号链接进行索引。
索引会影响生成吗？ 不会。索引和实时搜索在提示队列之外运行，且在生成任务执行时会暂停，确保不与 GPU 生成任务竞争资源。
文本如何处理？ 文本文件会被添加前缀 title: none | text: 并在 2048 token 处截断；查询时则添加 task: search result | query: 前缀以优化语义匹配。

ComfyUI-EmbeddingQuery 为创作者提供了一种高效管理海量素材的方式，无论是回顾历史生成结果还是快速定位参考图，都能通过自然的语义描述轻松实现，极大提升了工作流的流畅度。