# Z-Image Turbo Local Setup Notes

Z-Image Turbo is a high-performance image generation model that combines:
- **Stable Diffusion 3 with DFloat11 quantization**
- **Qwen 3.4B text encoder (fp8 quantized)**
- **Custom VAE for optimal output quality**

## Key Files Required

| File Type | Path | Notes |
|-----------|------|-------|
| Diffusion Model | `/home/wildlama/comfy/ComfyUI/models/diffusion_models/z_image_turbo_bf16-DF11.safetensors` | DFloat11 quantized Stable Diffusion 3 model |
| Text Encoder | `/home/wildlama/comfy/ComfyUI/models/text_encoders/qwen_3_4b_bf16_fp8_scaled.safetensors` | fp8 quantized Qwen 3.4B text encoder |
| VAE | `/home/wildlama/comfy/ComfyUI/models/vae/ae.safetensors` | Custom VAE for optimal image quality |

## Download URLs

**Diffusion Model:**
```
https://huggingface.co/mingyi456/Z-Image-Turbo-DF11-ComfyUI/resolve/main/z_image_turbo_bf16-DF11.safetensors
```

**Text Encoder (fp8):**
```
https://huggingface.co/tsqn/Z-Image-Turbo_fp8_comfyui/resolve/main/qwen_3_4b_bf16_fp8_scaled.safetensors
```

**VAE:**
```
https://huggingface.co/tsqn/Z-Image-Turbo_fp32-fp16-bf16_comfyui/resolve/main/vae/ae.safetensors
```

**Workflow (JSON):**
```
https://huggingface.co/mingyi456/Z-Image-Turbo-DF11-ComfyUI/resolve/main/z_image_turbo_bf16-DF11-workflow.json
```

## Download Pattern for Resumable Downloads

Due to large file sizes (several GB), downloads should be resumable:

```bash
# Start download with resumable curl
curl -L --fail --retry 50 --retry-delay 10 -C - \
  -o /home/wildlama/comfy/ComfyUI/models/diffusion_models/z_image_turbo_bf16-DF11.safetensors \
  https://huggingface.co/mingyi456/Z-Image-Turbo-DF11-ComfyUI/resolve/main/z_image_turbo_bf16-DF11.safetensors
```

## Setup Considerations

### VRAM Requirements
- Requires **≥24 GB VRAM** for optimal performance.
- With 32 GB GPU (RTX 5090), should handle full inference.

### Custom Node Installation
The DFloat11 node was installed manually:
```bash
cd /home/wildlama/comfy/ComfyUI/custom_nodes
git clone https://github.com/mingyi456/ComfyUI-DFloat11-Extended.git
```

### Hermes-specific Notes

When downloading models in Hermes sessions, the following issues were encountered:

1. **Hermes Venv Issue**: 
   - `comfy` commands would fail if `VIRTUAL_ENV` was set to Hermes's own venv
   - Resolution: Use clean environment with explicit PATH
   ```bash
   env -u VIRTUAL_ENV PATH=/home/wildlama/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin comfy node install ...
   ```

2. **SSL Certificate Issues**:
   - `curl` failed due to missing certificates from Hermes's venv
   - Solution: Install `ca-certificates` package system-wide

3. **Background Downloads**:
   - Large model downloads should be started with `terminal(background=true, notify_on_complete=true)` 
   - This allows Hermes to track completion and resume interrupted downloads

## Workflow Conversion Notes

The workflow from HuggingFace uses a JSON structure compatible with ComfyUI API format.

Note that when converting workflows from the ComfyUI editor (which uses nodes/links format), ensure they are exported using "Workflow → Export (API)" or "Save (API Format)" before execution.