# https://github.com/Comfy-Org/ComfyUI 项目说明书 生成时间：2026-05-10 16:23:38 UTC ## 目录 - [ComfyUI 项目概述](#page-overview) - [快速入门指南](#page-quick-start) - [系统架构设计](#page-architecture) - [执行引擎与工作流](#page-execution-engine) - [支持的模型列表](#page-supported-models) - [模型管理与加载](#page-model-management) - [文本编码器系统](#page-text-encoders) - [节点系统与节点类型](#page-node-system) - [工作流模板与 Blueprints](#page-blueprints) - [服务器与 API 接口](#page-server-api) ## ComfyUI 项目概述 ### 相关页面 相关主题：[系统架构设计](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) - [app/user_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/user_manager.py) - [app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py) - [app/frontend_management.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/frontend_management.py) - [api_server/routes/internal/README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/api_server/routes/internal/README.md) - [comfy/comfy_types/README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/comfy_types/README.md)
# ComfyUI 项目概述 ComfyUI 是一个专为视觉专业人士设计的模块化 AI 生成引擎，提供对模型、参数和输出的完全控制。其强大的节点图（node graph）模块化界面使创作者能够生成图像、视频、3D 模型、音频等多种内容。资料来源：[README.md]() ## 项目定位与目标 ComfyUI 的核心定位是成为一个**开源、可扩展、离线运行**的 AI 内容生成平台。项目追求以下核心目标： | 目标类别 | 描述 | |---------|------| | 模块化架构 | 通过节点图实现高度灵活的工作流构建 | | 开源开放 | 原生支持最新的开源 SOTA 模型 | | 跨平台支持 | 支持 Windows、Linux、macOS 及多种硬件平台 | | 生产就绪 | 可无缝集成到生产流程的 API 端点 | 资料来源：[README.md]() ## 核心特性 ### 支持的模型类型 ComfyUI 原生支持多种前沿模型架构： **图像生成模型** - Stable Diffusion 系列（SDXL、SD3、SD3.5） - Flux 系列（Flux Dev/Schnell/Kontext） - Lumina Image 2.0、HiDream、Qwen Image - HunyuanDiT、Hunyuan Image 2.1、AuraFlow **图像编辑模型** - Omnigen 2、HiDream E1.1 - Qwen Image Edit、Flux Kontext **视频生成模型** - Stable Video Diffusion、Mochi、LTX-Video - Hunyuan Video、Wan 2.1、Wan 2.2 **音频模型** - Stable Audio 系列 资料来源：[README.md]() ### 高级功能 ```mermaid graph TD A[ComfyUI 核心功能] --> B[Textual Inversion] A --> C[Loras Locon/Loha] A --> D[Hypernetworks] A --> E[ControlNet/T2I-Adapter] A --> F[Inpainting] A --> G[Upscale Models] A --> H[GLIGEN] A --> I[Model Merging] A --> J[LCM models] A --> K[Latent Previews] ``` | 功能模块 | 支持特性 | |---------|---------| | 文本处理 | Textual Inversion、Embedding | | LoRA | Regular、Locon、Loha | | 控制网络 | ControlNet、T2I-Adapter | | 超分辨率 | ESRGAN、SwinIR、Swin2SR | | 修复增强 | Inpainting、Hires Fix、Area Composition | 资料来源：[README.md]() ## 系统架构 ### 整体架构图 ```mermaid graph TD subgraph 前端层 A[Web UI Frontend] B[Desktop App] C[API Endpoints] end subgraph 核心层 D[Execution Engine] E[Node Graph System] F[Model Manager] G[Frontend Manager] end subgraph 数据层 H[User Data Store] I[Model Storage] J[Workflow Files] end subgraph API层 K[REST API] L[WebSocket] end A --> K B --> K C --> K K --> D K --> L D --> E E --> F F --> I G --> A H --> K J --> K ``` ### 核心模块说明 | 模块名称 | 文件位置 | 功能描述 | |---------|---------|---------| | comfy_types | `comfy/comfy_types/` | 类型提示和节点开发基类 | | model_manager | `app/model_manager.py` | 模型文件的发现、加载和管理 | | user_manager | `app/user_manager.py` | 用户数据目录管理和 API 路由 | | frontend_management | `app/frontend_management.py` | 前端版本检查和管理 | | api_server | `api_server/` | RESTful API 和 WebSocket 服务 | 资料来源：[comfy/comfy_types/README.md](), [app/model_manager.py](), [app/user_manager.py](), [app/frontend_management.py](), [api_server/routes/internal/README.md]() ### 节点类型系统 ComfyUI 提供强类型的节点开发系统，基于 `ComfyNodeABC` 抽象基类： ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` **内置 IO 类型** | 类型标识 | 说明 | 格式 | |---------|------|------| | `ANY` | 任意类型 | `"*"` | | `NUMBER` | 数值类型 | `"FLOAT,INT"` | | `PRIMITIVE` | 基础类型 | `"STRING,FLOAT,INT,BOOLEAN"` | 资料来源：[comfy/comfy_types/README.md]() ## 安装与运行 ### 系统要求 | 组件 | 要求 | |-----|------| | 操作系统 | Windows、Linux、macOS | | Python | 3.x | | 硬件 | NVIDIA GPU / AMD GPU / Apple Silicon / Intel / Ascend | ### 基本安装步骤 ```bash # 1. 克隆仓库 git clone https://github.com/Comfy-Org/ComfyUI.git # 2. 安装依赖 pip install -r requirements.txt # 3. 启动程序 python main.py ``` 资料来源：[README.md]() ### 硬件平台特定安装 **NVIDIA GPU** ```bash pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 ``` **AMD GPU (ROCm)** ```bash pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm ``` **Apple Silicon (M1/M2)** ```bash # 参考 Apple 官方 PyTorch Metal 加速指南安装 nightly 版本 ``` **Intel XPU** ```bash pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu ``` **Ascend NPU** 需要安装 Ascend Basekit 和 torch-npu，参考 [Ascend 安装文档](https://ascend.github.io/docs/sources/ascend/quick_install.html) 资料来源：[README.md]() ### ComfyUI-Manager 扩展 | 标志 | 说明 | |-----|------| | `--enable-manager` | 启用 ComfyUI-Manager | | `--enable-manager-legacy-ui` | 使用旧版 Manager UI | | `--disable-manager-ui` | 禁用 Manager UI 但保留后台功能 | ```bash pip install -r manager_requirements.txt python main.py --enable-manager ``` 资料来源：[README.md]() ## 命令行选项 | 选项 | 说明 | |-----|------| | `--preview-method auto/taesd` | 预览方法设置 | | `--tls-keyfile ` | TLS 密钥文件路径 | | `--tls-certfile ` | TLS 证书文件路径 | | `--front-end-version @` | 指定前端版本 | | `--disable-api-nodes` | 禁用 API 节点 | ### TLS/SSL 配置 ```bash # 生成自签名证书 openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" # 启动 HTTPS 服务 python main.py --tls-keyfile key.pem --tls-certfile cert.pem ``` 资料来源：[README.md]() ### 高质量预览配置 TAESD 预览需要下载以下文件到 `models/vae_approx` 目录： - `taesd_decoder.pth` - `taesdxl_decoder.pth` - `taesd3_decoder.pth` - `taef1_decoder.pth` 然后使用 `--preview-method taesd` 启动。 资料来源：[README.md]() ## 模型管理 ### 模型文件发现机制 `model_manager.py` 实现了智能模型文件发现功能，支持以下特性： ```python # 自动匹配基础名称 # 支持 .preview 后缀预览图 # 支持 safetensors 元数据解析 # Base64 编码的封面图片提取 ``` ### 模型目录结构 ``` models/ ├── checkpoints/ # 主模型 ├── loras/ # LoRA 模型 ├── vae/ # VAE 模型 ├── controlnet/ # ControlNet 模型 ├── embeddings/ # Textual Inversion embeddings └── vae_approx/ # TAESD 预览模型 ``` 资料来源：[app/model_manager.py]() ## 用户数据管理 ### API 路由结构 | 端点 | 方法 | 功能 | |-----|------|------| | `/v1/userdata` | GET | 列出用户数据目录内容 | | `/v2/userdata` | GET | 结构化用户数据列表 | | `/internal/*` | - | 内部专用接口 | `/v1/userdata` 和 `/v2/userdata` 端点支持以下查询参数： | 参数 | 说明 | 可选值 | |-----|------|-------| | `recurse` | 递归列出子目录 | `true`/`false` | | `full_info` | 返回完整文件信息 | `true`/`false` | | `split` | 分割路径为数组 | `true`/`false` | 资料来源：[app/user_manager.py](), [api_server/routes/internal/README.md]() ## 前端版本管理 ### 版本检查机制 `frontend_management.py` 模块负责管理前端包的版本一致性： ```python def check_frontend_version(): # 获取已安装的前端版本 # 获取需要的前端版本 # 检查版本是否匹配 ``` **版本格式**: `X.Y.Z` (语义化版本) ```python def parse_version(version: str) -> tuple[int, int, int]: return tuple(map(int, version.split("."))) def is_valid_version(version: str) -> bool: pattern = r"^(\d+)\.(\d+)\.(\d+)$" return bool(re.match(pattern, version)) ``` ### 旧版前端 如需使用旧版前端，可通过命令行指定： ```bash --front-end-version Comfy-Org/ComfyUI_legacy_frontend@latest ``` 资料来源：[app/frontend_management.py](), [README.md]() ## 快捷键参考 | 快捷键 | 功能 | |-------|------| | `Ctrl+Z` / `Ctrl+Y` | 撤销/重做 | | `Ctrl+S` | 保存工作流 | | `Ctrl+O` | 加载工作流 | | `Ctrl+A` | 全选节点 | | `Alt+C` | 折叠/展开节点 | | `Ctrl+M` | 静音/取消静音节点 | | `Ctrl+B` | 绕过选中节点 | | `Delete` | 删除选中节点 | | `Space` + 拖动 | 平移画布 | | `Double-Click` | 打开节点搜索面板 | | `Ctrl+G` | 创建节点组 | 资料来源：[README.md]() ## 发布流程 ComfyUI 采用周发布周期，目标是每周一发布新版本。 | 发布类型 | 说明 | |---------|------| | 主版本 | 约每两周发布一次 (如 v0.7.0) | | 小版本 | 从 master 分支发布 | | 补丁版本 | 用于当前稳定版的后向修复 | **三个关联仓库** 1. **ComfyUI Core**: 核心引擎和节点系统 2. **ComfyUI Frontend**: Web 前端界面 3. **ComfyUI Manager**: 节点管理和安装系统 资料来源：[README.md]() ## 执行引擎特性 ### 智能执行优化 ```mermaid graph LR A[提交工作流] --> B{检查输出是否变化} B -->|未变化| C[跳过执行] B -->|有变化| D{输入是否完整} D -->|完整| E[执行节点] D -->|不完整| F[等待上游完成] ``` **执行规则**： 1. 只有所有输入正确的节点输出才会被执行 2. 仅执行与上一次执行相比发生变化的节点 3. 连续提交相同工作流时，仅第一次会被执行 资料来源：[README.md]() ## 离线特性 ComfyUI 的核心模块**完全离线运行**，不会自动下载任何资源，除非用户明确要求。这种设计使其非常适合： - 企业内网环境 - 安全敏感的生产环境 - 网络受限的部署场景 可通过可选的 API 节点访问外部付费模型服务。 资料来源：[README.md]() ## 配置示例 ### extra_model_paths.yaml 支持通过配置文件设置模型的搜索路径： ```yaml # 复制自 extra_model_paths.yaml.example # 设置模型目录的额外搜索路径 ``` 这允许用户复用其他 UI 工具已下载的模型文件。 资料来源：[README.md]() --- ## 快速入门指南 ### 相关页面 相关主题：[ComfyUI 项目概述](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) - [requirements.txt](https://github.com/Comfy-Org/ComfyUI/blob/main/requirements.txt) - [pyproject.toml](https://github.com/Comfy-Org/ComfyUI/blob/main/pyproject.toml) - [extra_model_paths.yaml.example](https://github.com/Comfy-Org/ComfyUI/blob/main/extra_model_paths.yaml.example) - [app/user_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/user_manager.py) - [app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py)
# 快速入门指南 ## 概述 ComfyUI 是为视觉专业人士打造的最强大、最模块化的 AI 生成引擎，提供对模型、参数和输出的完全控制。其强大的模块化节点图界面使创作者能够生成图像、视频、3D 模型、音频等。资料来源：[README.md]() ComfyUI 原生支持最新的开源 SOTA 模型，并提供 API 节点以访问 Nano Banana、Seedance、Hunyuan3D 等顶级闭源模型。该平台可在 Windows、Linux 和 macOS 上本地使用，也可通过桌面应用程序或云端访问。资料来源：[README.md]() ## 安装方式 ### 桌面应用程序 桌面应用程序是入门最简单的方式，支持 Windows 和 macOS 系统。 | 平台 | 下载地址 | |------|----------| | Windows | [Comfy 官网下载](https://www.comfy.org/download) | | macOS | [Comfy 官网下载](https://www.comfy.org/download) | ### Windows 便携版 Windows 提供独立的便携式构建版本，适用于 NVIDIA GPU 或仅使用 CPU 运行。资料来源：[README.md]() ### 手动安装（跨平台） ComfyUI 支持所有操作系统和 GPU 类型，包括 NVIDIA、AMD、Intel、Apple Silicon 和 Ascend。资料来源：[README.md]() ## 依赖安装 ### 系统依赖 根据不同的 GPU 类型，需要安装对应的 PyTorch 版本： #### NVIDIA GPU 安装 stable 版本的 PyTorch： ```bash pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 ``` 如需 nightly 版本（可能有性能提升）： ```bash pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132 ``` #### AMD GPU (ROCm) 安装 AMD 支持的 PyTorch： ```bash pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/rocm ``` 对于非官方支持的 AMD 显卡，使用以下命令： | 显卡型号 | 命令 | |----------|------| | 6700, 6600 及部分 RDNA2 或更旧型号 | `HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py` | | 7600 及部分 RDNA3 型号 | `HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py` | #### Apple Mac Silicon 1. 安装 PyTorch nightly，参考 [Apple 官方指南](https://developer.apple.com/metal/pytorch/) 2. 按照 Windows 和 Linux 的手动安装说明操作 3. 安装 ComfyUI 依赖 4. 运行 `python main.py` 启动 #### Intel GPU (XPU) 安装 PyTorch XPU nightly： ```bash pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu ``` #### Ascend NPU 1. 安装推荐的或更新的 Linux 内核版本 2. 安装 Ascend Basekit（包含驱动、固件和 CANN） 3. 安装 torch-npu 包 4. 按照 ComfyUI 手动安装说明操作 ### Python 依赖 安装所有必需的 Python 包： ```bash pip install -r requirements.txt ``` ## 运行 ComfyUI 安装完成后，通过以下命令启动 ComfyUI： ```bash python main.py ``` ## 命令行选项 | 参数 | 描述 | |------|------| | `--preview-method ` | 预览方法，可选值包括 `auto` | | `--tls-keyfile ` | TLS 密钥文件路径 | | `--tls-certfile ` | TLS 证书文件路径 | | `--use-pytorch-cross-attention` | 使用 PyTorch 跨注意力机制 | | `--enable-manager` | 启用 ComfyUI-Manager | | `--enable-manager-legacy-ui` | 使用旧版 Manager UI | | `--disable-manager-ui` | 禁用 Manager UI | | `--disable-api-nodes` | 禁用 API 节点 | | `--front-end-version ` | 指定前端版本 | ### TLS/SSL 配置 生成自签名证书： ```bash openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" ``` 启动时启用 TLS： ```bash python main.py --tls-keyfile key.pem --tls-certfile cert.pem ``` ### 高质量预览 使用 TAESD 启用高质量预览： 1. 下载 [TAESD decoder 文件](https://github.com/madebyollin/taesd/)： - taesd_decoder.pth - taesdxl_decoder.pth - taesd3_decoder.pth - taef1_decoder.pth 2. 将文件放入 `models/vae_approx` 目录 3. 重启 ComfyUI 并使用 `--preview-method taesd` 启动 ## 模型管理 ### 目录结构 ComfyUI 使用以下目录结构管理模型： ```mermaid graph TD A[ComfyUI Root] --> B[models] B --> C[checkpoints] B --> D[vae] B --> E[lora] B --> F[embeddings] B --> G[controlnet] B --> H[upscale_models] B --> I[vae_approx] ``` ### 外部模型路径配置 通过 `extra_model_paths.yaml` 配置文件可以设置模型的外部搜索路径，便于复用其他 Stable Diffusion UI 的模型。资料来源：[extra_model_paths.yaml.example]() 配置文件示例： ```yaml # 从其他 UI 导入模型路径 a1111: base_path: /path/to/stable-diffusion-webui/models # 或指定具体子目录 # checkpoints: checkpoints # vae: vae other_ui: base_path: /path/to/other/ui/models ``` ## ComfyUI-Manager ComfyUI-Manager 是一个扩展，可轻松安装、更新和管理自定义节点。资料来源：[README.md]() ### 安装 1. 安装管理器依赖： ```bash pip install -r manager_requirements.txt ``` 2. 启用管理器： ```bash python main.py --enable-manager ``` ### 功能 | 功能 | 描述 | |------|------| | 安装自定义节点 | 一键安装社区开发的节点 | | 更新管理 | 批量更新已安装的节点 | | 节点搜索 | 搜索和浏览可用的自定义节点 | ## 快捷键 ### 基础操作 | 快捷键 | 功能 | |--------|------| | `Ctrl + Z` | 撤销 | | `Ctrl + Y` / `Ctrl + Z` | 重做 | | `Ctrl + S` | 保存工作流 | | `Ctrl + O` | 加载工作流 | | `Ctrl + A` | 全选节点 | | `Alt + C` | 折叠/展开选中节点 | | `Ctrl + M` | 静音/取消静音选中节点 | | `Ctrl + B` | 绕过选中节点 | | `Delete` / `Backspace` | 删除选中节点 | | `Ctrl + Backspace` | 删除当前图 | | `Space` + 拖动 | 移动画布 | | `Shift + 拖动` | 同时移动多个节点 | ### 选择操作 | 快捷键 | 功能 | |--------|------| | `Ctrl + 点击` | 添加节点到选择 | | `Shift + 点击` | 添加节点到选择 | | `Ctrl + C` | 复制选中节点 | | `Ctrl + V` | 粘贴节点（不保留未选节点连接） | | `Ctrl + Shift + V` | 粘贴节点（保留未选节点连接） | ### 视图操作 | 快捷键 | 功能 | |--------|------| | `Alt + +` | 放大画布 | | `Alt + -` | 缩小画布 | | `Ctrl + Shift + 左键 + 垂直拖动` | 画布缩放 | | `P` | 固定/取消固定选中节点 | | `Ctrl + G` | 分组选中节点 | | `Q` | 切换队列可见性 | | `H` | 切换历史记录可见性 | | `R` | 刷新图 | | `F` | 显示/隐藏菜单 | | `.` | 适应选择视图 | | `双击左键` | 打开节点快速搜索面板 | | `Shift + 拖动线` | 同时移动多条线 | | `Ctrl + Alt + 左键` | 断开点击插槽的所有连线 | > 注意：macOS 用户可将 `Ctrl` 替换为 `Cmd`。 ## 工作流示例 ComfyUI 支持多种高级功能： | 功能 | 说明 | |------|------| | Textual Inversion | 文本反转嵌入 | | Loras | 常规 LoRA、LoCon 和 LoHa | | Hypernetworks | 超网络 | | Hires Fix | 高分辨率修复 | | Area Composition | 区域构图 | | Inpainting | 局部重绘（支持常规和重绘模型） | | ControlNet / T2I-Adapter | 条件控制网络 | | Upscale Models | 超分辨率模型（ESRGAN、SwinIR 等） | | GLIGEN | 布局引导生成 | | Model Merging | 模型融合 | | LCM | LCM 模型和 LoRa | 详细示例请参考 [ComfyUI Examples](https://comfyanonymous.github.io/ComfyUI_examples/)。 ## 工作流程执行机制 ComfyUI 的执行优化机制： ```mermaid graph LR A[提交工作流] --> B{检查输出} B --> |输入完整| C[执行节点] B --> |输入不完整| D[跳过执行] C --> E{与上次比较} E --> |有变化| F[重新执行] E --> |无变化| G[使用缓存] F --> H[更新输出] G --> H ``` ### 执行规则 1. **完整性检查**：只有所有输入都正确的节点才会被执行 2. **增量执行**：仅执行与上次执行相比有变化的部分 3. **缓存机制**：提交相同工作流两次，只有第一次会执行 4. **依赖传播**：修改工作流的最后部分时，只有修改部分及其依赖部分会重新执行 ## 发布周期 ComfyUI 采用每周发布周期，但会因模型发布或代码库重大变更而调整。 | 版本类型 | 说明 | |----------|------| | 主版本 | 约每两周发布一次（如 v0.7.0） | | Patch 版本 | 用于当前稳定版的修复回退 | | Minor 版本 | 从 master 分支发布的版本 | > 警告：稳定版本标签之外的提交可能非常不稳定，可能导致许多自定义节点失效。 ## 故障排除 ### Torch CUDA 错误 如果遇到 "Torch not compiled with CUDA enabled" 错误： ```bash pip uninstall torch # 重新安装（参考上方 NVIDIA GPU 安装命令） pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 ``` ### AMD ROCm 性能优化 启用实验性内存高效注意力： ```bash TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention ``` 可选性能优化（首次运行较慢）： ```bash PYTORCH_TUNABLEOP_ENABLED=1 python main.py --- ## 系统架构设计 ### 相关页面 相关主题：[ComfyUI 项目概述](#page-overview), [执行引擎与工作流](#page-execution-engine), [服务器与 API 接口](#page-server-api)
相关源码文件 以下源码文件用于生成本页说明： - [comfy](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy) - [comfy_execution](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_execution) - [comfy_extras](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_extras) - [comfy_api](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_api) - [api_server](https://github.com/Comfy-Org/ComfyUI/blob/main/api_server) - [app](https://github.com/Comfy-Org/ComfyUI/blob/main/app)
# 系统架构设计 ## 概述 ComfyUI 是一个模块化的 AI 创作引擎，采用节点图（Node Graph）架构设计。其核心设计理念是将复杂的 AI 生成流程分解为可复用、可组合的独立节点单元，用户通过可视化界面连接这些节点构建完整的工作流。 系统架构采用分层设计，从底层的张量计算到上层的 Web 服务，各层职责明确，模块间通过清晰定义的接口通信。这种设计使得 ComfyUI 能够支持多种硬件平台（NVIDIA、AMD、Intel、Apple Silicon、Ascend）以及多种 AI 模型类型。 ## 核心架构分层 ComfyUI 的系统架构可以分为以下几个层次： ```mermaid graph TD A[应用层 app] --> B[API层 api_server] B --> C[核心层 comfy + comfy_execution] C --> D[模型层 comfy_extras] D --> E[执行后端 PyTorch/CUDA/ROCm] A1[前端界面] --> A A2[用户管理 user_manager] --> A A3[模型管理 model_manager] --> A ``` ### 核心模块职责 | 模块 | 路径 | 职责 | |------|------|------| | **app** | `app/` | 应用层服务，处理用户交互、模型管理、前端资源分发 | | **api_server** | `api_server/` | RESTful API 服务端，处理工作流执行请求 | | **comfy** | `comfy/` | 核心类型系统和工具函数库 | | **comfy_execution** | `comfy_execution/` | 图执行引擎，负责节点调度和依赖解析 | | **comfy_extras** | `comfy_extras/` | 扩展节点库，包含各类预置节点实现 | | **comfy_api** | `comfy_api/` | API 节点封装，提供外部模型服务接口 | ## 节点类型系统 ComfyUI 的节点系统基于类型化的输入输出设计，核心类型定义位于 `comfy/comfy_types/` 模块。 ### 内置数据类型 ```mermaid graph LR A[IO 枚举] --> B[基础类型] A --> C[特殊类型] A --> D[复合类型] B --> B1[STRING] B --> B2[FLOAT] B --> B3[INT] B --> B4[BOOLEAN] C --> C1[ANY "*"] C --> C2[NUMBER "FLOAT,INT"] C --> C3[PRIMITIVE "STRING,FLOAT,INT,BOOLEAN"] D --> D1[IMAGE] D --> D2[MODEL] D --> D3[LATENT] ``` ### 节点基类设计 所有自定义节点应继承自 `ComfyNodeABC` 抽象基类： ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` 资料来源：[comfy/comfy_types/README.md](comfy/comfy_types/README.md) ## 执行引擎架构 ### 图执行模型 ComfyUI 的执行引擎采用**懒加载**和**增量执行**策略： 1. **依赖解析**：系统分析节点图的依赖关系，构建拓扑排序 2. **条件执行**：仅执行所有输入都已就绪的节点 3. **缓存复用**：对于相同输入的节点，结果会被缓存复用 4. **增量更新**：重新执行时只运行发生变化的节点及其下游节点 ```mermaid graph TD A[提交工作流] --> B{检查节点输入} B -->|所有输入就绪| C[执行节点] B -->|输入缺失| D[跳过执行] C --> E{结果缓存} E -->|首次执行| F[缓存结果] E -->|命中缓存| G[返回缓存] F --> H[下游节点执行] G --> H H --> I[完成输出] ``` 资料来源：[README.md](README.md) ### 执行流程特点 根据源码分析，ComfyUI 的执行机制具有以下特点： - 只有图中所有输出都具有正确输入的节点才会被执行 - 只有相比上次执行发生变化的节点及其依赖链会被重新执行 - 连续提交相同的工作流定义，第二次将跳过执行 ## API 服务架构 ### 服务端路由设计 API 服务层位于 `api_server/` 目录，采用分层路由设计： | 路由类别 | 路径前缀 | 用途 | |----------|----------|------| | **内部路由** | `/internal/` | ComfyUI 内部使用，可能随时变更 | | **公共 API** | `/v1/` | 稳定的公共接口 | | **用户数据** | `/v2/userdata` | 用户数据访问 | ### 内部路由规范 所有 `/internal` 路径下的路由均为 ComfyUI 内部使用，不对外部应用开放，可能在任何版本中发生变更而无另行通知。 资料来源：[api_server/routes/internal/README.md](api_server/routes/internal/README.md) ## 用户数据管理 用户数据管理通过 `app/user_manager.py` 实现，提供文件系统的安全隔离访问。 ### 文件列表接口 ``` GET /v2/userdata?path=&recurse=&full_info=&split= ``` | 参数 | 类型 | 说明 | |------|------|------| | `path` | string | 用户数据目录内的相对路径，默认为根目录 | | `recurse` | boolean | 是否递归列出子目录，默认 false | | `full_info` | boolean | 是否返回完整文件信息，默认 false | | `split` | boolean | 是否分割路径返回数组，默认 false | ### 安全机制 - 路径验证：所有请求路径必须位于用户数据目录内 - 路径遍历防护：自动阻止 `..` 等路径遍历攻击 - 仅返回文件：目录不包含在结果中 资料来源：[app/user_manager.py](app/user_manager.py) ## 模型管理 ### 模型文件发现 模型管理器 (`app/model_manager.py`) 负责模型文件的自动发现和元数据提取： ```mermaid graph TD A[请求模型预览] --> B[查找同名图片] A --> C[查找 .preview 后缀图片] A --> D[检查 safetensors 元数据] B --> E[返回预览图列表] C --> E D --> F[提取 ssmd_cover_images] F --> E ``` ### 模型预览格式 模型预览支持以下格式： | 类型 | 格式 | 说明 | |------|------|------| | 同名图片 | `{basename}.{ext}` | 与模型文件同名的图片 | | 预览图片 | `{basename}.preview.{ext}` | 带 .preview 后缀的图片 | | 内嵌预览 | safetensors 元数据 | 存储在 safetensors 文件头中的 base64 图片 | 资料来源：[app/model_manager.py](app/model_manager.py) ## 前端资源管理 前端资源通过 `app/frontend_management.py` 进行版本控制和管理。 ### 版本检查机制 ```mermaid graph TD A[启动时检查] --> B{版本匹配?} B -->|匹配| C[正常启动] B -->|不匹配| D[显示警告] D --> E[提示更新前端包] ``` ### 版本验证规则 版本字符串必须符合语义化版本规范 (X.Y.Z)： ```python def is_valid_version(version: str) -> bool: """Validate if a string is a valid semantic version (X.Y.Z format).""" pattern = r"^(\d+)\.(\d+)\.(\d+)$" return bool(re.match(pattern, version)) ``` ### 前端切换选项 | 参数 | 说明 | |------|------| | `--front-end-version Comfy-Org/ComfyUI_legacy_frontend@latest` | 使用旧版前端界面 | ## 部署架构 ### 启动入口 ComfyUI 的主入口为 `python main.py`，支持多种启动参数： | 参数 | 说明 | |------|------| | `--enable-manager` | 启用 ComfyUI-Manager | | `--enable-manager-legacy-ui` | 使用传统管理界面 | | `--disable-manager-ui` | 禁用管理 UI 但保留后台功能 | | `--preview-method {auto,taesd}` | 预览图生成方式 | | `--tls-keyfile` | TLS 私钥文件路径 | | `--tls-certfile` | TLS 证书文件路径 | | `--disable-api-nodes` | 禁用付费 API 节点 | | `--use-pytorch-cross-attention` | 使用 PyTorch 交叉注意力 | 资料来源：[README.md](README.md) ### 多硬件支持 ```mermaid graph TD A[ComfyUI] --> B[PyTorch Backend] B --> C[NVIDIA CUDA] B --> D[AMD ROCm] B --> E[Intel XPU] B --> F[Apple Metal] B --> G[Ascend NPU] ``` ## 类型系统详解 ### 输入类型定义 节点的 `INPUT_TYPES` 返回字典结构： ```python { "required": { "input_name": input_definition, ... }, "optional": { "input_name": input_definition, ... }, "hidden": { "input_name": input_definition, ... } } ``` ### 输入定义选项 每个输入定义可包含以下属性（通过类型提示获取完整信息）： - `INPUT_TYPES()` 返回值自动补全 - 单个输入选项的自动补全 - 返回值类型提示 资料来源：[comfy/comfy_types/README.md](comfy/comfy_types/README.md) ## 总结 ComfyUI 采用现代化的分层架构设计，核心优势包括： 1. **模块化节点设计**：通过 `ComfyNodeABC` 基类提供统一的节点开发接口 2. **高效的执行引擎**：懒加载和增量执行减少不必要的计算 3. **灵活的 API 层**：内部路由和公共 API 分离，便于扩展 4. **多平台支持**：统一的抽象层支持 NVIDIA、AMD、Intel、Apple Silicon、Ascend 等多种硬件 5. **安全的数据访问**：用户数据目录隔离，路径遍历防护 6. **版本化管理**：前端资源与后端核心分离独立版本控制 --- ## 执行引擎与工作流 ### 相关页面 相关主题：[系统架构设计](#page-architecture), [节点系统与节点类型](#page-node-system)
相关源码文件 以下源码文件用于生成本页说明： - [execution.py](https://github.com/Comfy-Org/ComfyUI/blob/main/execution.py) - [comfy_execution/graph.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_execution/graph.py) - [comfy_execution/jobs.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_execution/jobs.py) - [comfy_execution/caching.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_execution/caching.py) - [comfy_execution/validation.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_execution/validation.py)
# 执行引擎与工作流 ## 概述 ComfyUI 的执行引擎是整个系统的核心组件，负责解析、管理和执行基于节点图的工作流。该引擎采用智能缓存机制，仅执行图中发生变化的部分，从而实现高效的迭代开发体验。执行引擎与工作流系统协同工作，将用户通过可视化界面构建的节点图转换为可执行的任务序列。 ComfyUI 采用模块化的节点架构，每个节点代表一个特定的功能单元，节点之间通过输入输出端口形成数据流连接。工作流执行时，引擎会根据节点之间的依赖关系自动确定执行顺序，确保每个节点在其所有依赖输入可用时才开始执行。 ## 工作流图结构 ### 节点图表示 ComfyUI 的工作流以有向无环图（DAG）结构存储，每个节点包含以下核心属性： | 属性 | 说明 | |------|------| | `node_id` | 节点的唯一标识符 | | `node_type` | 节点类型名称，对应具体的实现类 | | `inputs` | 节点的输入端口及其连接关系 | | `outputs` | 节点的输出端口及其连接关系 | | `widgets` | 节点的可配置参数 | 节点类型定义在节点的 `INPUT_TYPES` 类方法中，描述了节点接受的所有输入类型、默认值和约束条件。 ### 数据流连接 节点之间的数据通过端口连接传递。每个连接包含源节点、源端口、目标节点和目标端口四个要素。当执行引擎处理工作流时，它会沿着这些连接追踪数据流动，确保信息正确地从上游节点传递到下游节点。 ## 执行模型 ### 增量执行机制 ComfyUI 执行引擎实现了智能增量执行策略，这是其核心性能优化特性之一： 1. **变化检测**：当用户提交工作流执行时，引擎首先比较当前工作流与上一次执行的差异 2. **影响分析**：确定工作流中被修改的部分及其所有下游依赖节点 3. **选择性执行**：仅执行必要的节点，保留未受影响节点的缓存结果 这种机制使得用户可以在修改工作流的某个环节后快速获得更新结果，而无需重新执行整个图。资料来源：[README.md:变化检测逻辑]() ### 执行顺序确定 执行引擎采用拓扑排序算法确定节点的执行顺序。拓扑排序确保每个节点在其所有前驱节点执行完成之前不会开始执行，从而保证数据依赖的正确性。 当工作流中存在并行执行的节点（即没有相互依赖关系的节点）时，引擎会将它们分配到同一批次并行执行，充分利用多核处理器的计算能力。 ### 条件执行 只有当节点的输出端口被其他节点使用时，该输出才会被计算。引擎会自动识别工作流图中实际需要执行的路径，忽略未被引用的分支。这种优化显著减少了不必要的计算开销。 ## 执行流程 ```mermaid graph TD A[提交工作流] --> B[验证工作流结构] B --> C{与上次工作流比较} C -->|完全相同| D[返回缓存结果] C -->|存在差异| E[确定脏区域] E --> F[拓扑排序] F --> G[构建执行批次] G --> H[按批次执行节点] H --> I[缓存输出结果] I --> J{所有批次完成?} J -->|否| G J -->|是| K[返回最终输出] ``` ## 缓存系统 ### 节点输出缓存 执行引擎维护一个结果缓存系统，用于存储已执行节点的输出。当工作流被重新提交时，引擎会检查哪些节点的输出可以从缓存中复用： - **完全匹配**：如果节点的输入和参数与上次执行完全相同，则直接使用缓存输出 - **部分变化**：只有受变化影响且无法从缓存复用的节点才需要重新执行 缓存键由节点的输入值、参数配置和节点类型共同计算生成，确保缓存的唯一性和正确性。 ### 缓存清理策略 缓存系统会持续监控内存使用情况，当缓存数据量超过配置阈值时，引擎会采用最近最少使用（LRU）策略清理旧条目，释放内存空间供新结果使用。 ## 验证机制 ### 工作流验证 在执行工作流之前，引擎会执行多层次验证： 1. **结构验证**：检查节点图是否有断开的连接或循环依赖 2. **类型验证**：确认连接的数据类型是否兼容 3. **完整性验证**：确保所有必需输入都已连接 ### 输入验证 每个节点类型定义了自己的输入约束条件，包括： - 数据类型要求（如必须为图像、必须为浮点数等） - 取值范围限制 - 维度约束（如张量形状要求） 验证失败的节点会阻止工作流执行，并向用户报告具体的错误信息和位置。 ## 节点类型系统 ### 内置类型 ComfyUI 通过 `comfy/comfy_types` 模块提供了一套类型系统，用于标准化节点间的数据交换： | 类型标识 | 说明 | |----------|------| | `*` (ANY) | 接受任意类型 | | `FLOAT,INT` (NUMBER) | 数值类型 | | `STRING,FLOAT,INT,BOOLEAN` (PRIMITIVE) | 基本类型 | ### 自定义节点开发 开发者可以通过继承 `ComfyNodeABC` 抽象基类来创建自定义节点： ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` 资料来源：[comfy/comfy_types/README.md:节点开发示例]() ## API 与路由 ### 执行端点 ComfyUI 通过 RESTful API 暴露执行功能： | 端点 | 方法 | 说明 | |------|------|------| | `/prompt` | POST | 提交工作流执行 | | `/queue` | GET | 查询执行队列状态 | | `/history` | GET | 获取执行历史记录 | ### 内部路由 部分路由标记为内部使用，仅供 ComfyUI 前端调用，这些路由的实现可能在版本更新时发生变化： 资料来源：[api_server/routes/internal/README.md:内部路由说明]() ## 性能优化 ### 批处理执行 对于相互独立的节点，引擎会自动将它们批处理并行执行。这种批处理机制能够充分利用硬件的并行计算能力，特别是在处理大量相似操作时效果显著。 ### 内存管理 执行引擎实现了智能内存管理策略： - **流式处理**：对于大型中间结果，采用流式处理避免一次性加载到内存 - **及时释放**：节点执行完成后立即释放不再需要的中间数据 - **显存优化**：在 NVIDIA GPU 上利用 CUDA 内存管理优化显存使用 ## 配置选项 ComfyUI 提供了多个命令行参数用于调整执行引擎行为： | 参数 | 说明 | |------|------| | `--preview-method` | 设置预览生成方法（auto、taesd 等） | | `--use-pytorch-cross-attention` | 启用 PyTorch 跨注意力优化 | | `--disable-api-nodes` | 禁用付费 API 节点 | | `--multi-user` | 启用多用户模式 | 资料来源：[README.md:命令行参数]() ## 相关文件结构 ``` ComfyUI/ ├── execution.py # 执行入口 ├── comfy_execution/ │ ├── graph.py # 图结构定义 │ ├── jobs.py # 任务调度 │ ├── caching.py # 缓存实现 │ └── validation.py # 验证逻辑 └── app/ └── api_server/ # API 路由 --- ## 支持的模型列表 ### 相关页面 相关主题：[模型管理与加载](#page-model-management), [文本编码器系统](#page-text-encoders)
相关源码文件 以下源码文件用于生成本页说明： - [comfy/supported_models.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/supported_models.py) *(未在当前上下文中获取)* - [comfy/supported_models_base.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/supported_models_base.py) *(未在当前上下文中获取)* - [comfy/model_detection.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/model_detection.py) *(未在当前上下文中获取)* - [comfy/model_base.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/model_base.py) *(未在当前上下文中获取)*
# 支持的模型列表 ComfyUI 作为一款强大的模块化 AI 生成引擎，原生支持多种开源模型，涵盖图像、视频、3D 模型、音频等多种模态。本文档详细介绍 ComfyUI 所支持的模型类型、使用方式及模型管理机制。 ## 1. 模型类型概述 ComfyUI 支持的模型主要分为以下几个大类： | 类别 | 说明 | 示例模型 | |------|------|----------| | **图像生成模型** | 文本到图像、图像编辑等 | Stable Diffusion 系列、Flux、DALL-E 等 | | **视频生成模型** | 文本/图像到视频生成 | Stable Video Diffusion、Mochi、LTX-Video、Hunyuan Video、Wan 2.1/2.2 等 | | **音频模型** | 音频生成与处理 | Stable Audio 等 | | **3D 模型** | 3D 内容生成 | Hunyuan3D 等 | | **ControlNet/T2I-Adapter** | 条件控制模型 | 多种 ControlNet 变体 | | **Upscale Models** | 图像超分辨率 | ESRGAN、SwinIR、Swin2SR 等 | 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 2. 图像生成模型 ### 2.1 主流图像模型 ComfyUI 原生支持最新的开源图像生成模型，包括： - **Stable Diffusion 系列** - 包括 SD 1.5、SD 2.x、SDXL 等 - **Flux** - 包括 Flux Dev、Flux Schnell 等 - **HiDream** - 包括 HiDream I1、HiDream E1.1 等 - **SDXL** - 高分辨率图像生成 - **LCM (Latent Consistency Models)** - 快速图像生成 ### 2.2 图像编辑模型 | 模型名称 | 功能描述 | |----------|----------| | OmniGen 2 | 通用的图像编辑 | | Flux Kontext | 基于 Flux 的图像编辑 | | Qwen Image Edit | 阿里 Qwen 系列图像编辑 | | Ernie Image | 百度 Ernie 图像处理 | 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ### 2.3 图像生成增强技术 ComfyUI 支持多种图像增强技术： - **Hires Fix** - 高分辨率修复，提升生成图像质量 - **Inpainting** - 局部重绘，支持常规模型和专用修复模型 - **Area Composition** - 区域构图，多区域组合生成 - **Textual Inversion** - 文本嵌入自定义概念 - **Loras** - 支持常规 LoRA、LoCon 和 LoHA - **Hypernetworks** - 超网络训练与使用 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 3. 视频生成模型 ComfyUI 支持多种视频生成模型，覆盖从开源到商业级的解决方案： ### 3.1 开源视频模型 | 模型 | 说明 | 文档链接 | |------|------|----------| | Stable Video Diffusion | 基于 Stable Diffusion 的视频生成 | [链接](https://comfyanonymous.github.io/ComfyUI_examples/video/) | | Mochi | 高质量视频生成 | [链接](https://comfyanonymous.github.io/ComfyUI_examples/mochi/) | | LTX-Video | 长视频生成 | [链接](https://comfyanonymous.github.io/ComfyUI_examples/ltxv/) | | Hunyuan Video | 腾讯混元视频 | [链接](https://comfyanonymous.github.io/ComfyUI_examples/hunyuan_video/) | | Wan 2.1 / 2.2 | 通义万相视频系列 | [链接](https://comfyanonymous.github.io/ComfyUI_examples/wan/) | ### 3.2 商业视频模型 通过 API 节点访问的商业模型： - **Seedance** - 商汤视频生成 - **Nano Banana** - 实验性模型 - **Hunyuan3D** - 3D 模型生成 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 4. 音频模型 ComfyUI 支持音频内容的生成与处理： | 模型 | 功能 | |------|------| | Stable Audio | 文本到音频生成 | 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 5. 条件控制模型 ### 5.1 ControlNet ControlNet 提供对图像生成的精确控制，支持多种条件输入： - Canny 边缘检测 - Depth Map 深度图 - Pose 姿态估计 - Semantic Segmentation 语义分割 - 更多... [官方示例](https://comfyanonymous.github.io/ComfyUI_examples/controlnet/) ### 5.2 T2I-Adapter T2I-Adapter 是另一种条件控制方案，与 ControlNet 类似但更轻量。 ### 5.3 GLIGEN GLIGEN (Grounded Layout-to-Image Generation) 允许基于布局边界框生成图像。 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 6. 超分辨率模型 ComfyUI 内置多种图像超分辨率模型： | 模型类型 | 示例 | |----------|------| | ESRGAN | 经典超分辨率 | | ESRGAN 变体 | 多种专用版本 | | SwinIR | 基于 Transformer 的超分辨率 | | Swin2SR | 升级版 SwinIR | 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 7. 模型合并 ComfyUI 支持模型合并功能，可以将多个模型合并生成新的模型： - 支持不同的合并策略 - 可以保留多个源模型的特点 - 参考示例：[Model Merging](https://comfyanonymous.github.io/ComfyUI_examples/model_merging/) 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 8. Embeddings 和 Loras ### 8.1 Embeddings 自定义概念可以通过 Embeddings 加载： ```embedding:embedding_filename.pt ``` 将 embedding 文件放入 `models/embeddings` 目录，即可在 CLIPTextEncode 节点中使用。 ### 8.2 Loras 支持 ComfyUI 支持三种 Lora 类型： | 类型 | 说明 | |------|------| | 常规 LoRA | 标准的 Lora 权重 | | LoCon | 带卷积层的 LoRA | | LoHA | Hadamard 乘积 LoRA | 参考示例：[LCM models and Loras](https://comfyanonymous.github.io/ComfyUI_examples/lcm/) 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 9. 模型管理 ### 9.1 模型目录结构 ComfyUI 使用 `folder_paths` 模块管理模型文件，主要目录包括： | 目录 | 用途 | |------|------| | `models/checkpoints` | 主模型检查点 | | `models/vae` | VAE 模型 | | `models/embeddings` | Textual Inversion embeddings | | `models/loras` | Lora 文件 | | `models/controlnet` | ControlNet 模型 | | `models/upscale_models` | 超分辨率模型 | | `models/vae_approx` | VAE 近似模型（TAESD 等） | ### 9.2 模型发现机制 模型文件管理器 (`ModelFileManager`) 负责发现和索引模型文件： ```python class ModelFileManager: def __init__(self) -> None: self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {} ``` 支持以下 API 端点： - `GET /experiment/models` - 获取所有模型文件夹 - `GET /experiment/models/{folder}` - 获取指定文件夹中的所有模型 资料来源：[app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py) ### 9.3 自定义模型路径 可以通过 `extra_model_paths.yaml.example` 配置文件设置额外的模型搜索路径，便于与现有工作流集成。 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 10. 硬件支持 ### 10.1 NVIDIA GPU 推荐使用 CUDA 加速的 PyTorch： ```bash pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 ``` 或使用夜间版本以获得更好的性能： ```bash pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132 ``` ### 10.2 AMD GPU (ROCm) AMD GPU 用户可以使用 ROCm 版本的 PyTorch： ```bash pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.1 ``` 针对特定显卡的兼容性问题，可设置环境变量： ```bash # 对于 6700, 6600 及更早的 RDNA2 显卡： HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py # 对于 AMD 7600 及 RDNA3 显卡： HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py ``` 启用实验性内存高效注意力： ```bash TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention ``` ### 10.3 Apple Silicon Mac 用户（ M1/M2/M3 ）可使用 Metal 加速的 PyTorch： 1. 安装 PyTorch 夜间版本 2. 按标准流程安装 ComfyUI ### 10.4 Intel XPU Intel 显卡用户可使用 XPU 后端： ```bash pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu ``` ### 10.5 Intel/Ascend NPU 使用 NPU 加速的 PyTorch 版本。 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 11. 模型执行机制 ComfyUI 采用智能图执行策略： - **部分执行**：只有输出具有所有正确输入的图部分才会被执行 - **增量执行**：只有相比上次执行发生变化的图部分才会重新执行 - **缓存机制**：相同图提交两次，只有第一次会被执行 这种机制确保了高效的模型利用和快速的迭代工作流。 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 12. 高质量预览 ComfyUI 支持多种预览方法： | 方法 | 质量 | 说明 | |------|------|------| | `auto` | 低分辨率 | 默认方法，速度快 | | `taesd` | 高质量 | 需要下载 TAESD 解码器 | 启用高质量预览： 1. 下载 TAESD 解码器文件（`taesd_decoder.pth`、`taesdxl_decoder.pth`、`taesd3_decoder.pth`、`taef1_decoder.pth`） 2. 放入 `models/vae_approx` 目录 3. 使用 `--preview-method taesd` 启动 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 13. 离线工作 ComfyUI 核心功能完全离线运行： > Works fully offline: core will never download anything unless you want it to. 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) ## 14. 相关文档链接 - [官方示例集](https://comfyanonymous.github.io/ComfyUI_examples/) - [ComfyUI Manager](https://github.com/Comfy-Org/ComfyUI-Manager/tree/manager-v4) - 模型和节点管理扩展 - [Comfy API](https://docs.comfy.org/tutorials/api-nodes/overview) - 商业 API 节点文档 --- ## 模型管理与加载 ### 相关页面 相关主题：[支持的模型列表](#page-supported-models)
相关源码文件 以下源码文件用于生成本页说明： - [app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py) - [README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) (模型存储路径、嵌入模型使用说明)
# 模型管理与加载 ## 概述 ComfyUI 的模型管理与加载系统负责组织、定位、缓存和加载各类 AI 模型文件（包括检查点模型、LoRA、VAE、ControlNet、嵌入模型等）。该系统采用集中化的路径管理机制，支持自定义模型搜索路径，并通过 HTTP API 提供模型文件的发现和预览功能。 核心职责包括： - 模型文件的路径解析与目录管理 - 模型元数据读取（特别是 safetensors 格式） - 模型预览图片提取与缓存 - 运行时模型注册与访问接口 资料来源：[app/model_manager.py:1-50]() ## 核心组件 ### ModelFileManager `ModelFileManager` 是模型文件管理的核心类，提供模型文件发现、缓存和元数据提取功能。 ```python class ModelFileManager: def __init__(self) -> None: self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {} def get_cache(self, key: str, default=None) -> tuple[list[dict], dict[str, float], float] | None: return self.cache.get(key, default) def set_cache(self, key: str, value: tuple[list[dict], dict[str, float], float]): self.cache[key] = value def clear_cache(self): self.cache.clear() ``` **缓存机制** 缓存数据结构为 `tuple[list[dict], dict[str, float], float]`，包含三个元素： | 索引 | 类型 | 说明 | |------|------|------| | 0 | `list[dict]` | 模型文件列表 | | 1 | `dict[str, float]` | 文件访问时间戳 | | 2 | `float` | 缓存过期时间 | 资料来源：[app/model_manager.py:32-46]() ### 模型预览与元数据处理 `ModelFileManager` 支持从 safetensors 文件中提取嵌入的预览图片和元数据： ```python if safetensors_file: safetensors_filepath = os.path.join(dirname, safetensors_file) header = comfy.utils.safetensors_header(safetensors_filepath, max_size=8*1024*1024) if header: safetensors_metadata = json.loads(header) safetensors_images = safetensors_metadata.get("__metadata__", {}).get("ssmd_cover_images", None) if safetensors_images: safetensors_images = json.loads(safetensors_images) for image in safetensors_images: result.append(BytesIO(base64.b64decode(image))) ``` **处理流程** ```mermaid graph TD A[查找同名 .safetensors 文件] --> B{文件存在?} B -->|是| C[读取文件头 max 8MB] B -->|否| D[仅返回 image 文件] C --> E{解析 JSON 元数据} E -->|成功| F[提取 ssmd_cover_images] E -->|失败| D F --> G[Base64 解码图片] G --> H[返回预览图片流] ``` 资料来源：[app/model_manager.py:54-73]() ## API 端点 ComfyUI 通过 aiohttp 提供模型相关的 REST API。 ### 实验性端点 以下端点为实验性功能，用于探索新的模型管理接口： #### GET /experiment/models 获取所有模型文件夹类型列表。 ```python @routes.get("/experiment/models") async def get_model_folders(request): model_types = list(folder_paths.folder_names_and_paths.keys()) folder_black_list = ["configs", "custom_nodes"] output_folders: list[dict] = [] for folder in model_types: if folder in folder_black_list: continue output_folders.append({"name": folder, "folders": folder_paths.get_folder_paths(folder)}) return web.json_response(output_folders) ``` **响应格式** ```json [ { "name": "checkpoints", "folders": ["/path/to/models/checkpoints"] }, { "name": "loras", "folders": ["/path/to/models/loras"] } ] ``` 资料来源：[app/model_manager.py:49-60]() #### GET /experiment/models/{folder} 获取指定文件夹中的所有模型文件。 **路径参数** | 参数 | 类型 | 说明 | |------|------|------| | folder | string | 模型类型名称（如 checkpoints、loras、vae） | 资料来源：[app/model_manager.py:62-65]() ## 模型存储结构 ComfyUI 采用规范的目录结构管理不同类型的模型文件： ```mermaid graph TD A[models/] --> B[checkpoints/] A --> C[loras/] A --> D[vae/] A --> E[controlnet/] A --> F[embeddings/] A --> G[upscale_models/] A --> H[vae_approx/] A --> I[custom_nodes/] B --> B1[.ckpt, .safetensors] C --> C1[.safetensors] F --> F1[.pt, .bin] H --> H2[taesd_decoder.pth] ``` **嵌入模型使用** 嵌入模型放置在 `models/embeddings` 目录后，可在 CLIPTextEncode 节点中通过前缀引用： ``` embedding:embedding_filename.pt ``` 注意：扩展名 `.pt` 可省略。 资料来源：[README.md:1-5]() ## 预览图片生成 ### TAESD 高质量预览 ComfyUI 支持使用 TAESD (Temporal Audio Encoding Super Resolution for Diffusion) 实现高质量的潜在空间预览。 **安装步骤** 1. 下载以下文件到 `models/vae_approx` 目录： - `taesd_decoder.pth` - `taesdxl_decoder.pth` - `taesd3_decoder.pth` - `taef1_decoder.pth` 2. 使用 `--preview-method taesd` 参数启动 **命令行配置** ```bash python main.py --preview-method taesd ``` | 参数值 | 说明 | |--------|------| | `auto` | 启用预览（默认低分辨率） | | `taesd` | TAESD 高质量预览 | | `none` | 禁用预览 | 资料来源：[README.md:7-15]() ## 模型路径配置 ComfyUI 支持通过配置文件自定义模型搜索路径。配置文件模板位于仓库根目录： ``` extra_model_paths.yaml.example ``` 该配置允许用户： - 设置额外的模型搜索目录 - 共享其他 Stable Diffusion UI 的模型目录 - 避免重复下载相同模型 资料来源：[README.md:1-5]() ## 相关模型类型 ComfyUI 原生支持多种模型类型： | 模型类型 | 目录 | 用途 | |----------|------|------| | 检查点模型 | checkpoints | 完整 Stable Diffusion 模型 | | LoRA | loras | 轻量级模型微调 | | VAE | vae | 变分自编码器 | | ControlNet | controlnet | 条件控制网络 | | 嵌入模型 | embeddings | 文本反转嵌入 | | 超分模型 | upscale_models | 图像放大（ESRGAN、SwinIR 等） | | 超分模型 | vae_approx | TAESD 预览解码器 | **高级功能支持** - Textual Inversion（文本反转） - LoRA（regular、locon、loha） - Hypernetworks（超网络） - ControlNet 和 T2I-Adapter - GLIGEN - 模型合并 - LCM 模型和 Lora - 潜在预览（TAESD） 资料来源：[README.md:1-5]() ## 与其他模块的关系 ```mermaid graph LR A[model_manager.py] --> B[folder_paths] A --> C[comfy/utils] D[API Routes] --> A E[前端] --> D F[comfy/model_management] --> A C --> C1[safetensors_header] B --> B1[get_folder_paths] ``` - **folder_paths**：提供模型目录路径解析 - **comfy/utils**：提供 safetensors 文件头读取工具 - **API Routes**：暴露模型发现接口给前端 ## 最佳实践 1. **模型组织**：将不同类型的模型放置在对应目录，便于 ComfyUI 自动识别 2. **使用 safetensors**：优先使用 safetensors 格式，可自动提取预览图片 3. **预览性能**：如需高质量预览，安装 TAESD 解码器文件 4. **共享配置**：多用户环境下使用 `extra_model_paths.yaml` 共享模型目录 5. **离线工作**：核心功能完全离线运行，不会自动下载任何内容 --- ## 文本编码器系统 ### 相关页面 相关主题：[支持的模型列表](#page-supported-models), [节点系统与节点类型](#page-node-system)
相关源码文件 以下源码文件用于生成本页说明： - [comfy/clip_model.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/clip_model.py) - [comfy/sd1_clip.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/sd1_clip.py) - [comfy/sdxl_clip.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/sdxl_clip.py) - [comfy/text_encoders](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/text_encoders) - [comfy/ldm/modules/attention.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/ldm/modules/attention.py)
# 文本编码器系统 ## 概述 ComfyUI 的文本编码器系统是将自然语言提示词（Prompt）转换为神经网络可处理的数值向量的核心模块。该系统支持多种文本编码架构，包括 CLIP、T5 等，并提供了灵活的节点接口供工作流调用。文本编码器生成的向量表示直接决定了生成内容的语义准确性，是图像、视频、音频等多模态生成任务的关键环节。 ## 架构设计 ### 核心组件 ComfyUI 的文本编码器系统由以下核心模块组成： | 模块 | 文件路径 | 功能描述 | |------|----------|----------| | CLIP模型加载器 | `comfy/clip_model.py` | 加载和初始化CLIP模型权重 | | SD1 CLIP编码器 | `comfy/sd1_clip.py` | 处理Stable Diffusion 1.x系列的CLIP文本编码 | | SDXL CLIP编码器 | `comfy/sdxl_clip.py` | 处理SDXL系列的双CLIP编码（clip_l + clip_g） | | 文本编码器包 | `comfy/text_encoders/` | 存放多种文本编码器实现 | | 注意力模块 | `comfy/ldm/modules/attention.py` | 实现文本向量与图像特征的交叉注意力机制 | ### 系统流程图 ```mermaid graph TD A[用户输入 Prompt] --> B[CLIPTextEncode 节点] B --> C[文本预处理与分词] C --> D[CLIP模型编码] D --> E[条件向量 embedding] E --> F[扩散模型去噪] G[负向提示词 Negative] --> H[负面条件向量] E --> F H --> F F --> I[生成图像] ``` ## CLIPTextEncode 节点 ### 功能说明 `CLIPTextEncode` 是ComfyUI工作流中最常用的文本编码节点，负责将输入的文本提示词转换为条件向量。每个工作流通常包含正向提示词的编码节点和负向提示词的编码节点。 ### 使用方式 在 CLIPTextEncode 节点中使用嵌入文件时，可通过以下语法引用： ``` embedding:embedding_filename.pt ``` 其中 `.pt` 扩展名可以省略。资料来源：[README.md:1]() ### 节点输入输出 | 类型 | 名称 | 描述 | |------|------|------| | 输入 | text | 文本提示词字符串 | | 输入 | clip | CLIP模型引用 | | 输出 | CONDITIONING | 编码后的条件向量 | ## 支持的文本编码模型 ### Stable Diffusion 1.x 系列 SD1.x 系列使用单 CLIP 编码器架构，采用 `openai/clip-vit-large-patch14` 预训练权重。该编码器将文本转换为 768 维的向量表示。资料来源：[comfy/sd1_clip.py]() ### Stable Diffusion XL 系列 SDXL 系列采用双 CLIP 编码器设计，包含： - **CLIP-L**：与 SD1.x 类似的 ViT-L/14 编码器，输出 768 维向量 - **CLIP-G**：更大的 ViT-g/14 编码器，输出 1280 维向量 两个编码器的输出通过融合层合并，生成最终的条件向量。资料来源：[comfy/sdxl_clip.py]() ### Flux 系列 Flux 模型采用更先进的文本编码方案，支持更长的上下文长度和更精细的语义理解。 ## 分词器与词汇表 ### 分词过程 文本编码器系统的工作流程如下： ```mermaid graph LR A[原始文本] --> B[词汇表匹配] B --> C[分词 tokenization] C --> D[添加特殊标记] D --> E[Padding/截断] E --> F[转换为ID序列] F --> G[Embedding查找] G --> H[Transformer编码] H --> I[条件向量输出] ``` ### 特殊标记 系统支持以下特殊标记格式： | 标记格式 | 用途 | |----------|------| | `embedding:filename` | 加载文本嵌入文件 | | `()` | 括号内为权重系数 | ## 与注意力机制的集成 ### 交叉注意力机制 文本编码器输出的条件向量通过交叉注意力（Cross Attention）机制与图像特征进行交互。在 `comfy/ldm/modules/attention.py` 中实现了关键的注意力计算逻辑。资料来源：[comfy/ldm/modules/attention.py]() ### 注意力计算流程 ```mermaid graph TD A[图像特征 Query] --> D[注意力计算] B[文本向量 Key] --> D C[文本向量 Value] --> D D --> E[注意力权重矩阵] E --> F[加权求和] F --> G[特征增强] ``` ## 嵌入管理与加载 ### 嵌入文件位置 ComfyUI 在以下目录管理文本嵌入文件： ``` models/embeddings/ ``` ### 嵌入格式支持 系统支持以下嵌入文件格式： | 格式 | 说明 | |------|------| | `.pt` | PyTorch模型格式 | | `.safetensors` | SafeTensors安全格式 | ### 从图片元数据加载 系统支持从 PNG、WebP、FLAC 等图片文件的元数据中提取工作流信息，包括文本编码器相关的配置和嵌入数据。资料来源：[README.md:1]() ## 类型定义与接口 ComfyUI 提供了 `ComfyNodeABC` 抽象基类用于节点开发，文本编码器节点可通过继承该基类实现类型安全的开发： ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleTextEncoder(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` 资料来源：[comfy/comfy_types/README.md]() ## 配置与优化 ### 命令行选项 文本编码器系统可通过以下命令行参数进行配置： | 参数 | 说明 | |------|------| | `--disable-api-nodes` | 禁用API节点（包括部分文本处理功能） | | `--preview-method` | 预览生成方法，影响Latent预览质量 | ### 性能优化 系统采用惰性加载机制，仅在需要时才初始化文本编码器模型，以减少内存占用和启动时间。资料来源：[comfy/comfy_types/README.md]() ## 常见问题排查 ### 编码器加载失败 如果遇到文本编码器无法加载的问题，请检查： 1. 模型文件是否完整下载并放置在正确目录 2. PyTorch 是否正确安装并支持 CUDA（如使用GPU） 3. 依赖包版本是否满足 `requirements.txt` 要求 ### 内存优化 对于显存有限的环境，可考虑： - 使用量化后的CLIP模型 - 减少同时加载的编码器数量 - 利用系统的执行优化：仅执行图中输入完整的节点 ## 相关文档 - [工作流示例](https://comfyanonymous.github.io/ComfyUI_examples/) - [LoRA与文本反转](https://comfyanonymous.github.io/ComfyUI_examples/lora/) - [ControlNet与文本条件](https://comfyanonymous.github.io/ComfyUI_examples/controlnet/) --- ## 节点系统与节点类型 ### 相关页面 相关主题：[执行引擎与工作流](#page-execution-engine), [工作流模板与 Blueprints](#page-blueprints)
相关源码文件 以下源码文件用于生成本页说明： - [comfy/comfy_types/README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/comfy_types/README.md) - [comfy/comfy_types/node_typing.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/comfy_types/node_typing.py) - [app/subgraph_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/subgraph_manager.py) - [app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py) - [comfy_extras](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_extras)
# 节点系统与节点类型 ## 概述 ComfyUI 的节点系统是整个工作流引擎的核心，它采用模块化的图（Graph）结构来定义和管理 AI 生成任务。每个节点（Node）代表一个具体的计算单元，通过输入/输出端口与其他节点连接，形成完整的工作流程。 ComfyUI 的节点系统具备以下核心特性： - **类型安全**：提供强类型输入/输出定义 - **懒执行**：仅执行图中需要计算的部分 - **热重载**：支持自定义节点的动态加载 - **可扩展性**：允许通过自定义节点扩展功能 资料来源：[comfy/comfy_types/README.md:1-15]() ## 节点类型层级 ComfyUI 的节点类型采用层级化的组织结构： ```mermaid graph TD A[ComfyNodeABC] --> B[基础节点] A --> C[图像处理节点] A --> D[模型加载节点] A --> E[条件节点] B --> F[Latent 节点] B --> G[VAE 编解码节点] ``` ### 核心基类：ComfyNodeABC `ComfyNodeABC` 是所有节点的基础抽象类，提供统一的接口定义和类型提示支持。 ```python class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` 资料来源：[comfy/comfy_types/README.md:10-15]() ### 内置数据类型 ComfyUI 提供以下内置数据类型： | 类型标识 | 说明 | 实际值 | |---------|------|--------| | `ANY` | 任意类型 | `"*"` | | `NUMBER` | 数值类型（浮点或整数） | `"FLOAT,INT"` | | `PRIMITIVE` | 基础数据类型 | `"STRING,FLOAT,INT,BOOLEAN"` | 资料来源：[comfy/comfy_types/README.md:20-25]() ## 输入类型系统 ### INPUT_TYPES 结构 每个节点必须定义 `INPUT_TYPES` 类方法，返回值包含以下键： ```python { "required": {}, # 必需输入 "optional": {}, # 可选输入 "hidden": {} # 隐藏输入 } ``` ### 输入选项配置 节点开发者可以为每个输入定义详细选项： | 选项 | 说明 | 示例 | |------|------|------| | `default` | 默认值 | `{"default": 1.0}` | | `min`/`max` | 数值范围 | `{"min": 0, "max": 100}` | | `step` | 步进值 | `{"step": 0.1}` | | `forceInput` | 强制从连线获取 | `{"forceInput": True}` | 资料来源：[comfy/comfy_types/README.md:35-45]() ## 子图系统 ComfyUI 支持将多个节点封装为子图（Subgraph），便于工作流的复用和模块化管理。 ```mermaid graph TD A[子图入口] --> B[子节点1] A --> C[子节点2] B --> D[子图出口] C --> D ``` ### 子图数据结构 ```python class SubgraphEntry(TypedDict): source: str # 来源：custom_node 或 templates path: str # 相对路径 name: str # 子图文件名 info: dict # 附加信息 data: str # 子图数据 ``` 资料来源：[app/subgraph_manager.py:15-35]() ### 子图来源 | 来源类型 | 说明 | |---------|------| | `custom_node` | 自定义节点目录中的子图 | | `templates` | 内置模板子图 | 资料来源：[app/subgraph_manager.py:10-14]() ## 模型管理与节点集成 ComfyUI 的模型管理器与节点系统紧密集成，负责处理模型文件的发现、加载和缓存。 ### 模型文件匹配逻辑 ```python # 模型加载节点会根据 basename 匹配以下文件： # - basename.png / jpg / webp # - basename.safetensors # - basename_preview.png (预览图) ``` 资料来源：[app/model_manager.py:35-55]() ### Safetensors 元数据 支持从 `.safetensors` 文件中读取嵌入的元数据和封面图像： ```python safetensors_metadata = json.loads(header) safetensors_images = safetensors_metadata.get("__metadata__", {}).get("ssmd_cover_images", None) ``` 资料来源：[app/model_manager.py:50-55]() ## 节点执行模型 ### 懒执行机制 ComfyUI 采用懒执行（Lazy Execution）策略： > 只有当节点的输出端口连接了其他节点且所有必需输入都就绪时，该节点才会被执行。 ### 执行优化规则 | 规则 | 说明 | |------|------| | 局部执行 | 仅执行输出被使用的节点 | | 缓存复用 | 相同输入的节点不会重复执行 | | 增量更新 | 仅重新执行变更的节点及其下游节点 | 资料来源：[README.md:执行相关说明]() ## 自定义节点开发 ### 基础模板 ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class MyCustomNode(ComfyNodeABC, CheckLazyMixin): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return { "required": { "model": ("MODEL",), "clip": ("CLIP",), }, "optional": { "vae": ("VAE",), } } RETURN_TYPES = ("MODEL",) FUNCTION = "process" CATEGORY = "custom" def process(self, model, clip, vae=None): # 处理逻辑 return (processed_model,) ``` ### 类型提示支持 Visual Studio Code 等 IDE 可为 `INPUT_TYPES` 提供自动补全： ```python def INPUT_TYPES(s) -> InputTypeDict: # IDE 会提示正确的类型和结构 ``` 资料来源：[comfy/comfy_types/README.md:25-40]() ## 常见节点类型 | 类别 | 功能 | 代表节点 | |------|------|---------| | **模型加载** | 加载检查点模型 | CheckpointLoader, LoadCheckpoint | | **采样器** | 执行降噪采样 | KSampler, SamplerCustom | | **条件** | 构建条件向量 | CLIPTextEncode, ControlNet | | **图像处理** | 图像解码/编码 | VAEDecode, VAEEncode | | **Latent** | 潜在空间操作 | EmptyLatentImage, LatentUpscale | | **输出** | 结果保存 | SaveImage, PreviewImage | ## 扩展节点集 `comfy_extras` 模块提供了额外的节点类型，包括但不限于： - 高级采样器算法 - 图像增强工具 - 额外的模型格式支持 - 性能优化工具 ## 总结 ComfyUI 的节点系统采用清晰的抽象层级设计，通过 `ComfyNodeABC` 基类提供统一的开发接口。类型系统确保了节点间的数据传递安全，而子图机制则支持复杂工作流的模块化管理。懒执行模型和增量更新策略保证了大规模工作流的高效运行。 --- ## 工作流模板与 Blueprints ### 相关页面 相关主题：[节点系统与节点类型](#page-node-system), [执行引擎与工作流](#page-execution-engine)
相关源码文件 以下源码文件用于生成本页说明： - [app/frontend_management.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/frontend_management.py) - [comfy/comfy_types/README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/comfy_types/README.md) - [README.md](https://github.com/Comfy-Org/ComfyUI/blob/main/README.md) - [app/user_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/user_manager.py) - [app/model_manager.py](https://github.com/Comfy-Org/ComfyUI/blob/main/app/model_manager.py)
# 工作流模板与 Blueprints ## 概述 ComfyUI 中的工作流模板（Workflow Templates）和 Blueprints 是用于标准化、可复用和快速部署 AI 生成工作流的机制。这些功能使用户能够保存复杂的工作流配置，并在不同环境或用户之间轻松共享。 Blueprints 是 ComfyUI 系统中模板的核心实现方式，它们以结构化格式定义工作流的节点图、参数配置和资源路径。资料来源：[app/frontend_management.py:1-1]() ## 核心概念 ### 工作流模板的架构 ComfyUI 的工作流模板系统包含以下几个关键组件： | 组件 | 描述 | 资料来源 | |------|------|----------| | 模板定义 | JSON/元数据格式的工作流描述 | [README.md:1-1]() | | 模板资产 | 与模板关联的图像、配置文件等资源 | [app/frontend_management.py:80-90]() | | 模板解析器 | 加载和验证模板的模块 | [app/frontend_management.py:60-75]() | | UI 集成 | 前端展示和选择模板的界面 | [app/frontend_management.py:45-55]() | ### 模板资源映射机制 ComfyUI 通过 `template_asset_map()` 方法维护模板资产名称到绝对路径的映射关系。资料来源：[app/frontend_management.py:70-90]() ```python def template_asset_map(cls) -> Optional[Dict[str, str]]: """Return a mapping of template asset names to their absolute paths.""" try: from comfyui_workflow_templates import ( get_asset_path, iter_templates, ) except ImportError: logging.error(...) return None ``` ## 工作流模板包 ### comfyui_workflow_templates 包 工作流模板通过独立的 pip 包 `comfyui_workflow_templates` 分发，与 ComfyUI 核心代码分离管理。资料来源：[app/frontend_management.py:74-85]() ``` comfyui_workflow_templates/ ├── templates/ # 模板定义文件 ├── assets/ # 关联资源（图像、配置等） └── __init__.py # 包入口 ``` ### 模板资产解析流程 ```mermaid graph TD A[用户选择模板] --> B[加载模板元数据] B --> C{检查资产可用性} C -->|资产存在| D[解析资产路径] C -->|资产缺失| E[记录错误日志] D --> F[构建完整工作流] F --> G[前端渲染节点图] ``` ## Blueprints 系统 ### Blueprints 目录结构 Blueprints 存储在仓库根目录的 `blueprints` 文件夹中，包含以下子目录： | 目录 | 用途 | 资料来源 | |------|------|----------| | `blueprints/` | 主要蓝图定义文件 | [blueprints](https://github.com/Comfy-Org/ComfyUI/blob/main/blueprints) | | `blueprints/.glsl/` | GLSL 着色器代码 | [blueprints/.glsl](https://github.com/Comfy-Org/ComfyUI/blob/main/blueprints/.glsl) | ### GLSL 集成 ComfyUI 的 Blueprints 系统支持 GLSL 着色器，这些着色器通过 `comfy_extras/nodes_glsl.py` 模块与节点系统集成。资料来源：[comfy_extras/nodes_glsl.py](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_extras/nodes_glsl.py) GLSL 着色器允许在 Blueprints 中实现自定义图像处理和特效节点。 ## 模板管理 API ### 模板版本检查 ComfyUI 实现了模板包的版本验证机制：资料来源：[app/frontend_management.py:30-45]() ```python def check_frontend_version(): """Check if the frontend version is up to date.""" try: frontend_version_str = get_installed_frontend_version() frontend_version = parse_version(frontend_version_str) required_frontend_str = get_required_frontend_version() ``` ### 版本解析规则 | 规则 | 描述 | |------|------| | 格式要求 | X.Y.Z（主版本.次版本.修订号） | | 解析方式 | 按点号分割并转换为整数元组 | | 验证正则 | `^(\d+)\.(\d+)\.(\d+)$` | 资料来源：[app/frontend_management.py:20-30]() ## 工作流保存与加载 ### 文件格式支持 ComfyUI 支持多种工作流保存格式：资料来源：[README.md:1-1]() | 格式 | 扩展名 | 特性 | |------|--------|------| | JSON | `.json` | 纯文本，可读性强 | | PNG | `.png` | 嵌入元数据，包含种子值 | | WebP | `.webp` | 支持有损压缩 | | FLAC | `.flac` | 音频格式元数据 | ### 用户数据管理 工作流模板与用户数据通过 `UserManager` 类管理，支持多用户环境：资料来源：[app/user_manager.py:1-30]() ```python class UserManager(): def __init__(self): user_directory = folder_paths.get_user_directory() self.settings = AppSettings(self) ``` ## ComfyUI-Manager 集成 ComfyUI-Manager 扩展提供了模板和工作流的安装、更新、管理功能：资料来源：[README.md:ComfyUI-Manager]() ### 启用方式 ```bash python main.py --enable-manager ``` ### 管理功能 | 功能 | 描述 | |------|------| | 安装自定义节点 | 扩展工作流能力 | | 更新管理 | 保持节点和模板最新 | | 模板同步 | 在多设备间同步工作流 | | 安全检查 | 验证节点来源可信性 | ## 类型系统与节点定义 ### ComfyNodeABC 基类 工作流模板中的节点通过 `ComfyNodeABC` 抽象基类定义：资料来源：[comfy/comfy_types/README.md:1-20]() ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` ### 输入类型定义 | 类型 | 描述 | |------|------| | `IO.ANY` | 接受任意类型 `"*"` | | `IO.NUMBER` | 数值类型 `"FLOAT,INT"` | | `IO.PRIMITIVE` | 基本类型 `"STRING,FLOAT,INT,BOOLEAN"` | 资料来源：[comfy/comfy_types/README.md:10-25]() ## 最佳实践 ### 模板开发建议 1. **版本锁定**：在模板元数据中明确依赖的包版本 2. **资源封装**：将模板相关资源打包在同一目录结构下 3. **路径相对化**：使用相对路径确保模板可移植性 4. **节点验证**：确保所有依赖节点已安装或提供安装指引 ### 性能考虑 - 模板加载时会检查资产完整性，应提前验证资源可用性 - 大型模板建议使用增量加载机制 - GLSL 着色器应进行预编译验证 ## 故障排除 ### 常见问题 | 问题 | 解决方案 | |------|----------| | 模板资产缺失 | 检查 `comfyui_workflow_templates` 包是否正确安装 | | 版本不匹配 | 使用 `pip install -U comfyui-workflow-templates` 更新 | | 节点类型未找到 | 通过 ComfyUI-Manager 安装缺失节点 | | 蓝图加载失败 | 检查 `blueprints/` 目录权限和文件完整性 | ### 诊断命令 ```bash # 检查模板包版本 pip show comfyui-workflow-templates # 验证蓝图目录 ls -la blueprints/ # 检查前端包依赖 python -c "from app.frontend_management import check_frontend_version; check_frontend_version()" ``` ## 总结 ComfyUI 的工作流模板与 Blueprints 系统提供了强大的工作流复用和分享能力。通过模块化的模板设计、独立的资源管理和灵活的节点类型系统，用户可以高效地构建、分享和部署复杂的 AI 生成工作流。Blueprints 作为模板的核心实现，结合 GLSL 着色器支持和类型安全的节点定义，为高级用户和开发者提供了极大的灵活性。 --- ## 服务器与 API 接口 ### 相关页面 相关主题：[系统架构设计](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [server.py](https://github.com/Comfy-Org/ComfyUI/blob/main/server.py) - [api_server](https://github.com/Comfy-Org/ComfyUI/blob/main/api_server) - [comfy_api](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy_api) - [protocol.py](https://github.com/Comfy-Org/ComfyUI/blob/main/protocol.py) - [openapi.yaml](https://github.com/Comfy-Org/ComfyUI/blob/main/openapi.yaml) - [script_examples](https://github.com/Comfy-Org/ComfyUI/blob/main/script_examples)
# 服务器与 API 接口 ## 概述 ComfyUI 的服务器与 API 接口系统是整个框架的核心通信层，负责处理客户端请求、管理用户会话、提供模型访问、管理工作流执行以及前端资源分发。该系统基于 aiohttp 异步 Web 框架构建，支持高性能并发请求处理，同时提供 TLS/SSL 加密传输能力。 ComfyUI 的架构采用前后端分离设计，后端服务器负责处理业务逻辑和模型管理，前端通过 RESTful API 与之通信。所有核心功能都通过 HTTP/HTTPS 接口暴露，供前端界面、第三方工具和自动化脚本调用。 ## 架构设计 ### 系统组件架构 ComfyUI 的服务器系统由多个协同工作的模块组成： ```mermaid graph TD A[客户端/前端] -->|HTTP/HTTPS| B[API Server] B --> C[用户管理 UserManager] B --> D[模型管理 ModelFileManager] B --> E[前端管理 FrontendManagement] B --> F[内部路由 Internal Routes] C --> G[AppSettings] D --> H[folder_paths] B --> I[Comfy API] I --> J[protocol.py] ``` ### 服务启动流程 服务器在启动时执行以下初始化步骤： 1. 解析命令行参数和配置文件 2. 初始化文件夹路径管理系统 3. 加载用户设置和用户目录 4. 注册所有 API 路由 5. 配置中间件和安全策略 6. 启动 aiohttp Web 服务器 ## API 服务器核心 ### 服务入口 服务器主入口文件 `server.py` 负责初始化和启动整个 Web 服务。该文件定义了应用的生命周期管理、路由注册和请求处理逻辑。 API 服务器支持以下启动方式： ```python python main.py ``` ### 路由注册机制 API 服务器采用模块化路由注册方式，不同功能模块通过 `add_routes()` 方法注册自己的路由： | 模块 | 功能 | 主要路由 | |------|------|----------| | UserManager | 用户数据管理 | `/v2/userdata` | | ModelFileManager | 模型文件访问 | `/experiment/models/*` | | FrontendManagement | 前端资源服务 | `/system_stats`, `/api/*` | ### TLS/SSL 配置 ComfyUI 支持通过 TLS/SSL 加密通信以确保数据传输安全。要启用 HTTPS，需要提供证书和私钥文件： **证书生成命令：** ```bash openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" ``` **启动参数：** ```bash python main.py --tls-keyfile key.pem --tls-certfile cert.pem ``` 启用后，服务将通过 `https://...` 协议访问。 ## 用户管理模块 ### UserManager 类 用户管理模块 (`app/user_manager.py`) 负责管理用户数据和会话状态。在单用户模式下，系统使用默认用户配置；在多用户模式下，支持完整的用户隔离和管理功能。 ### 用户目录结构 用户数据存储在专用目录中，通过 `folder_paths.get_user_directory()` 获取。首次启动时，如果目录不存在，系统会自动创建。 ### API 端点 #### 列出用户数据 **端点：** `GET /v2/userdata` **查询参数：** | 参数 | 类型 | 说明 | |------|------|------| | path | string | 相对路径，默认为空（根目录） | | recurse | boolean | 是否递归列出子目录，默认为 false | | full_info | boolean | 是否返回完整文件信息，默认为 false | | split | boolean | 是否分割路径为数组，默认为 false | **返回值：** ```python # full_info = false 时返回 str | list[str] # 文件路径或路径数组 # full_info = true 时返回 FileInfo: { "path": str, # 相对路径 "size": int, # 文件大小（字节） "modified": int, # 修改时间（毫秒时间戳） "created": int # 创建时间（毫秒时间戳） } ``` **错误码：** - `400`：请求路径无效、超出用户数据目录范围或路径不是目录 - `404`：请求路径不存在 ### 多用户支持 启用多用户模式需要在启动时添加 `--multi-user` 参数： ```bash python main.py --multi-user ``` 在此模式下，用户数据相互隔离，每个用户拥有独立的工作流、设置和历史记录。 ## 模型管理模块 ### ModelFileManager 类 模型管理模块 (`app/model_manager.py`) 提供对模型文件的访问和管理功能。该模块实现了模型目录浏览、模型元数据读取和模型预览图片获取等功能。 ### 实验性模型路由 #### 获取模型文件夹列表 **端点：** `GET /experiment/models` **响应示例：** ```json [ { "name": "checkpoints", "folders": ["/path/to/models/checkpoints"] }, { "name": "loras", "folders": ["/path/to/models/loras"] } ] ``` #### 获取特定文件夹中的所有模型 **端点：** `GET /experiment/models/{folder}` ### 模型预览机制 ModelFileManager 支持多种模型预览格式，包括： - 与模型同名的 `.preview.png` 文件 - SafeTensor 格式嵌入的封面图片（存储在 `__metadata__.ssmd_cover_images` 中） 当查询模型时，系统会自动收集并返回相关的预览资源。 ### 缓存机制 模型管理模块实现了内存缓存以提高性能： ```python class ModelFileManager: def __init__(self) -> None: self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {} def clear_cache(self): self.cache.clear() ``` 缓存键基于模型路径和查询参数，缓存内容包含文件列表、修改时间和元数据。 ## 前端管理模块 ### FrontendManagement 类 前端管理模块 (`app/frontend_management.py`) 负责 ComfyUI 前端资源的分发和版本管理。 ### 前端版本检查 系统会自动检查已安装的前端包版本是否与要求匹配： ```python def check_frontend_version(): frontend_version_str = get_installed_frontend_version() required_frontend_str = get_required_frontend_version() # 版本比较逻辑... ``` 版本不匹配时会输出警告信息，提示用户更新前端包。 ### 前端路径管理 前端静态文件存储在 pip 包 `comfyui_frontend_package` 中，系统通过 `importlib.resources` 动态定位资源路径。 ### 工作流模板 系统支持工作流模板功能，模板文件存储在 `comfyui_workflow_templates` 包中： ```python def template_asset_map(cls) -> Optional[Dict[str, str]]: from comfyui_workflow_templates import get_asset_path, iter_templates # 返回模板资源名称到绝对路径的映射 ``` ## ComfyUI-Manager 扩展 ### 简介 ComfyUI-Manager 是一个可选扩展，用于简化自定义节点的安装、更新和管理。 ### 安装与启用 1. 安装依赖： ```bash pip install -r manager_requirements.txt ``` 2. 启用管理器： ```bash python main.py --enable-manager ``` ### 管理器相关参数 | 参数 | 说明 | |------|------| | `--enable-manager` | 启用 ComfyUI-Manager | | `--enable-manager-legacy-ui` | 使用旧版管理器 UI（需配合 `--enable-manager`） | | `--disable-manager-ui` | 禁用管理器 UI，保留后台功能（需配合 `--enable-manager`） | ## API 协议 ### protocol.py `protocol.py` 文件定义了 ComfyUI 的通信协议规范，包括消息格式、请求/响应结构等内部协议细节。 ### OpenAPI 规范 ComfyUI 提供完整的 OpenAPI 规范文档 (`openapi.yaml`)，定义了所有公开 API 的结构、参数和响应格式。该规范可用于： - 生成客户端 SDK - 自动化 API 测试 - 文档自动生成 ## 执行模型 ### 图执行策略 ComfyUI 的图执行采用增量计算策略： 1. **部分执行**：只有输出端具有所有正确输入的图部分才会被执行 2. **变更检测**：仅执行与上次执行相比发生变化的节点 3. **依赖追踪**：自动追踪节点间的数据依赖关系 ```mermaid graph LR A[提交工作流] --> B{检测变更} B -->|无变更| C[跳过执行] B -->|部分变更| D[执行变更节点及依赖] B -->|完整变更| E[执行全部节点] ``` ### 工作流持久化 系统支持通过 API 保存和加载工作流： - 支持的工作流格式：JSON - 支持嵌入元数据的图片格式：PNG、WebP、FLAC ## 脚本示例 `script_examples` 目录包含与 API 交互的示例脚本，可供参考学习 API 的使用方法。 ## 安全考虑 ### 内部路由 所有位于 `/internal` 路径下的路由仅供 ComfyUI 内部使用，可能在任何版本中变更而无需提前通知。外部应用不应依赖这些端点。 ### 路径遍历防护 API 服务器实现了路径遍历防护机制，用户数据请求被限制在用户目录范围内，防止越权访问。 ### 异步安全 服务器采用 aiohttp 异步框架，所有 I/O 操作均为非阻塞，支持高并发连接。 ## 命令行参数汇总 | 参数 | 说明 | |------|------| | `--tls-keyfile ` | TLS 私钥文件路径 | | `--tls-certfile ` | TLS 证书文件路径 | | `--enable-manager` | 启用 Manager 扩展 | | `--multi-user` | 启用多用户模式 | | `--preview-method auto\|taesd` | 设置预览生成方法 | | `--disable-api-nodes` | 禁用 API 节点 | | `--disable-manager-ui` | 禁用 Manager UI | ## 参考资料 - ComfyUI 官方文档与 README.md - 各模块源码文件中的内联文档和类型定义 --- --- ## Doramagic 踩坑日志 项目：Comfy-Org/ComfyUI 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。 ## 1. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `comfyui` 与安装入口 `comfy-cli` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。 - 复现命令：`pip install comfy-cli` - 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。 - 证据：identity.distribution | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | repo=comfyui; install=comfy-cli ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | last_activity_observed missing ## 4. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | release_recency=unknown