Upload README.md with huggingface_hub
Browse files
README.md
ADDED
@@ -0,0 +1,442 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1 |
+
# runpod-worker-comfy
|
2 |
+
|
3 |
+
> [ComfyUI](https://github.com/comfyanonymous/ComfyUI) as a serverless API on [RunPod](https://www.runpod.io/)
|
4 |
+
|
5 |
+
<p align="center">
|
6 |
+
<img src="assets/worker_sitting_in_comfy_chair.jpg" title="Worker sitting in comfy chair" />
|
7 |
+
</p>
|
8 |
+
|
9 |
+
Read our article here: https://blib.la/blog/comfyui-on-runpod
|
10 |
+
|
11 |
+
[![Discord](https://img.shields.io/discord/1091306623819059300?color=7289da&label=Discord&logo=discord&logoColor=fff&style=for-the-badge)](https://discord.com/invite/m3TBB9XEkb)
|
12 |
+
|
13 |
+
→ Please also checkout [Captain: The AI Platform](https://github.com/blib-la/captain)
|
14 |
+
|
15 |
+
---
|
16 |
+
|
17 |
+
<!-- toc -->
|
18 |
+
|
19 |
+
- [Quickstart](#quickstart)
|
20 |
+
- [Features](#features)
|
21 |
+
- [Config](#config)
|
22 |
+
* [Upload image to AWS S3](#upload-image-to-aws-s3)
|
23 |
+
- [Use the Docker image on RunPod](#use-the-docker-image-on-runpod)
|
24 |
+
* [Create your template (optional)](#create-your-template-optional)
|
25 |
+
* [Create your endpoint](#create-your-endpoint)
|
26 |
+
* [GPU recommendations](#gpu-recommendations)
|
27 |
+
- [API specification](#api-specification)
|
28 |
+
* [JSON Request Body](#json-request-body)
|
29 |
+
* [Fields](#fields)
|
30 |
+
+ ["input.images"](#inputimages)
|
31 |
+
- [Interact with your RunPod API](#interact-with-your-runpod-api)
|
32 |
+
* [Health status](#health-status)
|
33 |
+
* [Generate an image](#generate-an-image)
|
34 |
+
+ [Example request for SDXL with cURL](#example-request-for-sdxl-with-curl)
|
35 |
+
- [How to get the workflow from ComfyUI?](#how-to-get-the-workflow-from-comfyui)
|
36 |
+
- [Bring Your Own Models and Nodes](#bring-your-own-models-and-nodes)
|
37 |
+
* [Network Volume](#network-volume)
|
38 |
+
* [Custom Docker Image](#custom-docker-image)
|
39 |
+
- [Local testing](#local-testing)
|
40 |
+
* [Setup](#setup)
|
41 |
+
+ [Setup for Windows](#setup-for-windows)
|
42 |
+
* [Testing the RunPod handler](#testing-the-runpod-handler)
|
43 |
+
* [Local API](#local-api)
|
44 |
+
+ [Access the local Worker API](#access-the-local-worker-api)
|
45 |
+
+ [Access local ComfyUI](#access-local-comfyui)
|
46 |
+
- [Automatically deploy to Docker hub with GitHub Actions](#automatically-deploy-to-docker-hub-with-github-actions)
|
47 |
+
- [Acknowledgments](#acknowledgments)
|
48 |
+
|
49 |
+
<!-- tocstop -->
|
50 |
+
|
51 |
+
---
|
52 |
+
|
53 |
+
## Quickstart
|
54 |
+
|
55 |
+
- 🐳 Choose one of the five available images for your serverless endpoint:
|
56 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-base`: doesn't contain anything, just a clean ComfyUI
|
57 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-flux1-schnell`: contains the checkpoint, text encoders and VAE for [FLUX.1 schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell)
|
58 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-flux1-dev`: contains the checkpoint, text encoders and VAE for [FLUX.1 dev](https://huggingface.co/black-forest-labs/FLUX.1-dev)
|
59 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-sdxl`: contains the checkpoint and VAE for [Stable Diffusion XL](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0)
|
60 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-sd3`: contains the checkpoint for [Stable Diffusion 3 medium](https://huggingface.co/stabilityai/stable-diffusion-3-medium)
|
61 |
+
- ℹ️ [Use the Docker image on RunPod](#use-the-docker-image-on-runpod)
|
62 |
+
- 🧪 Pick an [example workflow](./test_resources/workflows/) & [send it to your deployed endpoint](#interact-with-your-runpod-api)
|
63 |
+
|
64 |
+
## Features
|
65 |
+
|
66 |
+
- Run any [ComfyUI](https://github.com/comfyanonymous/ComfyUI) workflow to generate an image
|
67 |
+
- Provide input images as base64-encoded string
|
68 |
+
- The generated image is either:
|
69 |
+
- Returned as base64-encoded string (default)
|
70 |
+
- Uploaded to AWS S3 ([if AWS S3 is configured](#upload-image-to-aws-s3))
|
71 |
+
- There are a few different Docker images to choose from:
|
72 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-flux1-schnell`: contains the [flux1-schnell.safetensors](https://huggingface.co/black-forest-labs/FLUX.1-schnell) checkpoint, the [clip_l.safetensors](https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/clip_l.safetensors) + [t5xxl_fp8_e4m3fn.safetensors](https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/t5xxl_fp8_e4m3fn.safetensors) text encoders and [ae.safetensors](https://huggingface.co/black-forest-labs/FLUX.1-schnell/resolve/main/ae.safetensors) VAE for FLUX.1-schnell
|
73 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-flux1-dev`: contains the [flux1-dev.safetensors](https://huggingface.co/black-forest-labs/FLUX.1-dev) checkpoint, the [clip_l.safetensors](https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/clip_l.safetensors) + [t5xxl_fp8_e4m3fn.safetensors](https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/t5xxl_fp8_e4m3fn.safetensors) text encoders and [ae.safetensors](https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/ae.safetensors) VAE for FLUX.1-dev
|
74 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-sdxl`: contains the checkpoints and VAE for Stable Diffusion XL
|
75 |
+
- Checkpoint: [sd_xl_base_1.0.safetensors](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0)
|
76 |
+
- VAEs:
|
77 |
+
- [sdxl_vae.safetensors](https://huggingface.co/stabilityai/sdxl-vae/)
|
78 |
+
- [sdxl-vae-fp16-fix](https://huggingface.co/madebyollin/sdxl-vae-fp16-fix/)
|
79 |
+
- `timpietruskyblibla/runpod-worker-comfy:3.1.0-sd3`: contains the [sd3_medium_incl_clips_t5xxlfp8.safetensors](https://huggingface.co/stabilityai/stable-diffusion-3-medium) checkpoint for Stable Diffusion 3 medium
|
80 |
+
- [Bring your own models](#bring-your-own-models)
|
81 |
+
- Based on [Ubuntu + NVIDIA CUDA](https://hub.docker.com/r/nvidia/cuda)
|
82 |
+
|
83 |
+
## Config
|
84 |
+
|
85 |
+
| Environment Variable | Description | Default |
|
86 |
+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
87 |
+
| `REFRESH_WORKER` | When you want to stop the worker after each finished job to have a clean state, see [official documentation](https://docs.runpod.io/docs/handler-additional-controls#refresh-worker). | `false` |
|
88 |
+
| `COMFY_POLLING_INTERVAL_MS` | Time to wait between poll attempts in milliseconds. | `250` |
|
89 |
+
| `COMFY_POLLING_MAX_RETRIES` | Maximum number of poll attempts. This should be increased the longer your workflow is running. | `500` |
|
90 |
+
| `SERVE_API_LOCALLY` | Enable local API server for development and testing. See [Local Testing](#local-testing) for more details. | disabled |
|
91 |
+
|
92 |
+
### Upload image to AWS S3
|
93 |
+
|
94 |
+
This is only needed if you want to upload the generated picture to AWS S3. If you don't configure this, your image will be exported as base64-encoded string.
|
95 |
+
|
96 |
+
- Create a bucket in region of your choice in AWS S3 (`BUCKET_ENDPOINT_URL`)
|
97 |
+
- Create an IAM that has access rights to AWS S3
|
98 |
+
- Create an Access-Key (`BUCKET_ACCESS_KEY_ID` & `BUCKET_SECRET_ACCESS_KEY`) for that IAM
|
99 |
+
- Configure these environment variables for your RunPod worker:
|
100 |
+
|
101 |
+
| Environment Variable | Description | Example |
|
102 |
+
| -------------------------- | ------------------------------------------------------- | -------------------------------------------- |
|
103 |
+
| `BUCKET_ENDPOINT_URL` | The endpoint URL of your S3 bucket. | `https://<bucket>.s3.<region>.amazonaws.com` |
|
104 |
+
| `BUCKET_ACCESS_KEY_ID` | Your AWS access key ID for accessing the S3 bucket. | `AKIAIOSFODNN7EXAMPLE` |
|
105 |
+
| `BUCKET_SECRET_ACCESS_KEY` | Your AWS secret access key for accessing the S3 bucket. | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
|
106 |
+
|
107 |
+
## Use the Docker image on RunPod
|
108 |
+
|
109 |
+
### Create your template (optional)
|
110 |
+
|
111 |
+
- Create a [new template](https://runpod.io/console/serverless/user/templates) by clicking on `New Template`
|
112 |
+
- In the dialog, configure:
|
113 |
+
- Template Name: `runpod-worker-comfy` (it can be anything you want)
|
114 |
+
- Template Type: serverless (change template type to "serverless")
|
115 |
+
- Container Image: `<dockerhub_username>/<repository_name>:tag`, in this case: `timpietruskyblibla/runpod-worker-comfy:3.1.0-sd3` (or `-base` for a clean image or `-sdxl` for Stable Diffusion XL or `-flex1-schnell` for FLUX.1 schnell)
|
116 |
+
- Container Registry Credentials: You can leave everything as it is, as this repo is public
|
117 |
+
- Container Disk: `20 GB`
|
118 |
+
- (optional) Environment Variables: [Configure S3](#upload-image-to-aws-s3)
|
119 |
+
- Note: You can also not configure it, the images will then stay in the worker. In order to have them stored permanently, [we have to add the network volume](https://github.com/blib-la/runpod-worker-comfy/issues/1)
|
120 |
+
- Click on `Save Template`
|
121 |
+
|
122 |
+
### Create your endpoint
|
123 |
+
|
124 |
+
- Navigate to [`Serverless > Endpoints`](https://www.runpod.io/console/serverless/user/endpoints) and click on `New Endpoint`
|
125 |
+
- In the dialog, configure:
|
126 |
+
|
127 |
+
- Endpoint Name: `comfy`
|
128 |
+
- Worker configuration: Select a GPU that can run the model you have chosen (see [GPU recommendations](#gpu-recommendations))
|
129 |
+
- Active Workers: `0` (whatever makes sense for you)
|
130 |
+
- Max Workers: `3` (whatever makes sense for you)
|
131 |
+
- GPUs/Worker: `1`
|
132 |
+
- Idle Timeout: `5` (you can leave the default)
|
133 |
+
- Flash Boot: `enabled` (doesn't cost more, but provides faster boot of our worker, which is good)
|
134 |
+
- Select Template: `runpod-worker-comfy` (or whatever name you gave your template)
|
135 |
+
- (optional) Advanced: If you are using a Network Volume, select it under `Select Network Volume`. Otherwise leave the defaults.
|
136 |
+
|
137 |
+
- Click `deploy`
|
138 |
+
- Your endpoint will be created, you can click on it to see the dashboard
|
139 |
+
|
140 |
+
### GPU recommendations
|
141 |
+
|
142 |
+
| Model | Image | Minimum VRAM Required | Container Size |
|
143 |
+
| ------------------------- | --------------- | --------------------- | -------------- |
|
144 |
+
| Stable Diffusion XL | `sdxl` | 8 GB | 15 GB |
|
145 |
+
| Stable Diffusion 3 Medium | `sd3` | 5 GB | 20 GB |
|
146 |
+
| FLUX.1 Schnell | `flux1-schnell` | 24 GB | 30 GB |
|
147 |
+
| FLUX.1 dev | `flux1-dev` | 24 GB | 30 GB |
|
148 |
+
|
149 |
+
## API specification
|
150 |
+
|
151 |
+
The following describes which fields exist when doing requests to the API. We only describe the fields that are sent via `input` as those are needed by the worker itself. For a full list of fields, please take a look at the [official documentation](https://docs.runpod.io/docs/serverless-usage).
|
152 |
+
|
153 |
+
### JSON Request Body
|
154 |
+
|
155 |
+
```json
|
156 |
+
{
|
157 |
+
"input": {
|
158 |
+
"workflow": {},
|
159 |
+
"images": [
|
160 |
+
{
|
161 |
+
"name": "example_image_name.png",
|
162 |
+
"image": "base64_encoded_string"
|
163 |
+
}
|
164 |
+
]
|
165 |
+
}
|
166 |
+
}
|
167 |
+
```
|
168 |
+
|
169 |
+
### Fields
|
170 |
+
|
171 |
+
| Field Path | Type | Required | Description |
|
172 |
+
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
173 |
+
| `input` | Object | Yes | The top-level object containing the request data. |
|
174 |
+
| `input.workflow` | Object | Yes | Contains the ComfyUI workflow configuration. |
|
175 |
+
| `input.images` | Array | No | An array of images. Each image will be added into the "input"-folder of ComfyUI and can then be used in the workflow by using it's `name` |
|
176 |
+
|
177 |
+
#### "input.images"
|
178 |
+
|
179 |
+
An array of images, where each image should have a different name.
|
180 |
+
|
181 |
+
🚨 The request body for a RunPod endpoint is 10 MB for `/run` and 20 MB for `/runsync`, so make sure that your input images are not super huge as this will be blocked by RunPod otherwise, see the [official documentation](https://docs.runpod.io/docs/serverless-endpoint-urls)
|
182 |
+
|
183 |
+
| Field Name | Type | Required | Description |
|
184 |
+
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
|
185 |
+
| `name` | String | Yes | The name of the image. Please use the same name in your workflow to reference the image. |
|
186 |
+
| `image` | String | Yes | A base64 encoded string of the image. |
|
187 |
+
|
188 |
+
## Interact with your RunPod API
|
189 |
+
|
190 |
+
1. **Generate an API Key**:
|
191 |
+
|
192 |
+
- In the [User Settings](https://www.runpod.io/console/serverless/user/settings), click on `API Keys` and then on the `API Key` button.
|
193 |
+
- Save the generated key somewhere safe, as you will not be able to see it again when you navigate away from the page.
|
194 |
+
|
195 |
+
2. **Use the API Key**:
|
196 |
+
|
197 |
+
- Use cURL or any other tool to access the API using the API key and your Endpoint ID:
|
198 |
+
- Replace `<api_key>` with your key.
|
199 |
+
|
200 |
+
3. **Use your Endpoint**:
|
201 |
+
- Replace `<endpoint_id>` with the [ID of the endpoint](https://www.runpod.io/console/serverless). (You can find the endpoint ID by clicking on your endpoint; it is written underneath the name of the endpoint at the top and also part of the URLs shown at the bottom of the first box.)
|
202 |
+
|
203 |
+
![How to find the EndpointID](./assets/my-endpoint-with-endpointID.png)
|
204 |
+
|
205 |
+
### Health status
|
206 |
+
|
207 |
+
```bash
|
208 |
+
curl -H "Authorization: Bearer <api_key>" https://api.runpod.ai/v2/<endpoint_id>/health
|
209 |
+
```
|
210 |
+
|
211 |
+
### Generate an image
|
212 |
+
|
213 |
+
You can either create a new job async by using `/run` or a sync by using `/runsync`. The example here is using a sync job and waits until the response is delivered.
|
214 |
+
|
215 |
+
The API expects a [JSON in this form](#json-request-body), where `workflow` is the [workflow from ComfyUI, exported as JSON](#how-to-get-the-workflow-from-comfyui) and `images` is optional.
|
216 |
+
|
217 |
+
Please also take a look at the [test_input.json](./test_input.json) to see how the API input should look like.
|
218 |
+
|
219 |
+
#### Example request for SDXL with cURL
|
220 |
+
|
221 |
+
```bash
|
222 |
+
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
|
223 |
+
```
|
224 |
+
|
225 |
+
Example response with AWS S3 bucket configuration
|
226 |
+
|
227 |
+
```json
|
228 |
+
{
|
229 |
+
"delayTime": 2188,
|
230 |
+
"executionTime": 2297,
|
231 |
+
"id": "sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1",
|
232 |
+
"output": {
|
233 |
+
"message": "https://bucket.s3.region.amazonaws.com/10-23/sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1/c67ad621.png",
|
234 |
+
"status": "success"
|
235 |
+
},
|
236 |
+
"status": "COMPLETED"
|
237 |
+
}
|
238 |
+
```
|
239 |
+
|
240 |
+
Example response as base64-encoded image
|
241 |
+
|
242 |
+
```json
|
243 |
+
{
|
244 |
+
"delayTime": 2188,
|
245 |
+
"executionTime": 2297,
|
246 |
+
"id": "sync-c0cd1eb2-068f-4ecf-a99a-55770fc77391-e1",
|
247 |
+
"output": { "message": "base64encodedimage", "status": "success" },
|
248 |
+
"status": "COMPLETED"
|
249 |
+
}
|
250 |
+
```
|
251 |
+
|
252 |
+
## How to get the workflow from ComfyUI?
|
253 |
+
|
254 |
+
- Open ComfyUI in the browser
|
255 |
+
- Open the `Settings` (gear icon in the top right of the menu)
|
256 |
+
- In the dialog that appears configure:
|
257 |
+
- `Enable Dev mode Options`: enable
|
258 |
+
- Close the `Settings`
|
259 |
+
- In the menu, click on the `Save (API Format)` button, which will download a file named `workflow_api.json`
|
260 |
+
|
261 |
+
You can now take the content of this file and put it into your `workflow` when interacting with the API.
|
262 |
+
|
263 |
+
## Bring Your Own Models and Nodes
|
264 |
+
|
265 |
+
### Network Volume
|
266 |
+
|
267 |
+
Using a Network Volume allows you to store and access custom models:
|
268 |
+
|
269 |
+
1. **Create a Network Volume**:
|
270 |
+
- Follow the [RunPod Network Volumes guide](https://docs.runpod.io/pods/storage/create-network-volumes) to create a volume.
|
271 |
+
2. **Populate the Volume**:
|
272 |
+
|
273 |
+
- Create a temporary GPU instance:
|
274 |
+
- Navigate to `Manage > Storage`, click `Deploy` under the volume, and deploy any GPU or CPU instance.
|
275 |
+
- Navigate to `Manage > Pods`. Under the new pod, click `Connect` to open a shell (either via Jupyter notebook or SSH).
|
276 |
+
- Populate the volume with your models:
|
277 |
+
```bash
|
278 |
+
cd /workspace
|
279 |
+
for i in checkpoints clip clip_vision configs controlnet embeddings loras upscale_models vae; do mkdir -p models/$i; done
|
280 |
+
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
|
281 |
+
```
|
282 |
+
|
283 |
+
3. **Delete the Temporary GPU Instance**:
|
284 |
+
|
285 |
+
- Once populated, [terminate the temporary GPU instance](https://docs.runpod.io/docs/pods#terminating-a-pod).
|
286 |
+
|
287 |
+
4. **Configure Your Endpoint**:
|
288 |
+
- Use the Network Volume in your endpoint configuration:
|
289 |
+
- Either create a new endpoint or update an existing one.
|
290 |
+
- In the endpoint configuration, under `Advanced > Select Network Volume`, select your Network Volume.
|
291 |
+
|
292 |
+
Note: The folders in the Network Volume are automatically available to ComfyUI when the network volume is configured and attached.
|
293 |
+
|
294 |
+
### Custom Docker Image
|
295 |
+
|
296 |
+
If you prefer to include your models directly in the Docker image, follow these steps:
|
297 |
+
|
298 |
+
1. **Fork the Repository**:
|
299 |
+
|
300 |
+
- Fork this repository to your own GitHub account.
|
301 |
+
|
302 |
+
2. **Add Your Models in the Dockerfile**:
|
303 |
+
|
304 |
+
- Edit the `Dockerfile` to include your models:
|
305 |
+
```Dockerfile
|
306 |
+
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
|
307 |
+
```
|
308 |
+
- You can also add custom nodes:
|
309 |
+
```Dockerfile
|
310 |
+
RUN git clone https://github.com/<username>/<custom-node-repo>.git custom_nodes/<custom-node-repo>
|
311 |
+
```
|
312 |
+
|
313 |
+
3. **Build Your Docker Image**:
|
314 |
+
- Build the **base** image locally:
|
315 |
+
```bash
|
316 |
+
docker build -t <your_dockerhub_username>/runpod-worker-comfy:dev-base --target base --platform linux/amd64 .
|
317 |
+
```
|
318 |
+
- Build the **sdxl** image locally:
|
319 |
+
```bash
|
320 |
+
docker build --build-arg MODEL_TYPE=sdxl -t <your_dockerhub_username>/runpod-worker-comfy:dev-sdxl --platform linux/amd64 .
|
321 |
+
```
|
322 |
+
- Build the **sd3** image locally:
|
323 |
+
```bash
|
324 |
+
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 .
|
325 |
+
```
|
326 |
+
|
327 |
+
> [!NOTE]
|
328 |
+
> Ensure to specify `--platform linux/amd64` to avoid errors on RunPod, see [issue #13](https://github.com/blib-la/runpod-worker-comfy/issues/13).
|
329 |
+
|
330 |
+
## Local testing
|
331 |
+
|
332 |
+
Both tests will use the data from [test_input.json](./test_input.json), so make your changes in there to test this properly.
|
333 |
+
|
334 |
+
### Setup
|
335 |
+
|
336 |
+
1. Make sure you have Python >= 3.10
|
337 |
+
2. Create a virtual environment:
|
338 |
+
```bash
|
339 |
+
python -m venv venv
|
340 |
+
```
|
341 |
+
3. Activate the virtual environment:
|
342 |
+
- **Windows**:
|
343 |
+
```bash
|
344 |
+
.\venv\Scripts\activate
|
345 |
+
```
|
346 |
+
- **Mac / Linux**:
|
347 |
+
```bash
|
348 |
+
source ./venv/bin/activate
|
349 |
+
```
|
350 |
+
4. Install the dependencies:
|
351 |
+
```bash
|
352 |
+
pip install -r requirements.txt
|
353 |
+
```
|
354 |
+
|
355 |
+
#### Setup for Windows
|
356 |
+
|
357 |
+
1. Install WSL2 and a Linux distro (like Ubuntu) following [this guide](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support#1-overview). You can skip the "Install and use a GUI package" part.
|
358 |
+
2. After installing Ubuntu, open the terminal and log in:
|
359 |
+
```bash
|
360 |
+
wsl -d Ubuntu
|
361 |
+
```
|
362 |
+
3. Update the packages:
|
363 |
+
```bash
|
364 |
+
sudo apt update
|
365 |
+
```
|
366 |
+
4. Install Docker in Ubuntu:
|
367 |
+
- Follow the [official Docker installation guide](https://docs.docker.com/engine/install/ubuntu/).
|
368 |
+
- Install docker-compose:
|
369 |
+
```bash
|
370 |
+
sudo apt-get install docker-compose
|
371 |
+
```
|
372 |
+
- Install the NVIDIA Toolkit in Ubuntu:
|
373 |
+
Follow [this guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuring-docker) and create the `nvidia` runtime.
|
374 |
+
5. Enable GPU acceleration on Ubuntu on WSL2:
|
375 |
+
Follow [this guide](https://canonical-ubuntu-wsl.readthedocs-hosted.com/en/latest/tutorials/gpu-cuda/).
|
376 |
+
- If you already have your GPU driver installed on Windows, you can skip the "Install the appropriate Windows vGPU driver for WSL" step.
|
377 |
+
6. Add your user to the `docker` group to use Docker without `sudo`:
|
378 |
+
```bash
|
379 |
+
sudo usermod -aG docker $USER
|
380 |
+
```
|
381 |
+
|
382 |
+
Once these steps are completed, switch to Ubuntu in the terminal and run the Docker image locally on your Windows computer via WSL:
|
383 |
+
|
384 |
+
```bash
|
385 |
+
wsl -d Ubuntu
|
386 |
+
```
|
387 |
+
|
388 |
+
### Testing the RunPod handler
|
389 |
+
|
390 |
+
- Run all tests: `python -m unittest discover`
|
391 |
+
- If you want to run a specific test: `python -m unittest tests.test_rp_handler.TestRunpodWorkerComfy.test_bucket_endpoint_not_configured`
|
392 |
+
|
393 |
+
You can also start the handler itself to have the local server running: `python src/rp_handler.py`
|
394 |
+
To get this to work you will also need to start "ComfyUI", otherwise the handler will not work.
|
395 |
+
|
396 |
+
### Local API
|
397 |
+
|
398 |
+
For enhanced local development, you can start an API server that simulates the RunPod worker environment. This feature is particularly useful for debugging and testing your integrations locally.
|
399 |
+
|
400 |
+
Set the `SERVE_API_LOCALLY` environment variable to `true` to activate the local API server when running your Docker container. This is already the default value in the `docker-compose.yml`, so you can get it running by executing:
|
401 |
+
|
402 |
+
```bash
|
403 |
+
docker-compose up
|
404 |
+
```
|
405 |
+
|
406 |
+
#### Access the local Worker API
|
407 |
+
|
408 |
+
- With the local API server running, it's accessible at: [localhost:8000](http://localhost:8000)
|
409 |
+
- When you open this in your browser, you can also see the API documentation and can interact with the API directly
|
410 |
+
|
411 |
+
#### Access local ComfyUI
|
412 |
+
|
413 |
+
- With the local API server running, you can access ComfyUI at: [localhost:8188](http://localhost:8188)
|
414 |
+
|
415 |
+
## Automatically deploy to Docker hub with GitHub Actions
|
416 |
+
|
417 |
+
The repo contains two workflows that publish the image to Docker hub using GitHub Actions:
|
418 |
+
|
419 |
+
- [dev.yml](.github/workflows/dev.yml): Creates the image and pushes it to Docker hub with the `dev` tag on every push to the `main` branch
|
420 |
+
- [release.yml](.github/workflows/release.yml): Creates the image and pushes it to Docker hub with the `latest` and the release tag. It will only be triggered when you create a release on GitHub
|
421 |
+
|
422 |
+
If you want to use this, you should add these **secrets** to your repository:
|
423 |
+
|
424 |
+
| Configuration Variable | Description | Example Value |
|
425 |
+
| -------------------------- | ----------------------------------------- | ------------------- |
|
426 |
+
| `DOCKERHUB_USERNAME` | Your Docker Hub username. | `your-username` |
|
427 |
+
| `DOCKERHUB_TOKEN` | Your Docker Hub token for authentication. | `your-token` |
|
428 |
+
| `HUGGINGFACE_ACCESS_TOKEN` | Your READ access token from Hugging Face | `your-access-token` |
|
429 |
+
|
430 |
+
And also make sure to add these **variables** to your repository:
|
431 |
+
|
432 |
+
| Variable Name | Description | Example Value |
|
433 |
+
| ---------------- | ------------------------------------------------------------ | --------------------- |
|
434 |
+
| `DOCKERHUB_REPO` | The repository on Docker Hub where the image will be pushed. | `timpietruskyblibla` |
|
435 |
+
| `DOCKERHUB_IMG` | The name of the image to be pushed to Docker Hub. | `runpod-worker-comfy` |
|
436 |
+
|
437 |
+
## Acknowledgments
|
438 |
+
|
439 |
+
- Thanks to [all contributors](https://github.com/blib-la/runpod-worker-comfy/graphs/contributors) for your awesome work
|
440 |
+
- Thanks to [Justin Merrell](https://github.com/justinmerrell) from RunPod for [worker-1111](https://github.com/runpod-workers/worker-a1111), which was used to get inspired on how to create this worker
|
441 |
+
- Thanks to [Ashley Kleynhans](https://github.com/ashleykleynhans) for [runpod-worker-a1111](https://github.com/ashleykleynhans/runpod-worker-a1111), which was used to get inspired on how to create this worker
|
442 |
+
- Thanks to [comfyanonymous](https://github.com/comfyanonymous) for creating [ComfyUI](https://github.com/comfyanonymous/ComfyUI), which provides such an awesome API to interact with Stable Diffusion
|