ComfyUI-Roundabout

一个 ComfyUI custom node：把本地工作流包装成 OpenAI 兼容 REST API + MCP 工具（14 个），让 AI agent / 脚本 / 任意 OpenAI 客户端直接调用你本机的图像与视频生成。

不碰画布、不改代码。 你在 ComfyUI 里搭好的流程，导出一个 JSON、在 models.yaml 写一段参数映射，就变成了一个可被任意客户端调用的 model。

不止是「把 ComfyUI 接到 MCP 上」。大模型工作流的显存分块、分辨率档位、注意力档位这些「跟着硬件和目标变的经验值」都不写进工作流 JSON，而由网关在渲染前代入 —— 换张卡、换个分辨率，工作流 JSON 一个字都不用改。只是「配置化」的深浅不同：分块档位在 models.yaml（改 YAML 热加载即生效），分辨率与注意力档位的取值是 gateway/params.py 里的常量（改了要重启）。

设计目的

1. 让 ComfyUI 成为 agent 的 AIGC 后端

ComfyUI 已经有模型、显存和队列，缺的只是一层 agent 能听懂的接口。Roundabout 把它包成 OpenAI 兼容 REST（base_url 指过来即可，任何 OpenAI SDK / 客户端零改动接入）和 MCP 服务（agent 直接调工具）。本地算力因此变成一个私有、按次调用不计费的图像 / 视频后端。

2. 嵌入 ComfyUI，无需额外维护

它是一个 custom node，不是一套要单独部署的服务：

• 随 ComfyUI 启动自动加载、随 ComfyUI 退出而结束，没有独立进程

• MCP 端点挂在 ComfyUI 自己的端口（/mcp），不额外占端口

• 复用 ComfyUI 的 Python 解释器与依赖（纯 REST 场景零新增依赖）

• 配置只有 models.yaml（模型）与 .env（可选）两个文件，改完热加载；模型专属参数可在 models.yaml 的 params: 块声明式注册（type/min/max/default/bind 全数据驱动，声明即免 KNOWN_PARAMS 白名单、bind/default 自动并入、tool-info 元数据取自声明，v1.43.0）；本机专属模型与本机微调写 models.local.yaml（gitignored，合并语义见 models.local.yaml.example，上游更新不覆盖，v1.44.0）；另有一个可选的 device_weights.yaml（机器本地权重覆盖，gitignored，见下方多机部署）

没有 docker、没有守护进程、没有第二份 registry 要同步。

3. 不把 workflow 交给 agent，精准传参省 token

agent 全程看不到也用不着工作流 JSON。它只传语义参数，节点字段的写入由网关在本地按 models.yaml 的映射完成。

本仓库自带工作流的实测体积（按 字符÷3 粗估 token）：

对应的 Roundabout 调用：

{"model":"qwen-image-2.1","prompt":"一只戴宇航头盔的柴犬","size":"1024x1024"}

约 30 tokens —— 单次生成请求携带的载荷差 40~90 倍，且工作流越复杂（视频、多参考图）差距越大。

4. 硬件与画质经验值下沉到配置层，换机器不换工作流

同一份工作流 JSON，在 8 GiB 笔记本卡和 24 GiB 台式卡上最合适的分块参数差好几倍。这些值写死在 JSON 里，换机器就得改图。Roundabout 把它们从工作流里提出来，由网关在渲染前代入：

第一行改 YAML、热加载即生效；后两行是代码常量，改了要重启 ComfyUI。三者都不进工作流 JSON—— 工作流永远只有一份模板。细节见按显卡自动调参。

Related MCP server: ComfyUI MCP Hub

文档分工

配套 skills

本仓库的三份文档是给人读的；配套 skill 是同一套知识的给 agent 读版本 —— 把调用姿势、注册流程、权重坑位压成 agent 能直接加载的操作手册。装了 skill 的 agent 不必先通读文档，也不会照着过期印象乱传参。

装法就是把这个目录放进 agent 的 skills 目录（目录名与 skill 的 name 保持一致）：

git clone https://github.com/HJH-AILab/roundabout-skill.git <agent 的 skills 目录>/roundabout
git clone https://github.com/HJH-AILab/h3-playbook-skill.git <agent 的 skills 目录>/h3-playbook
git clone https://github.com/HJH-AILab/qwen-image2.1-prompt-writing-skill.git <agent 的 skills 目录>/qwen-image-prompt-writing

一句话安装（把这句丢给 agent 即可，装在哪、怎么落位由它按自家约定处理）：

安装这个skill https://github.com/HJH-AILab/roundabout-skill
安装这个skill https://github.com/HJH-AILab/h3-playbook-skill
安装这个skill https://github.com/HJH-AILab/qwen-image2.1-prompt-writing-skill

