Serverless API

Serverless API 目前处于测试版（beta）阶段。请前往 platform.comfy.org 注册以获取访问权限。

Serverless API 为 ComfyUI 工作流提供托管 URL 和按需 GPU 算力。新的 Build and Deploy CLI 将构建定义保存在你的项目中，基于该定义创建发布版本（release），并在准备好对外提供服务时部署某个发布版本。

1. 构建（Build）

从你的本地 ComfyUI 安装创建构建规格文件。

2. 发布（Release）

从 Build 切出一个不可变的 Linux/NVIDIA 发布版本。

3. 部署（Deploy）

为发布版本分配 URL 和托管 GPU 算力。

4. 运行（Run）

向处于活动状态的部署提交 API 格式的工作流。

快速开始

当本地安装和 API 格式的工作流准备就绪后，使用以下命令：利用 compute 命令的输出选择有效的区域和 GPU。按需替换 <region> 和 l4；将 deploy up 打印的部署 ID 复制到最后一条命令中。

comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes

comfy build push --release --target linux/nvidia
comfy deploy refs compute # 获取可用区域和 GPU 类型
comfy deploy up --gpu l4 --region <region> --min 1 --max 4 --watch # 打印部署 ID
comfy deploy run --workflow workflow_api.json --deployment <deployment-id> --output-dir ./results

初始化

comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes

创建发布版本

comfy build push --release --target linux/nvidia

该命令会同步 Build 并为指定目标创建一个发布版本。

启动部署

如果你还不确定所选 GPU 在哪些区域可用，请先查询：

comfy deploy refs compute --region <region>

然后创建或调整（reconcile）部署：

comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch

deploy up 会打印新的部署 ID。如需稍后再获取，可列出当前 Build 处于就绪状态的部署：

comfy deploy ls --status ready

将返回的 dep_... 值用于 --deployment 参数。

运行工作流

comfy deploy run \
  --workflow workflow_api.json \
  --deployment <deployment-id> \
  --output-dir ./results

CLI 会提交 API 格式的工作流，并将其输出下载到 ./results。

构建文件

comfy-build.yaml 是 Build 的本地事实来源（source of truth）。它保存构建定义和最近一次已知的远程状态，因此 CLI 可以自动选择正确的 Build，并在本地更改可能覆盖较新的远程定义时发出警告。请将此文件与项目放在一起。它只描述 Build，本身不包含模型文件的内容。

1. 初始化 Build

从本地 ComfyUI 安装开始。该命令会扫描模型和自定义节点，然后写入 comfy-build.yaml。

comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes

在推送之前，检查本地规格与本地安装及远程 Build 的差异：

comfy build status

2. 更新与发布

修改本地 ComfyUI 安装后，刷新本地构建定义：

comfy build update --yes

若想走快捷路径，可用一条命令推送定义并为目标发布：

comfy build push --release --target linux/nvidia

当需要从现有 Build 创建另一个发布版本时，先查看支持的构建目标，再显式切出发布版本：

comfy build refs build-targets
comfy build release create --target linux/nvidia --watch

跟踪某个发布版本的构建日志：

comfy build release logs rel_123456 --target linux/nvidia --follow

区域与 GPU 可用性

区域容量会变化，因此不要在脚本中硬编码静态列表。选择部署目标时，请查询平台目录：

comfy deploy refs compute

使用 --region <region> 过滤结果：

comfy deploy refs compute --region <region>

将返回的 region 和 gpu 组合复制到 comfy deploy up 中：

comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch

在部署时，该目录是各区域可用 GPU 类型的事实来源。

3. 部署发布版本

先查询区域内可用的算力，然后为所选发布版本创建或调整部署：

comfy deploy refs compute --region US-MO-2

comfy deploy up \
  --gpu l4 \
  --region US-MO-2 \
  --min 1 \
  --max 4 \
  --watch

--min 和 --max 设置工作节点（worker）数量的上下限。使用 comfy deploy status --watch 跟踪部署健康状况、发布版本新旧程度以及服务活动。

4. 运行工作流

向就绪的部署提交 API 格式的工作流：

comfy deploy run \
  --workflow workflow_api.json \
  --deployment dep_123456 \
  --output-dir ./results

也可以通过 Comfy SDK 调用该端点，只需将 COMFY_BASE_URL 设置为部署 URL。SDK 请求仍需要 API 密钥：参见选择基础 URL。

运维部署

# 修改工作节点数量上下限
comfy deploy scale --deployment dep_123456 --min 2 --max 5

# 暂停或恢复，同时保留部署记录
comfy deploy stop --deployment dep_123456
comfy deploy start --deployment dep_123456

查看与清理

# Build 状态
comfy build ls
comfy build show --id bld_123456
comfy build release ls
comfy build release show rel_123456

# 部署状态
comfy deploy ls --workspace --status ready
comfy deploy logs --deployment dep_123456
comfy deploy events --deployment dep_123456

删除部署与删除 Build 是两个相互独立且不可逆的操作。在使用 comfy deploy delete --yes 或 comfy build delete --id bld_123456 --yes 之前，请确认操作对象。

使用 Comfy 开发

运行工作流

Comfy CLI

规范

1. 构建（Build）

2. 发布（Release）

3. 部署（Deploy）

4. 运行（Run）

快速开始

构建文件

1. 初始化 Build

2. 更新与发布

区域与 GPU 可用性

3. 部署发布版本

4. 运行工作流

运维部署

查看与清理

后续步骤

1. 构建（Build）

2. 发布（Release）

3. 部署（Deploy）

4. 运行（Run）

​快速开始

​构建文件

​1. 初始化 Build

​2. 更新与发布

​区域与 GPU 可用性

​3. 部署发布版本

​4. 运行工作流

​运维部署

​查看与清理

​后续步骤

快速开始

构建文件

1. 初始化 Build

2. 更新与发布

区域与 GPU 可用性

3. 部署发布版本

4. 运行工作流

运维部署

查看与清理

后续步骤