---
name: z_image_controlnet
description: Z-Image-Turbo ControlNet（Fun-Controlnet-Union）已验证配置：节点/加载器/模型位置/2.1下载/管线，纠正"要装包/要controlnet_aux库"两条错路
type: project
---

为 Z-Image-Turbo 加 ControlNet 精确控制（Canny/Depth/Pose），本地已验证全链路可用（2026-08-02 实查+跑通）。

**关键事实（已逐一验证，别再走错路）：**
1. 应用节点 `QwenImageDiffsynthControlnet` 与 `ZImageFunControlnet` **本地 ComfyUI 已自带**（comfy_extras/nodes_model_patch.py:547 / :584），**无需安装任何自定义节点包**。
2. 加载器 `ModelPatchLoader`（分类 model/loaders）会**按权重 key 自动识别** Z-Image 控制模型（检测到 `control_all_x_embedder.2-1.weight` 即实例化 `comfy.ldm.lumina.controlnet.ZImage_Control`，支持到 15 控制层 + refiner）。模型放 `models/model_patches/` 即被扫描到。
3. `comfyui_controlnet_aux` 节点**自带全套预处理**（`src/custom_controlnet_aux/`：canny/depth_anything/open_pose/dwpose/lineart/hed…），**不需要外挂 `controlnet_aux` PyPI 库**。
4. 唯一缺的：模型文件 `Z-Image-Turbo-Fun-Controlnet-Union`。官方最新 **2.1** 版在 `alibaba-pai/Z-Image-Turbo-Fun-Controlnet-Union-2.1`（2.0 / ModelScope 原版也兼容加载器）。

**下载（需开沙箱联网）：**
`huggingface-cli download alibaba-pai/Z-Image-Turbo-Fun-Controlnet-Union-2.1 --include "*.safetensors" --local-dir /home/ls/comfy/ComfyUI/models/model_patches/`
（下载前先列清单确认精确 safetensors 文件名与体积）

**工作流节点链（加进现有 Z-Image img2img 草图→上色）：**
```
参考图 →[comfyui_controlnet_aux 预处理: Canny/Depth/OpenPose 任选]→ hint图
model(Z-Image Turbo) + ModelPatchLoader(Union模型)→MODEL_PATCH
  └─[QwenImageDiffsynthControlnet: model, model_patch, vae, image=hint, strength=1.0]→ 受控MODEL
受控MODEL → KSampler(denoise=0.75, steps=8, cfg=1.0, res_multistep, simple)
  + VAEEncode(草图)作latent + CLIPTextEncode(qwen_3_4b)正 + ConditioningZeroOut负
  → VAEDecode → SaveImage
```

**Why:** 之前 summary 记了两条错路（"要装 QwenImageDiffsynthControlnet 自定义包"、"缺 controlnet_aux 库要 pip 装"），实查都是错的，白费时间。ControlNet 让 Z-Image 草图生图能锁定构图/姿态/深度，是爸爸要的"功能要全"。

**How to apply:** 再遇到 Z-Image 加 ControlNet，直接按本文件走，先查 eed 复用，别重新瞎找节点包或装库。模型下载属联网操作，按 EED-PROTO-005（申请→爸爸验证码→固定动作→回执）走，且沙箱禁联网需 dad 批准开 dangerouslyDisableSandbox。

## 验证记录（2026-08-02 实跑通过）
- ✅ 模型下载完成并校验：Z-Image-Turbo-Fun-Controlnet-Union-2.1.safetensors = **6712485600 字节（精确匹配）**，放 `models/model_patches/`
- ✅ 工作流实跑成功链路：`sketch_test.png` → CannyEdgePreprocessor(分辨率1024) → QwenImageDiffsynthControlnet(model, model_patch, vae, image=hint, strength=1.0) → VAEEncode(草图)作latent → KSampler(denoise=0.75, steps=8, cfg=1.0, res_multistep/simple) → VAEDecode → 出图 `suba_cn_canny_v1.png`（1024²）
- ⚠️ 踩坑：SaveImage 节点**必须带 `filename_prefix`**，否则 `/prompt` 返回 400（prompt_outputs_failed_validation: Required input is missing: filename_prefix）
- 节点名确认本地齐全：UNETLoader / ModelSamplingAuraFlow / CLIPLoader(type=lumina2) / VAELoader(ae.safetensors) / ModelPatchLoader / CannyEdgePreprocessor / QwenImageDiffsynthControlnet / VAEEncode / KSampler / VAEDecode，全在 ComfyUI 0.29.0 内核
- 模型文件确认：diffusion_models/z_image_turbo_bf16.safetensors(12G) · text_encoders/qwen_3_4b.safetensors(7.5G) · vae/ae.safetensors · 三处都在