From fc78b51e29497703a65f125e844f7da558dbc577 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 6 Jul 2026 18:34:31 +0200 Subject: Initial commit: local SDXL image generation on Intel Arc B580 Containerized SDXL-base generation targeting a 12GB Arc B580 under Slackware. The container carries the Intel Level Zero runtime the host distro does not package; the fp16-fix VAE removes the fp32 upcast that would otherwise OOM at decode. - imggen: host wrapper (GPU passthrough, /out bind-mount, model cache) - generate.py: in-container XPU pipeline, scope-bounded to SDXL base - Dockerfile: pinned to the known-good torch-XPU / diffusers stack - README.md, CLAUDE.md: rationale, limits, and version-pinning notes Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 CLAUDE.md (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3c19091 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,48 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +Local SDXL-base image generation on an Intel Arc B580 (12GB) under Slackware. Three files: +`imggen` (host bash wrapper) → `docker run` → `generate.py` (in-container, XPU). README.md carries +the full rationale and VRAM measurements; read it before changing behavior. + +## Build and run + +``` +docker build -t imggen:local . # image tag is hardcoded as imggen:local in the wrapper +cp imggen ~/bin/imggen && chmod +x ~/bin/imggen +imggen "a prompt" --steps 30 --seed 42 -o out.png -n "blurry" +``` + +No test suite, no lint config. Verification is running `imggen` end to end and checking the PNG. + +## Architecture constraints (the whole point of the project) + +- **12GB VRAM is the hard limit.** Stock SDXL fp16 OOMs at VAE decode because diffusers upcasts + the VAE to fp32. The fix is the fp16-fix VAE (`madebyollin/sdxl-vae-fp16-fix`, hardcoded in + `generate.py`). This one swap is why the pipeline fits. Do not remove it. Peak VRAM in the + working config is 9.07 GB. +- **Scope is deliberately bounded:** SDXL base, single 1024x1024 image, 25 steps, no refiner, + no Flux, no batching. Refiner/Flux/heavy work is explicitly out of scope and belongs on a + RunPod endpoint, not here. Don't add them "to be helpful." +- **XPU only.** `build_pipe()` fails loud (`sys.exit(2)`) if `torch.xpu` is unavailable rather + than falling back to CPU (which would be minutes per image). Keep that behavior. + +## Version pinning is load-bearing + +The Dockerfile pins EXACT versions (torch 2.12.1+xpu, diffusers 0.39.0, transformers 5.13.0, +etc.) captured from the known-good container. XPU-for-diffusion is young and fast-moving. Never +`pip install -U` or loosen a pin casually. torch comes from the Intel XPU wheel index +(`download.pytorch.org/whl/xpu`); everything else from PyPI. If you rebuild with newer versions, +keep the old Dockerfile in git to revert. + +## Container boundaries + +- `imggen` bind-mounts host `$IMGGEN_OUT` (default `~/imggen-out`) → `/out`, and + `$IMGGEN_CACHE` (default `~/.cache/imggen-models`) → `/models`. `HF_HOME=/models` so the + ~7.5GB weights download once. Output paths in `generate.py` are all under `/out`. +- All wrapper args pass straight through to `generate.py` argparse. Adding a CLI flag means + editing `generate.py` only; the wrapper needs no change. +- GPU passthrough is `--device /dev/dri`. -- cgit v1.2.3