JoyAI-Image-Edit (GGUF) for ComfyUI

Introduction

This is the unofficial GGUF companion package for joyai_image_comfyui. It adds two GGUF loader nodes that produce drop-in replacements for the bf16 transformer / text encoder loaders provided by the main package.

It follows the same conventions as the ComfyUI-GGUF plugin:

• Dedicated GGUF loader nodes, separate from the safetensors loaders.
• GGUF files live in the standard ComfyUI folders (ComfyUI/models/diffusion_models/ and ComfyUI/models/text_encoders/), next to their safetensors counterparts.
• Loader dropdowns are filtered by extension, so the GGUF nodes only list .gguf files.
• Display names carry the (GGUF) suffix to keep them visually distinct from the bf16 loaders.

This package must be installed alongside joyai_image_comfyui. The GGUF loaders only emit JOY_MODEL / JOY_CLIP sockets; the actual JoyAIImageEditPipeline node lives in joyai_image_comfyui, which is required to assemble the pipeline and run inference. There is no GGUF VAE loader — the VAE format is not GGUF-supported and is always loaded as bf16 by the main package.

Quick Start

1. Requirements

• joyai_image_comfyui (the bf16 package) — must be installed first; it provides the JoyAIImageEditPipeline node and the VAE loader.
• diffusers: >=0.39.0.dev0 (with JoyImageEditPipeline support; install from source: pip install git+https://github.com/huggingface/diffusers.git)
• transformers: >=4.57.0
• gguf: pip install gguf

2. Installation Steps

Step 1: Install the bf16 package first

cd ComfyUI/custom_nodes
git clone https://github.com/jd-opensource/JoyAI-Image.git
cp -r JoyAI-Image/joyai_image_comfyui ./

Step 2: Install this GGUF companion package

git clone https://github.com/feice-huang/joyai_image_comfyui_gguf.git
rm -rf JoyAI-Image

Step 3: Download Model Weights

Drop the GGUF files directly into the same standard ComfyUI folders that the bf16 package reads from — no diffusers-style subdirectory layout is needed. Each loader filters by extension, so safetensors and GGUF files can coexist in the same directory:

ComfyUI/models/
├── diffusion_models/
│   ├── joy_image_edit_bf16.safetensors                    # bf16 transformer (optional)
│   └── joy-image-edit-transformer-Q4_K_M.gguf             # one or more GGUF quants
├── text_encoders/
│   ├── qwen3vl_joyimage_bf16.safetensors                  # bf16 text encoder (optional)
│   └── joy-image-edit-text_encoder-Q4_K_M.gguf            # one or more GGUF quants
└── vae/
    └── joy_image_edit_vae.safetensors                     # VAE is never quantized

GGUF quants are published at huangfeice/JoyAI-Image-Edit-Diffusers-GGUF. Download whichever quants you need (one transformer file and one text-encoder file is enough to run) and drop them into the folders above — the loader nodes will pick them up automatically.

Step 4: Restart ComfyUI

ComfyUI will discover both packages. The bf16 loaders appear under loaders/joyai, and the GGUF loaders appear next to them with the (GGUF) display-name suffix.

Node Reference

This package provides 2 nodes:

| Node | Display Name | Category | Description | |------|-------------|----------|-------------| | JoyAIImageEditUNETLoaderGGUF | Load JoyAI Diffusion Model (GGUF) | loaders/joyai | Loads a GGUF-quantized JoyImageEditTransformer3DModel from ComfyUI/models/diffusion_models/ | | JoyAIImageEditCLIPLoaderGGUF | Load JoyAI CLIP (GGUF) | loaders/joyai | Loads a GGUF-quantized Qwen3VL text encoder from ComfyUI/models/text_encoders/ and bundles it with the tokenizer + processor |

Non-quantized submodules (condition_embedder/img_in/proj_out/norm_out on the transformer; visual/embed_tokens/lm_head on the text encoder) are dequantized to bfloat16 at load time, RoPE buffers on the meta device are rebuilt, and remaining floating-point parameters are cast to bfloat16.

ComfyUI-GGUF compatibility

This package mirrors the ComfyUI-GGUF plugin's design so users moving between the two ecosystems see a familiar layout:

• folder_paths extension keys for GGUF are registered separately (joy_unet_gguf, joy_clip_gguf), reusing the same underlying paths as diffusion_models / text_encoders but restricted to the .gguf extension.
• Loader nodes are split per format rather than overloaded behind a single dropdown.
• Display names carry the (GGUF) suffix, and class names keep the GGUF suffix to avoid collisions when both packages are loaded into the same ComfyUI instance.

CPU Offload Strategy

This package does not own the pipeline — it only emits JOY_MODEL / JOY_CLIP sockets. The 4-phase CPU offload (text encoding → VAE encode → denoising → VAE decode) is implemented by the JoyAIImageEditPipeline node from joyai_image_comfyui, and works identically with GGUF or bf16 inputs: each phase moves exactly one sub-module to GPU and back. See the bf16 package README for the full 4-phase description.