
来源:github · 原文链接:https://github.com/Comfy-Org/ComfyUI · 整理:github_bot · 发布时间:2026-10-21
一、项目概览
ComfyUI 由 Comfy-Org 维护,以 Python + PyTorch 实现,采用 GPL-3.0 许可。仓库创建于 2023 年 1 月,至今已积累 140k+ stars 与 16k+ forks——在扩散模型工具链这个更新极快的领域里,这样的体量基本等同于「事实标准」的另一种写法。它同时扮演三个角色:面向人的节点图 GUI、面向程序的 API 服务、以及真正干活的本地推理后端。
README 的定位句写得很克制也很准确:面向「要求掌控每个模型、每个参数、每个输出」的视觉专业人士。这句话实际上划出了它与一众「输入提示词、点击生成」型 WebUI 的分界线——ComfyUI 不隐藏复杂度,而是把复杂度结构化成一张可复用、可版本化、可序列化的图。项目保持周更节奏,主版本约每两周推进一次,桌面端、前端、核心三个仓库协同发布;这种工程纪律,是它能长期承载数百个第三方自定义节点生态的前提。
二、核心特性速览
| 能力维度 | 具体表现 |
|---|---|
| 编排方式 | 可视化节点图,无代码搭建图像、视频、音频、3D 与文本流程;支持可复用于图与模板 |
| 推理优化 | 异步权重流式加载,号称 4GB 显存 + 8GB 内存即可较快运行超大开源模型 |
| 执行策略 | 只执行输入完整的子图;只重执行相对上次发生变更的节点及其下游 |
| 显存管理 | 智能 VRAM/RAM 调度、模型卸载(offload)、量化模型支持 |
| 模型覆盖 | 原生支持 SD1.5/SDXL/SD3.5、Flux.1/Flux.2、Qwen Image、Wan 2.1/2.2、LTX-Video 等;伙伴节点接入闭源模型 |
| 交付形态 | 桌面应用、便携包、本地手动安装、Comfy Cloud、API 端点 |
| 离线保证 | 核心默认不下载任何内容,--offline 可彻底切断外部调用 |
这张表最值得注意的不是「支持多少模型」,而是执行策略那一行。绝大多数图形化 AI 工具把「点一次生成」当作一次全量重算,而 ComfyUI 从设计之初就把图当作有状态的增量计算单元——这决定了它在迭代调参场景下的效率上限远高于同类。
三、系统架构设计

整体可以按三层来读。交互与接口层由「节点画布」(Frontend UI)与「API 服务」(api_server)并列构成:前者是浏览器里那张可以缩放、分组、折叠的图画布,后者把同一张图暴露成 HTTP 端点,让工作流可以被外部程序以 JSON 形式驱动。二者共享同一套图语义——你在画布上拖出来的东西,和脚本提交的东西,本质上是同一个对象。这就是 ComfyUI 能被塞进生产管线的结构性原因:GUI 不是唯一的入口。
推理核心层以「推理引擎」(PyTorch)为中心,向下挂接两条关键支线:一是「显存调度」(VRAM manager),负责张量的驻留、换出与权重的异步流式加载;二是「离线与安全」(--offline),在引擎启动时决定是否允许访问外部服务。图中从画布与 API 分别指向核心的「提交工作流」「接口调用」两条边,说明执行请求在此汇合;核心到显存调度的「显存调度」边,则是整个系统性能表现的实际控制点——ComfyUI 的「快」,很大一部分来自这里而非算子本身。
能力与硬件层解决「拿什么算」。经离线校验后「装载节点」进入节点工具库(custom nodes),扩展出自定义算子与模型加载器;工具库再「读取权重」落到模型权重目录,extra_model_paths.yaml 允许把这些路径指向别的 UI 已有的模型库,避免重复下载几十 GB;最后「下发算力」到本地 GPU 后端,覆盖 NVIDIA、AMD、Intel、Apple Silicon、Ascend、MLU 等。另一条旁路是核心直连「云端模型」(Partner API),在本地算力不足或需要闭源模型时作为补充——它被刻意设计成可选旁路,而不是主链路,所以才能用开关一键关闭。
这种分层的价值在于:换硬件不动图,换模型不动图,接不接云也不动图。变更被约束在层内,工作流资产因此具备跨机器、跨年份的可迁移性。
四、核心流程或主循环

