[hephaex]

Summary

Adds the shared image generation runtime: the generate-image CLI, /v1/images/generations and /v1/images/edits routes behind --image-model, the family probe, a PNG writer, the FLUX.2 VAE, the flow-match schedulers, Z-Image DiT blocks, and a Qwen3 hidden-state conditioner. The family registry ships empty; model-family issues register their constructors on top of this.

Related issues

Closes #2341

Part of #2348. Unblocks #2424, #2425, #2426, #2427 and #2428.

Type of change

• feat — new user-visible feature
• docs — documentation (docs/image-generation.md, README, MLXCEL_IMAGE_MODEL)

Test plan

Everything below ran on the CPU MLX backend (MLXCEL_BUILD_METAL=OFF, --features accelerate), because the Metal toolchain is not installed on the author's machine.

• cargo fmt --all -- --check: clean
• cargo clippy --workspace --all-targets -D warnings (CPU backend): exit 0
• imagegen unit tests: 134 passed, 1 ignored (the real-checkpoint conditioner check)
• Workspace tests: 61 failures, all Metal/GPU-dependent (mlxcel-core cache/paged_v2/mla/turbo/ffi/hardware, plus 11 root-crate tests such as florence2, webui catalog, mllama). The same 11 root-crate tests fail on an unmodified upstream/main worktree; mlxcel-core is untouched.
• Upstream parity (Blaizzy/mlx-vlm @ 9527f2da, mlx 0.32.4 fixtures; tests/fixtures/generate_imagegen_fixtures.py reproduces the committed fixtures exactly):
  • schedulers at 1/4/12/30 steps: match
  • real ERNIE-Image-Turbo VAE vs upstream f32: decode 3.4e-6, packed decode 1.2e-6, encode 3.0e-6 (relative RMS); default f16 decode 1.2e-3 (asserted < 5e-3)
  • DiT blocks and Qwen3 conditioner on tiny models: match
• Real checkpoint mlx-community/Qwen3-0.6B-4bit: conditioner last hidden state reproduces the generation-path logits exactly (rel-RMS 0)
• Numbers traced: examples/logit_trace, Qwen3-0.6B-4bit, 96 positions, 12 chunks of 8 tokens. Baseline and branch traces are byte-identical, 0 disagreements, perplexity 80.1327 for both. The only change to Qwen3Model is one added method, forward_all_hidden.
• Manual: generate-image on an empty dir and on an unported family prints clear errors; generate/serve/mlxcel-server on an image checkpoint print "use mlxcel generate-image"; a real SmolLM2 server without --image-model returns 501 naming the flag on both routes and the /images/* aliases.
• cargo test --workspace --profile test-fast --features metal,accelerate: not run (no Metal toolchain)
• make verify / Metal numerics: not run
• cargo deny check: not run
• Real image-family checkpoint end to end: not possible yet, since no family is registered (follow-up issues)

Notes for reviewers

• Labels from the linked issue: please apply as appropriate (I do not have triage permission).
• Upstream defect found while porting: _match_conv_layout in mlx-vlm leaves the encoder's RGB conv_in (128,3,3,3) in PyTorch layout; encode-decode reconstruction rel-RMS is 0.96 there versus 0.096 when transposed. This port decides the conv layout once per checkpoint (detect_conv_layout) and is not affected. Not reported upstream.
• Deviations from upstream: attention mask fill is -30000 instead of -inf so a fully blocked row averages instead of producing NaN; scheduler sigmas are computed on the CPU in f32.
• image_model_path lives only in ServerStartupConfig, not ServerConfig, to avoid the runtime-settings schema and webui label cascade.
• Known gaps: mlxcel run <image dir> fails earlier with "No tokenizer found"; mlxcel arch --json has no ImageGenerate row until a family registers, so only the serialization is pinned by tests.

Checklist

• PR title uses a Conventional Commits prefix
• One logical change per PR
• Updated docs/ (new docs/image-generation.md, README, env-var table)
• Updated // Used by: ... comments on any shared function I modified (only an added method on Qwen3Model)
• No secrets, credentials, or .env files committed

[inureyes]

Reviewed PR #2497 against issue #2341 and its accepted scope amendments, including the Qwen3 conditioner, static scheduler, model probing, CLI, HTTP aliases and authentication.

Fixed four findings in 0de942c: expired queued requests could still start GPU work after the caller timed out; output dimensions and explicit diffusion steps had no shared resource ceiling; the predictable directory probe could truncate an existing file or follow a symlink; and the four numerical fixtures were undeclared in the binary-asset gate. Requests now cap each output at 16,777,216 pixels and explicit steps at 1–1,000, queued expiration is checked before execution, and probes use atomic exclusive creation. Fixture declarations have individual size limits and a bounded aggregate budget. Added focused regressions and documented the behavior. Commit 2fea6a6 documents the new Qwen3 checkpoint override, resolving the environment-documentation and Python-tooling CI failures.

Validation on Linux/aarch64 NVIDIA GB10: CUDA library selection imagegen:: server::image_worker:: server::routes::images:: server::api_prefix_tests:: server::auth_route_tests:: passed 165 tests (two checkpoint-dependent tests ignored); cargo test --profile test-fast --features cuda --bin mlxcel -- generate_image --test-threads=1 passed 14. The separately selected ignored Qwen3 test passed against the local Qwen3-0.6B-4bit checkpoint, with logits relative RMS 0 and matching greedy tokens. cargo clippy -j4 -p mlxcel --lib --tests -- -D warnings, formatting, diff checks and all six binary-gate self-tests passed. The current-main merge tree passed the environment-variable guard and all 15 associated tests.

Authentication and route-prefix regressions passed. Already-running generation remains non-interruptible through the current model trait; expired queued work is now discarded. The real ERNIE VAE checkpoint was unavailable locally. As agreed in #2341, this infrastructure PR has no registered production image family; model-family wiring remains follow-up work. CI completion is still required before merge.

Refs #2341