三份都由本仓库维护（MCP get_skills 里标 source="roundabout"）。 H3 官方写作指南（原 h3-prompt-writing）已于 playbook v2.0.0 并入 h3-playbook（含其 2026-08-11 Tips 更新；references/base-en.txt / ref-en.txt 为官方原文逐字节拷贝）， 不再作为独立 skill 推荐安装——官方仓库更新时可 diff 后同步进 playbook。 都按「先自己探、探不到再问」的方式取 ComfyUI 路径与端口，不含硬编的内网地址，换机器可直接用。 边界互不重叠：roundabout 只管网关这一侧（怎么调用、怎么注册、怎么排障）；剩余两份只管模型侧（H3 一份、Qwen-Image-2.1 一份）。

功能

两套接入层，共享同一个引擎

• OpenAI 兼容 REST：/v1/images/generations（文生图 / 图生图）、/v1/images/edits（multipart 标准编辑）、/v1/images/remove-background（去背景）、/v1/videos/generations（视频，支持异步）。返回格式可选 b64_json / url / file / path，可直接替换 OpenAI 官方地址使用。

• MCP 服务（19 个工具）：生成类 generate_image / edit_image / remove_background / process_image / generate_speech / generate_video，查询类 get_tool_info / list_models / get_task / cancel_task / queue_status / get_workflow / health / check_weights，运维类 reload / get_view_url / get_skills / manage_workflows，看板类 view_board（单入口按 action 分发：pin / remove / clear / get / history / load）。agent 用一组工具就能完成「查模型 → 体检权重 → 生成 → 跟踪进度 → 钉到看板」全流程。

• 共享端口：MCP 端点 /mcp 直接挂在 ComfyUI 同一端口（http://<comfyui>:8188/mcp），不用额外开端口、不用另起进程；REST 与 MCP 共用同一份注册表、生成链路与任务表。

声明式模型注册

• models.yaml 登记模型：工作流文件 + 参数绑定路径 + 默认值 + 别名 + 能力（文生图 / 图生图 / 视频）。

• 新增、修改模型只改 YAML，POST /admin/reload 热加载，不用重启 ComfyUI、不用写代码。

• 内置 15 个开箱可用的工作流（8 图像 + 6 视频 + 1 工具），也全部可以作为你写映射时的参照。

按机器自适应

• 显存自适应（vram_adaptive）：启动时探测显存，自动为 H3 系列选取分块档位，8 / 12 / 24 GiB 卡共用同一份工作流。

• 分块参数可在单次请求里显式覆盖，改档表不用动代码。

看得见、管得了

• 可视化页面 http://<comfyui>:8188/roundabout/view：顶部 Output / Input / 看板 三个标签页，浏览 input/ output/ 资源（缩略图分批懒加载、自适应分页、产物自动同步、视频格带播放角标），右下角悬浮任务面板实时显示 ComfyUI 队列 + 网关任务表，产物一键弹层预览。

• 任务看板：页面里的一个标签页，一块铺满视口的无限画布，agent 把产出钉上去并按语义排布（分镜顺序 / A/B 对照 / 按角色分组），用户一眼看全；钉进来的目录会变成可点的目录卡（一下跳到该目录），落在 input/ output/ 之外的产物变成标着「外部」的外部卡（点它先确认，再交给系统文件管理器打开 —— 仅本机访问时有效）；清空即归档进历史，随时只读回看或删掉某一份 —— 回看时若想把某份变回当前看板，点「用这份替换当前看板」（先确认，当前内容会自动归档）；agent 侧读当前板上有什么用 get_view_board（顺带回最近几轮归档的摘要与内容指纹 kinds/preview/models）、续接某一轮用 load_view_board（拿到用户复制的 ID 直接载，不给 ID 就是最近一轮）；一次钉多张走 items 数组 —— 一次往返、一次落盘，且严格按数组顺序排布；历史里每一份都能「复制 ID」 —— 用户把这串 ID 粘给 agent，就等于指定了续接哪一轮（agent 不必先扫一遍历史列表去猜），没给名字的归档由后端按内容自动命名（如「7 张 · image/text · 10:24」）。

• ComfyUI 内管理面板：菜单「Roundabout」提供工作流管理（上传 / 校验 / 删除）、模型配置（结构化编辑）、队列监控（含 seed，便于区分批量提交）。

• 任务留痕：同步与异步生成都记一条（状态 / 耗时 / seed / 产物地址），终态记录保留 6 小时。

安装

方式一 · 用 ComfyUI-Manager 从 Git URL 安装（推荐）——装好 ComfyUI-Manager 后，打开 Custom Nodes Manager，右上角菜单选 Install via Git URL，填入：

