Fabian
181 lines
5.1 KiB
Plaintext
181 lines
5.1 KiB
Plaintext
# Z-Image-Turbo on AMD BC-250 — Setup Documentation
|
||
|
||
## Overview
|
||
|
||
**Z-Image-Turbo** image generation server running on **AMD BC-250** (GFX1013 RDNA2, 24 CUs) via **Vulkan** (RADV/Mesa) on **CachyOS**.
|
||
|
||
| Component | Detail |
|
||
|-----------|--------|
|
||
| **GPU** | AMD BC-250 — 24 CUs, GFX1013 RDNA2, 16 GB shared GDDR6 |
|
||
| **Driver** | RADV (Mesa 25.3.4) via Vulkan 1.4.335 |
|
||
| **Backend** | Vulkan only (no ROCm) |
|
||
| **Server** | [stable-diffusion.cpp-restapi](https://github.com/fszontagh/stable-diffusion.cpp-restapi) |
|
||
| **OS** | CachyOS (Arch-based) |
|
||
|
||
## Models
|
||
|
||
| Model | File | Size | Location |
|
||
|-------|------|------|----------|
|
||
| Z-Image-Turbo | `z_image_turbo-Q5_K_S.gguf` | 4.9 GB | `~/sd-models/diffusion_models/` |
|
||
| Qwen3-4B Instruct | `Qwen3-4B-Instruct-2507-Q5_K_S.gguf` | 2.8 GB | `~/sd-models/llm/` |
|
||
| FLUX VAE | `ae.safetensors` | 320 MB | `~/sd-models/vae/` |
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
~/
|
||
├── stable-diffusion.cpp-restapi/
|
||
│ └── build/
|
||
│ ├── bin/sdcpp-restapi # Server binary (80 MB)
|
||
│ ├── config.json # Server configuration
|
||
│ └── webui/ # Vue.js WebUI
|
||
├── sd-models/
|
||
│ ├── diffusion_models/ # Main diffusion model GGUFs (Z-Image)
|
||
│ ├── checkpoints/ # Legacy checkpoint models
|
||
│ ├── vae/ # VAE models
|
||
│ ├── llm/ # LLM models (prompt enhancement)
|
||
│ ├── lora/ # LoRA adapters
|
||
│ ├── clip/ # CLIP models
|
||
│ ├── t5/ # T5 text encoders
|
||
│ ├── embeddings/ # Textual inversions
|
||
│ ├── controlnet/ # ControlNet models
|
||
│ ├── esrgan/ # Upscaler models
|
||
│ └── taesd/ # Tiny AutoEncoder models
|
||
├── sd-outputs/ # Generated images
|
||
├── start-zimage.sh # Quick start script
|
||
└── .config/systemd/user/
|
||
└── zimage.service # Systemd user service
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Option 1: Manual start
|
||
~/start-zimage.sh
|
||
|
||
# Option 2: Systemd service
|
||
systemctl --user start zimage
|
||
```
|
||
|
||
Then open: **http://localhost:8080/ui**
|
||
|
||
## Usage
|
||
|
||
### WebUI
|
||
|
||
1. Open http://localhost:8080/ui
|
||
2. Go to **Models** → select `z_image_turbo-Q5_K_S.gguf`
|
||
3. Set VAE to `ae.safetensors`, LLM to `Qwen3-4B-Instruct-2507-Q5_K_S.gguf`
|
||
4. First load takes 20–40 seconds
|
||
5. Settings: **Steps 8**, **CFG 1.0**, **Euler** sampler
|
||
6. Start with 512×512 (~37 s), then try 1024×1024 (~80 s)
|
||
|
||
### API — Load Model
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/models/load \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model_name": "z_image_turbo-Q5_K_S.gguf",
|
||
"model_type": "diffusion",
|
||
"vae": "ae.safetensors",
|
||
"llm": "Qwen3-4B-Instruct-2507-Q5_K_S.gguf"
|
||
}'
|
||
```
|
||
|
||
### API — Generate Image (512×512)
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/txt2img \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "astronaut on mars, cinematic",
|
||
"width": 512,
|
||
"height": 512,
|
||
"steps": 8,
|
||
"cfg_scale": 1.0,
|
||
"sampler_name": "euler",
|
||
"scheduler": "smoothstep",
|
||
"seed": -1
|
||
}' --output image.png
|
||
```
|
||
|
||
## Systemd Service
|
||
|
||
```bash
|
||
# Enable auto-start on login
|
||
systemctl --user enable zimage
|
||
|
||
# Start / stop / restart
|
||
systemctl --user start zimage
|
||
systemctl --user stop zimage
|
||
systemctl --user restart zimage
|
||
|
||
# View logs
|
||
journalctl --user -u zimage -f
|
||
```
|
||
|
||
## Vulkan Environment Variables
|
||
|
||
| Variable | Value | Purpose |
|
||
|----------|-------|---------|
|
||
| `AMD_VULKAN_ICD` | `RADV` | Use Mesa RADV driver |
|
||
| `GGML_VK_FORCE_MAX_ALLOCATION_SIZE` | `536870912` | 512 MB max alloc (OOM prevention) |
|
||
| `RADV_PERFTEST` | `nggc` | NGG culling compute boost |
|
||
|
||
## Troubleshooting
|
||
|
||
### Slow generation (>20s at 1024×1024)
|
||
```bash
|
||
# Check logs for allocation failures
|
||
journalctl --user -u zimage -f
|
||
|
||
# Try reducing max allocation to 256 MB
|
||
export GGML_VK_FORCE_MAX_ALLOCATION_SIZE=268435456
|
||
|
||
# Try AMDVLK instead of RADV
|
||
sudo pacman -S amdvlk
|
||
export AMD_VULKAN_ICD=AMDVLK
|
||
```
|
||
|
||
### Vulkan not detecting GPU
|
||
```bash
|
||
# Verify Vulkan
|
||
vulkaninfo --summary | grep BC-250
|
||
|
||
# Force ICD file path
|
||
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.x86_64.json vulkaninfo
|
||
```
|
||
|
||
### Out of Memory (OOM)
|
||
- Use Q3_K_S quantization (smaller model)
|
||
- Set `batch_count: 1` in generation requests
|
||
- Reduce resolution to 512×512
|
||
|
||
### Monitor GPU
|
||
```bash
|
||
# GPU utilization
|
||
watch radeontop
|
||
|
||
# VRAM usage
|
||
cat /sys/class/drm/card0/device/mem_info_vram_used
|
||
```
|
||
|
||
## Build from Source (Reference)
|
||
|
||
```bash
|
||
cd ~/stable-diffusion.cpp-restapi
|
||
mkdir -p build && cd build
|
||
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DSD_VULKAN=ON -DSDCPP_WEBUI=ON
|
||
ninja -j$(nproc --all)
|
||
```
|
||
|
||
## Performance Expectations
|
||
|
||
| Resolution | Expected Time | Notes |
|
||
|------------|--------------|-------|
|
||
| 512×512 | ~37 seconds | Q5_K_S, 8 steps, Euler, Vulkan |
|
||
| 512×1024 | ~80 seconds | Q5_K_S, 8 steps, Euler, Vulkan |
|
||
| 1024×1024 | ~150 seconds | Q5_K_S, 8 steps, Euler, Vulkan |
|
||
| First load | 20–40 seconds | One-time on startup |
|