| --- |
| license: openrail++ |
| tags: |
| - mlx |
| - apple-silicon |
| - diffusion |
| - stable-diffusion-xl |
| - sdxl |
| - anime |
| - text-to-image |
| base_model: OnomaAIResearch/Illustrious-XL-v1.0 |
| library_name: mlx-gen |
| pipeline_tag: text-to-image |
| --- |
| |
| # Illustrious-XL v1.0 — MLX pre-quantized tiers |
|
|
| Pre-quantized, packed-load tiers of [OnomaAIResearch/Illustrious-XL-v1.0](https://huggingface.co/OnomaAIResearch/Illustrious-XL-v1.0) |
| for on-device Apple-Silicon inference with [SceneWorks / `mlx-gen`](https://github.com/SceneWorks/mlx-gen) |
| (the `sdxl` generator). Each tier is a **self-contained diffusers turnkey snapshot** (U-Net + both |
| CLIP text encoders + VAE + tokenizers + scheduler + `model_index.json`) that loads directly — no |
| in-app quantization pass, no dense transient. |
|
|
| Illustrious-XL is a Danbooru-tag anime SDXL finetune (OnomaAI). It is architecturally vanilla SDXL: |
| dual CLIP-L + OpenCLIP-bigG text encoders, real classifier-free guidance + negative prompt, eps |
| prediction, VAE scaling factor 0.13025, and full sdxl-family LoRA support. ~30 steps at guidance 7.0, |
| native 1024×1024, and it handles wide frames up to 1536×1536. |
|
|
| ## Provenance |
|
|
| Upstream ships a **single-file LDM checkpoint** (`Illustrious-XL-v1.0.safetensors`), which the MLX |
| `sdxl` loader cannot read. These tiers were produced offline from that checkpoint with |
| [`scripts/build_sdxl_turnkey.py`](https://github.com/SceneWorks/SceneWorks/blob/main/scripts/build_sdxl_turnkey.py): |
| `StableDiffusionXLPipeline.from_single_file` → diffusers component tree → per-tier quantization. The |
| component configs are the canonical SDXL descriptors (adopted verbatim from a known-good SDXL |
| turnkey after an architecture-key match), not `from_single_file`'s output. |
|
|
| ## Tiers |
|
|
| | dir | precision | what's quantized | |
| |----------|-----------|------------------| |
| | `q4/` (default) | group-wise affine Q4, group size 64 | U-Net Linears + both CLIP encoders | |
| | `q8/` | group-wise affine Q8, group size 64 | U-Net Linears + both CLIP encoders | |
| | `bf16/` | dense (f16 source mirror) | nothing | |
|
|
| The **VAE stays dense in every tier** — the SDXL VAE is int8/fp16-unstable, so it is never |
| quantized. Convolutions, GroupNorms, and the CLIP token/position embeddings also stay dense (gather |
| lookups and convs, not matmuls); only the true Linear projections are packed. Quantization is |
| byte-identical to `mlx-gen`'s load-time `nn.quantize` (bf16 cast, group 64). |
|
|
| ## License |
|
|
| SDXL license — CreativeML Open RAIL++-M, per the upstream model card. Commercial use OK, ungated; |
| behavioral-use restrictions apply. |
|
|
