Extensions/ComfyUI-YogurtNodes-InstructSAM
ComfyUI Extension

ComfyUI-YogurtNodes-InstructSAM

ComfyUI custom nodes for InstructSAM.

By yogurt7771·Created about a month ago·Updated about a month ago· 0
yogurt7771/ComfyUI-YogurtNodes-InstructSAM
Nodes—
On cloudLocal install
Stars0
Updatedabout a month ago
Readme

ComfyUI-YogurtNodes-InstructSAM

在 ComfyUI 中使用 InstructSAM 进行指令驱动的多实例图像分割。

InstructSAM 不是单独的 Qwen 模型或 SAM 模型，而是由 Qwen3-VL 与 SAM3 组成的视觉语言分割模型。它可以理解类别、指代和推理类指令，并输出逐实例掩码。

功能

  • 使用自然语言指定需要分割的目标
  • 输出逐实例掩码和所有实例的合并掩码
  • 支持 transformers>=4.57.3,<6，不强制升级到 Transformers 5
  • 模型统一存放在 ComfyUI 的 models/instructsam/，不使用 Hugging Face cache 目录
  • 默认不联网、不自动下载；只有显式启用 download_model 才会下载模型文件
  • 支持缓存模型，以及由 ComfyUI 管理显存加载和卸载

当前节点一次处理一张 RGB 图片。建议使用清晰、具体的英文指令。

安装

将本仓库放到 ComfyUI 的 custom_nodes 目录：

ComfyUI/
└── custom_nodes/
    └── ComfyUI-YogurtNodes-InstructSAM/

使用运行 ComfyUI 的同一个 Python 环境安装依赖，然后重启 ComfyUI。

普通虚拟环境：

cd ComfyUI\custom_nodes\ComfyUI-YogurtNodes-InstructSAM
python -m pip install -r requirements.txt

Windows Portable：

cd ComfyUI
.\python_embeded\python.exe -m pip install -r .\custom_nodes\ComfyUI-YogurtNodes-InstructSAM\requirements.txt

依赖要求为：

transformers>=4.57.3,<6

对于安装了大量插件的 ComfyUI，建议优先保留兼容性更好的 Transformers 4.57.x，例如 4.57.6，不需要为了本插件升级到 5.x。插件在 4.57.x 下使用内置的 SAM3 兼容实现，在 5.x 下使用 Transformers 自带的 SAM3 组件。

模型放置

模型必须放在当前 ComfyUI 实例的 models/instructsam/ 目录中，最终结构如下：

ComfyUI/
└── models/
    └── instructsam/
        ├── CircleRadon--InstructSAM-2B/
        │   ├── chat_template.jinja
        │   ├── config.json
        │   ├── generation_config.json
        │   ├── model.safetensors
        │   ├── processor_config.json
        │   ├── tokenizer.json
        │   └── tokenizer_config.json
        └── facebook--sam3/
            ├── LICENSE
            ├── config.json
            ├── merges.txt
            ├── processor_config.json
            ├── special_tokens_map.json
            ├── tokenizer.json
            ├── tokenizer_config.json
            └── vocab.json

其中：

  • CircleRadon--InstructSAM-2B 来自 CircleRadon/InstructSAM-2B，包含主模型权重。
  • facebook--sam3 来自 facebook/sam3，但这里只需要上面列出的配置、processor、tokenizer 和许可证文件。
  • 不需要在 facebook--sam3 中放置 model.safetensors、sam3.pt 或其他 SAM3 权重。InstructSAM 主 checkpoint 已包含推理所需的分割权重。

如果已经下载到：

D:\Models\hf\CircleRadon--InstructSAM-2B

请把整个目录复制到：

<你的 ComfyUI>\models\instructsam\CircleRadon--InstructSAM-2B

不要只复制 model.safetensors，配置、processor、tokenizer 和 chat template 也必须完整保留。插件会校验解析后的真实路径是否仍位于 ComfyUI 已注册的模型目录内，因此不建议使用指向外部模型目录的符号链接或目录联接。

方式一：通过节点下载

这是准备缺失文件最简单的方式：

  1. 在 Yogurt InstructSAM Model Loader 中将 download_model 设为 true。
  2. 执行一次工作流。
  3. 文件会直接下载到 ComfyUI/models/instructsam/，不会写入 Hugging Face cache。
  4. 下载完成后可以把 download_model 改回 false，后续完全使用本地文件。

下载器只会获取插件固定清单中的模型文件，不会下载完整 SAM3 权重，也不会在后台检查更新。

facebook/sam3 是 Hugging Face gated 仓库。首次下载前需要：

  1. 登录 Hugging Face 并在 facebook/sam3 页面接受访问条款。
  2. 为运行 ComfyUI 的环境提供有权限的 Hugging Face token，例如设置 HF_TOKEN。

如果返回 HTTP 401 或 403，通常表示尚未接受访问条款、token 无效，或 ComfyUI 进程没有读取到 token。

方式二：手动准备

也可以从以下仓库手动下载，并按前面的目录树放置：

download_model=false 时插件不会联网，并会严格检查两个目录及所需文件。目录名、文件缺失或文件不完整都会导致加载失败。

节点使用

可直接导入 example_workflows/instructsam_segmentation.json。导入后先在 Load Image 中选择图片，再按本页的模型放置说明准备模型并执行。工作流会分别预览逐实例掩码和合并掩码。

插件提供两个节点：

  • Yogurt InstructSAM Model Loader
  • Yogurt InstructSAM Image Segmentation

基本连接方式：

Yogurt InstructSAM Model Loader ── model ──┐
                                           ├─ Yogurt InstructSAM Image Segmentation
