| | --- |
| | 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 |
| | ```bash |
| | 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. |
| |
|
