> **摘要**：本文记录把本地部署的 `ComfyUI_Z-Image-V2`（GGUF 量化版 Z-Image Turbo 6B）接入 AI 助手 WorkBuddy 的完整过程。核心思路是让 ComfyUI 暴露 HTTP API，由 WorkBuddy 侧的零依赖桥接脚本提交任务、轮询结果、回传图片。文章重点复盘三个工程坑：端口冲突、GGUF 首次加载极慢、6GB 显存下的 OOM 降级策略，并给出可复用的 Skill 封装方案。实测在 GTX 1660 6GB 上以 Q4_K_M 量化稳定出图。

---

## 一、背景：为什么这件事值得做

本地部署生图模型的痛点不在于「能不能跑」，而在于「好不好调」。ComfyUI 的图形界面适合单次调试，但一旦想把出图能力嵌进自动化流水线（比如定时生成素材、对话中一句话出图），纯手动点界面就成了瓶颈。

我的目标很明确：**让 AI 助手 WorkBuddy 能直接调用本机 ComfyUI 出图**，形成「对话 → 提示词 → 出图 → 存盘」的闭环，且全程不消耗云端积分、不上传任何素材。

这里有两个硬约束必须先说清，因为它们决定了整个方案的形状：


| 约束                   | 影响                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| 显卡为**GTX 1660 6GB** | Z-Image Turbo 全量 BF16 需 14–16G、FP8 需 8G，都跑不了；只能用**GGUF Q3/Q4 量化版（约 5–6G）** |
| 素材合规红线           | 出图能力定位为「通用本地素材库」，不归属具体业务项目，提示词不碰赛道禁用题材                     |

---

## 二、整体架构：本质是 HTTP API 桥接

ComfyUI 启动后会内置一个 Web/API 服务（默认 `:8188`）。所谓「接入 WorkBuddy」，本质是三层：

```
WorkBuddy（对话/调度）
   │  提交 prompt API 格式的 workflow JSON
   ▼
ComfyUI HTTP API  (127.0.0.1:8188)
   │  POST /prompt  →  轮询 /history  →  从 /view 下载图片
   ▼
本地 Z-Image Turbo (GGUF 节点链)
```

关键环节只有三个：

1. **ComfyUI 启动时要开网络监听**（带 `--listen 127.0.0.1 --port 8188`）；
2. **准备一份 API 格式的工作流 JSON**（在 WebUI 里 `Save (API Format)` 导出，或像本文一样手造）；
3. **一个桥接层**负责「改提示词/参数 → 提交 → 轮询 → 下载」，封装成 Skill 后就能一句话调用。

> 注意：ComfyUI 进程由用户手动启动并常驻，WorkBuddy 侧只提交任务、不负责启停重进程——避免在助手环境里 hold 住一个吃显存的常驻进程。

---

## 三、环境准备与启动配置

我的实际环境（供对照）：

- ComfyUI 根目录：`E:\ComfyUI_Z-Image-GGUF\ComfyUI_Z-Image-V2\ComfyUI\`
- Python 解释器：`...\ComfyUI_Z-Image-V2\deepface\python.exe`（便携版自带）
- 模型：unet `z_image_turbo-Q4_K_M.gguf`（+ `Q4_K_S` 备用）、text_encoder `Qwen3-4B-Q4_K_S.gguf`、VAE `ae.safetensors`
- GGUF 节点：`custom_nodes/ComfyUI-GGUF/`（提供 `UnetLoaderGGUF` / `CLIPLoaderGGUF` / `VAELoaderGGUF`）

原启动命令只做了 `--windows-standalone-build`，没有显式 `--listen`，实际仍监听本机 8188，但为稳妥我新建了一个 API 专用 bat（**不覆盖原文件**）：

```bat
@echo off
set HF_ENDPOINT=https://hf-mirror.com
cd /d "%~dp0"
.\deepface\python.exe -s ComfyUI\main.py --windows-standalone-build --listen 127.0.0.1 --port 8188
```

**写好 bat 别急着双击**——先验证服务是否就绪：

```bash
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8188/system_stats
# 返回 200 即代表 ComfyUI + API 已就绪
```

### 踩坑一：端口冲突 [WinError 10048]

我第一次后台拉起新实例时，任务立刻 `failed`，日志报 `[WinError 10048]`（地址已被占用）。查端口发现 `8188` 已被占用——原来系统里**已经有一个 ComfyUI 实例在跑**（之前用原 bat 启动的，默认就监听该地址）。

教训：**启动前先 `curl` 探一下 8188**。如果已经 200，直接复用即可，不必重复启动；重复启动反而会因冲突退出。这也说明 API 默认就是开放的，无需额外配置就能被 WorkBuddy 连上。

---

## 四、构造 API 工作流（节点链）

没有现成工作流，我用 `GET /object_info` 抓取节点 schema，确认 `ComfyUI-GGUF` 节点的精确参数后再手造 JSON。Z-Image Turbo 的标准链路是：

```
UnetLoaderGGUF ──► ModelSamplingAuraFlow(shift=3)
                          │
