runpod-worker-comfy

在RunPod上作为无服务器API的ComfyUI

阅读我们的文章：https://blib.la/blog/comfyui-on-runpod

→ 也请查看Captain: AI平台

快速开始
功能
配置
- 上传图片到AWS S3
在RunPod上使用Docker镜像
API规范
- JSON请求体
- 字段
  - "input.images"
与RunPod API交互
- 健康状态
- 生成图像
  - 使用cURL的示例请求
如何从ComfyUI获取工作流？
使用自己的模型和节点
- 网络卷
- 自定义Docker镜像
本地测试
使用GitHub Actions自动部署到Docker Hub
致谢

快速开始

🐳 为您的无服务器端点选择以下三个可用镜像之一：
- timpietruskyblibla/runpod-worker-comfy:3.0.0-base：不包含任何检查点，只是一个干净的ComfyUI
- timpietruskyblibla/runpod-worker-comfy:3.0.0-sdxl：包含Stable Diffusion XL的检查点和VAE
  - 检查点：sd_xl_base_1.0.safetensors
  - VAE：
    - sdxl_vae.safetensors
    - sdxl-vae-fp16-fix
- timpietruskyblibla/runpod-worker-comfy:3.0.0-sd3：包含Stable Diffusion 3的sd3_medium_incl_clips_t5xxlfp8.safetensors检查点
ℹ️ 在RunPod上使用Docker镜像

功能

运行任何ComfyUI工作流来生成图像
提供base64编码字符串形式的输入图像
生成的图像可以：
- 作为base64编码字符串返回（默认）
- 上传到AWS S3（如果配置了AWS S3）
有三种不同的Docker镜像可供选择：
- timpietruskyblibla/runpod-worker-comfy:3.0.0-base：不包含任何内容，只是一个干净的ComfyUI
- timpietruskyblibla/runpod-worker-comfy:3.0.0-sdxl：包含Stable Diffusion XL的检查点和VAE
- timpietruskyblibla/runpod-worker-comfy:3.0.0-sd3：包含Stable Diffusion 3的检查点
使用自己的模型
基于Ubuntu + NVIDIA CUDA

配置

环境变量	描述	默认值
`REFRESH_WORKER`	当您希望在每个作业完成后停止工作程序以获得干净状态时，请参阅官方文档。	`false`
`COMFY_POLLING_INTERVAL_MS`	轮询尝试之间的等待时间（毫秒）。	`250`
`COMFY_POLLING_MAX_RETRIES`	最大轮询尝试次数。随着工作流运行时间的增加，应该增加此值。	`500`
`SERVE_API_LOCALLY`	为开发和测试启用本地API服务器。有关更多详细信息，请参阅本地测试。	禁用

上传图片到AWS S3

只有在您想将生成的图片上传到AWS S3时才需要这样做。如果您不配置此项，您的图像将作为base64编码字符串导出。

在您选择的区域的AWS S3中创建一个存储桶（BUCKET_ENDPOINT_URL）
创建一个具有AWS S3访问权限的IAM
为该IAM创建一个访问密钥（BUCKET_ACCESS_KEY_ID 和 BUCKET_SECRET_ACCESS_KEY）
为您的RunPod工作程序配置以下环境变量：