一次执行按如下路径推进:
- 载入工作流(JSON 图):工作流本质是一份 JSON,节点为顶点、连线为边,参数内嵌在节点属性里。它可以从文件读取,也可以从一张生成图像的元数据中还原。
- 输入校验(节点检查):引擎遍历图,只有「所有必需输入都已就绪」的节点才被纳入执行集合。缺模型、缺连线的分支会被安静地跳过,而不是抛错中断整张图。
- 入队排队(async queue):请求进入异步队列,前端可以连续提交多次而不会阻塞画布交互;队列与历史记录各有独立面板(快捷键
Q/H)。 - 子图执行(部分重执行):这是全流程的焦点步骤。引擎对比本次与上次的图状态,只执行发生变更的节点及其下游依赖。提交完全相同的图两次,第二次不会真正运行任何采样。
- 采样推理(sampler):实际的前向计算发生在这一步——文本编码、潜空间迭代去噪、VAE 解码,按模型族切换到对应的采样器与调度器。
- 输出还原(内嵌工作流):生成媒体落盘时写入种子与完整工作流,把 PNG 拖回画布即可复原当初的每一个参数。 中间的「工作流图状态」是枢纽:它既向缓存「写回缓存」(节点输出被记住,供下次比对复用),也向队列「更新队列」(新的执行计划据此生成)。这个设计的直接收益是,在「改一个提示词、重跑一遍」这种高频小步迭代里,省掉的往往是 90% 以上的重复计算。代价则是状态管理本身的复杂度——缓存失效判断一旦出错,表现就是「改了没生效」,这是排查这类引擎问题时的经典陷阱。
五、核心模块解析
| 模块 | 职责 |
|---|---|
comfy/samplers 与 comfy/k_diffusion | 采样器与噪声调度实现,各模型族的去噪循环入口 |
comfy/ldm、comfy/latent_formats | 各代扩散模型的结构定义与潜空间格式适配 |
comfy/controlnet.py、comfy/conds.py | ControlNet、条件张量的组织与注入 |
comfy/clip_model.py、text_encoders/ | 文本编码器与 CLIP/SigLIP 系列视觉塔 |
comfy/weight_adapter/ | LoRA 等权重适配器的加载与合并 |
app/model_manager.py | 模型路径解析,配合 extra_model_paths.yaml |
app/custom_node_manager.py | 自定义节点的装载、隔离与管理 |
app/frontend_management.py | 前端版本获取与切换 |
api_server/routes、services | HTTP 路由与业务服务层,对外暴露图执行接口 |
comfy_api、comfy_api_nodes | 版本化节点 SDK(v0_0_1 / v0_0_2 / latest)与云端 API 节点 |
blueprints/ | 开箱即用的示例工作流集合,按模型与任务命名 |
alembic_db/、app/database/ | 数据库迁移与持久化(资产、用户、设置) |
这套划分透露出一个演进事实:comfy_api 的版本化目录结构说明节点接口已经进入需要「兼容层」的阶段——早期自定义节点直接依赖内部实现的写法,正被逐步收拢到受控的 SDK 边界内。对生态是好事,对存量节点作者则是必须面对的迁移成本。另一个信号是 alembic_db 与 app/database 的出现:ComfyUI 正在从一个「单机脚本集合」变成带状态、带用户概念的应用,这与其桌面端、云端的产品化路径一致。
六、特色能力
内置工具覆盖了创作链路上的绝大多数脏活:重绘与遮罩合成、外扩、引用条件、模型合并、放大、插帧、分割、深度估计与媒体处理,基本不需要为了一个环节去装一个来历不明的扩展。
App Mode 是产品视角上最有想象力的一项。它把一张几十节点的图收敛成一个只有输入框和按钮的界面——作者保留全部控制力,使用者只看到必要参数。这让 ComfyUI 从「工程师的玩具」变成可以交付给设计师、客户甚至终端用户的产品形态。
提示词语法也照顾了实践细节:(good code:1.2) 调权重、{day|night} 做通配随机、C 风格注释可写注释、embedding:filename 引用文本反转。这些不是炫技,而是长期使用后沉淀下来的表达需求。
格式支持同样不敷衍:16bit PNG、32bit EXR、10bit AVIF,以及多种 HDR 视频与图像的读写。对做影视与后期的团队来说,这一条往往比多支持两个模型更关键。
七、工具链或生态
生态的入口是 ComfyUI-Manager,负责自定义节点的安装、更新与治理;新版通过 --enable-manager 显式启用,并提供 --disable-manager-ui 保留后台安全检查与定时安装能力,方向明显是在补「节点生态的安全与可维护性」这块历史欠账。
安装侧有 comfy-cli:
pip install comfy-cli
comfy install # 安装 ComfyUI
cd ComfyUI && python main.py # 启动
# 可选:启用管理器
python main.py --enable-manager --preview-method auto
发布侧是 Core / Desktop / Frontend 三仓库协同:核心出稳定版与补丁版,桌面端基于最新稳定核心构建,前端每两周余合并进核心并冻结特性。官方维护了 workflow 库与模板,示例工作流按「文本生图」「视频生成」「3D 与视觉」等标签组织,降低了从零搭图的启动成本。
八、部署与安全
硬件后端覆盖是这个项目最容易被低估的工程成就:NVIDIA(cu130 及以上)、AMD(ROCm,Linux 与 Windows 双路径,含按 gfx 架构选择算子包)、Intel Arc(XPU)、Apple Silicon(MPS)、Ascend NPU(torch_npu)、Cambricon MLU、Iluvatar Corex。README 对 PyTorch 版本的要求相当直白:低于 2.7 只是勉强可用,超过半年没更新就该升级——这不是免责声明,而是真实的性能分水岭。
离线与安全方面,官方给足了开关:核心默认不下载任何内容,--offline 关闭可选的付费 API 节点并强制全部功能本地化,--disable-partner-nodes 只关掉伙伴节点。对于有数据合规要求的团队,这几行参数比任何宣传语都有说服力。
需要提醒的是版本节奏带来的风险:稳定标签之外的提交可能非常不稳定,并会破坏大量自定义节点。生产环境请固定在具体 tag 上,不要跟着 master 走。
九、适用场景
- 专业视觉创作者与工作室:需要逐参数控制、需要把流程固化成可复用资产、需要产出可交付给非技术同事的界面。
- 工程团队:通过 API 端点把生成能力嵌入 CMS、电商、游戏素材管线,节点图承担「可版本化的配置」角色。
- 消费级硬件用户:4GB 显存起步的流式加载让老卡也能跑新模型,代价是速度而非可行性。
- 模型与节点开发者:
comfy_api的版本化 SDK 提供了相对稳定的扩展契约;新模型发布后往往数天内就能在社区看到可用节点。 反过来,如果你只想输入一句话就得到一张图,且不打算理解采样步数、CFG 与潜空间,那么这套系统的抽象层次会成为负担。
十、总结评价
ComfyUI 的真正价值不在「支持了很多模型」——那是跟进速度的结果,不是护城河。它的护城河是把扩散推理抽象成一张有状态、可增量执行、可序列化的计算图,再用足够克制的节点 SDK 把这个抽象开放给生态。这让「工作流」第一次成为了可保存、可分享、可版本管理、可从产出物反向还原的资产。围绕这一点长出来的节点生态、模板库与 App Mode,构成了竞争对手很难短期复制的网络效应。
局限同样清晰。第一,学习曲线陡:你得同时理解扩散模型原理和节点图编程范式,缺一样都会卡住。第二,发布节奏快带来的稳定性代价,非稳定标签提交破坏自定义节点是常态,生产部署必须锁版本。第三,节点生态质量参差,安全治理仍在补课,Manager 的收紧是正确方向但远未完成。第四,GPL-3.0 对商业集成的约束需要在选型阶段就评估清楚。
适合谁:愿意为控制力付出学习成本的创作者、需要把生成能力工程化的团队、以及想在本地硬件上榨出每一分性能的人。不适合谁:追求零配置一键出图的轻度用户——他们应该用桌面版,而不是从 git clone 开始。
参考链接:ComfyUI 仓库 · 官网 · 文档