cang-ying/z_image_controlnet.md at ce32073d07668bfbf719a83bf06521e08dc9beb3

Zhuyuan Operations 3dd0d0b0c2 EED记忆: 推送范围铁律 + 面板自动唤醒经验 + Z-Image ControlNet 实跑验证

只同步 memory/eed/，未夹带任何代码/脚本/产物。

- feedback_memory_push: 新增推送范围铁律——只推 memory/eed/，
  代码脚本产物一律不碰，要推须先问过爸爸。爸爸原话「只提交经验和
  记忆就行，你不要随便什么都推送到代码仓库」。
- project_panel_autowake（新）: 面板开机自动唤醒的实现结构与踩坑
  （boot_id + 6h TTL + git 同步 + 快速唤醒卡三文件；broadcast/ 在
  仓库根目录不在 eererdan/ 下；重启别用 pkill -f 会自杀）
- z_image_controlnet: 补 2026-08-02 实跑验证记录（模型字节数校验、
  完整工作流链路、SaveImage 必带 filename_prefix 否则 400）
- user_setup / MEMORY.md: 随之更新

注：z_image_controlnet 与 user_setup 为面板端会话所写，本次做了
本地记忆库与仓库副本的双向合并，两边内容现已一致。

2026-08-02 22:40:23 +08:00

3.8 KiB

Raw Blame History

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 实查+跑通）。

关键事实（已逐一验证，别再走错路）：

应用节点 QwenImageDiffsynthControlnet 与 ZImageFunControlnet 本地 ComfyUI 已自带（comfy_extras/nodes_model_patch.py:547 / :584），无需安装任何自定义节点包。
加载器 ModelPatchLoader（分类 model/loaders）会按权重 key 自动识别 Z-Image 控制模型（检测到 control_all_x_embedder.2-1.weight 即实例化 comfy.ldm.lumina.controlnet.ZImage_Control，支持到 15 控制层 + refiner）。模型放 models/model_patches/ 即被扫描到。
comfyui_controlnet_aux 节点自带全套预处理（src/custom_controlnet_aux/：canny/depth_anything/open_pose/dwpose/lineart/hed…），不需要外挂 controlnet_aux PyPI 库。
唯一缺的：模型文件 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 · 三处都在

3.8 KiB Raw Blame History Unescape Escape

验证记录（2026-08-02 实跑通过）

3.8 KiB

Raw Blame History