Skip to content

02. Configuration

Jump to bottom
imi edited this page Aug 16, 2025 · 1 revision

Configuration Files

sd-optim uses Hydra to manage configuration through YAML files located in the conf/ directory. After following the 01. Getting Started guide, you should have copied the .tmpl.yaml files to .yaml files. This page explains the settings within those files.

config.yaml (Main Configuration)

This is the primary configuration file controlling the entire optimization run.

Sections:

  • defaults: Internal Hydra setting. Do not change.
  • run_name: A name for your optimization run. Used to create the output directory name in logs/. You can use variables like ${merge_method}.
  • hydra: Hydra-specific settings, mainly defining the output directory structure using the run_name.

WebUI Connection

Defines how sd-optim connects to your running Stable Diffusion WebUI's API.

  • webui_urls: A map of WebUI identifiers (keys) to their base URLs (values).
  • webui: Select the identifier of the WebUI you are running (e.g., forge, a1111, comfy, swarm).
  • url: (Do not set manually) Automatically determined based on the selected webui.
# Example WebUI Connection
webui_urls:
  a1111: http://localhost:7860
  forge: http://localhost:7860
  comfy: http://localhost:8188
webui: forge
url: "${webui_urls[${webui}]}" # This selects http://localhost:7860

File Paths

Specifies locations for necessary files.

  • configs_dir: Path to your custom sd-mecha block definition .yaml files.
  • conversion_dir: Path to your custom sd-mecha converter .py scripts.
  • wildcards_dir: Path to the directory containing your wildcard .txt files (used for prompt generation).
  • scorer_model_dir: Path to the directory where aesthetic/quality scorer models will be downloaded and stored.

Model Inputs

Defines the models to be merged.

  • model_paths: (Required) A list of strings, each pointing to the path of an input model file (.safetensors). At least one model is needed for merge or layer_adjust modes. Loras are detected automatically.
  • base_model_index: (Required for some merge methods) The index (starting from 0) within the model_paths list corresponding to the model that should be used as the base when calculating deltas (e.g., for add_difference).

Merge Settings (sd-mecha)

Controls how the sd-mecha library performs the merge.

  • merge_method: (Required for merge mode) The name (identifier string) of the sd-mecha merge method to use (e.g., weighted_sum, ties_sum_extended). Can be a built-in method or a custom one (see 06. Merge Methods).
  • device: The primary device (cuda or cpu) for sd-mecha calculations during the merge.
  • threads: Number of threads sd-mecha should use for merging.
  • merge_dtype: The precision used during the merge calculation (fp16, bf16, fp32, fp64). Using fp32 or fp64 is recommended for stability, even if saving in lower precision.
  • save_dtype: The precision used when saving the final merged model file (fp16, bf16, fp32, fp64).
  • add_extra_keys: If True, adds empty v_pred and ztsnr keys to the saved model. Useful for ensuring compatibility with v-prediction checkpoints.

General Workflow

General settings for the optimization run.

  • save_merge_artifacts: If True, saves a self-contained, runnable .py script for each merge that can reproduce it exactly. Highly recommended for sharing and debugging.
  • save_best: If True, keeps a separate copy of the model file from the iteration that achieved the best score so far.

Optimization Mode

Selects the primary operation mode for the tool.

  • optimization_mode: Choose one:
    • merge: Optimize hyperparameters for the specified merge_method applied to the model_paths.
    • layer_adjust: Optimize layer adjustment parameters (brightness, contrast, etc.) applied to the first model in model_paths..
    • recipe: Optimize hyperparameters within an existing .mecha recipe file.
  • recipe_optimization: (Settings used only if optimization_mode: recipe)
    • recipe_path: Path to the input .mecha file.
    • target_nodes: A string or list of strings referencing the node(s) inside the recipe file (e.g., '&3', ['&3', '&4']) whose parameters should be optimized.
    • target_params: A list of parameter names within the target node(s) to optimize (e.g., [alpha, beta]).

Optimizer Configuration (optimizer: block)

