用于外部工具的 ComfyUI 节点

提供专为将 ComfyUI 用作外部工具后端而设计的节点和 API。

• 发送和接收图像
• 区域（注意力掩码）
• 分块图像处理
• 其他节点
• HTTP API 扩展（模型检查）
• ⭳ 安装

发送和接收图像

ComfyUI 通过文件系统交换图像。这需要一个多步骤流程（上传图像、提示、下载图像），容易引发一系列你可能不想处理的问题。此外，如果通过外部工具使用 ComfyUI，这些图像会在何时被清理也并不明确。

加载图像（Base64）

从嵌入在提示中的 Base64 编码 PNG 图像中加载图像。

• 输入：Base64 编码的 PNG 图像二进制数据
• 输出：图像（RGB）以及存在的遮罩（Alpha）

加载遮罩（Base64）

从嵌入在提示中的 Base64 编码 PNG 图像中加载单通道遮罩。

• 输入：Base64 编码的 PNG 图像二进制数据
• 输出：图像的第一个通道作为遮罩

通过 WebSocket 发送图像

通过客户端 WebSocket 连接以 PNG 二进制数据的形式发送输出图像。

• 输入：图像（RGB 或 RGBA），支持批量传输

首先会通过 WebSocket 发送每张图像的一条二进制消息：

12<PNG-data>

即两个大端序的 32 位整数，值分别为 1 和 2，后面跟着 PNG 的二进制数据。随后还会发送一条 JSON 消息：

