Hunyuan Instruct Loader is a ComfyUI node in the Hunyuan/Instruct category from Comfy_HunyuanImage3. Inputs: model_name, force_reload, attention_impl…

Professional ComfyUI custom nodes for Tencent's HunyuanImage-3.0 80B multimodal model, with multiple loading modes, smart memory management, large image generation with CPU offload, and optional prompt enhancement via LLM APIs.

Comfy_HunyuanImage3

model_name

force_reload

attention_impl

moe_impl

vram_reserve_gb

blocks_to_swap

moe_drop_tokens

vae_dtype

HunyuanInstructLoader

model

Hunyuan Instruct Loader

Name	Type	Default	Description
model_name	COMBO	HunyuanImage-3.0-Instruct-Distil-INT8	Select Instruct or Instruct-Distil model folder
force_reload	BOOLEAN	false	Force reload model even if cached
attention_implopt	COMBO	sdpa	Attention implementation. flash_attention_2 requires flash-attn package.
moe_implopt	COMBO	eager	MoE implementation. flashinfer is faster but requires flashinfer package.
vram_reserve_gbopt	FLOAT	305–80	VRAM to reserve on primary GPU for inference (BF16 and INT8, only when blocks_to_swap=0). The MoE dispatch_mask during think_recaption can use 14-28GB (Distil) or 28-56GB (full Instruct). Default 30GB is auto-boosted to 40GB for full Instruct models (which use CFG with batch=2, doubling all inference tensors). Increase to 40-50 if you see OOM during generation. For INT8: if the model + reserve exceeds GPU memory, the model is automatically split across GPUs. Ignored when blocks_to_swap > 0 (block swap manages VRAM instead). Has no effect on NF4 models.
blocks_to_swapopt	INT	00–31	Number of transformer blocks to swap CPU↔GPU during inference. Enables running large models on GPUs with limited VRAM. 0 = no swapping (all blocks on GPU, fastest). Higher values save more VRAM but run slower. Quality is NOT affected — only memory management changes. Block sizes by quant type: NF4: ~0.75GB/block (10 blocks → saves ~7.5GB) INT8: ~2.5GB/block (10 blocks → saves ~25GB) BF16: ~5.0GB/block (22 blocks → saves ~110GB) IMPORTANT for full Instruct models (non-Distil): These use CFG (batch=2) which DOUBLES all inference tensors. For INT8 full Instruct, recommend blocks_to_swap=10-15 to leave 40GB+ free for CFG dispatch_mask + KV cache. When block swap is enabled for INT8/BF16, the model loads to CPU first then swaps blocks to GPU as needed, bypassing device_map=auto. This avoids accelerate hook conflicts.
moe_drop_tokensopt	BOOLEAN	true	True (default): MoE drops tokens that exceed expert capacity (lower VRAM, ~1–3% quality cost on dense regions). False: route every token through its top-K experts (best quality, higher VRAM peak — recommended only on ≥48GB cards).
vae_dtypeopt	COMBO	bfloat16	VAE decode precision. bfloat16 (default) matches model dtype. float32 reduces banding/chroma noise on smooth gradients with negligible cost on big cards. (Some users may already force this via ComfyUI launch flag.)

Hunyuan Instruct Loader

Inputs (8)

Outputs (1)