Configures the chosen optimization algorithm.

  • Optimizer Choice: Set one of bayes or optuna to True.
  • Common Settings:
    • random_state: Seed for reproducibility (-1 for random). Affects both initial sampling and optimizer behavior.
    • init_points: Number of initial exploration points/trials before exploitation begins.
    • n_iters: Number of main exploitation iterations/trials. Total evaluations = init_points + n_iters.
    • load_log_file: (Optional) Path to a previous run's log file (.json for Bayes, .jsonl for Optuna) to resume optimization.
    • reset_log_file: If True when resuming, overwrites the log file; otherwise, appends.
  • Bayes-Specific Settings (bayes: True): See 05. Optimization Strategies for details.
    • sampler: Strategy for init_points (random, latin_hypercube, sobol, halton).
    • acquisition_function: kind (ucb, ei, poi) and related parameters (kappa, xi, etc.).
    • bounds_transformer: Domain reduction settings (enabled, gamma_osc, etc.).
  • Optuna-Specific Settings (optuna: True): See 05. Optimization Strategies for details.
    • storage_dir: Folder where Optuna's study database files (.db) will be saved.
    • resume_from_study: To resume a specific study, provide its name here (e.g., "run_20250612_191003_tpe"). Set to null for new runs.
    • fork_study: If True when resuming, creates a new study that starts by enqueueing all successful trials from the parent study.
    • sampler: Nested dictionary defining the Optuna sampler (type and specific options).
    • use_pruning, pruner_type: Settings for trial pruning.
    • early_stopping, patience, min_improvement: Settings for early stopping.
    • n_jobs: Number of parallel trials (use carefully, experimental).
    • launch_dashboard: If True, automatically launches the Optuna dashboard in the background.
    • dashboard_port: Port for the Optuna dashboard.

Image Generation & Networking

Settings controlling the image generation process performed by the WebUI.

  • batch_size: How many images to generate for each payload listed in your cargo_*.yaml file during each optimization iteration. Total images per iteration = batch_size * number_of_payloads.
  • save_imgs: If True, generated images are saved in the logs/<run_folder>/imgs/ directory. Automatically enabled for manual scoring.
  • img_average_type: How scores for multiple images generated within the same iteration (due to batch_size > 1 or multiple payloads) are averaged together before being reported to the optimizer (arithmetic, geometric, quadratic).
  • generator_concurrency_limit: Max number of simultaneous API requests to the WebUI.
  • generator_keepalive_interval: Interval (seconds) for sending TCP Keep-Alive probes to prevent connection drops.
  • generator_total_timeout: Max total time (seconds) for a single API call. Set to 0 or null to disable client timeout.

Scoring

Settings controlling how generated images are evaluated. See 04. Scoring for details.

  • scorer_method: List of scorer identifiers (e.g., cityaes, imagereward, manual).
  • scorer_average_type: How scores from different scorers for the same image are averaged (arithmetic, geometric, quadratic).
  • scorer_weight: (Optional) Weights for combining scores from different scorers.
  • scorer_filters: (Optional) Exclude specific scorers from running on certain payloads.
  • scorer_default_device: Default device (cpu or cuda) for running scorers.
  • scorer_device: (Optional) Override the device for specific scorers.
  • scorer_alt_location: (Optional) Specify custom paths for scorer models.
  • scorer_print_individual: If True, shows the score from each individual scorer.
  • hpsv3_uncertainty_penalty: A multiplier for how much the hpsv3 scorer's uncertainty (sigma) penalizes its final score. Default is 0.5.
  • Undocumented scorer specific settings might be present at any time depending on what scorers are implemented, check their code specifically.

Visualizations

Controls the generation of plots summarizing the optimization run.

  • convergence_plot: If True, saves a plot showing the best score found over iterations/trials.
  • (Other plot to be added in the future)

optimization_guide.yaml

This file is the core of the optimization process, determining what to optimize and how. It uses a flexible component-and-strategy system to apply optimizable parameters from your merge method to different parts of the model.

custom_block_config_id (Optional)

If you are using a custom-defined set of blocks (e.g., sdxl-optim_blocks.yaml), specify its identifier here. The optimizer will use this for any component that is defined within it. For other components, it will fall back to the model's default key structure.

custom_block_config_id: "sdxl-optim_blocks"

components Section

