comfyui

OpenMontage 中的 ComfyUI 工作流

在调用 comfyui_image、comfyui_video 或 comfyui_music 前，以及将社区 ComfyUI 工作流转换为 OpenMontage 工具调用时，请先使用此技能。

服务约定

• 工具生成内容前，ComfyUI 必须正在运行。默认服务为 http://localhost:8188；使用 COMFYUI_SERVER_URL 可覆盖此设置。
• 是否要为不同能力运行单独的 ComfyUI 实例（使用不同的 GPU 或模型集）？COMFYUI_IMAGE_SERVER_URL / COMFYUI_VIDEO_SERVER_URL / COMFYUI_MUSIC_SERVER_URL 分别仅对对应工具生效，并覆盖 COMFYUI_SERVER_URL。此项可选——单服务设置无需使用这些变量。
• 健康状态和硬件状态来自 GET /system_stats。
• 任务通过 POST /prompt 提交，已完成的输出通过 GET /history/{prompt_id} 读取，资源文件字节通过 GET /view 下载。
• 对于长时间等待的视频和音乐任务，优先使用 ComfyUI 的 WebSocket 推送，以便立即检测完成或错误；如果未安装 websocket-client，则会自动回退到 REST 轮询。无论哪种方式，超时都可以恢复：将错误中的 prompt_id 作为 resume_prompt_id 传回，即可继续等待同一任务，而无需重新提交。
• 使用 ComfyUI 的 API 格式 JSON 导出工作流，而非 UI 布局格式。如果下载的工作流无法提交，请在 ComfyUI 中启用 API 格式并重新导出。

合作方节点由托管服务运行

• comfyui_video 中的 gemini_omni_flash、seedance_2.5 和 minimax_h3_api 是官方 ComfyUI 合作方节点。它们会调用托管 API，需要网络访问权限、已登录的 Comfy 账户和预付额度。
• 不要仅仅因为工作流在本地 ComfyUI 进程中运行，就将合作方节点描述为本地运行、离线或免费。
• minimax_h3_local 是单独的开放权重方案。它需要以 API 格式导出的官方 MiniMax H3 工作流、其 output_node，以及工具报告的模型堆栈。

选择工作流

• 请求的操作与捆绑工作流匹配，且本机具备所需模型和 VRAM 时，请使用捆绑工作流。
• 用户需要社区配方、更低 VRAM 占用的模型、不同风格系列或自定义节点时，请使用自定义 workflow_json 或 workflow_path。
• 对于 8GB-12GB GPU，优先选择占用较低的工作流，例如 Wan 2.1 1.3B、LTXV FP8 或量化工作流，或 Wan 2.2 GGUF/量化社区工作流。捆绑的 Wan 2.2 14B FP8 视频工作流需要 16GB 级别的显存，并非所有方案的最低要求。
• 不要保证任意自定义工作流都能在某台机器上运行。实际资源需求取决于工作流、量化方式、分辨率、帧数和卸载设置。

输出节点约定

• 自定义工作流必须传入 output_node。
• 选择写入资源文件的节点，通常是 SaveImage、SaveVideo、VHS_VideoCombine 或其他终端保存节点。
• 将节点 ID 作为字符串传入，例如 "108"。不要传入类名。
• 如果工作流有多个保存节点，请选择最终交付内容对应的节点，而非预览或中间节点。

模板化节点与固定节点

• 执行前识别模板化节点：提示词文本、种子、尺寸、帧数、源图像、采样器设置和输出文件名前缀。
• 固定节点包括模型加载器、VAE、文本编码器、LoRA 加载器、调度器和工作流图连接。除非工作流作者本就希望进行相应自定义，否则不要修改这些内容。
• 对于社区工作流，运行前请检查每个加载器节点，并记录所有必需的模型或自定义节点。缺失的模型应通过工具提供的结构化 missing_models 数据处理（如果可用）。

视频工作流需要时序潜变量