https://github.com/HJH-AILab/ComfyUI-Roundabout

装完点 Restart。节点包已按 Comfy Registry 规范声明元数据（pyproject.toml），ComfyUI-Manager 能从中识别名称与版本；因为是 git 仓库，之后也可以直接在 Manager 里检查/拉取更新。

本仓库未发布到 Comfy Registry，所以搜索框里搜不到、也没有 comfy node install 这条命令，请走上面的 Git URL 安装。

方式二 · 手动克隆：

1. 放进 ComfyUI 的 custom_nodes/ 目录：

   cd ComfyUI/custom_nodes
   git clone https://github.com/HJH-AILab/ComfyUI-Roundabout.git

2. 安装依赖 —— MCP 网关默认开启，所以默认需要这一步：

   <ComfyUI>/python/python.exe -m pip install -r custom_nodes/ComfyUI-Roundabout/requirements.txt
   # 即 mcp>=2.0.0（必须 2.x，1.x 的 FastMCP API 不兼容） + uvicorn>=0.30.0

   只要 REST、不要 MCP：在 .env 写 MCP_ENABLED=false，这两个包可以不装。

3. 配置（可选）：把 .env.example 复制成 .env，按需修改。MCP 默认已启用，不用额外设置；要关掉就把 MCP_ENABLED 改成 false。

4. 准备模型权重：仓库不含权重。内置 11 个工作流共引用 18 个权重文件（清单另列 9 个非内置引用的参考项，共 27 行 / 约 165 GB），全部来自 HuggingFace 上的 Comfy-Org 等官方仓库，逐条的下载命令与存放目录见下方权重清单。只想跑图像档的话约 49 GB，可以先只下这一族。

   视频档还需要四个第三方节点包：KJNodes（MiniMaxChunkFeedForward，视频档全用）、ComfyUI-Spark-H3（四支视频档的稀疏注意力，须按显卡架构下发布包）、ComfyUI-VPack（edit 两支的 vpack_ratio）、comfyui-SelfLift（lift 两支的 latent 上采样节点 SelfLiftH3LatentLift）。安装命令与自检见下方第三方节点依赖。

5. 重启 ComfyUI。启动日志出现 OpenAI gateway routes registered ... models=... 即成功。

使用方式

1. ComfyUI 面板（人在 ComfyUI 里操作）

菜单栏 Roundabout →

2. REST 接口（脚本 / OpenAI 客户端）

下面是四个最常用的最小示例；完整字段表、响应结构与错误码见 API.md。

文生图

curl -X POST http://127.0.0.1:8188/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-2.1","prompt":"一只戴宇航头盔的柴犬，赛博朋克霓虹灯背景","size":"1024x1024","response_format":"path"}'

编辑图片（换背景 / 换材质 / 图内写字）

curl -X POST http://127.0.0.1:8188/v1/images/edits \
  -F model=flux2-klein-image-edit-turbo \
  -F 'prompt=把背景换成星空，保留主体不变' \
  -F response_format=path \
  -F image=@input/source.png

去背景（透明 PNG，无需提示词）

curl -X POST http://127.0.0.1:8188/v1/images/remove-background \
  -F image=@input/source.png -F response_format=path

视频（长任务建议异步，再轮询任务）

# 提交
curl -X POST http://127.0.0.1:8188/v1/videos/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3","size":"576p-16:9","steps":8,"prompt":"a cat walking in rain","duration":5,"background":"pending"}'
# 查结果（id 来自上一步返回）
curl http://127.0.0.1:8188/v1/videos/tasks/<id>

size 支持档位预设 <tier>p-<ratio>：tier ∈ 480p / 576p / 720p / 768p / 1080p / 1440p，ratio ∈ 1:1 / 3:4 / 4:3 / 16:9 / 9:16（如 768p-16:9 = 1360×768、1080p-16:9 = 1920×1088、1440p-16:9 = 2560×1440）；也接受反向写法 <ratio>@<tier>p（如 9:16@768p）与直接 WxH。不传或 auto 用模型默认。

⚠️ 1440p 是大显存档（2560×1440 ≈ 768p 的 3.6 倍像素）：8GB 卡直接生跑不动，要更大画面请优先走 minimax-h3-lift（768p 画布 × 1.875 = 2528×1440）。

3. MCP（给 agent 用）

MCP 默认启用——装好依赖、重启 ComfyUI，端点就在 http://<comfyui>:8188/mcp，无需任何配置。

Streamable HTTP（推荐，走 ComfyUI 同端口，无独立进程）：

{
  "mcpServers": {
    "comfyui-roundabout": {
      "type": "streamable_http",
      "url": "http://127.0.0.1:8188/mcp"
    }
  }
}

