Agile Diffusers Inference (ADI)

Agile Diffusers Inference (ADI) is a C++ library with CLI tool. Purpose to leverage the acceleration capabilities of ONNXRuntime and the high compatibility of the .onnx model format to provide a convenient solution for the engineering deployment of Stable Diffusion, with suitable package size & high performance.

Why choose ONNXRuntime as our Inference Engine?

• Open Source: ONNXRuntime is an open-source project, allowing users to freely use and modify it to suit different application scenarios.

• Scalability: It supports custom operators and optimizations, allowing for extensions and optimizations based on specific needs.

• High Performance: ONNXRuntime is highly optimized to provide fast inference speeds, suitable for real-time applications.

• Strong Compatibility: It supports model conversion from multiple deep learning frameworks (such as PyTorch, TensorFlow), making integration and deployment convenient.

• Cross-Platform Support: ONNXRuntime supports multiple hardware platforms, including CPU, GPU, TPU, etc., enabling efficient execution on various devices.

• Community and Enterprise Support: Developed and maintained by Microsoft, it has an active community and enterprise support, providing continuous updates and maintenance.

How to install (CLI)?

Method 1: Install the Command Line Tool Using a Package Manager

Note: published packages are currently v1.0.1; v1.1.0/v1.2.0 packages will be produced by the automated release chain (see release/release-v* branches).

## macOS (Homebrew):
brew tap windsander/adi-stable-diffusion
brew install adi

## Windows (git-Bash + Chocolatey):
curl -L -o adi.1.0.1.nupkg "https://raw.githubusercontent.com/Windsander/ADI-Stable-Diffusion/deploy/adi.1.0.1.nupkg"
choco install adi.1.0.1.nupkg -y

Method 2: Download from the Released Version

You can find the latest available version from the Release Assets. The file tree of the package will look like this:

--bin
    --adi
