1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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`.
|