stdio（由 MCP 客户端拉起进程，适合不支持 HTTP 的客户端）：

{
  "mcpServers": {
    "comfyui-roundabout": {
      "command": "<ComfyUI>/python/python.exe",
      "args": ["<ComfyUI>/custom_nodes/ComfyUI-Roundabout/mcp_server.py"]
    }
  }
}

URL 里的主机端口 = 你访问 ComfyUI 的地址，路径固定 /mcp。远程访问换成 http://192.168.1.10:8188/mcp 即可，其余不变。 工具参数、完成推送（notifications/message，需显式 MCP_STATELESS=false）与助手侧注意事项见 API.md §7。

agent 典型流程：list_models 看有什么 → generate_image / generate_video 生成 → 异步任务用 get_task 轮询（默认无状态模式；设了 MCP_STATELESS=false 才可等服务端推送）→ 产物地址交给用户 → get_view_url 给出可视化页面。

agent 侧的操作手册（调用姿势、注册与下档、权重坑位、排障）见上方配套 skills —— 装了 skill 的 agent 不必通读本仓库文档。

4. 可视化页面

浏览器打开 http://<comfyui>:8188/roundabout/view（MCP 工具 get_view_url 也会返回这个地址）：

• 浏览 input/ 与 output/（按修改时间倒序、自适应分页、缩略图分批懒加载）

• 有新产物自动提示刷新，不打断你正在看的图

• 右下角「任务进度」悬浮面板：ComfyUI 队列 + 网关任务 + 一键查看产物

内置模型

默认 default_model = qwen-image-2.1-turbo（8 步，默认画布 2048×2048）。model 可传注册名或任一别名（不区分大小写）；不传则用默认模型。

• 编辑类模型必须传图：单图模型传 image；多图模型（flux2-klein-image-edit-turbo 4 张 / qwen-image-2.1 6 张）传 reference_images 按序喂槽，单图也可以直接传 image（等价第 1 张）。输出尺寸跟随输入图（klein 缩放到 1MP；qwen 按官方默认不做重采样，直接跟随第 1 张参考图），此时 size 不生效 —— qwen-image-2.1 是文生与编辑同一支，一张参考图都不传就是纯文生，那一支才用 size。

• 给文生图模型传 image 会被拒绝，错误信息里会列出所有支持输入图的模型名。

• 别名与绑定路径见 models.yaml 与 API.md §5.5。

权重清单（内置工作流的全部依赖）

本仓库不包含任何权重文件（体积与许可原因）。内置的 11 个工作流共引用 18 个权重文件，合计约 105 GB（图像档约 49 GB / 视频档约 56 GB）；下面两张清单表共 27 行，另 9 行是当前无内置工作流引用的参考项（2 个旧底模、1 个 w6a8 hybrid、2 个 Acc LoRA、1 个 hyperflow LoRA、2 个旧版 turbo LoRA、1 个 4 步 v1.3），仅作参考，计入则约 165 GB。缺文件时报错形如 value not in list: <字段>: <文件名> —— 网关会把这条报错改写成可执行的下载指引（该文件放哪个目录、curl 命令是什么），agent 收到即可照做；也可以主动体检当前缺哪些：GET /roundabout/admin/weights，或 MCP 工具 check_weights（只读、不占 GPU）。逐条来源即下方清单，同源数据在 weights.yaml，由网关与体检读取。（workflows/example_txt2img.json 是接入样本，用你自己的 checkpoint，不计入上列统计。）

这些文件基本都在 HuggingFace 的 Comfy-Org 官方仓库里（少数为模型原厂或社区仓库，已在表中标注）。国区建议把端点换成镜像，repo ID 与 repo 内路径完全一致：

set HF_ENDPOINT=https://hf-mirror.com          # Windows
export HF_ENDPOINT=https://hf-mirror.com       # Linux / macOS

⚠ 只有一个文件必须下载后改名（最常见的卡点）：

上游文件名	本仓库工作流引用的名字
minimax_h3_latent_upscaler_3d_conv_v1_fp16.safetensors	minimax_h3_latent_upscaler_3d_fp16.safetensors（去掉 _conv_v1）

其余文件的下载名 = 使用名，下完直接放进目标目录即可。

目录速查

所有权重放进 <ComfyUI>/models/ 下对应子目录（models/ 就是 ComfyUI 根目录下那个）：

图像档（11 个文件，约 49 GB）

几个共用 / 易混点：

• qwen3vl_8b_fp8_scaled.safetensors 由 flux2-klein-image-edit-turbo 使用。

• flux-2-klein-9b-kv-fp8.safetensors 来自 Black Forest Labs 官方仓库（不在 Comfy-Org）；Comfy-Org 只提供了它的 VAE 与文本编码器仓库（vae-text-encorder-for-flux-klein-9b，官方拼写如此）。