KSampler(8步/cfg=1/res_multistep/simple) ◄── positive: CLIPLoaderGGUF(Qwen3-4B) + CLIPTextEncode + 提示词
                          │                  negative: ConditioningZeroOut（清零，Turbo 蒸馏模型无需反向词）
                          ▼
EmptyLatentImage(768×768) ──► latent_image
                          │
VAELoader(ae.safetensors) ──► VAEDecode ──► SaveImage
```

工作流 JSON 的核心片段（完整文件随 Skill 提供，提示词/尺寸/seed 设计为可外部注入）：

```json
{
  "10": {"class_type": "UnetLoaderGGUF", "inputs": {"unet_name": "z_image_turbo-Q4_K_M.gguf"}},
  "11": {"class_type": "CLIPLoaderGGUF", "inputs": {"clip_name": "Qwen3-4B-Q4_K_S.gguf", "type": "qwen_image"}},
  "12": {"class_type": "VAELoader", "inputs": {"vae_name": "ae.safetensors"}},
  "13": {"class_type": "ModelSamplingAuraFlow", "inputs": {"model": ["10", 0], "shift": 3.0}},
  "14": {"class_type": "CLIPTextEncode", "inputs": {"clip": ["11", 0], "text": "a beautiful woman portrait, cinematic lighting"}},
  "15": {"class_type": "ConditioningZeroOut", "inputs": {"conditioning": ["14", 0]}},
  "16": {"class_type": "EmptyLatentImage", "inputs": {"width": 768, "height": 768, "batch_size": 1}},
  "17": {"class_type": "KSampler", "inputs": {"model": ["13",0], "positive": ["14",0], "negative": ["15",0],
            "latent_image": ["16",0], "seed": 0, "steps": 8, "cfg": 1.0,
            "sampler_name": "res_multistep", "scheduler": "simple", "denoise": 1.0}},
  "18": {"class_type": "VAEDecode", "inputs": {"samples": ["17",0], "vae": ["12",0]}},
  "19": {"class_type": "SaveImage", "inputs": {"images": ["18",0], "filename_prefix": "ZImage"}}
}
```

两个要点必须点出：

- **`CLIPLoaderGGUF` 的 `type` 要填 `qwen_image`**：这是 Z-Image 用 Qwen3 文本编码器的关键，不填对会加载失败。
- **negative 用 `ConditioningZeroOut` 清零**：Z-Image Turbo 是蒸馏模型，`cfg=1.0`，不需要反提示词。

---

## 五、桥接脚本：零依赖提交→轮询→下载

桥接脚本用纯标准库 `urllib` 实现，零第三方依赖，避免污染环境。核心三步走：

**1) 注入参数后提交任务**

```python
wf["10"]["inputs"]["unet_name"] = args.unet
wf["14"]["inputs"]["text"]     = args.prompt          # 正向提示词
wf["16"]["inputs"]["width"]    = args.width           # 768
wf["16"]["inputs"]["height"]   = args.height
wf["17"]["inputs"]["seed"]     = args.seed or random.randint(0, 2**63-1)
wf["17"]["inputs"]["steps"]    = args.steps           # 8
wf["17"]["inputs"]["cfg"]      = args.cfg             # 1.0

resp = _post_json(f"http://{host}:{port}/prompt", {"prompt": wf, "client_id": uuid.uuid4().hex})
pid  = resp["prompt_id"]        # 拿到任务 ID，后续轮询靠它
```

**2) 轮询 `/history/{pid}` 直到出图**

```python
while time.time() < deadline:
    hist = _get_json(f"http://{host}:{port}/history/{pid}")
    if pid in hist:
        node = hist[pid]["outputs"]["19"]          # SaveImage 节点固定 id=19
        if node and "images" in node:
            break
    time.sleep(3)
```

**3) 从 `/view` 下载图片到本地**

```python
url  = f"http://{host}:{port}/view?filename={fn}&subfolder={sub}&type={typ}"
data = _download(url)
open(os.path.join(out_dir, fn), "wb").write(data)
```

调用方式就是一句：

```bash
python zimage_bridge.py --prompt "一位年轻女性在午后窗边的柔和自然光下，电影感肖像" \
                        --width 768 --height 768 --out-dir zimage_out
