> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-willie-des-1087-router-migration-block.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy API：Serverless 部署

> 构建版本化的 ComfyUI 环境，将其部署为托管端点，并通过 API 运行工作流。

<Warning>
  Comfy API 的部署服务目前处于测试版（beta）阶段。请前往 [platform.comfy.org](https://platform.comfy.org) 注册以获取访问权限。
</Warning>

Comfy API 可让你将 ComfyUI 工作流部署为具备按需 GPU 算力的托管式自动扩缩容端点。**Build** 是 ComfyUI 环境的版本化定义，包含从本地安装中获取的模型、自定义节点和设置。Build and Deploy CLI 将 Build 定义保存在你的项目中，基于该定义创建发布版本（release），并在某发布版本准备好对外提供服务时将其部署。

<CardGroup cols={2}>
  <Card title="1. 构建（Build）" icon="box">
    从你的本地 ComfyUI 安装创建本地 Build 定义。
  </Card>

  <Card title="2. 发布（Release）" icon="tag">
    从 Build 切出一个不可变的 Linux/NVIDIA 发布版本。
  </Card>

  <Card title="3. 部署（Deploy）" icon="cloud-arrow-up">
    为发布版本分配 URL 和托管 GPU 算力。
  </Card>

  <Card title="4. 运行（Run）" icon="code">
    向处于活动状态的部署提交 API 格式的工作流。
  </Card>
</CardGroup>

## 快速开始

当本地安装和 API 格式的工作流准备就绪后，使用以下命令：

利用 compute 命令的输出选择有效的区域和 GPU。按需替换 `<region>` 和 `l4`；将 `deploy up` 打印的部署 ID 复制到最后一条命令中。

```bash theme={null}
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 # get available regions and GPU classes
comfy deploy up --gpu l4 --region <region> --min 1 --max 4 --watch # prints the deployment ID
comfy deploy run --workflow workflow_api.json --deployment <deployment-id> --output-dir ./results
```

<Steps>
  <Step title="初始化">
    ```bash theme={null}
    comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
    ```
  </Step>

  <Step title="创建发布版本">
    ```bash theme={null}
    comfy build push --release --target linux/nvidia
    ```

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

  <Step title="启动部署">
    如果你尚不清楚有哪些可用的区域和 GPU 类型，请先查询：

    ```bash theme={null}
    comfy deploy refs compute
    ```

    然后创建或协调部署：

    ```bash theme={null}
    comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
    ```

    `deploy up` 会打印新的部署 ID。如果之后需要取回它，可以列出该 Build 处于就绪状态的部署：

    ```bash theme={null}
    comfy deploy ls --status ready
    ```

    将返回的 `dep_...` 值用于 `--deployment`。
  </Step>

  <Step title="运行工作流">
    ```bash theme={null}
    comfy deploy run \
      --workflow workflow_api.json \
      --deployment <deployment-id> \
      --output-dir ./results
    ```

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

## 构建文件

`comfy-build.yaml` 是 Build 的本地事实来源（source of truth）。它保存 Build 定义和最近一次已知的远程状态，因此 CLI 可以自动选择正确的 Build，并在本地更改覆盖较新的远程定义之前发出警告。

请将此文件与项目放在一起。它描述的是 Build，本身并不包含模型字节。

## 1. 初始化 Build

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

```bash theme={null}
comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
```

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

```bash theme={null}
comfy build status
```

## 2. 更新与发布

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

```bash theme={null}
comfy build update --yes
```

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

```bash theme={null}
comfy build push --release --target linux/nvidia
```

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

```bash theme={null}
comfy build refs build-targets
comfy build release create --target linux/nvidia --watch
```

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

```bash theme={null}
comfy build release logs rel_123456 --target linux/nvidia --follow
```

## 区域与 GPU 可用性

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

```bash theme={null}
comfy deploy refs compute
```

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

```bash theme={null}
comfy deploy refs compute --region <region>
```

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

```bash theme={null}
comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
```

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

## 3. 部署发布版本

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

```bash theme={null}
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 格式的工作流](/zh/development/api-development/workflow-api-format)：

```bash theme={null}
comfy deploy run \
  --workflow workflow_api.json \
  --deployment dep_123456 \
  --output-dir ./results
```

也可以通过 [Comfy SDK](/zh/development/api-development/sdks) 调用该端点，只需将 `COMFY_BASE_URL` 设置为部署 URL。SDK 请求仍需要 API 密钥：参见[选择基础 URL](/zh/development/api-development/sdks#选择基础-url)。

## 运维部署

```bash theme={null}
# 修改工作节点数量上下限
comfy deploy scale --deployment dep_123456 --min 2 --max 5

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

## 查看与清理

```bash theme={null}
# Build state
comfy build ls
comfy build show --id bld_123456
comfy build release ls
comfy build release show rel_123456

# Deployment state
comfy deploy ls --workspace --status ready
comfy deploy logs --deployment dep_123456
comfy deploy events --deployment dep_123456
```

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

## FAQ

<AccordionGroup>
  <Accordion title="Comfy API 部署能提供什么？">
    Comfy API 部署是一个托管、可自动扩缩容的端点，用于运行 API 格式的工作流。使用 `comfy deploy run` 或 [Comfy SDK](/zh/development/api-development/sdks) 提交工作流。
  </Accordion>

  <Accordion title="一个 Build 可以来自多个工作流吗？">
    可以。在 Builder 中上传一个或多个工作流，以预选它们的模型和自定义节点。请包含你计划运行的所有工作流所需的依赖关系，然后将每个 API 格式的工作流提交到已部署的端点。

    每个部署使用一种 GPU 类型。要在不同的 GPU 类型上运行工作流，请为同一个 Build 创建多个独立的部署。
  </Accordion>

  <Accordion title="未部署的 Build 存储是否收费？">
    不会。Build 及其发布版本免费存储在你的账户中。在部署之前，Build 的存储占用不会产生费用。

    存储计费从部署开始：

    * 当你部署某个发布版本时，其模型会被暂存到该部署的 worker 所共享的网络存储上。部署完成后该存储为只读，并且只要该 Build 在该区域存在任何部署，就会按每 GB-月计费，包括使用 `comfy deploy stop` 暂停部署期间。
    * 每个 worker 还会获得一个固定的 50 GB 容器磁盘。它是临时的，仅在 worker 运行时作为其计算成本的一部分计费。
    * 删除部署会释放其计算资源。在该区域使用该 Build 的最后一个部署被删除后不久，暂存的网络存储会被清理，其计费也随之结束。

    当前的存储费率请参见 [Comfy 定价页面](https://www.comfy.org/pricing)。计算目录（`comfy deploy refs compute`）和部署对话框也会显示适用于该部署的费率。
  </Accordion>

  <Accordion title="活跃 worker 如何计费，每小时费率是多少？">
    `--min` 设置 **活跃 worker** 的数量：这些 worker 始终保持运行，因此请求永远不会等待冷启动。活跃 worker 在整个运行期间按秒计费，无论它是否正在处理任务。

    超过 `--min`、最多到 `--max` 的 worker 是 **弹性 worker**。弹性 worker 从启动那一刻起（包括启动和模型加载）按秒计费，贯穿任务处理过程，再加上一个短暂的闲置窗口（当前为 30 秒）后才会缩容。弹性 worker 缩容后不产生任何费用。使用 `--min 0` 时，整个部署会缩容到零，空闲时不产生计算费用，代价是首次请求会有冷启动。

    计费按 worker 的实际每秒使用量乘以正在运行的 worker 数量来计算。如果你的工作区积分已用完，部署会被自动停止。

    当前的每 worker GPU 费率请参见 [Comfy 定价页面](https://www.comfy.org/pricing)。费率以每 worker-小时报价，并按秒计费。各区域的 GPU 可用性来自计算目录：运行 `comfy deploy refs compute` 可获取当前列表。
  </Accordion>

  <Accordion title="部署如何处理多个请求？">
    部署会自动将请求分发到各个 worker，并在配置的 `--min` 和 `--max` 范围内扩缩容。无法立即运行的请求会被排队，并在 worker 容量可用时依次处理。
  </Accordion>

  <Accordion title="如果预配耗时很长，我该怎么办？">
    跟踪部署状态，然后检查其日志和事件以找出原因：

    ```bash theme={null}
    comfy deploy status --deployment <deployment-id> --watch
    comfy deploy logs --deployment <deployment-id>
    comfy deploy events --deployment <deployment-id>
    ```

    如果所选 GPU 或区域没有容量，请稍后重试，或运行 `comfy deploy refs compute` 选择一个可用的区域和 GPU 组合。寻求帮助时，请附上 Build、发布版本和部署 ID。
  </Accordion>

  <Accordion title="删除部署时会发生什么？">
    删除部署会移除其端点并释放其计算资源。它不会删除 Build 或其发布版本。在你删除某区域中使用该 Build 的最后一个部署后，其暂存的网络存储会被清理，存储计费也会随之很快结束。

    删除 Build 是另一项单独的操作：`comfy build delete --id <build-id> --yes`。
  </Accordion>
</AccordionGroup>

## 后续步骤

* [Comfy SDK](/zh/development/api-development/sdks)
* [Comfy API v2 概览](/zh/api-reference/v2/overview)
* [工作流 API 格式](/zh/development/api-development/workflow-api-format)
* [Comfy CLI 参考](/zh/comfy-cli/reference)