• Qwen-Image 2.1 的文本编码器是 qwen3vl_8b_int8_convrot.safetensors，与 klein 用的 qwen3vl_8b_fp8_scaled.safetensors 同名不同文件、不同仓库，别互相顶替 —— 跑哪支就下哪支。同仓库里另有 qwen3.5_9b_qwen_image_2.1_pe_t2i.int8_convrot.safetensors / ..._pe_i2i... 一路「PE」编码器，内置工作流不用它。

• 想省显存可以换更小的量化版（nvfp4 / pruned_int8_convrot 等，同仓库同目录下有），但要同步改工作流 JSON 里的文件名。

视频档（16 行：7 个内置引用 + 9 个参考项，约 56 GB）

视频档的三个坑：

• minimax_h3_hyperflow_8step_v1.0_comfyui_bf16.safetensors 是社区转换版（原始版在 videorebirth/hyperflow，文件名 minimax_h3_hyperflow_8step_v1.0.safetensors，无 _comfyui_bf16 后缀）。转换版在重映射 key 时把端点适配器 endpoint_time_embedder.* 并进了 time_embedder.proj_in/proj_out，本机实测端点条件进不了模型（画面出现非单段式晕开）—— 想用完整效果需上游原版 + 专用节点包 Addis-Pulse-Studio/ComfyUI-HyperFlow。内置工作流目前挂的是转换版。

• Acc LoRA 是 diffusers 命名，普通加载器挂不上（详见内置模型里 minimax-h3-turbo 那行）。若要真正加速，改用 ComfyUI 命名的转换版：内置工作流挂的是 lightx2v/Minimax-h3-Turbo 的 minimax_h3_fl2v_turbo_8step_v1.1_768p_comfyui_bf16.safetensors（768p，video_shift=6）。

一键下载

在 ComfyUI 根目录执行（models/ 就在当前目录下）。按族分组，只下你要用的族即可。仓库内路径与 HF 一致；hf-mirror 之外，ModelScope 也可作备用源（同一份仓库，把 $B/<repo>/resolve/main/<路径> 换成 https://modelscope.cn/models/<repo>/resolve/master/<路径> 即可）。

B=https://hf-mirror.com          # 走官方就换成 https://huggingface.co

# ---------- FLUX.2 Klein 图像编辑 + BiRefNet 抠图（约 11 GB）----------
curl -L -o models/diffusion_models/flux-2-klein-9b-kv-fp8.safetensors \
  $B/black-forest-labs/FLUX.2-klein-9b-kv-fp8/resolve/main/flux-2-klein-9b-kv-fp8.safetensors
curl -L -o models/vae/flux2-vae.safetensors \
  $B/Comfy-Org/vae-text-encorder-for-flux-klein-9b/resolve/main/split_files/vae/flux2-vae.safetensors
curl -L -o models/background_removal/birefnet.safetensors \
  $B/Comfy-Org/BiRefNet/resolve/main/background_removal/birefnet.safetensors

# ---------- Qwen-Image 2.1（文生图 + 多图编辑，约 17 GB）----------
curl -L -o models/diffusion_models/qwen_image_2.1_int8_convrot.safetensors \
  $B/Comfy-Org/Qwen-Image-2.1/resolve/main/diffusion_models/qwen_image_2.1_int8_convrot.safetensors
curl -L -o models/text_encoders/qwen3vl_8b_int8_convrot.safetensors \
  $B/Comfy-Org/Qwen-Image-2.1/resolve/main/text_encoders/qwen3vl_8b_int8_convrot.safetensors
curl -L -o models/vae/qwen_image_2.1_vae_bf16.safetensors \
  $B/Comfy-Org/Qwen-Image-2.1/resolve/main/vae/qwen_image_2.1_vae_bf16.safetensors
curl -L -o models/loras/qwen_image_2.1_turbo_lora_avg_rank_178_bf16.safetensors \
  $B/Comfy-Org/Qwen-Image-2.1/resolve/main/loras/qwen_image_2.1_turbo_lora_avg_rank_178_bf16.safetensors

# ---------- MiniMax H3 共用主干（H3 全系都要，约 81 GB）----------
curl -L -o models/diffusion_models/minimax_h3_fl2va_pruned_w6a8.safetensors \
  $B/Comfy-Org/MiniMax-H3/resolve/main/diffusion_models/minimax_h3_fl2va_pruned_w6a8.safetensors
curl -L -o models/diffusion_models/minimax_h3_ref2va_pruned_w6a8.safetensors \
  $B/Comfy-Org/MiniMax-H3/resolve/main/diffusion_models/minimax_h3_ref2va_pruned_w6a8.safetensors