```

---

## 六、封装成 WorkBuddy Skill（可复用闭环）

把「工作流 JSON + 桥接脚本 + SKILL.md」放进 `~/.workbuddy/skills/zimage-local-gen/`，定义触发词「用 Z-Image 出图」。之后在对话里说一句「用 Z-Image 出一张 XX 图」，助手就会自动改提示词、提交、轮询、下载，并把图片路径回传。

这也是把「一次性脚本」变成「可复用能力」的关键一步——后续无论接哪个项目，只要提示词遵守对应赛道规范，出图能力直接复用。

---

## 七、踩坑复盘（三个真实工程坑）

### 坑一：端口 10048 冲突

如前所述。**先探端口再启动**，已就绪就复用，别重复拉实例。

### 坑二：GGUF 首次加载极慢（看似卡死，实则正常）

我在 360s 轮询上限内没等到出图，查 `/queue` 发现任务还在 `queue_running`，`/system_stats` 显示 GPU 显存已用约 **5.2/6.1GB**——没报错、没 OOM，只是 6GB 卡反量化 GGUF 极慢。**解法是把脚本轮询超时拉到 600s+**，首次加载完后续同模型会快很多。不要一超时就把任务 kill 掉重提，那是同一个 `prompt_id` 在跑，重提只会叠加队列。

### 坑三：6GB 显存 OOM 降级链

Q4_K_M 已接近 6GB 上限。若升分辨率到 1024×1024 或换更大模型可能 OOM。既定降级顺序：

1. 降 `--unet` 到 `z_image_turbo-Q4_K_S.gguf`（体积更小、显存更省，画质略损）；
2. 降分辨率到 512 / 640；
3. 降 batch_size（当前固定 1）。

> 实测结论：GTX 1660 6GB + `Q4_K_M` + 768×768 时，显存占用约 5.2GB，**稳定不 OOM，画质合格**。这是性价比最优档。

---

## 八、验证结果

冒烟测试 prompt：「一位年轻女性在午后窗边的柔和自然光下，电影感肖像，高清写实摄影，细腻皮肤质感」，768×768。

- 出图成功，`ZImage_00001_.png`（约 600KB）；
- GPU 显存峰值约 5.2 / 6.1 GB，**未 OOM**；
- 人像写实度高、符合提示词，Z-Image Turbo 在 6GB 量化下表现可用。

全链路（提交 → 轮询 → 下载 → 存盘）验证通过。

---

## 九、结语

把本地 ComfyUI 接入 WorkBuddy，技术上没有黑魔法，就是「HTTP API + 一份 API 格式工作流 + 一个轮询桥接脚本」。真正的工程价值在于三点：

1. **量化选型决定生死**：6GB 卡必须走 GGUF Q3/Q4，全量/BF16/FP8 直接出局；
2. **常驻服务 + 桥接层解耦**：重进程留给用户手动管理，助手只做轻量调度；
3. **Skill 化沉淀**：一次打通，长期复用，后续项目零成本接入。

如果你也在 6–8GB 显存区间折腾本地生图，希望这篇手记能帮你少走几步弯路。

---

*本文实验环境：Windows 10 / GTX 1660 6GB / ComfyUI_Z-Image-V2 (GGUF Q4_K_M) / WorkBuddy。模型与节点均来自社区开源版本，请遵守对应许可证使用。*

摘要：本文记录把本地部署的 ComfyUI_Z-Image-V2（GGUF 量化版 Z-Image Turbo 6B）接入 AI 助手 WorkBuddy 的完整过程。核心思路是让 ComfyUI 暴露 HTTP API，由 WorkBuddy 侧的零依赖桥接脚本提交任务、轮询结果、回传图片。文章重点复盘三个工程坑：端口冲突、GGUF 首次加载极慢、6GB 显存下的 OOM 降级策略，并给出可复用的 Skill 封装方案。实测在 GTX 1660 6GB 上以 Q4_K_M 量化稳定出图。

用 WorkBuddy 指挥本地 ComfyUI_Z-Image-V2：6GB 显卡跑通 Z-Image Turbo 文生图实战手记

摘要：本文记录把本地部署的 ComfyUI_Z-Image-V2（GGUF 量化版 Z-Image Turbo 6B）接入 AI 助手 WorkBuddy 的完整过程。核心思路是让 ComfyUI 暴露 HTTP API，由 WorkBuddy 侧的零依赖桥接脚本提交任务、轮询结果、回传图片。文章重点复盘三个工程坑：端口冲突、GGUF 首次加载极慢、6GB 显存下的 OOM 降级策略，并给出可复用

自媒体运营

人工智能

本地部署ComfyUI_Z-Image-V2（GGUF量化版）接入WorkBuddy全流程解析：通过HTTP API桥接实现对话直出图，零云端依赖。实测GTX1660 6GB显存下，以Q4_K_M量化稳定运行768×768出图，显存占用5.2GB。深度复盘端口冲突、GGUF首次加载缓慢、OOM降级链三大工程坑，并提供可复用Skill封装方案，助你快速搭建本地AI生图闭环。

代码解释

解释器

WorkBuddy 

Python

JSON

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本地部署ComfyUI_Z-Image-V2（GGUF量化版）接入WorkBuddy全流程解析：通过HTTP API桥接实现对话直出图，零云端依赖。实测GTX1660 6GB显存下，以Q4_K_M量化稳定运行768×768出图，显存占用5.2GB。深度复盘端口冲突、GGUF首次加载缓慢、OOM降级链三大工程坑，并提供可...

用 WorkBuddy 指挥本地 ComfyUI_Z-Image-V2：6GB 显卡跑通 Z-Image Turbo 文生图实战手记-腾讯云开发者社区-腾讯云

用 WorkBuddy 指挥本地 ComfyUI_Z-Image-V2：6GB 显卡跑通 Z-Image Turbo 文生图实战手记

用 WorkBuddy 指挥本地 ComfyUI_Z-Image-V2：6GB 显卡跑通 Z-Image Turbo 文生图实战手记

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