{'type': 'executed', 'data': {'node': '<node ID>', 'output': {'images': [{'source': 'websocket', 'content-type': 'image/png', 'type': 'output'}, ...]}, 'prompt_id': '<prompt ID>}}

从缓存加载图像

加载之前已上传到工作流中的图像或遮罩。上传的图像暂时存储在内存中，而不是写入磁盘。与将图像以 Base64 形式嵌入提示相比，这种方法开销更小，但实现起来更为复杂。

• 输入：先前上传图像的 ID
• 输出：图像（RGB）以及遮罩（如果是 RGBA 输入，则为 Alpha 通道；若无 Alpha 通道，则为第一通道）。

要上传图像，需通过 HTTP PUT 请求将 PNG 的 字节 数据上传至 /api/etn/image/{id}。JPEG 或其他格式同样适用。选择一个不会与其他上传图像冲突的 id，并在节点中引用它。请求返回 201 表示图像已成功上传，返回 200 则表示该图像已在缓存中。

将图像保存到缓存

将输出图像临时存储在内存中，并可通过 HTTP 获取。通常比 WebSocket 更快，尤其是对于大图像。

• 输入：图像（RGB 或 RGBA）。支持批量处理。

当图像准备就绪时，此节点会通过 WebSocket 发送一条 JSON 消息：

{
  "type": "executed",
  "data": {
    "node": "<node ID>",
    "output": {
      "images": [
        {"source": "http", "id": "<image ID>", "content-type": "image/png", "type": "output"}
      ]
    },
    "prompt_id": "prompt ID"
  }
}

要下载这些图像，可向 /api/etn/image/{id} 发送 HTTP GET 请求，提供消息中的图像 ID。图像将在缓存中保留几分钟。

区域

这些节点实现了对任意数量图像区域的注意力掩码功能。文本提示仅应用于被掩码覆盖的区域。与条件掩码相比，这种方法不那么“强制”，但能生成更自然的图像构图。

工作流：region_attention_mask.json

背景区域

此节点开始一个区域列表。它接受提示，但不接受遮罩。该提示将应用于列表中所有未被其他区域遮罩覆盖的图像区域。

定义区域

将新区域添加到区域列表中（或开始一个新的列表）。接受提示和遮罩，遮罩定义了提示将作用于图像中的区域。遮罩必须与图像尺寸相同，或者与潜在空间尺寸一致（潜在空间尺寸是图像的 1/8）。

列出区域遮罩

此节点接受区域列表并输出所有遮罩。可用于检查、调试，或重新利用计算出的背景遮罩。

区域注意力掩码

修改模型以使用提供的区域列表。这会替换传递给采样器的正面文本条件。仍然可以将 ControlNet 和其他条件传递给采样器。

将遮罩应用到图像

将遮罩复制到图像的 Alpha 通道中。

• 输入：图像和遮罩
• 输出：RGBA 图像，遮罩用作透明度

分块

将图像分割成多个小块分别处理是一种加快扩散速度并节省显存的有效方法。市面上已有许多提供固定流程的节点。相比之下，以下节点仅提供将图像分割成小块并重新拼接的功能。借助工具和脚本，可以为每个小块生成独立的工作流，从而实现最大的灵活性（不同的提示、区域、控制等）。

工作流：image_tiles.json

创建分块布局

此节点定义分块参数：

• min_tile_size：每个小块的最小分辨率（以像素为单位）。小块可能会更大，以便均匀地适应图像尺寸。
• padding：每个小块周围的填充区域（以像素为单位）。与相邻小块有重叠，但在图像边缘则没有填充。
• blending：用于平滑过渡以避免接缝的填充区域部分。会影响由此布局生成的遮罩。

小块的数量为：image_size // (min_tile_size + 2 * padding)

提取图像小块

从图像中提取一部分。小块索引范围从 0 到小块总数，按列优先顺序排列（小块 1 通常位于小块 0 的下方）。

提取遮罩小块

与“提取图像小块”相同，但针对遮罩。

合并图像小块

将一个小块合并回完整图像，通常是在采样之后。根据填充和混合值，在相邻小块之间使用平滑过渡重叠区。

生成小块遮罩

为特定的小块创建覆盖遮罩。遮罩的大小与图像小块的尺寸一致。图像区域将显示为白色（1），填充区域显示为黑色（0），并根据所选的混合大小进行平滑过渡。

此遮罩由“合并图像小块”内部使用，但也可作为输入用于放大工作流中的“设置潜在噪声遮罩”。

其他节点

文本翻译

用于将字符串翻译成英语的节点。源语言通过一个格式为 lang:xx 的 语言指令 指定，其中 xx 是两位字母的语言代码。允许使用多个指令，这些指令会改变其后所有文本的语言，直到遇到下一个指令为止。lang:en（默认值）会原样传递文本片段。此功能对关键字、标签等非常有用。

示例：

输入	输出
lang:de eine modische handtasche aus grünem kunstleder	一款时尚的绿色人造革手提包
origami paperwork, lang:zh 狐狸和鹤, lang:en mountain view	折纸文件，狐狸与鹤，山景

翻译完全在本地进行，由 argosopentech/argos-translate 提供支持：

• 可通过 pip install argostranslate 或 pip install -r requirements.txt 进行安装。
• 模型会在首次使用时自动下载。

此外，还有一个 翻译 API，可在工具 UI 中提供即时反馈。

不适宜内容过滤器

使用 Safety-Checker 检测图像中是否存在不适宜内容。未通过检测的图像会被模糊处理以隐藏内容。模型会在首次使用时下载。

输入：图像和敏感度级别（0.5 仅针对明确的成人内容，0.7 及以上则包括部分裸露内容）。

重要提示： 此过滤器并不完美，仍有可能漏过一些成人内容。

API 扩展

GET /api/etn/model_info/{folder_name}

可以加载的模型类型多种多样，如检查点、LoRA、ControlNet 等，但它们不能互换使用。此端点有助于对这些模型进行分类和筛选。

参数

• folder_name: ComfyUI 模型文件夹中的子目录。 支持的模型类型：checkpoints、diffusion_models、unet、unet_gguf
• limit=n:（查询参数，可选）检查前 n 个模型。
• offset=i:（查询参数，可选）从第 i 个模型开始检查。

输出

列出可用模型，并附带额外的分类信息：

{
    "checkpoint_file.safetensors": {
        "base_model": "sd15",
        "is_inpaint": false,
        "type": "eps"
    },
    ...
}

基础模型的可能取值：sd15, sd20, sd21, sd3, sdxl, sdxl-refiner, ssd1b, svd, cascade-b, cascade-c, aura-flow, hunyuan-dit, flux, flux-schnell, flux2, lumina2, z-image, chroma, qwen-image

如果基础模型是 sdxl，则 type 属性的取值为：eps, edm, v-prediction, v-prediction-edm

检测还支持量化模型：

• GGUF：如果已安装 gguf 模块，则会检测 .gguf 文件，并设置 quant 字段。
• Nunchaku：SVDQuant 模型会被检测到，并将 quant 字段设置为 svdq。

对于格式未知或不符合任何已知基础模型的文件，会返回条目 {"base_model": "unknown"}。

分页

通过 limit 和 offset 查询参数，每次请求可以检查一部分模型。通常检查速度很快（只需查看模型头信息），但在某些情况下可能会因杀毒软件或硬盘速度较慢而变慢。

GET /api/etn/model_info/checkpoints?limit=10&offset=20

这将最多返回 10 个模型，从列表中的第 20 个模型开始。输出 JSON 中还会包含一个特殊的 _meta 条目：

{
    "checkpoint_20.safetensors": { ... },
    "_meta": { "offset": 20, "count": 1, "total": 21 }
}

GET /api/etn/languages

返回可用于翻译的语言列表。

[
    { "name": "英语", "code": "en" },
    { ... }
]

GET /api/etn/translate/{lang}/{text}

将 text 翻译成英语。lang 是一个两位字母的代码，表示要翻译的源语言。text 中也可以包含 语言指令，以便只翻译其中的部分内容。详情请参阅 节点文档。

• 输出：JSON 字符串。
• 示例：/api/etn/translate/de/eine%20modische%20Handtasche -> "a fashionable handbag"

PUT /api/etn/upload/{folder_name}/{filename}

将模型上传到 ComfyUI 的本地模型文件夹。

参数

• folder_name: 模型类型。必须与 ComfyUI 模型文件夹中现有的某个文件夹匹配。
• filename: 模型的目标文件名。不得包含任何（绝对或相对）路径。扩展名必须是 .safetensors。

输出

• 上传成功后返回状态码 201 和 { "status": "success" }。
• 如果文件已存在，则返回状态码 200 和 { "status": "cached" }。
• 如果参数无效，则返回状态码 400 和 { "error": "..." }。

安装

下载仓库并解压到 ComfyUI 安装目录下的 custom_nodes 文件夹中。

或者直接从 ComfyUI 安装目录克隆：

cd custom_nodes
git clone https://github.com/Acly/comfyui-tooling-nodes.git

重启 ComfyUI 后，节点即可正常使用。

ComfyUI Tooling Nodes 快速上手指南

comfyui-tooling-nodes 是一套专为将 ComfyUI 作为外部工具后端而设计的节点集。它提供了基于 Base64/内存的图像传输、区域注意力掩码（Region Attention Masking）、分块处理以及模型信息检索 API 等功能，旨在解决传统文件系统交互的痛点并提升工作流灵活性。

环境准备

• 系统要求：已安装 Python 3.8+ 的 Windows/Linux/macOS 系统。
• 前置依赖：
  • 已正常运行的 ComfyUI 主程序。
  • Git（推荐用于安装）。
  • 可选依赖：若需使用“文本翻译”节点，需安装 argos-translate 库。

安装步骤

1. 克隆仓库

进入 ComfyUI 安装目录下的 custom_nodes 文件夹，执行以下命令：

cd custom_nodes
git clone https://github.com/Acly/comfyui-tooling-nodes.git

提示：国内用户若访问 GitHub 较慢，可尝试使用镜像源或手动下载 ZIP 包解压至该目录。

2. 安装可选依赖（仅翻译功能需要）

如果您计划使用内置的本地文本翻译节点，请进入插件目录并安装依赖：

cd comfyui-tooling-nodes
pip install argostranslate
# 或者
pip install -r requirements.txt

注：翻译模型会在首次使用时自动下载。

3. 重启 ComfyUI

安装完成后，完全重启 ComfyUI 服务，新节点即可在界面中使用。

基本使用

本插件核心解决了图像传输效率和精细化控制问题，以下是三个最常用场景的快速示例：

场景一：高效图像输入输出（避免磁盘 IO）

传统方式需上传文件再读取，本插件支持直接通过内存或 WebSocket 传输。

1. 加载图像：
   • 使用 Load Image (Base64) 节点：直接将前端生成的 Base64 字符串传入，无需保存临时文件。
   • 或使用 Load Image from Cache 节点：先通过 HTTP PUT 请求将图片字节流发送至 /api/etn/image/{id}，然后在节点中填入对应的 {id} 即可从内存加载。
2. 输出图像：
   • 使用 Send Image (WebSocket)：直接将生成结果通过 WebSocket 二进制流推送到客户端。
   • 或使用 Save Image to Cache：将结果暂存内存，并通过返回的 JSON 获取图片 ID，随后通过 HTTP GET /api/etn/image/{id} 高速下载。

场景二：区域注意力控制 (Regions)

实现“局部重绘”或“多区域不同提示词”，比传统蒙版更自然。

1. 添加 Background Region 节点：设置全局背景的描述提示词（Prompt）。
2. 添加 Define Region 节点：
   • 连接上一步的背景区域列表。
   • 输入特定的 Mask（蒙版）和该区域专属的 Prompt。
   • 可串联多个 Define Region 以定义多个不同区域。
3. 添加 Regions Attention Mask 节点：
   • 连接最终的区域列表。
   • 将该节点的输出连接到采样器（Sampler）的 positive 条件输入端，替代原有的普通 Prompt 输入。

场景三：大图分块处理 (Tiles)

用于节省显存或加速高分辨率生成。

1. 使用 Create Tile Layout：设定最小瓦片尺寸 (min_tile_size)、重叠填充 (padding) 和融合系数 (blending)。
2. 使用 Extract Image Tile：根据布局将原图切割为单个瓦片。
3. 独立处理：对每个瓦片运行独立的生成工作流（可配合不同的 Prompt 或 ControlNet）。
4. 使用 Merge Image Tile：将处理后的瓦片重新拼合，自动处理边缘融合，消除接缝。

附加功能：API 模型探测

外部工具可通过 HTTP 请求获取模型详细信息，以便动态构建下拉菜单：

GET /api/etn/model_info/checkpoints?limit=10&offset=0

返回 JSON 包含模型类型（如 sd15, sdxl, flux）、是否为重绘模型等元数据，便于程序化筛选。