curl -L -o models/text_encoders/qwen3vl_32b_minimax_h3_int8_convrot.safetensors \
  $B/Comfy-Org/MiniMax-H3/resolve/main/text_encoders/qwen3vl_32b_minimax_h3_int8_convrot.safetensors
curl -L -o models/vae/minimax_h3_video_vae_int8_convrot.safetensors \
  $B/Comfy-Org/MiniMax-H3/resolve/main/vae/minimax_h3_video_vae_int8_convrot.safetensors
curl -L -o models/vae/minimax_h3_audio_vae_fp32.safetensors \
  $B/Comfy-Org/MiniMax-H3/resolve/main/vae/minimax_h3_audio_vae_fp32.safetensors

# ---------- 视频档专用（按需选，全选约 30 GB）----------
# turbo 两支的 Acc LoRA
curl -L -o models/loras/MiniMax-H3-FL2VA-Acc-8Step.safetensors \
  $B/alibaba-pai/MiniMax-H3-Acc-LoRAs/resolve/main/MiniMax-H3-FL2VA-Acc-8Step.safetensors
curl -L -o models/loras/MiniMax-H3-Ref2VA-Acc-8Step.safetensors \
  $B/alibaba-pai/MiniMax-H3-Acc-LoRAs/resolve/main/MiniMax-H3-Ref2VA-Acc-8Step.safetensors
# SelfLift 上采样权重（下完改名）
curl -L -o models/latent_upscale_models/minimax_h3_latent_upscaler_3d_fp16.safetensors \
  $B/LBH-123-AI/Minimax_h3_latent_Upscaler/resolve/main/minimax_h3_latent_upscaler_3d_conv_v1/minimax_h3_latent_upscaler_3d_conv_v1_fp16.safetensors

嫌 curl 麻烦也可以用 HuggingFace CLI（pip install -U huggingface_hub）：

hf download Comfy-Org/MiniMax-H3 diffusion_models/minimax_h3_fl2va_pruned_w6a8.safetensors \
  --local-dir models

注意它会保留仓库内的目录结构（Comfy-Org 的 split_files/ 前缀不是 ComfyUI 的目录），下完还得手动挪到上表的目标位置 —— 所以这里默认给 curl。

工作流 → 权重对照

第三方节点依赖

这些工作流用到的节点绝大多数来自 ComfyUI 核心（comfy_extras/），ComfyUI 版本太老会缺 MiniMaxH3UnifiedToVideo（Roundabout 自带，随包加载）/ LoadBackgroundRemovalModel / Flux2Scheduler / TextEncodeQwenImage21 等节点。视频档另有四个第三方包，按档位装 —— 只跑图像档的话一个都不用：

Spark-H3：按显卡架构下发布包，别用 clone 顶替

Spark-H3 依赖打了 Spark 补丁的 comfy-kitchen。git clone 只拿到节点代码、拿不到那个 wheel，采样时才报缺 kernel，所以走发布包：

1. 打开 releases/tag/comfyui-v0.1.5，按显卡挑 zip —— 文件名里的 sm 号必须对上（cu130 要求 torch.version.cuda >= 13.0）：

   GPU	Windows 包名
   RTX 30 系 · SM86	ComfyUI-Spark-H3-0.1.5-windows-x86_64-sm86-cu130.zip
   RTX 40 系 · SM89	ComfyUI-Spark-H3-0.1.5-windows-x86_64-sm89-cu130.zip
   RTX 50 系 · SM120	ComfyUI-Spark-H3-0.1.5-windows-x86_64-sm120-cu130.zip

   Linux 把 windows 换成 linux。

2. 先完全关掉 ComfyUI，再解压到 custom_nodes/。层级必须是 custom_nodes/ComfyUI-Spark-H3/install.py；套成两层同名目录（ComfyUI-Spark-H3/ComfyUI-Spark-H3/）会装不上。

3. 用启动 ComfyUI 的那个 python 执行安装器（不是双击、也不是系统 python），它会挑匹配架构的 kitchen wheel 装进去：

   "<ComfyUI>/python/python.exe" custom_nodes/ComfyUI-Spark-H3/install.py

4. 自检三条：pip show comfy-kitchen 的版本串必须带 +spark.h3.<架构>（如 RTX 3070Ti / SM86 是 0.2.40+spark.h3.sm86.cu130.1）；且版本号 ≥ 0.2.37 —— 安装器按 ComfyUI 版本挑 wheel，可能挑到包内的 0.2.36，那个版本叠 LoRA patch 会崩（见下方版本下限那条），低了就用 pip install --force-reinstall 换成 0.2.37 以上、同架构的 wheel；启动日志里对应架构的 Spark 节点注册成功。架构对不上时节点会硬校验 capability 后报错，不是静默降级。

