README.md

metadata

title: Zig
emoji: 🏃
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false

Z-Image Hugging Face Space

Gradio Space using the official Z-Image pipeline (Tongyi-MAI/Z-Image-Turbo) with optional LoRA injection (Civitai link you provided). There is no SD1.5 fallback—if the Z-Image model is unavailable, the Space will fail to load.

Files

• app.py: Z-Image pipeline, FlowMatch scheduler, LoRA toggle/strength, simple gallery UI.
• requirements.txt: Python deps for Spaces/local runs.
• lora/: Place zit-mystic-xxx.safetensors here (or point LORA_PATH to your filename).
• .gitattributes: Tracks .safetensors via Git LFS for large LoRA files.

Using on Hugging Face Spaces

1. Create a Space (Python) and select a GPU hardware type.
2. Add/clone this repo into the Space.
3. Manually add the LoRA file from https://civitai.com/models/2206377/zit-mystic-xxx to lora/zit-mystic-xxx.safetensors (or set LORA_PATH). Network fetch of Civitai is not handled in the Space.
4. If model download fails with a token error, set HF_TOKEN in the Space secrets (some repos require authentication).
5. (Optional) Toggle advanced envs below; then the Space will launch app.py. The header shows whether the LoRA was detected/loaded.
   • If the header/log says PEFT backend is required for LoRA, install peft (already included in requirements.txt) and restart/rebuild.

Environment variables

• MODEL_PATH (default Tongyi-MAI/Z-Image-Turbo): HF repo or local path for the Z-Image model.
• LORA_PATH (default lora/zit-mystic-xxx.safetensors): Path to the LoRA file; loaded if present.
• HF_TOKEN: HF token for gated/private models or faster pulls.
• MODEL_DTYPE (default auto): bf16 if supported, else fp16 (override with bf16/fp16/fp32).
• ENABLE_COMPILE (default true): Enable torch.compile on the transformer.
• ENABLE_WARMUP (default false): Run a quick warmup across resolutions after load (adds startup time).
• ATTENTION_BACKEND (default flash_3): Backend for transformer attention (falls back to flash/xformers/native).
• OFFLOAD_TO_CPU_AFTER_RUN (default false): Move the model back to CPU after each generation (useful on ZeroGPU; slower on normal GPUs).
• ENABLE_AOTI (default true): Try to load ZeroGPU AoTI blocks via spaces.aoti_blocks_load for faster inference.
• AOTI_REPO (default zerogpu-aoti/Z-Image): AoTI blocks repo.
• AOTI_VARIANT (default fa3): AoTI variant.
• AOTI_ALLOW_LORA (default false): Allow AoTI to load even if LoRA adapters are loaded (may crash; AoTI blocks generally don’t support LoRA).
• DEBUG (default false): When set to a truthy value (1, true, yes, on), hide the Status/Debug floating panel.

Run locally

python -m venv .venv
.venv\Scripts\activate  # Windows; on Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python app.py

Place the LoRA file under lora/ first (or set LORA_PATH); otherwise the app will run the base Z-Image model without LoRA.

UI controls

• Prompt
• Resolution category + explicit WxH selection
• Seed (with random toggle)
• Steps + Time Shift
• Advanced: CFG, scheduler + extra scheduler params, max sequence length
• LoRA toggle + strength (enabled only if the file is found)

Git LFS note

.gitattributes tracks .safetensors with LFS. If you commit the LoRA, run git lfs install once before pushing so large files go through LFS.