Uploaded sanitized BC250/ROCm Repository.

2026-08-20 00:45:43 +02:00
parent 7d2184f1e8
commit d7d22e93b3
678 changed files with 65963 additions and 1 deletions
@@ -0,0 +1,180 @@
+# 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 |