其余三个直接 clone（VPack 无额外 pip 依赖）：

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-KJNodes.git
git clone https://github.com/zechengtang/VPack.git
git clone https://github.com/0c0/comfyui-SelfLift.git

换卡部署时节点类型名带算力后缀（MiniMaxH3SparkAttentionSM86 / SM89 / SM120），必须同步改工作流里的节点类型，否则加载即报错。manage_workflows 的 list/deploy 会顺带给出这条 hints。

⛔ 不要在视频档里接 KJNodes 的 MiniMaxLowVRAMAttention：它替换 block.forward，而 BlockSparseAttention 的 block patch 会无条件补传 attention= 关键字（comfy/ldm/minimax/model.py），签名对不上 ⇒ 实测 TypeError。两者硬互斥，因此 base 四支原先的 LowVRAM 节点已于 2026-09-21 撤除（head_chunks 档位值随之失去消费者，保留在表里仅为复原方便）。 稀疏节点的参数（tau / min_tokens / dense_blocks …）不在可注入白名单；其中 tau 的键名是 selection.tau（含点号），按 . 切分的路径解析寻址不到，要调只能改工作流 JSON 再 /admin/reload。但「更快 ↔ 更高质量」这一档有正式请求参数：attention（sparse 默认 / dense 关闭稀疏换致密画质）。落点：H3 四支全落 Spark 节点的 mode（sparse→fidelity，dense→dense，后者让节点完全旁路 Spark）。这一档只给 H3 四支（minimax-h3 / -edit / -lift / -lift-edit）；其它模型传 attention 会报 400。 全部视频档的 ModelAttentionBackend 统一用 comfy kitchen attention（comfy_kitchen 的 INT8 实现，省显存）。要换 pytorch attention 得改工作流模板里那个节点的值；它不在 bindings 白名单里，但可以用 workflow_overrides 在运行时点改（{"156.inputs.attention": "pytorch attention"}）—— workflow_overrides 是任意路径注入，与白名单无关。 ⚠️ comfy_kitchen 版本下限：>= 0.2.37。0.2.36 的 w4a8 反量化 kernel 有 stack-overflow 回归 —— 量化权重叠加 LoRA patch（turbo_lora）时采样第 2 步直接杀死进程（2026-10-08 实测 2/2 复现，0.2.37 修复）；0.2.35 及更早则不支持 ref2va 权重里的 K=8064 层（采样即报 ValueError: K=8064 must be divisible by 16…）。两端都不行的只有 0.2.36，钉住 0.2.37 或更高。 上述权重多为 int8_convrot 量化版，只在你已具备同名权重的机器上开箱即用；换成自己的模型时，同步改工作流 JSON 里的文件名即可。

接入自己的工作流

内置工作流只是样本，随时可以删。接入自己的流程 = 导出 API 格式 JSON + 在 models.yaml 写一段参数映射，支持热加载，不用改代码。

三步：

1. ComfyUI 画布 → Workflow → Export (API)（必须是 API 格式，不是普通 Export）→ 存进 workflows/

2. 在 models.yaml 加一条：workflow / mode / capabilities / output_node / bindings（接口参数 → 节点路径）。只想本机用、不进仓库就写到 models.local.yaml（gitignored，写法与 models.yaml 完全一致）

3. POST /admin/reload 或面板点「重新加载」，然后打一发接口验证

完整指南见 WORKFLOWS.md —— 参数白名单、常见落点表、找路径的方法、三条铁律（尤其：别绑被连线覆盖的 input）、models.yaml 全字段、references 段、排错表。

最小可跑参考样本：workflows/example_txt2img.json（CheckpointLoaderSimple + KSampler + SaveImage，把 ckpt_name 换成你自己的即可）。 另有三种落地路径（面板 / REST / Agent）的逐步说明。

配置

完整环境变量清单见 API.md §2.3，常用项：

多机部署：权重覆盖

同一份仓库跑在不同硬件上时，量化权重（w6a8 等）在免 offload 的大显存机器上有 dequant 每步税，反而比全量慢；低显存机器却必须用量化版。解法是把「选哪个权重文件」从仓库剥离到机器本地：

1. 复制 device_weights.example.yaml 为 device_weights.yaml（gitignored，不进仓库、不随 push 同步）；

2. 按本机硬件声明覆盖（如 4090 侧把 video_minimax_h3.json 节点 127 的 unet_name 换回全量 bf16）；

3. 重启或 /roundabout/admin/reload 生效，启动日志逐条回显 device override: ...。

同一套思路也覆盖模型登记表：本机专属模型与本机微调写 models.local.yaml（gitignored，见 models.local.yaml.example），上游更新 models.yaml 不会覆盖你的条目。

