docs/COMFY_BACKEND.md

Embedded ComfyUI Backend

This Space keeps the Gradio UI and ZeroGPU decorator but runs generation through embedded ComfyUI nodes instead of Diffusers or a separate Comfy server.

Runtime Flow

1. app.py validates Gradio inputs into GenerationParams.
2. src.comfy_backend.run_generation() initializes ComfyUI imports and model folder paths.
3. Comfy loader outputs for UNET, CLIP, and VAE are cached per worker.
4. Before caching, the UNET may pass through ModelSamplingAuraFlow (unless ZANIME_DISABLE_AURA_SAMPLING=1) to mirror the official Z-Anime workflow.
5. Each generation runs CLIPTextEncode, EmptyLatentImage, native KSampler, and VAEDecode.
6. Decoded tensors become RGB PIL.Image objects for the Gradio gallery.

No Comfy HTTP server (/prompt, websocket, etc.).

Only core Comfy nodes load by default; ModelSamplingAuraFlow is pulled from comfy_extras.nodes_model_advanced without loading all optional node packs.

Set ZANIME_INIT_COMFY_EXTRA_NODES=1 only if you intentionally need broader Comfy extra/custom initialization.

Optional audio-related imports may pull torchaudio; by default a stub is installed when the real wheel is missing or incompatible.

Source And Models

ComfyUI source lives at ComfyUI/. If missing, the runtime downloads the pinned archive (see COMFYUI_SOURCE.md), unless ZANIME_DISABLE_COMFY_SOURCE_FETCH=1.

Model layout under ZANIME_MODELS_ROOT or ComfyUI/models/:

• diffusion_models/z-anime-distill-8step-fp8.safetensors
• text_encoders/qwen_3_4b-fp8.safetensors
• vae/ae.safetensors
• optional mirror: clip/qwen_3_4b-fp8.safetensors (bootstrap tries to hardlink/copy)

ZeroGPU Notes

Heavy work runs inside @spaces.GPU. Loader outputs stay cached per worker.

If Comfy removes CLIPLoader support for type="qwen_image" or changes loader APIs, startup or first generation fails with a user-facing error.