--lib
    --[Corresponding platform's ADI library, e.g., libadi.a]
    --[Corresponding platform's ORT library, e.g., libonnxruntime.dylib]
--include
    --adi.h
--CHANGELOG.md
--README.md
--LICENSE

After unzipping, you can simply install the bin and lib directories to your system, or just go into the unzipped bin directory, and start using adi.

Method 3: Build [adi-lib & adi-cli] Locally

• An automated script is provided to compile ADI on your device more easily.

Simply execute the script auto_build.sh:

# if you do not pass the BUILD_TYPE parameter, the script will use the default Debug build type.
# and, if you not enable certain ORTProvider by [options]], script will choose default ORTProvider by platform
bash ./auto_build.sh

# Example-MacOS:
bash ./auto_build.sh --platform macos --build-type debug
           
# Example-Windows:
bash ./auto_build.sh --platform windows --build-type debug
                    
# Example-Linux(Ubuntu):
bash ./auto_build.sh --platform linux --build-type debug
           
# Example-Android:
bash ./auto_build.sh --platform android \
           --build-type debug \
           --android-ndk /Volumes/AL-Data-W04/WorkingEnv/Android/sdk/ndk/26.1.10909125 \
           --android-ver 27
           
# Example(with Extra Options) as below, build release with CUDA=ON TensorRT=ON, and custom compiler configs
bash ./auto_build.sh [params] \
           --cmake /opt/homebrew/Cellar/cmake/3.29.5/bin/cmake \
           --ninja /usr/local/bin/ninja \
           --arch-abi x86_64 \
           --jobs 8 \
           --options "-DORT_ENABLE_CUDA=ON -DORT_ENABLE_TENSOR_RT=ON"

currently, this project provide below [Options]:

# 1. Option list
option(ORT_COMPILED_ONLINE           "adi: using online onnxruntime(ort), otherwise local build" ${SD_ORT_ONLINE_AVAIL})
option(ORT_COMPILED_HEAVY            "adi: using HEAVY compile, ${Red}only for debug, default OFF${ColourReset}" OFF)
option(ORT_BUILD_COMMAND_LINE        "adi: build command line tools" ${CMAKE_STANDALONE})
option(ORT_BUILD_COMBINE_BASE        "adi: build combine code together to build a single output lib" OFF)
option(ORT_BUILD_SHARED_ADI          "adi: build ADI project shared libs" OFF)
option(ORT_BUILD_SHARED_ORT          "adi: build ORT in shared libs" OFF)
option(ORT_ENABLE_TENSOR_RT          "adi: using TensorRT provider to accelerate inference" ${DEFAULT_TRT_STATE})
option(ORT_ENABLE_CUDA               "adi: using CUDA provider to accelerate inference" ${DEFAULT_CUDA_STATE})
option(ORT_ENABLE_COREML             "adi: using CoreML provider to accelerate inference" ${DEFAULT_COREML_STATE})
option(ORT_ENABLE_NNAPI              "adi: using NNAPI provider to accelerate inference" ${DEFAULT_NNAPI_STATE})
option(ADI_AUTO_INSTALL              "adi: auto-install ADI-CLI to current system when build finish, request admin permission" OFF)

enable if you have to (ONLY FOR YOU TRULY NEEDS, UNRECOMMENDED).

How to use?

Example: 1-step Euler_A img2img latent space visualized

• Below show What actually happened in [Example: 1-step img2img inference] in Latent Space (Skip All Models):

• You can use the command-line tools generated by CMake to execute the relevant functionalities of this project

doing 1-step img2img inference, like:

# Optional(if using local build & not install): cd to ./[your_adi_path]/bin/ ,like: 
cd ./cmake-build-debug/bin/

# and here is an example of using this tool:
# sd-turbo, img2img, positive, inference_steps=1, guide=1.0, euler_a(for 1-step purpose)
adi \
 -p "A cat in the water at sunset" \
 -m img2img \
 -i ../../sd/io-test/input-test.png \
 -o ../../sd/io-test/output.png \
 -w 512 -h 512 -c 3 \
 --seed 15.0 \
 --dims 1024 \
 --clip ../../sd/sd-base-model/onnx-sd-turbo/text_encoder/model.onnx \
 --unet ../../sd/sd-base-model/onnx-sd-turbo/unet/model.onnx \
 --vae-encoder ../../sd/sd-base-model/onnx-sd-turbo/vae_encoder/model.onnx \
 --vae-decoder ../../sd/sd-base-model/onnx-sd-turbo/vae_decoder/model.onnx \
 --dict ../../sd/sd-base-model/onnx-sd-turbo/tokenizer/vocab.json \
 --merges ../../sd/sd-base-model/onnx-sd-turbo/tokenizer/merges.txt \
 --beta-start 0.00085 \
 --beta-end 0.012 \
 --beta scaled_linear \
 --alpha cos \
 --scheduler euler_a \
 --predictor epsilon \
 --tokenizer bpe \
 --train-steps 1000 \
 --token-idx-num 49408 \
 --token-length 77 \
 --token-border 1.0 \
 --gain 1.1 \
 --decoding 0.18215 \
 --guidance 1.0 \
 --steps 1 \
 -v

And now, you can have a try~ (0w0 )

More verified examples (v1.2.0)

# SD v2.1 @ 768px, v_prediction, 20 steps:
adi -p "A cat in the water at sunset" -m txt2img -o output.png \
 -w 768 -h 768 -c 3 --seed 15.0 --dims 1024 \
 --clip  <onnx-sd-v21-768>/text_encoder/model.onnx \
 --unet  <onnx-sd-v21-768>/unet/model.onnx \
 --vae-encoder <onnx-sd-v21-768>/vae_encoder/model.onnx \
 --vae-decoder <onnx-sd-v21-768>/vae_decoder/model.onnx \
 --dict  <onnx-sd-v21-768>/tokenizer/vocab.json \
 --merges <onnx-sd-v21-768>/tokenizer/merges.txt \
 --beta scaled_linear --scheduler euler_a --predictor v_prediction \
 --guidance 7.5 --steps 20

# SDXL-turbo: dual text encoders via --clip2 (VAE scaling 0.13025):
adi -p "A cat in the water at sunset" -m txt2img -o output.png \
 -w 512 -h 512 -c 3 --seed 15.0 --dims 768 \
 --clip  <onnx-sdxl-turbo>/text_encoder/model.onnx \
 --clip2 <onnx-sdxl-turbo>/text_encoder_2/model.onnx \
 --unet  <onnx-sdxl-turbo>/unet/model.onnx \
 --vae-encoder <onnx-sdxl-turbo>/vae_encoder/model.onnx \
 --vae-decoder <onnx-sdxl-turbo>/vae_decoder/model.onnx \
 --dict  <onnx-sdxl-turbo>/tokenizer/vocab.json \
 --merges <onnx-sdxl-turbo>/tokenizer/merges.txt \
 --beta scaled_linear --scheduler euler_a --predictor epsilon \
 --decoding 0.13025 --guidance 1.0 --steps 4

# Karras sigma schedule (composable with any scheduler):
adi ... --scheduler dpm_m --sigma karras ...

# All 14 schedulers:
# euler / euler_a / lms / lcm / heun / ddpm / ddim / unipc
# dpm_m / dpm_sde / dpm_s / pndm / ipndm / deis_m

Model-specific parameter notes:

Model	--dims	--predictor	--decoding	typical
sd v1.x / turbo	768 (v1.x) / 1024 (turbo)	epsilon	0.18215	turbo: guidance 1.0, 1~4 steps
sd v2.x	1024	v_prediction (v2.1-768)	0.18215	768px for v2.1-768
SDXL / SDXL-turbo	768	epsilon	0.13025	requires --clip2

Extra intelligence：

• Project structure & design notes, see at: ARCHITECTURE.md

• Manually Prepare Inference Engine, see at: Engine's README.md

• Manually Prepare ONNX-Format Converter & SD-Models, see at: SD_ORT's README.md

Development Progress Checklist (latest):

Audited against the v1.2.0 codebase (2026-08); roadmap targets aligned with PLAN-supplement.md.

Basic Pipeline Functionalities (Major)

• [SD_v1] Stable-Diffusion (v1.0 ~ v1.5, turbo) (after 2024/06/04 tested)

  • v1.0 (HuggingFace): Initial version ✅
  • v1.1 (HuggingFace): Improved image quality and generation speed ✅
  • v1.2 (HuggingFace): Further optimized generation effects ✅
  • v1.3 (HuggingFace): Added more training data ✅
  • v1.4 (HuggingFace): Enhanced image generation diversity ✅
  • v1.5 (HuggingFace): Final optimized version ✅
  • turbo (HuggingFace): Community-driven optimized version, faster and efficiency ✅

• [SD_v2] Stable-Diffusion (v2.0, v2.1) (v2.1 768px v-prediction after 2026/07/31 ✅tested)

  • v2.0 (HuggingFace): Significant improvements in image quality and generation efficiency (untested; identical architecture/pipeline to the verified v2.1)
  • v2.1 (HuggingFace): Further optimized model stability and generation effects ✅ (official repo gated since 2025 — acquired via sd2-community mirror + optimum ONNX export chain, see sd/auto_prepare_sd_models.sh)

• [SD_v3.x] Stable-Diffusion 3 / 3.5 (MMDiT era) (v2.0.0 window — PLAN-supplement 2.3)

  • v3.0 (HuggingFace): First MMDiT release (2024/06) (superseded by v3.5; no longer the primary target)
  • v3.5 (Large / Large-Turbo / Medium) (HuggingFace): Stability flagship since 2024/10 and the open-weights mainstream of 2026. Requires: MMDiT transformer unit (structural source/units/ extension, not a config-level one), triple text encoders (CLIP-L + OpenCLIP-G + T5-XXL → SentencePiece becomes mandatory), rectified-flow scheduling (new scheduler family below)

• [SDXL] Stable-Diffusion-XL (SDXL-turbo after 2026/07/31 ✅tested)

  • SDXL (HuggingFace): Experimental version for larger-scale models and higher-resolution image (untested; same pipeline as SDXL-turbo — dual-encoder --clip2, pooled embedding, time-ids micro-conditioning all landed in v1.2.0)
  • SDXL-turbo (HuggingFace): Community-driven optimized version, faster and efficiency ✅

• [FLUX-class] Flow-Matching Models [post-v2.0.0 candidate, under evaluation]

  • FLUX.1 [dev] / [schnell] (HuggingFace): The community-favorite open-weights family of 2026. Shares the MMDiT + rectified-flow + T5-XXL stack with SD3.5, so most prerequisites land together with the SD3.5 work; extras: single-file checkpoint conversion chain, guidance-distilled variants, non-commercial license review

• [SVD] Stable-Video-Diffusion

  • SVD (HuggingFace): Version specifically for video generation and editing (CLI img2vid mode name reserved; still the open-weights entry for short img2vid in 2026 — long-form video has moved to closed DiT stacks)

Scheduler Abilities

• Strategy

  • Discrete/Method Default (discrete) (after 2024/05/22)
  • Karras (karras, ρ=7) (after 2026/07/30 ✅tested — sigma sequence value-identical to diffusers use_karras_sigmas)

• Sampling Methods (14/14 complete since v1.1.0)

  • Euler (euler) (after 2024/06/04 ✅tested)
  • Euler Ancestral (euler_a) (after 2024/05/24 ✅tested)
  • Laplacian Pyramid Sampling (lms) (after 2024/07/09 ✅tested)
  • Latent Consistency Models (lcm) (after 2024/07/04 ✅tested)
  • Heun's Predictor-Corrector (heun) (after 2024/07/08 ✅tested)
  • Unified Predictor-Corrector (unipc) (completed after 2026/07/29 ✅tested — was an empty-stub segfault before v1.1.0)
  • Pseudo Numerical Diffusion Model Scheduler (pndm) (after 2026/07/30 ✅tested)
  • Improved Pseudo Numerical Diffusion Model Scheduler (ipndm) (after 2026/07/30 ✅tested — paper-form AB4 + DDIM update; diffusers' ADM-grid variant verified unsuitable for SD)
  • Diffusion Exponential Integrator Sampler Multistep (deis_m) (after 2026/07/30 ✅tested)
  • Denoising Diffusion Implicit Models (ddim) (after 2024/07/12 ✅tested)
  • Denoising Diffusion Probabilistic Models (ddpm) (after 2024/07/09 ✅tested)
  • Diffusion Probabilistic Models Solver in Stochastic Differential Equations (dpm_sde) (after 2026/07/30 ✅tested)
  • Diffusion Probabilistic Models Solver in Multistep (dpm_m) (after 2026/07/30 ✅tested)
  • Diffusion Probabilistic Models Solver in Singlestep (dpm_s) (after 2026/07/30 ✅tested)

• Flow-Matching / Rectified-Flow Family (v2.0.0 requirement — a new scheduler paradigm, not another scheduler_discrete_* extension)

  • Flow Euler discrete (default sampler of SD3.5 / FLUX-class models; ODE-style few-step integration)
  • Flow Heun / higher-order flow solvers [if necessary]

Tokenizer Type

• Byte-Pair Encoding (bpe) (after 2024/07/03 ✅tested — covers CLIP-L / OpenCLIP-G/H, i.e. every model supported so far)
• Word Piece Encoding (word_piece) (after 2024/05/27 ✅tested) (note: available via internal registry & CLI, but not yet exposed in the public AvailableTokenizerType C enum)
• Sentence Piece Encoding (sp) promoted: [if necessary] → [required] — the T5-XXL text encoder is mandatory for SD3.5 / FLUX-class models (v2.0.0 window)

Engineering & Distribution (audited 2026-08)

• Smoke-matrix runner scripted (sd/io-test/run_smoke_matrix.sh, 19 quick / 24 full cases; hard gates: ORT-exception count, output size, flat-pixel check) (after 2026/07/31 — local quick 19/19 green)
• Release chain hardened (CHANGELOG-driven auto-publish; retired node12 actions replaced; artifact actions v2→v4; deploy_linux formally disabled per decision 0.4) (after 2026/07/31)
• Golden-image regression in CI (test-native is compile-only today; the smoke matrix is not yet wired into workflows)
• ONNXRuntime engine upgrade (prebuilt 1.17.3/1.18.0 packages + 2024-era submodule → current stable; regression over CoreML / NNAPI / TensorRT / CUDA — scheduled with the v2.0.0 window)
• Linux .deb/.rpm packaging (disabled since 2024/08; repair bundled with the ORT upgrade, decision 0.4)
• ControlNet / safety-checker integration (fields reserved in IOrtSDConfig as onnx_control_net_path / onnx_safty_path, currently not available)