.safetensors 结尾的值会在 ComfyUI 模型目录里做存在性校验，缺失打启动告警（提交时 ComfyUI 侧仍会硬报错兜底）。不建这个文件 = 零覆盖，行为与单机部署完全一致。

按显卡自动调参（vram_adaptive）

大模型工作流（H3 一支的权重合计 ~65 GiB）靠节点级分块在显存吃紧的卡上跑，而分块参数的合适取值只取决于显存大小。在 models.yaml 给模型加一行 vram_adaptive: true，网关启动时探测本机显存，从 defaults.vram_tiers 取「min_gb 不超过本机显存」的最大一档，作为该模型分块参数的默认值：

defaults:
  vram_tiers:
    - min_gb: 24        # 24 ~ 31 GiB（32 GiB 及以上有单独的档）
      chunks: 2
      seq_threshold: 16384
      head_chunks: 8         # ← 当前无节点绑定（见第三方节点依赖节）
      highres_tiling: true   # ← 当前无节点绑定
    # ... 12 / 8 / 0 各档
models:
  minimax-h3-lift:
    vram_adaptive: true
    bindings:
      chunks: 158.inputs.chunks
      seq_threshold: 158.inputs.seq_threshold

• 优先级：档位值 < 模型自己写的 defaults < 请求参数（请求里传 chunks 等可按单次任务覆盖）。

• 探测不到显存（纯 CPU / 无 torch）时不覆盖，行为与不声明 vram_adaptive 一致。

• 档位表在 YAML 里，改档位不用动代码；ROUNDABOUT_VRAM_GB 可手动钉住。

同机跑多个 ComfyUI 实例

Roundabout 随 ComfyUI 进程启动，每个实例都有自己的 MCP 后端。如果想让端口可预期（防火墙放行、日志好认），用映射表把「ComfyUI 端口 → Roundabout 端口」一一对上：

MCP_PORT_MAP=[8188,888],[8189,999]

于是 --port 8188 的实例用 888、--port 8189 的实例用 999，互不干扰。不配映射也不会冲突（自动分配空闲端口），配了映射更可控；映射端口恰好被别的程序占用时会自动回落到空闲端口并在日志里告警，端点不会因此失效。

目录结构

ComfyUI-Roundabout/
├── __init__.py            # ComfyUI 节点入口（启动网关、加载模型）
├── mcp_server.py          # MCP 服务（18 工具）+ 共享端口嵌入启动
├── gateway/               # REST 网关
│   ├── config.py          # 配置（.env / 环境变量）
│   ├── registry.py        # models.yaml 解析、绑定校验、热加载
│   ├── pipeline.py        # 生成链路（参数校验 → 工作流渲染 → 提交 → 收集产物）
│   ├── handlers.py        # REST 端点
│   ├── routes.py          # 路由表
│   ├── admin.py           # 工作流 / 模型配置管理端点
│   ├── viewer.py          # 资源浏览与任务进度页面后端
│   ├── analyze.py         # 上传工作流时的参数映射自动分析
│   ├── tasks.py           # 任务表
│   ├── vram.py            # 显存探测 + 低显存分块档位选取（vram_adaptive）
│   ├── log_filters.py     # 把 aiohttp「客户端断开」的 ERROR 降级为 DEBUG
│   └── ...
├── web/                   # 前端（可视化看板页面）
├── workflows/             # API 格式工作流（example_txt2img.json 为接入样本）
├── models.yaml            # 模型注册表
├── models.local.yaml.example  # 本机模型登记扩展模板（复制为 models.local.yaml，gitignored、上游更新不覆盖）
├── weights.yaml           # 权重 → 下载来源索引（报错里的下载指引与体检的数据源）
├── pyproject.toml         # 节点包元数据（供 ComfyUI-Manager 等抓取识别）
├── requirements.txt       # mcp + uvicorn（MCP 默认启用故默认需要；关掉 MCP 可不装）
├── tests/                 # 冒烟连通性测试（run_tests.py 为入口；分发时由 .comfyignore 排除）
├── WORKFLOWS.md           # 接入自己的工作流
└── API.md                 # 完整接口文档

测试

仓库只保留冒烟连通性用例：服务起得来、MCP 工具注册齐、端点在、参数覆盖对，外加两支 踩过坑的轻量守卫（test_weights_index 锁 权重表一致性）。全部离线、用临时端口，不需要 ComfyUI 在跑。

<ComfyUI>/python/python.exe tests/run_tests.py                # 全部用例
<ComfyUI>/python/python.exe tests/run_tests.py --list         # 只列出将执行的文件
<ComfyUI>/python/python.exe tests/run_tests.py test_port_map.py   # 跑单个文件

许可

MIT