Load Image ─────────────────────── image ──┘

在分割节点的 instruction 中输入要分割的内容，然后执行工作流。例如：

Please segment all pillows in the image.

Please segment the yellow fruit behind the apples.

Please segment the two blue ceramic mugs in the image.

尽量明确写出目标的类别、颜色、位置或与其他物体的关系。模型以英文指令训练为主，中文或过于简短、含糊的提示词可能降低结果稳定性。

Model Loader 参数

| 参数 | 默认值 | 说明 | | --- | --- | --- | | model_name | CircleRadon--InstructSAM-2B | 从 models/instructsam/ 中选择主模型目录。 | | dtype | auto | auto 自动选择合适精度；还可选择 bfloat16 或 float32。 | | download_model | false | 缺少模型时是否显式下载到 ComfyUI 模型目录。关闭时不会联网。 | | cache_model | true | 是否复用已加载的模型句柄。开启可减少重复加载时间，但会继续占用一部分内存。 | | force_reload | false | cache_model=true 时强制释放并重新创建匹配的缓存模型。 |

cache_model=false 时，分割结束后会释放当前模型句柄；同一个 Loader 输出在后续队列再次使用时会自动重新加载，不需要重新创建节点。该模式启动更慢，但适合希望任务结束后尽快释放模型内存的工作流，因此不再单独提供 unload 节点。

Image Segmentation 参数

| 参数 | 默认值 | 说明 | | --- | --- | --- | | model | - | Loader 节点输出的 InstructSAM 模型。 | | image | - | 单张 ComfyUI IMAGE。 | | instruction | - | 分割指令，建议使用具体的英文描述。 | | score_threshold | 0.3 | 只保留分数严格大于该值的候选实例。结果缺失时可适当降低，误检较多时可提高。 | | mask_threshold | 0.5 | 将掩码概率二值化的阈值。降低会扩大掩码，提高会收紧掩码。 |

输出

| 输出 | 类型 | 说明 | | --- | --- | --- | | text | STRING | 模型生成的文本结果。 | | instance_masks | MASK | 每个保留实例各一张二值掩码。 | | union_mask | MASK | 所有保留实例的合并掩码。 | | scores | STRING | 保留实例的分数，使用 JSON 字符串表示。 | | instance_count | INT | 保留的实例数量。 |

没有候选实例通过 score_threshold 时，instance_masks 和 union_mask 都会返回一张与输入图像同尺寸的全黑掩码，scores 为空数组，instance_count 为 0。

缓存与显存

  • cache_model=true：相同模型和精度会复用缓存，连续执行更快。缓存可能继续占用 CPU 内存，VRAM 的加载与 offload 由 ComfyUI 管理。
  • cache_model=false：每次分割完成后释放句柄，下次执行时重新加载。适合内存紧张、但能接受加载时间增加的情况。
  • force_reload=true：仅在缓存开启时有意义，适合模型文件刚刚被替换后刷新缓存。
  • dtype=auto：通常是首选。float32 占用的内存和显存更多。

常见问题

提示模型目录或文件不存在

确认当前运行的 ComfyUI 对应的路径是：

<当前 ComfyUI>\models\instructsam\CircleRadon--InstructSAM-2B
<当前 ComfyUI>\models\instructsam\facebook--sam3

重点检查目录名是否完全一致，以及前面模型目录树中的文件是否齐全。多个 ComfyUI 安装并存时，模型必须放在实际启动的那一份 ComfyUI 的模型目录中。

下载 facebook--sam3 时出现 401 或 403

先在 Hugging Face 仓库页面接受访问条款，再确认 HF_TOKEN 对启动 ComfyUI 的进程可见。仅在网页中登录 Hugging Face 并不一定会让本地 ComfyUI 获得 token。

节点没有出现，或启动时提示 import error

确认依赖安装在 ComfyUI 实际使用的 Python 中，而不是系统的另一个 Python。安装后完整重启 ComfyUI；只刷新浏览器页面不会重新加载 Python 插件。

显存或内存不足

优先使用 dtype=auto，并尝试关闭 cache_model。避免使用 float32。输入分辨率也会影响推理阶段的显存占用。

能出结果，但分割效果不理想

  1. 使用英文完整句子，明确目标类别、颜色、位置或关系。
  2. 确认连接的是 union_mask 还是单实例批次 instance_masks。
  3. 先使用默认 score_threshold=0.3、mask_threshold=0.5；漏检时降低 score 阈值，边缘过窄时降低 mask 阈值。
  4. 确认输入是单张正常 RGB 图像，而不是意外组成的批次或带有错误预处理的图像。
  5. 更新插件代码或替换模型文件后，重启 ComfyUI，或在缓存开启时执行一次 force_reload=true。

阈值只能筛选候选和调整二值化边界，不能修正模型对指令的错误理解。若目标描述本身含糊，优先改写指令，而不是大幅调低阈值。

Transformers 兼容性

  • Transformers 4.57.3 至 4.x：使用插件内置的 SAM3 兼容实现，避免强制升级影响其他 ComfyUI 插件。
  • Transformers 5.x：使用 Transformers 原生的 SAM3 配置、视觉主干和 processor，并保留 InstructSAM 所需的 query bridge。
  • Transformers <4.57.3：不支持，因为缺少 InstructSAM 使用的 Qwen3-VL 组件。
  • Transformers >=6：当前未声明支持。

License

本插件新增的集成代码使用 MIT License。模型权重不包含在本仓库中。

InstructSAM 源码、InstructSAM 模型权重和 SAM3 assets 分别受各自上游许可证与访问条款约束。详情见 THIRD_PARTY_NOTICES.md。