From 32ac027e0e677af5bbca92e7e52635de7695eabc Mon Sep 17 00:00:00 2001 From: Robert Wojciechowski Date: Sun, 12 Jul 2026 11:13:22 +0000 Subject: [PATCH] docs: align selected copy with current behavior --- README.md | 4 ++-- docs/comfyui-distributed-api.md | 26 ++++++++++++++++++-------- docs/worker-setup-guides.md | 4 ++-- nodes/__init__.py | 2 +- nodes/distributed_upscale.py | 12 ++++++------ nodes/utilities.py | 4 ++-- web/sidebar/settingsSection.js | 4 ++-- workflows/distributed-upscale.json | 2 +- 8 files changed, 34 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 4809d43..f5725c5 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ Accelerate Ultimate SD Upscaler by distributing video tiles across multiple work Control your distributed cluster programmatically without opening the browser. * **Endpoint:** `POST /distributed/queue` -* **Functionality:** Accepts a standard ComfyUI workflow JSON, automatically distributes it to available workers, and returns the execution ID. +* **Functionality:** Accepts a ComfyUI API-format prompt, dispatches it to the requested reachable workers, and returns the master `prompt_id`. * **Documentation:** [See API Examples & Scripts](https://github.com/robertvoy/ComfyUI-Distributed/blob/main/docs/comfyui-distributed-api.md) > **⚠️ Security Warning:** Do not expose your ComfyUI port to the public internet. If you need remote access, run ComfyUI behind a secure proxy (like Cloudflare or a VPN). @@ -175,7 +175,7 @@ Use **Distributed Value** when you want per-worker overrides (for example, diffe | **Distributed Value** | Outputs per-worker override values with fallback to default | | **Ultimate SD Upscale Distributed** | Distributes upscale tiles across workers | | **Image Batch Divider** | Splits image batches for multi-GPU output | -| **Audio Batch Divider** | Splits audio batches for multi-GPU output | +| **Audio Segment Divider** | Splits an audio waveform into up to ten sequential time segments | | **Distributed Model Name** | Passes model paths to workers, enabling workflows to use models not present on the master in orchestrator-only mode | | **Distributed Empty Image** | Produces an empty IMAGE batch used when the master delegates all work | diff --git a/docs/comfyui-distributed-api.md b/docs/comfyui-distributed-api.md index 21383be..34836b1 100644 --- a/docs/comfyui-distributed-api.md +++ b/docs/comfyui-distributed-api.md @@ -19,8 +19,8 @@ This document describes the **public HTTP API** added to ComfyUI-Distributed to - `POST /distributed/queue` — queues a workflow using the same distributed orchestration rules as the UI: - Detects distributed nodes in the prompt (`DistributedCollector`, `UltimateSDUpscaleDistributed`). - Resolves enabled/selected workers. - - Pings workers (`GET /prompt`) to include only reachable ones. - - Dispatches the workflow to workers (`POST /prompt`). + - Probes and dispatches workers through `/distributed/worker_ws` by default. + - If `settings.websocket_orchestration=false`, probes with `GET /prompt` and dispatches with `POST /prompt` instead. - Queues the master workflow in ComfyUI’s prompt queue. - If any `DistributedCollector` has `load_balance=true`, selects one least-busy participant for this run. @@ -61,7 +61,8 @@ Queue a workflow for distributed execution. #### Fields - `prompt` (required unless `workflow.prompt` is present, object) - - The ComfyUI prompt/workflow graph, same shape as used by `POST /prompt`. + - A complete ComfyUI API-format prompt graph, using the same shape as `POST /prompt`. + - This is not the normal visual workflow export from the ComfyUI editor. - `workflow` (optional, object) - Workflow metadata that ComfyUI normally stores in `extra_pnginfo.workflow`. - If you don’t care about UI metadata, you can omit it. @@ -123,10 +124,14 @@ $cfg.workers | Select-Object id,name,enabled,host,port,type | Format-Table -Auto ## Worker requirements (important) -For a worker to participate, it must be reachable from the master: +For a worker to participate, it must be reachable from the master. By default: + +- WebSocket probe and dispatch: `/distributed/worker_ws` must accept the connection. + +If `settings.websocket_orchestration=false`: - Health check: `GET /prompt` must return HTTP 200. -- Dispatch: `POST /prompt` must accept the workflow. +- Dispatch: `POST /prompt` must accept the prompt. Also, for collector-based flows: @@ -201,7 +206,7 @@ Proxy endpoint on master that fetches logs from a configured remote/cloud worker ## Examples -### 1) Minimal `curl` +### 1) Minimal `curl` request envelope ```bash curl -X POST "http://127.0.0.1:8188/distributed/queue" \ @@ -209,18 +214,23 @@ curl -X POST "http://127.0.0.1:8188/distributed/queue" \ -d @payload.json ``` -Where `payload.json` contains at least: +`payload.json` must contain a complete ComfyUI API-format prompt. The abbreviated envelope below illustrates the request shape but is not directly executable: ```json { "prompt": { - "1": {"class_type": "KSampler", "inputs": {} } + "": { + "class_type": "", + "inputs": {"": ""} + } }, "enabled_worker_ids": [], "client_id": "external-client" } ``` +Export or construct a valid API-format prompt with all required node inputs and at least one output node before submitting it. + ### 2) Python (`requests`) ```python diff --git a/docs/worker-setup-guides.md b/docs/worker-setup-guides.md index 1d1dba6..dd6bd1e 100644 --- a/docs/worker-setup-guides.md +++ b/docs/worker-setup-guides.md @@ -79,7 +79,7 @@ The master can either contribute GPU work or stay in **orchestrator-only** mode: 📺 [Watch Tutorial](https://www.youtube.com/watch?v=wxKKWMQhYTk) **On Runpod:** -> If using your own template, make sure you launch ComfyUI with the `--enable-cors-header` argument and you `git clone ComfyUI-Distributed` into custom_nodes. ⚠️ **Required!** +> If using your own template, launch ComfyUI with `--listen --enable-cors-header` and clone `ComfyUI-Distributed` into `custom_nodes`. ⚠️ **Required!** 1. Register a [Runpod](https://get.runpod.io/0bw29uf3ug0p) account. 2. On Runpod, go to Storage > New Network Volume and create a volume that will store the models you need. Start with 40 GB, you can always add more later. Learn more [about Network Volumes](https://docs.runpod.io/pods/storage/create-network-volumes). @@ -92,7 +92,7 @@ The master can either contribute GPU work or stay in **orchestrator-only** mode: - SAGE_ATTENTION: optional optimisation (set to true/false) 5. Deploy your pod. 6. Connect to your pod using JupyterLabs. This gives us access to the pod's file system. -7. Download models into /workspaces/ComfyUI/models/ (these will remain on your network drive even after you terminate the pod). Example commands below: +7. Download models into `/workspace/ComfyUI/models/` (these will remain on your network drive even after you terminate the pod). Example commands below: ``` # Download from CivitAI comfy model download --url https://civitai.com/api/download/models/1759168 --relative-path /workspace/ComfyUI/models/checkpoints --set-civitai-api-token $CIVITAI_API_TOKEN diff --git a/nodes/__init__.py b/nodes/__init__.py index d7327b3..b7de07f 100644 --- a/nodes/__init__.py +++ b/nodes/__init__.py @@ -26,6 +26,6 @@ NODE_DISPLAY_NAME_MAPPINGS = { "DistributedModelName": "Distributed Model Name", "DistributedValue": "Distributed Value", "ImageBatchDivider": "Image Batch Divider", - "AudioBatchDivider": "Audio Batch Divider", + "AudioBatchDivider": "Audio Segment Divider", "DistributedEmptyImage": "Distributed Empty Image", } diff --git a/nodes/distributed_upscale.py b/nodes/distributed_upscale.py index 2e92e44..2f9b288 100644 --- a/nodes/distributed_upscale.py +++ b/nodes/distributed_upscale.py @@ -56,22 +56,22 @@ class UltimateSDUpscaleDistributed( """ Distributed version of Ultimate SD Upscale (No Upscale). - Supports three processing modes: + Supports two currently selected processing modes: 1. Single GPU: No workers available, process everything locally - 2. Static Mode: Small batches, distributes tiles across workers (flattened) - 3. Dynamic Mode: Large batches, assigns whole images to workers dynamically + 2. Distributed tile queue: Workers pull tiles from a shared queue Features: - - Multi-mode batch handling for efficient video/image upscaling + - Tile-based batch handling for video/image upscaling - Tiled VAE support for memory efficiency - - Dynamic load balancing for large batches + - Shared work queue so faster workers can process more tiles - Backward compatible with single-image workflows Environment Variables: - COMFYUI_MAX_BATCH: Chunk size for tile sending (default 20) - COMFYUI_MAX_PAYLOAD_SIZE: Max API payload bytes (default 50MB) - Threshold: dynamic_threshold input controls mode switch (default 8) + The hidden dynamic_threshold input is retained for workflow compatibility but + does not affect the current mode-selection policy. """ def __init__(self): diff --git a/nodes/utilities.py b/nodes/utilities.py index 3fda3de..5355a5e 100644 --- a/nodes/utilities.py +++ b/nodes/utilities.py @@ -269,7 +269,7 @@ class ImageBatchDivider: class AudioBatchDivider: - """Divides an audio waveform into multiple parts along the time/samples dimension.""" + """Divides an audio waveform into sequential segments along the time dimension.""" @classmethod def INPUT_TYPES(s): @@ -282,7 +282,7 @@ class AudioBatchDivider: "max": 10, "step": 1, "display": "number", - "tooltip": "Number of parts to divide the audio into" + "tooltip": "Number of sequential time segments to create" }), } } diff --git a/web/sidebar/settingsSection.js b/web/sidebar/settingsSection.js index 0b15233..7cee524 100644 --- a/web/sidebar/settingsSection.js +++ b/web/sidebar/settingsSection.js @@ -72,7 +72,7 @@ export function renderSettingsSection(extension) { createCheckboxSetting( "setting-debug", "Debug Mode", - "Enable verbose logging in the browser console.", + "Enable verbose logging in the browser console and ComfyUI server output.", extension.config?.settings?.debug || false, (event) => extension._updateSetting("debug", event.target.checked) ) @@ -100,7 +100,7 @@ export function renderSettingsSection(extension) { createNumberSetting( "setting-worker-timeout", "Worker Timeout", - "Seconds without a heartbeat before a worker is considered timed out. Default 60.", + "Maximum result-wait and heartbeat inactivity period before recovery begins. Busy workers may receive additional grace. Default: 60 seconds.", extension.config?.settings?.worker_timeout_seconds ?? 60, 10, 1, diff --git a/workflows/distributed-upscale.json b/workflows/distributed-upscale.json index 044a9f9..8914267 100644 --- a/workflows/distributed-upscale.json +++ b/workflows/distributed-upscale.json @@ -814,7 +814,7 @@ "outputs": [], "properties": {}, "widgets_values": [ - "If all your GPUs are the same/similar, set static_distribution to true\n" + "Workers pull tiles from a shared queue, so faster workers can process more tiles automatically.\n" ], "color": "#432", "bgcolor": "#653"