cang-ying/memory/eed/z_image_controlnet.md

name, description, type

name	description	type
z_image_controlnet	Z-Image-Turbo ControlNet（Fun-Controlnet-Union）已验证配置：节点/加载器/模型位置/2.1下载/管线，纠正"要装包/要controlnet_aux库"两条错路	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 · 三处都在