• 视频工作流的空潜变量节点必须是视频潜变量——Wan 2.2 t2v 使用 EmptyHunyuanLatentVideo，图像条件变体使用 Wan22ImageToVideoLatent 或 WanImageToVideo。帧数填入 length；batch_size 表示要生成的独立视频片段数量，应保持为 1。
• 将 EmptyLatentImage 的 batch_size 设为帧数是个陷阱：它会要求生成 N 张互不相关的图像。生成的 MP4 帧数、时长和编解码器都正确，通过 ffprobe 检查也没有问题——但画面只会闪烁。运行任何不熟悉的视频工作流之前，请先检查潜变量节点。

模型和 LoRA 设置

• 有可用选项时，请使用 ComfyUI Manager 或工作流作者提供的模型链接，并遵守模型许可证。
• 将模型放入加载器节点要求的文件夹：扩散模型放在 ComfyUI/models/diffusion_models/，文本编码器放在 ComfyUI/models/text_encoders/，VAE 放在 ComfyUI/models/vae/，LoRA 放在 ComfyUI/models/loras/。
• 对于 LoRA 堆栈，请在工作流中使用 LoraLoader 或 LoraLoaderModelOnly 链。记录每个 LoRA 的名称，以及适用时的 strength_model 和 strength_clip。
• 当前的 ComfyUI 工具不会将 LoRA 注入任意图中。要使用 LoRA，请提供已包含 LoRA 加载器链的工作流，并传递模型堆栈来源信息。

来源信息

• 对于自定义工作流，请在已知时提供 workflow_name 和 workflow_model。
• 如果工作流未打包在一起，请提供 workflow_model_stack 以便复现。包括基础检查点或扩散模型、量化方式、文本编码器、VAE、LoRA 及其强度、采样器或调度器、步数，以及工作流提供的引导参数。
• 工具会记录最终工作流哈希。请将该哈希与模型堆栈、种子、尺寸和提示词一并视为复现约定。

故障处理

• 如果服务不可用，请显示结构化的设置提示。启动 ComfyUI 或设置 COMFYUI_SERVER_URL 是首要解决方法。
• 如果缺少模型，请读取 data.missing_models[]；每个条目应包含文件名、用途、目标路径提示，以及 OpenMontage 知道时提供的下载 URL。
• 如果缺少自定义节点，请让用户通过 ComfyUI Manager 或工作流作者记录的安装方式进行安装，然后重启 ComfyUI。
• 如果本地长时间渲染超时，请先检查 ComfyUI 历史记录，再从头重试；服务端可能已经完成了提示词任务——或者直接再次调用，并将 resume_prompt_id 设为超时错误中的 prompt_id。

音乐（comfyui_music）

• 捆绑的默认工作流是 ACE-Step v1（3.5B）文本转音频，基于 ComfyUI 的原生 TextEncodeAceStepAudio/EmptyAceStepLatentAudio 节点构建（核心节点，而非第三方扩展包）——与 ACE-Step 1.5 或其他自定义节点包不同，v1 的接口足够标准化，可以安全地捆绑。
• prompt 映射到捆绑工作流的 tags 字段（风格／流派／情绪，例如 "upbeat electronic pop, female vocals"），符合 suno_music 使用的同一种“prompt = 音乐描述”惯例。lyrics 是单独的可选字段——纯器乐曲目请留空；也可以使用 [verse]/[chorus]/[bridge] 结构标签，以及 [zh]/[ja]/[ko] 这类语言代码前缀来标注非英语歌词。
• 可以调整捆绑工作流中的 duration_seconds、steps、cfg、lyrics_strength 和 seed。缺少 ace_step_v1_3.5b.safetensors 时，会通过与图像／视频相同的 data.missing_models[] 契约提示。
• 需要 ACE-Step 1.5、其他节点包或非 ACE-Step 音频模型？请像使用自定义图像／视频工作流一样，改用 workflow_json/workflow_path + output_node——在这种模式下，prompt 会再次仅用于记录来源／日志，且必须已预先写入图中。
• output_node（捆绑工作流或自定义工作流）应为写入最终音频的节点——捆绑工作流中该节点为 SaveAudioMP3。客户端会从该节点的 "audio" 输出键读取生成内容（相当于图像／视频保存节点的 "images"）。
• 对于自定义工作流，请像为自定义图像／视频工作流提供来源信息一样，提供 workflow_name/workflow_model/workflow_model_stack。