环境变量	描述	示例
`BUCKET_ENDPOINT_URL`	S3存储桶的端点URL。	`https://<bucket>.s3.<region>.amazonaws.com`
`BUCKET_ACCESS_KEY_ID`	用于访问S3存储桶的AWS访问密钥ID。	`AKIAIOSFODNN7EXAMPLE`
`BUCKET_SECRET_ACCESS_KEY`	用于访问S3存储桶的AWS秘密访问密钥。	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`

在RunPod上使用Docker镜像

通过点击New Template创建一个新模板
在对话框中配置：
- 模板名称：runpod-worker-comfy（可以是任何您想要的名称）
- 模板类型：serverless（将模板类型更改为"serverless"）
- 容器镜像：<dockerhub用户名>/<仓库名称>:标签，在这种情况下：timpietruskyblibla/runpod-worker-comfy:3.0.0-sd3（或-base用于干净镜像，或-sdxl用于Stable Diffusion XL）
- 容器注册凭证：您可以保留所有内容不变，因为此仓库是公开的
- 容器磁盘：20 GB
- （可选）环境变量：配置S3
  - 注意：您也可以不配置它，图像将保留在工作程序中。为了永久存储它们，我们必须添加网络卷
点击Save Template
导航到Serverless > Endpoints并点击New Endpoint
在对话框中配置：
- 端点名称：comfy
- 选择模板：runpod-worker-comfy（或您给模板起的任何名称）
- 活动工作程序：0（根据您的需求而定）
- 最大工作程序：3（根据您的需求而定）
- 空闲超时：5（您可以保留默认值）
- 快速启动：启用（不会增加成本，但可以更快地启动我们的工作程序，这是好的）
- （可选）高级：如果您使用网络卷，请在Select Network Volume下选择它。否则保留默认设置。
- 选择一个有可用性的GPU
- 每个工作程序的GPU：1
点击deploy
您的端点将被创建，您可以点击它查看仪表板

API规范

以下描述了在向API发送请求时存在的字段。我们只描述通过input发送的字段，因为这些字段是工作程序本身所需的。有关完整的字段列表，请查看官方文档。

JSON请求体

{
  "input": {
    "workflow": {},
    "images": [
      {
        "name": "example_image_name.png",
        "image": "base64_encoded_string"
      }
    ]
  }
}

字段

字段路径	类型	必需	描述
`input`	对象	是	包含请求数据的顶级对象。
`input.workflow`	对象	是	包含ComfyUI工作流配置。
`input.images`	数组	否	图像数组。每个图像将被添加到ComfyUI的"input"文件夹中，然后可以在工作流中使用其`name`来引用

"input.images"

一个图像数组，其中每个图像应该有不同的名称。 🚨 RunPod端点的请求体大小限制为：/run接口10 MB，/runsync接口20 MB。请确保您的输入图像不要过大，否则会被RunPod阻止。详见官方文档

字段名	类型	是否必需	描述
`name`	字符串	是	图像的名称。请在工作流中使用相同的名称引用图像
`image`	字符串	是	图像的base64编码字符串

与RunPod API交互

生成API密钥:
- 在用户设置中，点击API Keys，然后点击API Key按钮。
- 将生成的密钥保存在安全的地方，因为离开页面后将无法再次查看。
使用API密钥:
- 使用cURL或其他工具，通过API密钥和端点ID访问API：
  - 将<api_key>替换为您的密钥。
使用您的端点:
- 将<endpoint_id>替换为端点ID。（点击端点可以找到ID；它显示在端点名称下方，也是底部显示的URL的一部分。）

如何找到端点ID

健康状态

curl -H "Authorization: Bearer <api_key>" https://api.runpod.ai/v2/<endpoint_id>/health

生成图像

您可以使用/run异步创建新任务，或使用/runsync同步创建。此处示例使用同步任务，等待响应返回。

API期望此格式的JSON，其中workflow是从ComfyUI导出的JSON格式工作流，images是可选的。

请参考test_input.json查看API输入应该是什么样子。

使用cURL的请求示例

curl -X POST -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" -d '{"input":{"workflow":{"3":{"inputs":{"seed":1337,"steps":20,"cfg":8,"sampler_name":"euler","scheduler":"normal","denoise":1,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]},"class_type":"KSampler"},"4":{"inputs":{"ckpt_name":"sd_xl_base_1.0.safetensors"},"class_type":"CheckpointLoaderSimple"},"5":{"inputs":{"width":512,"height":512,"batch_size":1},"class_type":"EmptyLatentImage"},"6":{"inputs":{"text":"beautiful scenery nature glass bottle landscape, purple galaxy bottle,","clip":["4",1]},"class_type":"CLIPTextEncode"},"7":{"inputs":{"text":"text, watermark","clip":["4",1]},"class_type":"CLIPTextEncode"},"8":{"inputs":{"samples":["3",0],"vae":["4",2]},"class_type":"VAEDecode"},"9":{"inputs":{"filename_prefix":"ComfyUI","images":["8",0]},"class_type":"SaveImage"}}}}' https://api.runpod.ai/v2/<endpoint_id>/runsync

AWS S3存储桶配置的响应示例

{
  "delayTime": 2188,
  "executionTime": 2297,
  "id": "sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1",
  "output": {
    "message": "https://bucket.s3.region.amazonaws.com/10-23/sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1/c67ad621.png",
    "status": "success"
  },
  "status": "COMPLETED"
}

base64编码图像的响应示例

{
  "delayTime": 2188,
  "executionTime": 2297,
  "id": "sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1",
  "output": { "message": "base64encodedimage", "status": "success" },
  "status": "COMPLETED"
}

如何从ComfyUI获取工作流？

在浏览器中打开ComfyUI
打开设置（菜单右上角的齿轮图标）
在弹出的对话框中配置：
- 启用开发模式选项：打开
- 关闭设置
在菜单中，点击保存（API格式）按钮，将下载一个名为workflow_api.json的文件

现在您可以把这个文件的内容放入与API交互时的workflow中。

使用自定义模型和节点

网络卷

使用网络卷可以存储和访问自定义模型：

创建网络卷:
- 按照RunPod网络卷指南创建卷。

填充卷:

创建临时GPU实例：
- 导航到管理 > 存储，点击卷下的部署，部署任意GPU或CPU实例。
- 导航到管理 > Pods。在新pod下，点击连接打开shell（通过Jupyter笔记本或SSH）。

用模型填充卷：

cd /workspace
for i in checkpoints clip clip_vision configs controlnet embeddings loras upscale_models vae; do mkdir -p models/$i; done
wget -O models/checkpoints/sd_xl_turbo_1.0_fp16.safetensors https://huggingface.co/stabilityai/sdxl-turbo/resolve/main/sd_xl_turbo_1.0_fp16.safetensors

删除临时GPU实例:
- 填充完成后，终止临时GPU实例。
配置端点:
- 在端点配置中使用网络卷：
  - 创建新端点或更新现有端点。
  - 在端点配置的高级 > 选择网络卷下，选择您的网络卷。

注意：当配置并附加网络卷时，ComfyUI可自动访问网络卷中的文件夹。

自定义Docker镜像

如果您更喜欢直接在Docker镜像中包含模型，请按以下步骤操作：

Fork仓库:
- 将此仓库fork到您自己的GitHub账户。

在Dockerfile中添加模型:

编辑Dockerfile以包含您的模型：

RUN wget -O models/checkpoints/sd_xl_base_1.0.safetensors https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

您也可以添加自定义节点：

RUN git clone https://github.com/<username>/<custom-node-repo>.git custom_nodes/<custom-node-repo>

构建Docker镜像:

在本地构建base镜像：

docker build -t <your_dockerhub_username>/runpod-worker-comfy:dev-base --target base --platform linux/amd64 .

在本地构建sdxl镜像：

docker build --build-arg MODEL_TYPE=sdxl -t <your_dockerhub_username>/runpod-worker-comfy:dev-sdxl --platform linux/amd64 .

在本地构建sd3镜像：

docker build --build-arg MODEL_TYPE=sd3 --build-arg HUGGINGFACE_ACCESS_TOKEN=<your-huggingface-token> -t <your_dockerhub_username>/runpod-worker-comfy:dev-sd3 --platform linux/amd64 .

[!注意]
确保指定--platform linux/amd64以避免在RunPod上出错，参见问题#13。

本地测试

两种测试都将使用test_input.json中的数据，请在那里做适当修改以进行正确测试。

设置

确保您的Python版本 >= 3.10
创建虚拟环境：
```
python -m venv venv
```

激活虚拟环境：

Windows:
```
.\venv\Scripts\activate
```
Mac / Linux:
```
source ./venv/bin/activate
```

安装依赖：
```
pip install -r requirements.txt
```

Windows设置

按照本指南安装WSL2和Linux发行版（如Ubuntu）。您可以跳过"安装和使用GUI包"部分。
安装Ubuntu后，打开终端并登录：
```
wsl -d Ubuntu
```
更新软件包：
```
sudo apt update
```
在Ubuntu中安装Docker：
- 遵循Docker官方安装指南。
- 安装docker-compose：
```
sudo apt-get install docker-compose
```
- 在Ubuntu中安装NVIDIA工具包：按照此指南创建nvidia运行时。
在WSL2的Ubuntu上启用GPU加速：遵循此指南。
- 如果您已在Windows上安装了GPU驱动程序，可以跳过"为WSL安装适当的Windows vGPU驱动程序"步骤。
将您的用户添加到docker组以无需sudo即可使用Docker：
```
sudo usermod -aG docker $USER
```

完成这些步骤后，在终端中切换到Ubuntu并通过WSL在Windows计算机上本地运行Docker镜像：

wsl -d Ubuntu

测试RunPod处理程序

运行所有测试：python -m unittest discover
如果要运行特定测试：python -m unittest tests.test_rp_handler.TestRunpodWorkerComfy.test_bucket_endpoint_not_configured

您还可以启动处理程序本身以运行本地服务器：python src/rp_handler.py 要使其正常工作，您还需要启动"ComfyUI"，否则处理程序将无法工作。

本地API

为了增强本地开发，您可以启动一个模拟RunPod工作环境的API服务器。这个功能对于在本地调试和测试您的集成特别有用。

运行Docker容器时，将SERVE_API_LOCALLY环境变量设置为true以激活本地API服务器。这已经是docker-compose.yml中的默认值，因此您可以通过执行以下命令来运行：

docker-compose up

访问本地Worker API

本地API服务器运行后，可在以下地址访问：localhost:8000
在浏览器中打开此地址时，您还可以查看API文档并直接与API交互

访问本地ComfyUI

本地API服务器运行时，您可以在以下地址访问ComfyUI：localhost:8188

使用GitHub Actions自动部署到Docker Hub

该仓库包含两个工作流，使用GitHub Actions将镜像发布到Docker Hub：

dev.yml：在每次推送到main分支时创建镜像并将其推送到Docker Hub，标记为dev
release.yml：创建镜像并将其推送到Docker Hub，标记为latest和发布标签。仅在GitHub上创建发布时触发

如果要使用此功能，您应该向仓库添加以下密钥：

配置变量	描述	示例值
`DOCKERHUB_USERNAME`	您的Docker Hub用户名	`your-username`
`DOCKERHUB_TOKEN`	用于认证的Docker Hub令牌	`your-token`
`HUGGINGFACE_ACCESS_TOKEN`	您的Hugging Face READ访问令牌	`your-access-token`