XB-BOX - 📦 模型加载大全V1 (GGUF)

Same shape as XB_ModelLoaderV1 - one node, MODEL + CLIP + VAE, eight LoRA slots, SageAttention and block-swap hooks - except the model and CLIP dropdowns load GGUF files instead of safetensors. That's the whole difference, and it's a big one if you run big models on a small card.

GGUF is the llama.cpp quantized-format that jumped to diffusion in the Flux era and became the default way to run 12B+ models on 12GB cards. The Q ladder is the whole appeal: Q8 is basically fp16 at half the size, Q4_K_M is the accepted compromise for tight cards. This node is for people who already decided they're running quantized weights and just want the same one-node loading convenience as the safetensors version.

How it works

The crucial mechanism detail is that this node doesn't ship its own GGUF loader - it borrows the ComfyUI-GGUF node pack's. At first run it looks through your custom_nodes folder for a directory named ComfyUI-GGUF, loads that pack's nodes.py at runtime, and calls its UnetLoaderGGUFAdvanced and CLIPLoaderGGUF for the model and CLIP. If it can't find ComfyUI-GGUF installed, it raises a hard error: ComfyUI-GGUF 未安装！请先安装 GGUF 节点包。

So the honest dependency chain is: XB_ToolBox → ComfyUI-GGUF → llama.cpp backend. The VAE stays a plain safetensors VAELoader call, and LoRAs go through the standard LoraLoader - same as V1.

Inputs

Identical layout to V1 minus model_weight_dtype (GGUF quants are baked into the file, so there's no dtype dropdown):

• model_type - the keyword filter (same subfolder rule: files must live in a folder matching the keyword).
• model - the .gguf UNet.
• clip + clip_type - the .gguf text encoder (usually a quantized T5/Qwen).
• vae - plain VAE.
• lora_1..8 with _on/_strength.
• sage_preset, blocks_to_swap.

Outputs: MODEL, CLIP, VAE. _filter_by_keyword in this module also accepts .gguf extensions, which is how the dropdown sees your quant files in the first place.

Install

# 1. the real dependency - the GGUF node pack:
cd ComfyUI/custom_nodes
git clone https://github.com/city96/ComfyUI-GGUF.git

# 2. this pack:
cd ComfyUI/custom_nodes
git clone https://github.com/WJLUOXIAO/XB_ToolBox.git
# or: ComfyUI Manager → "XB_ToolBox"

Skip step 1 and the node will load but error the moment it tries to list or load a model. This is the single most common "why doesn't it work" report for the GGUF variants, and the pack's own README doesn't mention it because the README claims zero dependencies generally.

Notes

SageAttention's silent-fallback behavior applies here too: no sageattention package installed means no actual speedup, just a log line. And one GGUF-specific warning worth carrying from the format's history - LoRAs on GGUF pay a dequantize-patch-requantize tax per layer, so loading a LoRA onto a Q4 model can be slower than the quant saved you. For heavy LoRA stacks, weigh whether the full-precision V1 loader fits after all.