This is a list where each item defines the optimization plan for a model component (like unet, clip_l, etc.).

# Example guide.yaml structure
components:
  - name: unet
    optimize_params: [alpha, beta] # Optional: Default params for all strategies in this component.
    strategies:
      - type: group
        target_type: block # Target block names from your custom_block_config_id
        groups:
          - name: unet_in
            keys: ["UNET_IN*"] # Wildcard for all input blocks
          - name: unet_mid
            keys: ["UNET_MID*"]
      - type: select
        target_type: key # Target raw key names from the base model
        optimize_params: [alpha] # Override component's default, only use alpha here.
        keys: ["*.output_blocks.8.*"]

Component Keys:

  • name: (Required) The name of the component (e.g., unet, clip_l). Must match a component in your custom_block_config_id or the base model's config.
  • optimize_params: (Optional) A list of parameter names from your merge method (e.g., [alpha, rank_ratio]) to be applied by default to all strategies within this component.
  • strategies: (Required) A list of strategy blocks that define how the optimize_params are applied.

Strategy Block Keys:

  • type: (Required) The strategy to use.
    • all: Create an independent parameter for every single key/block in the component. (e.g., UNET_IN00_alpha, UNET_IN01_alpha, ...). Use with caution!
    • select: Create an independent parameter for only the keys/blocks that match the wildcard patterns in the keys list.
    • group: Create a single shared parameter for all keys/blocks matching the patterns within each defined group. (e.g., a single unet_in_alpha for all input blocks).
    • single: Create one single shared parameter for the entire component.
    • none: Exclude this component/part from optimization.
  • target_type: (Optional) Specifies whether the keys refer to block names (from your custom config) or key names (from the base model). If omitted, it defaults to block if the component is in the custom config, otherwise key.
  • optimize_params: (Optional) Override the component-level optimize_params for just this strategy.
  • keys: (Required for select, group) A list of key/block names or wildcard patterns.
  • groups: (Required for group) A list of group definitions, each with a name and a list of keys.

custom_bounds Section

This optional dictionary allows you to override the default optimization bounds for any parameter generated by the strategies.

Parameter Naming Convention:

  • all/select: {key_or_block_name}_{param_name} (e.g., UNET_IN04_alpha)
  • group: {group_name}_{param_name} (e.g., unet_in_alpha)

Bound Formats:

  • Continuous Range: param_name: (0.1, 0.9) (using parentheses ()). The optimizer can select any float value between 0.1 and 0.9.
  • Categorical: param_name: [8, 16, 32, 64] (using square brackets []). The optimizer will only choose from the specific values provided in the list.
  • Fixed Value: param_name: 0.75 (This parameter will not be optimized).

Important

The use of parentheses () vs. square brackets [] is critical.

  • (min, max) defines a continuous range.
  • [val1, val2, ...] defines a categorical choice. For a simple range, [0.1, 0.9] would be treated as a categorical choice between only 0.1 and 0.9, not the numbers in between.
  • Advanced (Optuna): 
    param_name:
  range: [0.01, 1.0]
  log: true  # Use logarithmic scale
  step: 0.01 # Suggest values in increments

You can also set a global override for a base parameter name (e.g., alpha: [0.2, 0.8]), which will apply to all generated ..._alpha parameters that don't have a more specific override.

# Optional: Override default bounds (e.g., 0.0 to 1.0) for specific parameters
custom_bounds:
  # Parameter names depend on strategy, names, keys, and merge method params (e.g., _alpha)
  # See examples below and parameter naming conventions section.

  # Examples:
  # constraint: [0.01, 0.2] # Applies to all generated parameters named 'constraint'
  # alpha: [0.1, 0.9]       # Applies to all generated parameters ending in '_alpha'

  # specific.key.name_alpha: [0.0, 0.5] # More specific override
  # my_group_1_k: [0.1, 0.5]            # Override for a group parameter
  # unet_single_param_alpha: [0.2, 0.8] # Override for a single component parameter

  # fixed_parameter_name: 0.75          # Fix a value (not optimized)
  # categorical_parameter: [128, 256, 512] # Categorical choices
  # binary_parameter: [0, 1]            # Binary choice

Clone this wiki locally