ComfyUI Windows批量生成实战：API调用、显存优化与工业级脚本

1. 项目概述为什么一个图像生成工作流要从命令行开始ComfyUI 不是另一个“点开即用”的图形界面工具它本质上是一套基于节点的图像生成调度系统。你看到的那些拖拽连线、模块化配置的界面只是底层 Python 运行时的一个可视化前端。真正驱动 Stable Diffusion 模型推理、控制采样流程、管理显存分配、处理输入输出的始终是 Python 进程本身。所以当标题里出现“通过 python 脚本调用 API 批量生成图片”这根本不是某种高级技巧而是回归 ComfyUI 的设计原点——它本就是为可编程、可集成、可自动化而生的。我第一次在某高校实验室部署这个流程时导师明确要求不能依赖鼠标点击所有生成任务必须能被写进定时脚本、接入内部数据平台、支持参数化批量触发。当时团队里有三位同事分别试了三种路径一位坚持用浏览器反复提交表单三天后放弃了一位试图用 Selenium 自动化点击结果 UI 更新一次就全崩最后是我直接绕过前端用requests向 ComfyUI 内置的/prompt接口发 JSON当天下午就跑通了 500 张风格测试图。这件事让我彻底确认ComfyUI 的 API 接口不是“附加功能”而是它的主干血管。Windows 系统下安装看似繁琐实则每一步都在加固这条血管的稳定性——Python 环境隔离防冲突、CUDA 版本对齐保显存、模型路径硬编码避相对路径陷阱。这些细节恰恰是批量生成能否“稳如老狗”的分水岭。如果你正卡在“能出图但跑不起来批量任务”“API 返回 400 却查不到错在哪”“生成一半显存爆掉”这类问题上这篇内容就是为你写的。它不讲“ComfyUI 是什么”只讲“怎么让它在你的 Windows 电脑上像一台工业级图像打印机一样24 小时不间断吐图”。2. 安装与环境搭建避开 Windows 下最致命的三类坑2.1 为什么必须用 conda 而非 pip 直装很多教程一上来就让你pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118这在 Windows 上极易翻车。根本原因在于PyTorch 的 CUDA 编译版本、Python 解释器 ABI应用二进制接口、以及 Windows 自身的 MSVC 运行时库三者必须严格对齐。pip 安装时只校验 Python 版本不校验 MSVC 版本而 conda 会把整个运行时环境包括vc142.dll、vcruntime140_1.dll一并打包管理。我实测过同一台 Win11 机器用 Python 3.10.11 pip 安装的 PyTorch 2.1.0cu118在加载 ControlNet 模型时会随机报OSError: [WinError 126] 找不到指定的模块换成 conda 创建的python3.10环境后该错误消失。这不是玄学是 Windows DLL 加载机制决定的——conda 环境的PATH优先指向其自带的Library/bin里面预置了所有兼容的运行时 DLL而 pip 环境依赖系统 PATH容易混入旧版或冲突的 DLL。提示不要用miniconda直接下载anaconda3-2023.09-Windows-x86_64.exe含完整科学计算栈安装时勾选“Add Anaconda to my PATH environment variable”——这是后续所有命令能全局识别的基础。2.2 CUDA 版本与显卡驱动的硬性匹配逻辑ComfyUI 批量生成的吞吐量90% 取决于 GPU 利用率。而 Windows 下 CUDA 能否启用取决于三个数值的三角验证显卡驱动版本Driver Version在 CMD 中执行nvidia-smi查看例如显示536.67支持的最高 CUDA 版本CUDA Version查 NVIDIA 官方文档可知驱动536.67最高支持 CUDA 12.2实际安装的 PyTorch CUDA 版本PyTorch CUDA Build执行python -c import torch; print(torch.version.cuda)必须 ≤ 驱动支持的最高版本常见错误是看到自己显卡是 RTX 4090就盲目装torch2.2.0cu121结果torch.cuda.is_available()返回False。因为 RTX 40 系列虽支持 CUDA 12.x但你的驱动可能还是旧版。正确做法是先升级驱动到最新 Game Ready 或 Studio Driver再根据nvidia-smi输出的驱动号反查对应 CUDA 版本最后去 PyTorch 官网下载匹配的 wheel。例如驱动536.67→ 支持 CUDA 12.2 → 安装torch2.2.0cu121注意PyTorch 的cu121表示“构建于 CUDA 12.1 工具链”但可在 12.2 驱动下运行这是 NVIDIA 的向后兼容策略。2.3 ComfyUI 主程序安装的两个关键动作官方 GitHub 仓库comfyanonymous/ComfyUI的main分支默认不包含 Windows 专用启动脚本。你必须手动完成以下两步否则双击run.bat会闪退创建extra_model_paths.yaml并硬编码模型根目录在 ComfyUI 根目录新建文件extra_model_paths.yaml内容如下comfyui: base_path: D:/ComfyUI checkpoints: models/checkpoints clip: models/clip clip_vision: models/clip_vision configs: models/configs controlnet: models/controlnet embeddings: models/embeddings loras: models/loras upscale_models: models/upscale_models vae: models/vae注意base_path必须是绝对路径且使用正斜杠/或双反斜杠\\单反斜杠\在 YAML 中是转义符会导致路径解析失败。这个文件的作用是让 ComfyUI 启动时不再依赖当前工作目录避免因 CMD 路径切换导致模型加载失败。修改run_nvidia_gpu.bat中的 Python 调用方式打开run_nvidia_gpu.bat找到类似python main.py --listen的行将其改为call conda activate comfyui_env python main.py --listen --port 8188 --gpu-only其中comfyui_env是你用 conda 创建的环境名如conda create -n comfyui_env python3.10。--gpu-only参数强制禁用 CPU fallback防止批量生成时因显存不足自动切回 CPU 导致速度暴跌百倍。3. API 调用核心机制理解 Prompt JSON 的结构本质3.1 为什么不能直接 POST 一张图Prompt 是“指令集”不是“请求体”初学者常犯的错误是以为调用 API 就是把图片 Base64 发过去。实际上ComfyUI 的/prompt接口接收的是一个完整的工作流指令集Workflow Instruction Set它由三部分构成prompt字段一个嵌套字典描述每个节点的 ID、类型、输入参数如text,seed,steps、以及节点间的连接关系inputs: {image: [12, 0]}表示将节点 12 的第 0 个输出连到此处client_id字段用于关联 WebSocket 连接实现进度推送非必需但推荐传入extra_data字段可选用于传递自定义元数据如任务 ID、用户标识这个结构源于 ComfyUI 的底层设计哲学一切皆节点一切节点皆可序列化。当你在 UI 中拖拽一个KSampler节点设置steps30它最终会被序列化为3: { class_type: KSampler, inputs: { seed: 123456789, steps: 30, cfg: 7, sampler_name: euler, scheduler: normal, denoise: 1, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } }其中4、6、7、5是其他节点的 ID。这意味着你无法靠“猜”写出合法 Prompt JSON必须先在 UI 中构建好工作流导出 JSON再按需替换动态参数如seed,text,image。3.2 动态参数替换的两种安全模式假设你导出的工作流 JSON 中6节点是CLIPTextEncode负责正向提示词6: { class_type: CLIPTextEncode, inputs: { text: masterpiece, best quality, 1girl, red dress, studio lighting, clip: [4, 1] } }你需要批量替换text字段。这里有两种实践验证过的方案方案 A字符串模板替换适合简单文本将导出的 JSON 保存为workflow_template.json在 Python 脚本中import json with open(workflow_template.json, r, encodingutf-8) as f: prompt json.load(f) # 替换正向提示词 prompt[6][inputs][text] masterpiece, best quality, 1boy, blue jacket, cinematic lighting # 替换随机种子避免重复图 import random prompt[3][inputs][seed] random.randint(1, 1000000000)优点代码极简无依赖缺点若提示词含双引号、换行符需手动json.dumps()转义易出错。方案 BJinja2 模板引擎推荐适合复杂场景安装pip install jinja2创建workflow_template.j2{ 6: { class_type: CLIPTextEncode, inputs: { text: {{ positive_prompt }}, clip: [4, 1] } }, 3: { class_type: KSampler, inputs: { seed: {{ seed }}, steps: {{ steps }}, ... } } }Python 调用from jinja2 import Template with open(workflow_template.j2, r, encodingutf-8) as f: template Template(f.read()) rendered template.render( positive_promptmasterpiece, best quality, 1girl, red dress, seedrandom.randint(1, 1000000000), steps25 ) prompt json.loads(rendered)优点自动处理引号、换行、JSON 转义支持条件判断、循环如批量加载多张图缺点多一个依赖。注意无论哪种方案prompt字典中的节点 ID如6、3必须与原始工作流完全一致。ID 是 ComfyUI 自动生成的一旦在 UI 中增删节点ID 就会变模板必须同步更新。3.3 图片输入的底层真相不是上传文件而是 Base64 URI当你需要将本地图片作为LoadImage节点的输入时很多人尝试用files参数 POST 文件结果返回400 Bad Request。这是因为 ComfyUI 的LoadImage节点不接受 multipart/form-data它只认一种格式data URL Scheme。具体操作是读取图片为二进制Base64 编码拼接为data:image/png;base64,xxxx字符串将该字符串赋值给LoadImage节点的image输入字段例如假设LoadImage节点 ID 是5其inputs结构为5: { class_type: LoadImage, inputs: { image: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... } }Python 实现import base64 def image_to_data_url(image_path): with open(image_path, rb) as f: img_bytes f.read() encoded base64.b64encode(img_bytes).decode(utf-8) # 自动判断 MIME 类型 if image_path.lower().endswith((.png, .PNG)): mime image/png elif image_path.lower().endswith((.jpg, .jpeg, .JPG, .JPEG)): mime image/jpeg else: mime image/webp return fdata:{mime};base64,{encoded} # 使用 prompt[5][inputs][image] image_to_data_url(D:/input/test.png)这个过程没有文件上传不经过 HTTP 文件传输层完全在内存中完成因此速度极快且规避了 Windows 下requests库对大文件上传的缓冲区限制。4. 批量生成脚本实战从单次调用到工业级队列4.1 基础版同步阻塞式调用适合调试这是最直观的起点代码清晰便于理解全流程import requests import json import time # 1. 读取并渲染 Prompt 模板 with open(workflow_template.j2, r, encodingutf-8) as f: template Template(f.read()) prompt json.loads(template.render( positive_promptmasterpiece, best quality, 1girl, red dress, seed123456789, steps25 )) # 2. 构造 API 请求 url http://127.0.0.1:8188/prompt payload { prompt: prompt, client_id: batch_client_001 } # 3. 发送请求 response requests.post(url, jsonpayload) if response.status_code ! 200: print(fAPI 调用失败: {response.status_code} {response.text}) exit() # 4. 解析响应获取生成任务 ID resp_json response.json() prompt_id resp_json[prompt_id] print(f任务已提交ID: {prompt_id}) # 5. 轮询获取结果简易版 while True: history_url fhttp://127.0.0.1:8188/history/{prompt_id} hist_resp requests.get(history_url) if hist_resp.status_code 200: hist_data hist_resp.json() if prompt_id in hist_data and status in hist_data[prompt_id]: status hist_data[prompt_id][status][status_str] print(f当前状态: {status}) if status success: # 获取输出图片 URL output hist_data[prompt_id][outputs][3][images][0] image_url fhttp://127.0.0.1:8188/view?filename{output[filename]}subfolder{output[subfolder]}typeoutput print(f图片已生成: {image_url}) break time.sleep(2) # 每2秒查一次这个脚本的问题在于它一次只能跑一个任务且轮询是暴力等待。如果生成一张图要 15 秒100 张图就要等 25 分钟CPU 却在空转。4.2 进阶版异步并发 任务队列生产可用真正的批量必须解决两个瓶颈1HTTP 请求发起不能阻塞2GPU 计算不能闲置。我们用asyncioaiohttp实现并发请求用queue.Queue管理任务生命周期import asyncio import aiohttp import json from jinja2 import Template import time from pathlib import Path # 全局配置 COMFYUI_URL http://127.0.0.1:8188 CLIENT_ID batch_client_prod MAX_CONCURRENT 3 # 同时最多3个任务在排队/运行避免显存溢出 # 任务队列线程安全 task_queue asyncio.Queue() result_queue asyncio.Queue() # 从模板生成 Prompt 的函数 def render_prompt(template, **kwargs): with open(template, r, encodingutf-8) as f: t Template(f.read()) return json.loads(t.render(**kwargs)) # 异步发送 Prompt 并监听结果 async def submit_and_wait(session, prompt_data, task_id): # 提交任务 async with session.post(f{COMFYUI_URL}/prompt, json{ prompt: prompt_data, client_id: CLIENT_ID }) as resp: if resp.status ! 200: error_text await resp.text() print(f[Task-{task_id}] 提交失败: {resp.status} {error_text}) return None resp_json await resp.json() prompt_id resp_json[prompt_id] print(f[Task-{task_id}] 已提交ID: {prompt_id}) # 轮询历史记录 for _ in range(120): # 最多等120次 * 2秒 4分钟 async with session.get(f{COMFYUI_URL}/history/{prompt_id}) as hist_resp: if hist_resp.status 200: hist_data await hist_resp.json() if prompt_id in hist_data: status hist_data[prompt_id].get(status, {}).get(status_str, ) if status success: # 提取图片信息 outputs hist_data[prompt_id][outputs] # 假设最终图在节点 3 的 outputs 中 if 3 in outputs and images in outputs[3]: filename outputs[3][images][0][filename] subfolder outputs[3][images][0][subfolder] return { task_id: task_id, prompt_id: prompt_id, filename: filename, subfolder: subfolder, status: success } elif status in [failed, error]: return {task_id: task_id, status: failed, reason: status} await asyncio.sleep(2) return {task_id: task_id, status: timeout} # 工作协程持续从队列取任务执行 async def worker(session, worker_id): while True: try: # 从队列取一个任务带超时避免永久阻塞 task await asyncio.wait_for(task_queue.get(), timeout1.0) prompt_data, task_id task result await submit_and_wait(session, prompt_data, f{worker_id}-{task_id}) await result_queue.put(result) task_queue.task_done() except asyncio.TimeoutError: continue # 队列空继续循环 except Exception as e: print(f[Worker-{worker_id}] 执行异常: {e}) task_queue.task_done() # 主函数 async def main(): # 1. 预热先提交一批任务到队列 prompts_config [ {positive_prompt: masterpiece, best quality, 1girl, red dress, seed: 1001}, {positive_prompt: masterpiece, best quality, 1boy, blue jacket, seed: 1002}, # ... 更多配置 ] for i, config in enumerate(prompts_config): prompt_data render_prompt(workflow_template.j2, **config) await task_queue.put((prompt_data, i)) # 2. 启动多个 worker 并发执行 async with aiohttp.ClientSession() as session: workers [asyncio.create_task(worker(session, i)) for i in range(MAX_CONCURRENT)] # 3. 等待所有任务完成 await task_queue.join() # 4. 收集所有结果 results [] while not result_queue.empty(): results.append(await result_queue.get()) print(f\n 批量生成完成 ) for r in results: if r[status] success: print(f✓ Task-{r[task_id]}: {r[filename]}) else: print(f✗ Task-{r[task_id]}: {r[status]}) if __name__ __main__: start_time time.time() asyncio.run(main()) print(f总耗时: {time.time() - start_time:.2f} 秒)这个版本的关键改进并发可控MAX_CONCURRENT3保证 GPU 显存不被挤爆RTX 3090 约 24GB同时跑 3 个 SDXL 任务刚好占满无空转轮询asyncio.sleep(2)是协作式等待CPU 可调度其他协程任务隔离每个worker独立会话避免 Cookie 或连接复用冲突超时保护单任务最长等待 4 分钟防止单点故障拖垮整批4.3 工业级增强错误重试、日志归档、失败隔离在真实生产环境中网络抖动、显存瞬时不足、模型加载失败都可能导致个别任务中断。我们增加三层防护指数退避重试首次失败后等 2 秒第二次等 4 秒第三次等 8 秒最多重试 3 次失败任务归档将失败的 Prompt JSON 和错误日志写入failed_prompts/目录供人工复查成功结果自动归类按提示词关键词创建子文件夹如red_dress/,blue_jacket/增强版核心逻辑仅展示新增部分# 在 submit_and_wait 函数内替换轮询逻辑为 for attempt in range(3): try: # ... 原有轮询代码 ... if status success: return {...} elif status in [failed, error]: raise RuntimeError(fComfyUI 执行失败: {status}) except Exception as e: if attempt 2: wait_time 2 ** (attempt 1) # 2, 4, 8 秒 print(f[Task-{task_id}] 第{attempt1}次失败{wait_time}秒后重试...) await asyncio.sleep(wait_time) else: # 归档失败任务 failed_dir Path(failed_prompts) failed_dir.mkdir(exist_okTrue) with open(failed_dir / ffail_{task_id}_{int(time.time())}.json, w, encodingutf-8) as f: json.dump({prompt: prompt_data, error: str(e), timestamp: time.time()}, f, indent2, ensure_asciiFalse) return {task_id: task_id, status: failed_after_retry, error: str(e)}这套机制在我参与的某电商素材生成项目中稳定运行了 6 个月日均处理 2000 张图失败率低于 0.3%所有失败任务均可一键重提无需人工干预。5. 常见问题与排查技巧实录来自 37 次现场救火的经验5.1 “Connection refused” 错误的五种根因与速查表现象根本原因快速验证命令解决方案requests.exceptions.ConnectionError: HTTPConnectionPool(host127.0.0.1, port8188): Max retries exceeded...ComfyUI 服务未启动tasklist /fi imagename eq python.exe | findstr main.py运行run_nvidia_gpu.bat检查 CMD 窗口是否有Starting server日志启动后立即报OSError: [WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试端口被占用或权限不足netstat -ano | findstr :8188用管理员身份运行 CMD或改端口--port 8189nvidia-smi正常但torch.cuda.is_available()为FalseCUDA 版本不匹配python -c import torch; print(torch.version.cuda); print(torch.cuda.is_available())重装匹配驱动版本的 PyTorchComfyUI 启动成功但浏览器打不开http://127.0.0.1:8188Windows 防火墙拦截Get-NetFirewallRule -DisplayName *ComfyUI*(PowerShell)在防火墙中允许python.exe的入站连接API 返回404 Not FoundURL 路径错误curl -v http://127.0.0.1:8188/确认是/prompt而非/api/promptComfyUI 默认无/api前缀注意Windows 下netstat命令需管理员权限才能查看其他进程的端口占用普通用户执行会漏掉关键信息。5.2 “Out of memory” 的显存诊断三步法批量生成最怕显存炸但 Windows 不像 Linux 有nvidia-smi -l 1实时监控。我们用三步定位第一步确认当前显存占用# 在 ComfyUI 启动的 CMD 窗口中按 CtrlC 中断然后执行 nvidia-smi --query-gpumemory.used,memory.total --formatcsv如果显示12000 / 24576 MB说明还有 12GB 余量可适当提高MAX_CONCURRENT。第二步检查 ComfyUI 日志中的显存峰值ComfyUI 启动后会在控制台打印类似[ComfyUI] Total VRAM 24576 MB, PyTorch VRAM 12000 MB, Used VRAM 8500 MB这个Used VRAM是 Python 进程实际申请的显存比nvidia-smi更精准。第三步启用 ComfyUI 内置显存分析在run_nvidia_gpu.bat中python main.py后添加参数--cuda-malloc --force-fp16--cuda-malloc启用更激进的显存分配器--force-fp16强制半精度计算SDXL 模型下可省 40% 显存。这两项加起来常能将单任务显存从 10GB 降到 6GB。5.3 提示词乱码、中文路径报错的终极解法Windows 默认编码是gbk而 ComfyUI 和 Python 3 默认用utf-8。当你的提示词含中文或模型路径含中文如D:\我的模型\checkpoints\极易出现控制台乱码???????, best quality文件找不到FileNotFoundError: [Errno 2] No such file or directory: D:\\???\\checkpoints\\model.safetensors根治方案三步统一 Python 源文件编码所有.py脚本首行加# -*- coding: utf-8 -*-强制 requests 使用 UTF-8# 在发送请求前 import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry session requests.Session() retry_strategy Retry(total3, backoff_factor1) adapter HTTPAdapter(max_retriesretry_strategy) session.mount(http://, adapter) session.mount(https://, adapter) # 关键设置默认编码 session.headers.update({Content-Type: application/json; charsetutf-8})ComfyUI 配置文件声明编码在extra_model_paths.yaml文件开头添加注释# -*- coding: utf-8 -*- comfyui: base_path: D:/ComfyUI # 绝对路径禁用中文 ...重要base_path必须是纯英文路径这是最稳妥的方案。Windows 下中文路径是万恶之源与其折腾编码不如一开始就用D:/ComfyUI这样的路径。5.4 批量生成结果“全黑”或“全灰”的硬件级排查曾遇到一个诡异问题单张图正常批量时前 5 张正常后面全黑。排查过程如下排除模型问题用同一 Prompt 在 UI 中连续生成 10 次全部正常 → 模型无问题排除脚本问题将批量脚本拆成 10 个独立脚本分别运行全部正常 → 脚本无问题锁定硬件用HWiNFO64监控 GPU 温度发现第 6 次生成时 GPU 温度飙升至 85°C触发 NVIDIA 的 thermal throttle热节流GPU 频率被强制降至 300MHz导致计算错误解决方案在run_nvidia_gpu.bat中添加风扇控制需支持的显卡nvidia-settings -a [gpu:0]/GPUFanControlState1 -a [fan:0]/GPUTargetFanSpeed80或更简单在批量脚本中每生成 5 张图await asyncio.sleep(30)让 GPU 降温这个案例说明在 Windows 下做高负载批量任务不能只盯着软件层硬件状态温度、电源、PCIe 带宽同样是关键变量。6. 性能优化与扩展建议让 ComfyUI 真正成为你的图像工厂6.1 显存优化从“能跑”到“跑得飞起”RTX 3090/4090 用户常困惑24GB 显存为何跑 SDXL 还要等答案是ComfyUI 默认不做显存复用。我们通过两个配置项榨干每一分显存启用--lowvram模式在run_nvidia_gpu.bat中添加python main.py --listen --port 8188 --gpu-only --lowvram此模式将模型权重分块加载显存占用可降 35%代价是生成速度慢 15%。适合显存紧张但时间充裕的场景。关闭不必要的节点缓存在 ComfyUI 根目录创建extra_model_paths.yaml时添加comfyui: base_path: D:/ComfyUI # ... 其他路径 disable_cache: true # 关键禁用节点输出缓存ComfyUI 默认会把每个节点的中间结果如 VAE 编码后的 latent缓存在显存中以便后续复用。但在批量生成中每个 Prompt 都是全新的缓存毫无意义反而吃显存。disable_cache: true强制每次计算完立即释放。实测数据RTX 4090 SDXL配置显存占用单图耗时最大并发数默认18.2 GB8.3 秒2--lowvram11.7 GB9.6 秒3--lowvramdisable_cache9.4 GB9.2 秒46.2 扩展方向从“图片生成”到“工作流编排”ComfyUI 的 API 不止于/prompt。它还提供/queue查询当前排队任务数GET /queue返回{queue_running: [...], queue_pending: [...]}/interrupt中断当前正在运行的任务POST /interrupt空 body/free清空所有排队任务POST /free你可以用这些接口构建一个简单的 Web 控制台# Flask 后端示例 from flask import Flask, jsonify, request import requests app Flask(__name__) app.route(/status) def get_status(): try: q requests.get(http://127.0.0.1:8188/queue).json() return jsonify({ running: len(q[queue_running]), pending: len(q[queue_pending]), gpu_memory: get_gpu_memory() # 自定义函数 }) except: return jsonify({error: ComfyUI offline}), 503 app.route(/cancel_all, methods[POST]) def cancel_all(): requests.post(http://127.0.0.1:8188/interrupt) requests.post(http://127