- π― What is This? - Overview and introduction
- π Supported Models - List of supported SD models
- ποΈ Image Generation Methods - Description of text-to-image, image-to-image, inpainting, removal, outpainting
- π Hardware Prerequisites - AMD hardware requirements
- π Quick Start - Installation process: get up and running
- π§© Pipelines and Pipeline Groups Configuration - Configure YAML and JSON files
βΆοΈ Running Pipelines - How to execute pipelines and pipeline groups- π¨ Text-To-Image - Text-to-image parameters and dynamic resolution in detail
- οΏ½ Image-To-Image Modes - Strength-based and ControlNet image-to-image in detail
- οΏ½π€ Output - Generated images, results, and logs
- π¬ Community & Support - Get help and connect
AMD SD Sandbox is a framework for running Stable Diffusion (SD) models accelerated by AMD Ryzen AI hardware. It provides an easy-to-use interface for evaluating, comparing, and deploying multiple SD pipelines. When developing AI-powered applications with SD, developers face several challenges:
| π« Problem | β Solution |
|---|---|
| Model Selection Complexity - Dozens of SD models exist, each with different capabilities and tradeoffs, requiring separate tools and interfaces | Unified Pipeline Interface - Run any supported SD model with consistent commands and a single orchestration framework |
| Hardware Optimization Guesswork - Need to compare NPU vs GPU vs CPU performance to justify hardware investments and optimize deployments | Built-in Performance Benchmarking - Automated profiling with CPU baseline comparison to measure real acceleration gains with the NPU |
| Tedious Manual Testing - Testing multiple prompts across multiple models requires repetitive manual work and scattered results | Automated Batch Processing - Test hundreds of prompts across multiple models automatically with organized result management |
| Code Modification Barriers - Official examples require source code changes for simple customizations like prompts or resolution | No-Code Customization - Configure everything via YAML files and CLI arguments without adjusting source code |
The SD sandbox uses scripts to orchestrate GenAI-SD code distributed with Ryzen AI software. To use GenAI-SD without the orchestrator script please refer to the following: π GenAI-SD Documentation
Here is a list of currently supported SD models. Note that these models have had nodes replaced with custom ops specifically designed for AMD NPUs. Models that aren't stored locally will be downloaded from Hugging Face on first use.
These are the same NPU-optimized pipelines featured in the Ryzen AI Stable Diffusion Demo. That demo is the official AMD preview, shipped with Ryzen AI software, of Stable Diffusion image generation running on Ryzen AI hardware. It shows how to drive each model directly from the GenAI-SD code β covering Text-to-Image, Image-to-Image, and ControlNet (Canny, Depth, Tile, Pose) plus SD3 inpainting β by calling the unified run.py entry point with a --model_id. This sandbox wraps those same pipelines in a configurable, batch-friendly orchestrator so you can run and benchmark many of them without editing source code.
The table below lists every model with its Hugging Face model ID (RAI 1.9).
| Model | Hugging Face Model ID (RAI 1.9) | Default Resolution | Text-To-Image | Image-To-Image |
|---|---|---|---|---|
| SD 1.5 | amd/stable-diffusion-1.5-amdnpu | 512x512 | β | |
| SD 1.5 ControlNet (Canny) | amd/sd1.5-controlnet-canny-amdnpu | 512x512 | βοΈ | |
| SD Turbo | amd/sd-turbo-amdnpu | 512x512 | β | |
| SD XL Turbo | amd/sdxl-turbo-amdnpu | 512x512, 5x DynRes | β | |
| SD XL Base | amd/sdxl-base-amdnpu | 1024x1024, 20x DynRes | β | |
| SSD-1B | amd/SSD-1B-amdnpu | 1024x1024, 20x DynRes | β | |
| Segmind Vega | amd/segmind-vega-amdnpu | 1024x1024 | β | βοΈ |
| Playground 2.5 | amd/playground-v2.5-1024px-aesthetic-amdnpu | 1024x1024, 20x DynRes | β | |
| DreamShaper XL | amd/dreamshaper-xl-lightning-amdnpu | 1024x1024, 20x DynRes | β | |
| SD 3.0 Medium β Text-to-Image, ControlNet (Canny, Depth, Tile, Pose), Inpainting | amd/stable-diffusion-3-medium-amdnpu | 512x512, 20x DynRes (Inpainting: 1024x1024) | β | βοΈ |
| SD 3.5 Medium β Text-to-Image | amd/stable-diffusion-3.5-medium-amdnpu | 512x512, 20x DynRes | β | |
| FLUX.1 Schnell | amd/FLUX.1-schnell-amdnpu | 512x512, 20x DynRes | β | |
| FLUX.2 Klein | amd/FLUX.2-klein-4B-amdnpu | 1024x1024 | β |
DynRes indicates the number of dynamic-resolution presets a model supports (e.g. 5x, 20x) in addition to its default resolution. The exact widthΓheight pairs for each preset are defined in the config/dynamic_shape_*.json files β the 20x grid spans 512x288 β 1024x1024 across 1:1, 3:4, 4:3, 9:16, and 16:9 aspect ratios.
Note: SD 3.0 Medium and SD 3.5 Medium should be run at 1024x1024, even though their default in the code is 512x512. The shipped
sd3_baseandsd35_basepipelines setwidth: 1024andheight: 1024inargs.
Which config file? Pipelines are defined in config/pipeline_configs_strx.yaml, which is used when --config is not given; pass --config to choose another file. See Pipelines and Pipeline Groups Configuration.
Here are some explanations of each of the SD methods. Note that pre- and post-processing padding and depadding are applied to the images where the resolutions do not match the model's inference resolution.
π¨ Text-To-Image (T2I) β Generate images from scratch using only text descriptions. Simply provide a prompt like "a mountain landscape at sunset" and the model creates a completely new image based on your description. Example use cases: concept art, marketing visuals, creative exploration, rapid prototyping
See Text-To-Image for parameters and dynamic resolution.
β’ β’ β’
π Image-To-Image (I2I) β Transform an existing image based on a text prompt while preserving certain structural or compositional elements. You provide both a reference image and a prompt, and the model generates a new image that follows the guidance of the input image while incorporating your text description. Example use cases: style transfer, image variations, artistic reinterpretation, photo enhancement
Supported image-to-image modes:
- Strength-based image-to-image (Segmind Vega): repaints the input image itself;
strengthsets how much changes. See Strength-Based Image-To-Image. - ControlNet image-to-image (SD 3.0 Medium: Canny, Depth, Pose, Tile, InPainting; SD 1.5: Canny): keeps only the layout from a control image. See ControlNet Image-To-Image.
Before getting started, make sure you meet the minimum hardware and OS requirements.
Hardware requirements:
| Series | Codename | Abbreviation | Graphics Model | Launch Year | Windows 11 | Linux |
|---|---|---|---|---|---|---|
| Ryzen AI PRO 400 Series | Gorgon Point | GPT | Radeon 800M Series | 2026 | βοΈ | |
| Ryzen AI 400 Series | Gorgon Point | GPT | Radeon 800M Series | 2026 | βοΈ | |
| Ryzen AI Max PRO 300 Series | Strix Halo | STX | Radeon 8000S Series | 2025 | βοΈ | |
| Ryzen AI PRO 300 Series | Strix Point / Krackan Point | STX/KRK | Radeon 800M Series | 2025 | βοΈ | |
| Ryzen AI Max 300 Series | Strix Halo | STX | Radeon 8000S Series | 2025 | βοΈ | |
| Ryzen AI 300 Series | Strix Point / Krackan Point | STX/KRK | Radeon 800M Series | 2025 | βοΈ |
Follow the instructions here to download necessary NPU drivers and Ryzen AI SW: Ryzen AI SW Installation Instructions. Please allow for around 5 minutes to install all of the necessary components of Ryzen AI SW.
The binaries found in GenAI-SD\lib within the RAI installation directory (C:\Program Files\RyzenAI\1.9.0\GenAI-SD\lib) are the only code needed to run the pipelines. Copy
the directory to the sandbox root.
Next, configure paths by editing config/pipeline_configs_strx.yaml. Relative paths are resolved from the sandbox root. The bare minimum that you need to change in order to run a pipeline is:
test_path: the directory whosegenerated_imagessubfolder receives output images (and is emptied by--clean-images). Pipelines always runtest/run.pyfrom the sandbox root, regardless oftest_path.
Optional paths that can be configured are:
control_images_path: the directory holding control and input images (the sandbox'stest/assetsby default). This is used for ControlNet and image-to-image pipelines. You can also specify a custom path here if desired.config_files_path: the directory holding the dynamic shape files (the sandbox'sconfigby default). This is used to resolve relativedynamic_shape_file_pathvalues. You can also specify a custom path here if desired.
paths:
test_path: "./test"
control_images_path: "./test/assets"
config_files_path: "./config"More details on configurations can be found in the Pipelines and Pipeline Groups Configuration section.
Supported models are downloaded from the Hugging Face Hub on first use, so you need to authenticate your machine with a Hugging Face access token.
- Generate and copy a token from https://huggingface.co/settings/tokens. A token with Read access is sufficient to download the models. Some gated repos additionally require you to accept their license on the model page before the first download will succeed.
- Log in from your terminal using the Hugging Face CLI (
hf), which ships with thehuggingface_hubpackage:
hf auth loginPaste your token when prompted (or run it non-interactively with hf auth login --token <YOUR_TOKEN>). On success you should see, among other things:
Login successful.
Note:
hf auth loginis the current command and replaces the deprecatedhuggingface-cli login. For installation options (including running the CLI withuvviauvx hf, with no install), see the Hugging Face CLI guide and its Using uv section.
Activate the Python virtual environment created during the Ryzen AI SW installation:
:: Command Prompt
"C:\Program Files\RyzenAI\ryzen-ai-1.9.0\Scripts\activate"Please use the activate command with the proper extension for your environment (e.g., .bat for Command Prompt, .ps1 for PowerShell, etc.).
Change into the sandbox directory, then verify that the main run script shows the possible pipelines and pipeline groups. All python scripts/... commands in this README are run from this directory.
cd sd-sandbox
# Uses config/pipeline_configs_strx.yaml by default
python scripts/run_pipelines.py --listYou should see a list of all available pipelines and groups of pipelines, similar to this:
[AUTO] Automatic provider selection (NPU > DML > CPU)
==================================================
Available Pipelines
==================================================
sd_15 - SD 1.5 Pipeline
sd_turbo - SD Turbo Pipeline
sdxl_base - SDXL Base Pipeline
sdxl_turbo - SDXL Turbo Pipeline
...
==================================================
Available Pipeline Groups
==================================================
all - sd_15, sd_15_controlnet, sd_turbo, sdxl_turbo, sdxl_base, ...
...
You should now be able to run a pipeline with:
python scripts/run_pipelines.py --pipelines sd_15And get an output similar to:
[AUTO] Automatic provider selection (NPU > DML > CPU)
============================================================
Running 1 pipelines in QUICK TEST mode
============================================================
--- Pipeline 1/1: SD 1.5 Pipeline ---
---Loading ONNX Unet for DD
2025-11-24 10:11:14,521 [INFO] Load unet/dd ...
...
2025-11-24 10:11:44,580 [INFO] Total NPU memory usage: 1521.66MB (1.49GB)
[OK] SUCCESS in 36.5s
[Dir] Images saved to: generated_images/
============================================================
SUMMARY - QUICK TEST MODE
============================================================
Total runs: 1
Successful: 1/1 (100.0%)
Total duration: 0:00:36.465767
Results saved to: <repo>\results\pipeline_results_quick_20251124_101145.txt
Now that everything is installed, you are ready to configure and run SD pipelines. Pipelines are defined in a YAML configuration file, config/pipeline_configs_strx.yaml, and can be run via the main scripts/run_pipelines.py script.
A pipeline is a complete SD workflow configuration that includes a specific model (e.g., SD 1.5, SDXL, SD 3.0), execution script, and parameters (resolution, inference steps, guidance scale). Each pipeline represents a single configured image generation setup, from text/image input to final image output.
Pipelines can be arranged into groups for common workflows (e.g., all SDXL models, all ControlNet models, etc.) to simplify running multiple pipelines at once. To create a pipeline group, simply list the desired pipelines under a group name in your YAML configuration file.
An overview of the directory structure that contains pipeline files and configurations is given below. The config directory contains two file types: YAML and JSON.
YAML files define pipeline configurations, parameters, and execution settings. Here are the important YAML files:
- config/pipeline_configs_strx.yaml - Default configuration, used when
--configis not given pipeline_custom_config.yaml- If not using the default, custom YAML files can be used with the--configargument as below:
python scripts/run_pipelines.py --pipelines sd_15 --config pipeline_custom_config.yamlThe configuration file has 3 main sections:
- Global Pipeline Defaults
- Pipeline Definitions
- Pipeline Groups
1. Global Pipeline Defaults
Global defaults are defined at the top of the YAML file and are useful for setting parameters that apply to all pipelines, such as the output image resolution, or an external prompt file. The global defaults can always be overridden on a per-pipeline basis, by making a change to a variable in the pipeline definition.
One example of setting a global default might be setting the num_inference_steps to 20 with default_args: ["--num_inference_steps", "20"] under defaults. Every pipeline will use 20 inference steps unless overridden in the pipeline's args. Only width, height, prompt, prompt_file, image_only, streaming_output, execution, and default_args are read from defaults; other runner parameters such as guidance_scale must go in default_args.
Under paths, test_path sets where generated images are saved (<test_path>/generated_images); pipelines always run the sandbox's test/run.py from the sandbox root. models_path is optional and defaults to models. A global prompt_file under defaults is optional; without it, each pipeline's prompt (or the global prompt) is used.
2. Pipeline Definitions
Pipelines are defined in the YAML configuration file under the pipelines section. Each pipeline has its own set of parameters that can override the global defaults. A pipeline definition uses the following keys:
- A unique pipeline identifier (e.g.,
sd_15,sdxl_turbo). (required) nameβ a human-readable display name (e.g.,"SD 1.5 Pipeline"). (required)model_idsβ a list of one or more Hugging Face model IDs or local model folder names (e.g.,["amd/stable-diffusion-1.5-amdnpu"]). (required)argsβ a dictionary of model/runner parameters such as resolution, inference steps, and guidance scale.
** Unified entry point.** All pipelines now run through a single unified script,
run.py. The previous per-model scripts (run_sd.py,run_sd_xl.py,run_sd3.py) have been consolidated, so you no longer specify ascriptfor each pipeline βrun.pyis selected automatically. Ascriptkey is still accepted for backward compatibility but is ignored.
A minimal pipeline definition looks like this:
sd_15:
name: "SD 1.5 Pipeline"
model_ids: ["amd/stable-diffusion-1.5-amdnpu"]
args:
num_inference_steps: 20If nothing else is specified, default values are used. Almost all hyperparameters can be overridden on a per-pipeline basis.
To see all available runner parameters, run --help on the unified entry point in the test directory:
python test/run.py --help** The args dictionary (recommended)**
Pipeline parameters are now set using an args dictionary of key: value pairs. This replaces the older flat extra_args list. Each entry is converted to a --key value command-line flag automatically:
YAML args value type |
Example | Resulting CLI flag |
|---|---|---|
| string / number | num_inference_steps: 20 |
--num_inference_steps 20 |
boolean true |
dynamic_shape: true |
--dynamic_shape (bare flag) |
boolean false |
dynamic_shape: false |
(omitted) |
| list | image_pads: [0, 64, 0, 64] |
--image_pads 0 64 0 64 |
For example, a fully configured SD3 pipeline:
sd3_base:
name: "SD3 Pipeline"
model_ids: ["amd/stable-diffusion-3-medium-amdnpu"]
args:
num_inference_steps: 30
width: 1024
height: 1024
controlnet: "None"
guidance_scale: 4.5
dynamic_shape: trueNote: The legacy
extra_argslist (e.g.extra_args: ["--num_inference_steps", "20"]) is still supported for backward compatibility. If bothargsandextra_argsare present, theargsentries are applied first.
Pipeline configurations are validated against the known set of runner arguments before each run, so unknown keys and out-of-range values are caught early with a clear warning rather than failing mid-run.
The best way to become familiar with the available parameters is to examine the configuration file.
Dynamic resolution: dynamic_shape and dynamic_shape_file_path let one model generate several resolutions without recompilation. See Dynamic Resolution.
3. Pipeline Groups
For convenience, you can organize pipelines into groups for common workflows. A pipeline group is created by creating a unique group name and listing the desired pipelines under that group in the YAML file.
The shipped configuration defines two groups, all (every pipeline) and flux:
flux:
- flux1_schnell
- flux2_kleinTo run this pipeline group, you can run with the --pipeline_groups command as follows:
python scripts/run_pipelines.py --pipeline_groups fluxYou can also create your own pipeline groups by modifying the YAML file under pipeline_groups to specify which pipelines you would like to run:
pipeline_groups:
my_custom_pipeline_group: #group identifier
- sd_turbo
- sdxl_turboEach JSON file contains an array of text prompts passed sequentially to pipelines for batch testing. The example JSON files can be found here:
- config/artistic_prompts.json, config/anime_prompts.json, config/alt_prompts.json - Themed prompt collections
custom_prompts.json- Your own custom prompt file You can pass your own list of prompts with the--prompt_fileargument. For example:
python scripts/run_pipelines.py --pipelines sd_15 --prompt_file custom_prompts.jsonPipelines are run by invoking the scripts/run_pipelines.py with the desired pipeline or pipeline group specified. For example, we can run the sd_15 pipeline with:
python scripts/run_pipelines.py --pipelines sd_15Or we can run the all pipelines group with:
python scripts/run_pipelines.py --pipeline_groups allA full list of pipeline parameters and their descriptions can be found by running --help on the main script:
python scripts/run_pipelines.py --helpThe framework has three execution modes. They differ only in how many times each prompt is generated and how much timing information is reported. In every mode, one image is saved per prompt and resolution.
| Mode | Generations per prompt | Timing reported | Image filename tag | Results file |
|---|---|---|---|---|
| Image-Only | 1 | Model load summary and a single pipeline execution time (includes first-run overhead) | batch |
pipeline_results_image_only_*.txt |
| Quick Test | 2 (1 warmup + 1 profiled) | Model load summary, warmup (1st gen) time, average pipeline time, per-component times, memory | profiling |
pipeline_results_quick_*.txt |
| Benchmark | 11 (1 warmup + 10 profiled) | Same as Quick Test, averaged over 10 rounds | profiling |
pipeline_results_benchmark_*.txt |
The saved image always comes from the first generation; the profiled rounds are used for timing only. If a run mixes Image-Only and Quick Test pipelines (see Setting the mode per pipeline), the results file is named pipeline_results_mixed_*.txt. Log files saved with --save-log use the same mode in their name (e.g. pipeline_log_quick_test_*.txt).
Quick Test Mode is the default; the shipped configuration does not enable image_only. The mode for each pipeline is chosen in this order (highest first):
--benchmarkβ always Benchmark Mode, regardless of anyimage_onlysetting--image-onlyβ Image-Only Mode for every pipelineimage_onlyset on the pipeline in the YAMLimage_onlyunderdefaultsin the YAML- Otherwise, Quick Test Mode
Use this for generating images as fast as possible, e.g. batch-generating images from a prompt file. Each prompt is generated once with no warmup or profiling.
python scripts/run_pipelines.py --image-only --pipelines sd3_base --prompt_file config/anime_prompts.jsonOutput: 5 images (anime_prompts.json contains 5 prompts), no profiling metrics
To make Image-Only the default for every pipeline without passing --image-only, set image_only: true under defaults in the YAML.
Use this for a quick performance check. Each prompt is generated once as a warmup and once more for profiling, so the report separates the first-generation time from the steady-state time.
python scripts/run_pipelines.py --pipelines sdxl_turboOutput: 1 image per prompt, warmup and average timing statistics
Use this for performance measurement. Each prompt is generated once as a warmup, followed by 10 profiled rounds whose times are averaged. Benchmark Mode needs no YAML changes.
python scripts/run_pipelines.py --benchmark --pipelines sdxl_turboOutput: 1 image per prompt, timing averaged over 10 rounds. The log shows Running 10 profiling rounds... followed by __ROUND_COMPLETE__ 1/10 β¦ 10/10. Benchmark results files can be converted to CSV; see Benchmark Files.
Add a top-level image_only key to a pipeline definition (next to name and model_ids, not inside args) to override the defaults value for that pipeline only. For example, to profile every pipeline except FLUX.1 Schnell, which only generates images:
defaults:
image_only: false
pipelines:
flux1_schnell:
name: "FLUX.1 Schnell Pipeline"
image_only: true
model_ids: ["amd/FLUX.1-schnell-amdnpu"]
args:
num_inference_steps: 4The reverse also works: set image_only: true under defaults and image_only: false on the pipelines you want to profile. --image-only and --benchmark on the command line override per-pipeline settings.
The framework support argument priorities based on the following order (highest to lowest):
- Command-line arguments
- Pipeline-specific YAML config
- Global YAML defaults
- Script-level defaults
The following are framework-level options that can be passed at the command line, or set in the YAML configuration file. Please read this carefully as it describes all of the available options for running pipelines. You can run the --help argument to get the same information at the command line:
python scripts/run_pipelines.py --help| Option | Type | Default | Help |
|---|---|---|---|
| --benchmark | flag | False | Enable benchmark mode (10 profiling rounds). Default is quick mode (1 round). |
| --image-only | flag | False | Generate images only without profiling (batch mode). Disables warmup and profiling rounds for fastest execution. Overrides image_only in the YAML. --benchmark takes precedence over --image-only. |
| --timeout | int | 600 | Timeout in seconds for each run (default: 600) |
| --model_id | list | Accepted but not currently used to filter pipelines; use --pipelines or --pipeline_groups instead |
|
| --pipelines | list | Run specific pipelines by name (e.g. --pipelines sd_15 sd3_base) | |
| --pipeline_groups | list | Run pipeline groups (e.g. --pipeline_groups all_sd3 quick_test) | |
| --list | flag | False | List available pipelines and groups, then exit |
| --prompt | str | Custom prompt to use for all pipelines | |
| --prompt_file | str | Path to JSON file containing list of prompts to run through each pipeline | |
| --sd3-controlnet-mode | str | controlnet | For SD3 ControlNet with prompt files: 'controlnet' uses custom prompts with ControlNet enabled (recommended), 'text2img' converts to text-to-image mode without ControlNet guidance (default: controlnet) |
| --force-cpu | flag | False | Force CPU-only execution (disables DML and all accelerators). Overrides config setting. |
| --no-summary | flag | False | Skip printing the detailed summary report and skip saving results to disk |
| --config | str | auto-detected | Path to custom YAML configuration file (default: config/pipeline_configs_strx.yaml) |
| --clean-images | flag | False | Remove all existing images and Excel files from generated_images folder before running pipelines |
| --clean-results | flag | False | Remove all existing result files from results folder before running pipelines |
| --save-log | flag | False | Save complete log output to a text file when any pipeline has streaming output enabled |
| --traceback | flag | False | Include full traceback in error messages for detailed debugging |
This section details text-to-image generation, listed under Image Generation Methods.
Generation starts from random noise set by seed. The text encoders turn the prompt into embeddings, the denoiser removes the noise over num_inference_steps steps while following those embeddings, and the VAE decoder turns the result into an image. The denoiser is a UNet for SD 1.5 and the SDXL family, and a transformer for SD3, SD3.5 and FLUX. The denoiser and VAE decoder run on the NPU; the tokenizers and text encoders run on the CPU or GPU (except the SD3/SD3.5 T5 encoder, which runs on the NPU when available), as shown in the model load summary of each run.
Every pipeline without a control_image_path, controlnet type or edit_image_path is a text-to-image pipeline. A minimal one needs only a model and a prompt:
sdxl_base:
name: "SDXL Base Pipeline"
width: 1024
height: 1024
model_ids: ["amd/sdxl-base-amdnpu"]
prompt: "A cozy cabin by a mountain lake in autumn, golden hour lighting"
args:
num_inference_steps: 30python scripts/run_pipelines.py --pipelines sdxl_base| Parameter | Where to set it | Effect |
|---|---|---|
prompt |
Pipeline (next to name), defaults, --prompt, or --prompt_file |
What to generate |
n_prompt |
args |
What to avoid, e.g. "blurry, low quality, watermark, text" |
num_inference_steps |
args |
Number of denoising steps. More steps take longer; distilled models (Turbo, Lightning, Schnell, Klein) are built for very few |
guidance_scale |
args |
How strictly the prompt is followed. Distilled models use 0.0 |
width, height |
Pipeline, defaults, or args |
Output resolution. Must be a resolution the model supports; see Dynamic Resolution |
seed |
args |
Random seed. The same seed and settings give the same image |
num_images_per_prompt |
args |
Images generated per prompt |
The shipped text-to-image pipelines use these settings (blank guidance = model default):
| Pipeline | Steps | guidance_scale |
Default resolution | Dynamic resolution |
|---|---|---|---|---|
sd_15 |
20 | 512x512 | β | |
sd_turbo |
1 | 0.0 | 512x512 | β |
sdxl_turbo |
4 | 0.0 | 512x512 | 5 shapes |
sdxl_base |
30 | 1024x1024 | 20 shapes | |
ssd_1b |
30 | 1024x1024 | 20 shapes | |
playground_25 |
30 | 1024x1024 | 20 shapes | |
dreamshaper_xl |
6 | 1024x1024 | 20 shapes | |
segmind_vega |
50 | 1024x1024 | β | |
sd3_base |
30 | 4.5 | 1024x1024 | 20 shapes |
sd35_base |
30 | 4.5 | 1024x1024 | 20 shapes |
flux1_schnell |
4 | 0.0 | 1024x1024 | 20 shapes |
flux2_klein |
4 | 0.0 | 1024x1024 | β |
Models with dynamic resolution (DynRes) can generate several resolutions and aspect ratios from one set of compiled NPU models, with no recompilation. The supported resolutions for each model are listed in a shape file:
| Shape file | Used by | Resolutions |
|---|---|---|
| config/dynamic_shape_5x.json | SDXL Turbo | 512x512, 384x512, 512x384, 288x512, 512x288 |
| config/dynamic_shape_20x.json | SDXL Base, SSD-1B, Playground 2.5, DreamShaper XL, SD3, SD3.5, FLUX.1 Schnell | 20 sizes from 512x288 to 1024x1024 in 1:1, 3:4, 4:3, 9:16 and 16:9 |
Each entry gives a height and width. Any other keys in an entry (such as t5_sequence_len) are passed to the pipeline for that resolution.
Two args keys control dynamic resolution:
dynamic_shape |
dynamic_shape_file_path |
Result |
|---|---|---|
true |
not set | One resolution: the pipeline's width and height |
true |
set | Every resolution in the shape file, in order |
false / not set |
ignored | One resolution: the pipeline's width and height |
One non-square resolution. Set dynamic_shape: true and pick a width and height from the model's shape file:
sdxl_base_portrait:
name: "SDXL Base Portrait"
width: 768
height: 1024
model_ids: ["amd/sdxl-base-amdnpu"]
args:
num_inference_steps: 30
dynamic_shape: trueEvery resolution. Add dynamic_shape_file_path. Relative paths are resolved from config_files_path (./config by default):
flux1_schnell_all_sizes:
name: "FLUX.1 Schnell - All Sizes"
model_ids: ["amd/FLUX.1-schnell-amdnpu"]
args:
num_inference_steps: 4
guidance_scale: 0.0
dynamic_shape: true
dynamic_shape_file_path: "dynamic_shape_20x.json"One image is saved per prompt and resolution, so a 20-shape file with a 5-prompt file produces 100 images. Each filename contains its resolution (e.g. ..._768x1024_steps4_...png). The results file reports only the pipeline's configured widthxheight, so check the filenames or the Using resolutions from log line to see which shapes ran.
Notes:
- Use only resolutions from the model's shape file. SDXL Turbo supports up to 512x512 only.
- SD 1.5, SD Turbo, Segmind Vega and FLUX.2 Klein do not support dynamic resolution and run at their default resolution.
- SD3 ControlNet Inpainting is fixed at 1024x1024.
Checking every resolution. config/pipeline_configs_dynres_smoke.yaml runs each DynRes model across its full shape file with 1 inference step and no image output. A pipeline passes only if every resolution completes:
# All DynRes models
python scripts/run_pipelines.py --config config/pipeline_configs_dynres_smoke.yaml --pipeline_groups dynres_smoke
# One model
python scripts/run_pipelines.py --config config/pipeline_configs_dynres_smoke.yaml --pipelines dynres_sdxl_turboThis section details the image-to-image modes listed under Image Generation Methods.
Used by Segmind Vega. The input image is encoded into the model's latent space, partly re-noised, then denoised toward the prompt. strength (0β1) sets how much of the image is replaced: near 0 keeps the input almost unchanged, near 1 ignores it. Only the last strength Γ num_inference_steps denoising steps run, so the shipped segmind_vega_i2i pipeline (50 steps, strength 0.45) runs 22 steps.
Segmind Vega switches to image-to-image when control_image_path is set; no ControlNet is involved. The shipped pipeline repaints outpainting_output_1024x1024.png at 1024x1024:
segmind_vega_i2i:
name: "Segmind-Vega I2I Pipeline"
model_ids: ["amd/segmind-vega-amdnpu"]
args:
num_inference_steps: 50
control_image_path: "outpainting_output_1024x1024.png"
strength: 0.45
guidance_scale: 7.0python scripts/run_pipelines.py --pipelines segmind_vega_i2iGuide generation with a control image that fixes the layout of the result, such as an edge map, depth map, pose skeleton or masked photo. The ControlNet keeps the composition from the control image while the prompt decides the content and style. controlnet_conditioning_scale sets how strongly the control image is followed.
Example use cases: keeping a product's shape while changing its style, posing characters, replacing an object in a photo
ControlNet is available for SD 3.0 Medium and SD 1.5. Set the type with controlnet and the control image with control_image_path in the pipeline's args. Relative image paths are resolved from control_images_path (test/assets by default).
| Pipeline | Model | controlnet |
Control image | Example asset | Conditioning scale |
|---|---|---|---|---|---|
sd3_controlnet_canny |
SD 3.0 Medium | Canny |
Edge map (white lines on black) | control.png |
0.7 |
sd3_controlnet_depth |
SD 3.0 Medium | Depth |
Depth map (near = bright) | depth.jpeg |
0.8 |
sd3_controlnet_pose |
SD 3.0 Medium | Pose |
OpenPose skeleton | pose.jpg |
0.7 |
sd3_controlnet_tile |
SD 3.0 Medium | Tile |
Regular photo whose detail and structure are kept | tile.jpg |
0.65 |
sd3_controlnet_inpainting |
SD 3.0 Medium | InPainting |
Photo plus a mask in control_mask_path (white = regenerate, black = keep) |
coffee_table.png + precise_mask.png |
0.85 |
sd_15_controlnet |
SD 1.5 ControlNet | Canny (fixed) |
Regular photo; Canny edges are extracted automatically | test/ref/control.png (model default) |
1.5 |
Preparing control images: SD3 ControlNet uses the control image as-is, so Canny, Depth and Pose inputs must already be an edge map, depth map or pose skeleton. SD 1.5 ControlNet takes an ordinary photo and computes the Canny edge map itself. SD3 ControlNet pipelines run at 1024x1024.
Run a ControlNet pipeline like any other pipeline:
python scripts/run_pipelines.py --pipelines sd3_controlnet_depthWhen running scripts/run_pipelines.py, the outputs are images and result text files in specific locations with organized naming conventions.
Images by default can be found in test/generated_images/. Filenames include model name, image index, run type, resolution, number of steps, prompt index, and timestamp (e.g., test/generated_images/FLUX.1-schnell-amdnpu_img0_batch_1024x1024_steps4_prompt0_20261012_121816.png).
Note: You can use the
--clean-imagesflag to remove all existing images from thegenerated_imagesfolder before running any pipelines.
Results files can be found in results/ directory (e.g., results/pipeline_results_quick_20251124_100116.txt). They contain execution status (success/failure), duration, timing data, model information, resolution, and error messages for all pipelines run in a session.
Note: You can disable the generation of summary files by using the
--no-summaryflag when running the main script. You can also use the--clean-resultsflag to remove all existing result files from theresultsfolder before running any pipelines.
You can choose to save all lines printed to the console at runtime with the--save-log flag when running the main script. Log files are saved in the results/ directory and contain the complete console output from all pipeline executions, including detailed progress messages, warnings, and debug information (e.g., results\pipeline_log_quick_test_20251124_102713.txt).
When using the benchmarking mode (--benchmark), the results text file includes the benchmarking information (e.g., results/pipeline_results_benchmark_20251124_102713.txt).
After creating the pipeline_results_benchmark_*.txt files, you can run the scripts/process_benchmark_results.py script to extract benchmark data. This CSV can be imported into Excel for performance analysis and comparison. To generate the CSV file, simply run:
python scripts/process_benchmark_results.pyIt reads every results/pipeline_results_benchmark_*.txt file and writes a CSV to results/ (e.g., results/benchmark_summary_20251124_104406.csv) with an output similar to:
Model Name,Resolution,Inference Steps,NPU Models Load Time (s),All Models Load Time (s),1st Gen Pipeline Time (s),Avg Pipeline Time (s),Seconds/Iter,NPU Memory Usage (MB),Total Memory Usage (MB)
SD 1.5 Pipeline,512x512,20,3.898902,3.899352,5.979673,5.978549,0.298927,1527.36,4412.52These guides come from the GenAI-SD folder shipped with the Ryzen AI 1.9 software installer (C:\Program Files\RyzenAI\1.9.0\GenAI-SD) β the same folder you copy in Step 2. They describe how to use the GenAI-SD code directly β without this sandbox's orchestrator β covering driver and conda setup, the per-model run.py commands, troubleshooting, and more. Once you've copied that folder locally you can follow these documents in it; the copies below are mirrored in this repository's docs/ directory for convenience.
| Document | Contents |
|---|---|
| docs/01-quick-start.md | Driver installation, conda setup, first run |
| docs/02-user-guide.md | Batch pipelines, YAML config, execution modes |
| docs/03-model-reference-guide.md | All model commands and CLI arguments |
| docs/04-model-generate-guide.md | DD model creation workflow (onnx_utils, Windows only) |
| docs/05-linux-guide.md | Linux setup |
| docs/06-faq.md | Top 15 failure modes and solutions |
| docs/07-developer-guide.md | Adding new pipelines to the codebase |
| docs/08-glossary.md | NPU, DD, ControlNet, InPainting, and more |
- AMD Ryzen AI Documentation: https://ryzenai.docs.amd.com/
- AMD Driver Support Portal: https://www.amd.com/en/support
β If this framework helped your development, consider starring the repository! β
Built with β€οΈ by AMD for the AI developer community
Copyright Advanced Micro Devices, Inc.
Code written by Advanced Micro Devices, Inc. in this repository is released under the MIT License.
Some files are derived from third-party projects (Hugging Face Diffusers, Hugging Face Transformers, and Kwai-Kolors/Kolors) and remain under the Apache License 2.0. Those files keep their original copyright and license headers. The full Apache-2.0 text is included in LICENSE, and MANIFEST.md lists every third-party file, dependency, and media asset.



