HQH-XPU

HQH-XPU

ComfyUI optimization bundle for Intel Arc A770 (XPU) — self-developed nodes, patched plugins, core patches, and tooling, packaged for easy deployment and upstream contribution.

Baseline: ComfyUI 0.31.0 / torch 2.13.0+xpu / Intel Arc A770 16GB / Windows Created: 2026-08-10 · 中文说明见 README_zh.md Publishing policy: see PUBLISHING.md — this repo is source-only.

What This Bundle Does

HQH-XPU is a stable, fast, reusable ComfyUI node collection for the Arc A770. After install, typing HQH-XPU in the canvas node search lists every bundled node, each with its own "function / author / purpose" Markdown docs.

| Module | Function | Purpose | |--------|----------|---------| | TINT4 | INT4 quantized loading / quantizer / LoRA (oneDNN hybrid) | ~4× less weight VRAM for 22B-class models; ~2.4x mid-M forwards | | OmniXPU | XPU kernel integration + diagnostics | confirm/enable XPU acceleration, locate missing kernels | | XPU-CacheClean | VRAM cleanup / gated release / two-stage clean | prevents OOM and DEVICE_LOST on long runs | | ClipProj | small text encoder + learned projection | lossless Chinese dialogue with far less encoder VRAM | | UniversalIO | Conditioning / Latent save-load | two-stage workflow core, persist across runs | | H3-Latent-Upscaler | 2× clean MiniMax H3 latent upscaler | upscale before decode, audio unchanged, no pixel round-trip | | HQH-H3-Pipeline | H3 core / one-shot pipeline nodes | 9 ref-image slots + ref-audio, conditioning cache (ram/disk), cache controller, chunk auto + VRAM guard, report JSON |

Repository Layout

Git tracks source only (nodes/ + docs below). Local tooling/scripts (tools/) and working logs (docs/) are kept on disk but not published.

HQH-XPU/
├── nodes/                 # Ready-to-use node packs (mounted into ComfyUI via junctions)
│   ├── ComfyUI-TINT4/         # torchao INT4 quantization (heavily patched: oneDNN hybrid)
│   ├── ComfyUI-OmniXPU/       # XPU kernel integration (bugfixes + norm patch)
│   ├── ComfyUI-XPU-CacheClean # VRAM cache cleaner (new XPU_TwoStageClean)
│   ├── ComfyUI-ClipProj/      # small encoder + projection (XPU device patch)
│   ├── ComfyUI-UniversalIO/   # self-developed Conditioning/Latent save-load (two-stage core)
│   ├── ComfyUI-H3-Latent-Upscaler-Mamad8/ # H3 clean-latent 2× upscaler (with Chinese Markdown docs)
│   └── ComfyUI-HQH-H3-Pipeline/ # self-developed H3 core/one-shot pipeline (cache, guard, ref-audio)
├── install.ps1            # One-command deploy: links nodes/* into ComfyUI/custom_nodes
└── README.md / README_zh.md

tools/ (scripts, patches, installer archive) and docs/ exist locally but are not tracked/published — they are working tools for this machine.

What Is Included

ComfyUI-TINT4 (4 files modified — upstream-ready)

| File | Change | Status | |------|--------|--------| | tint4_quantizer.py | T1/T2: group-scale assignment order; skip fp8 source scale keys | ✅ | | tint4_loader.py | T3/T5 + oneDNN hybrid: M<4096 uses oneDNN u4 GEMM (f16 + asymmetric-zp correction), LRU sync release, M<512 fp16 dequant to avoid a driver crash | ✅ verified 4/4 | | tint4_lora_loader.py | adaln E-grid injection (dialogue/emotion stability) | ✅ | | tint4_aimdo.py | T4: force AIMDO detection keys | ✅ |

ComfyUI-OmniXPU (2 files modified — upstream-ready)

| File | Change | |------|--------| | probe.py | O1/O2: import os; sdp sidecar gate | | patches/patch_norm.py | O3: contiguous() for non-contiguous rms_norm inputs |

ComfyUI-XPU-CacheClean (1 file)

| Change | Status | |--------|--------| | XPU_CacheCleanGate hardening (O4: release shared CLIP cond_stage_model to CPU) | ✅ | | XPU_TwoStageClean (new, self-developed): TINT4 flush + dual sync + trigger passthrough | 🧪 experimental |

ComfyUI-ClipProj (1-line patch — upstream-ready)

• gpu_devices() adds xpu:0 (enables 4B fp8 encoder + projection on A770, lossless Chinese dialogue)

ComfyUI-UniversalIO (self-developed, local)

• Save/Load/Pass nodes for Conditioning & Latent (fixed filenames + auto-clean)
• Core of the two-stage workflow: A-stage encode to disk, B-stage sample
• Includes js/universal_io.js frontend extension

ComfyUI-H3-Latent-Upscaler-Mamad8 (new, based on upstream MIT code)

• Upstream: mamad8c/ComfyUI-H3-Latent-Upscaler-Mamad8 — 2× upscaler for clean MiniMax H3 video latents (before VAE decode; audio unchanged)
• Local change: nodes.py descriptions replaced with Chinese Markdown usage docs (rendered in the ComfyUI node properties panel)
• Model: models/h3_latent_upscalers/h3_clean_latent_upscaler_v1_mamad8.safetensors (56.3MB, HuggingFace / hf-mirror)
• Wiring: H3 Sampler (sigma=0) → Upscale Clean H3 Latent 2x → H3 VAE Decode

Frontend extension (HQH-XPU root pack)

• js/hqh_xpu_search.js: adds the HQH-XPU search alias to every bundled node (TINT4 / OmniXPU / CacheClean / ClipProj / UniversalIO / H3-Latent-Upscaler). Typing HQH-XPU in the canvas node search lists the whole bundle (original categories are kept).

Core Patches (patches/, re-apply after upgrade)

• comfy/sd.py: VAE decode/encode @torch.no_grad() + pre-decode cleanup (black-screen/OOM root fix)
• comfy/ldm/minimax/model.py: torch.xpu.synchronize() at _run_blocks entry
• folder_paths.py: add .gguf to supported extensions
• comfy-env detection/gpu.py: torch pre-import guard (see install.ps1)

Installation

git clone <HQH-XPU-repo-url> && cd HQH-XPU
powershell -ExecutionPolicy Bypass -File install.ps1 -ComfyRoot "<path-to-ComfyUI>"
# (omit -ComfyRoot when the repo lives in <ComfyUI>/custom_nodes/HQH-XPU: it auto-detects)

Recommended environment variable (already set by install notes / your launcher):

$env:TINT4_ONEDNN = "1"   # oneDNN hybrid: ~2.4x mid-M forwards, stable int4pack for large M

Upstream Contribution Plan

| Repo | Content | |------|---------| | JWLHS/ComfyUI-TINT4 | T1~T5 + oneDNN hybrid mode | | Jasonzzt/ComfyUI-OmniXPU | O1~O3 | | comfy-org/ComfyUI | VAE no_grad + pre-decode cleanup | | nicolab28/ComfyUI-ClipProj | XPU device patch | | intel/llm-scaler | dg2 build support (evaluation) |

Known Limitations (driver-level, awaiting upstream)

• Single-prompt unified graph (A+B): driver kernel hang → use the two-stage flow (tools/)
• SDPA acceleration: Xe2-only sidecar, not compilable for dg2
• oneDNN large M: intermittent NaN → hybrid mode avoids it
• TeaCache: drift/face-collapse on quantized models

License

MIT for this bundle; each plugin follows its upstream license. Model weights are not included.