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

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.

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

Specifies locations for necessary files.

• 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.

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).

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 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 settings for the optimization run.

• save_merge_method_code: If True, saves the Python source code of the specific merge_method used in each iteration to the logs directory. Useful for tracking custom methods.
• save_best: If True, keeps a separate copy of the model file from the iteration that achieved the best score so far.

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)
  • enabled: Set to True to activate recipe optimization.
  • 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.

Configures the chosen optimization algorithm.

• Optimizer Choice: Set one of bayes or optuna to True.
  • bayes: Uses the bayesian-optimization library.
  • optuna: Uses the Optuna library.
• 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 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 Optimization Strategies for details.
  • sampler: Nested dictionary defining the Optuna sampler (type and specific options).
  • use_pruning, pruner_type: Settings for trial pruning.
  • checkpoint_dir, checkpoint_interval: Settings for saving Optuna study state.
  • early_stopping, patience, min_improvement: Settings for early stopping.
  • n_jobs: Number of parallel trials (use carefully).

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).

Settings controlling how generated images are evaluated. See 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_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.

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 options may be added)

This file determines which parameters of the chosen merge_method (from config.yaml) are optimized and how they apply to the model structure defined by sd-mecha. It allows for fine-grained control over the optimization search space.

# Example guide.yaml structure

components:
  - name: unet # Component name (must match a component in the sd-mecha ModelConfig)
    strategy: all # Optimization Strategy: 'all', 'select', 'group', 'single', 'none'

    # --- Optional sections based on strategy ---
    # keys: (Only used if strategy: select)
    #   - "key_name_or_wildcard_pattern"
    #   # - "*.attn1.*" # Example wildcard

    # groups: (Only used if strategy: group)
    #   - name: my_group_1 # Unique name for this group's parameter(s)
    #     keys:
    #       - "key_name_or_wildcard_1"
    #       - "key_name_or_wildcard_2"
    #   # - name: my_group_2
    #   #   keys: [...]

# 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

This is a list where each item configures optimization for a specific model component.

• name: The target component identifier (e.g., unet, clip_l, vae). This must match a component name defined in the sd-mecha ModelConfig being used (which is inferred from your input models).
• strategy: Defines how optimizable parameters from the merge_method are applied to this component.
  • all: Create an independent parameter for each key within this component for each optimizable parameter of the merge method. (Generates many parameters like key1_alpha, key2_alpha, etc.).
  • select: Create an independent parameter only for keys matching the patterns listed in the keys: section below it. Supports wildcards (*). (Generates parameters like matching_key1_alpha, matching_key2_alpha, etc.).
  • group: Create a single shared parameter for all keys listed within each defined group below it. (Generates parameters like group_name1_alpha, group_name2_alpha, etc.).
  • single: Create one single shared parameter for the entire component. (Generates parameters like component_name_single_param_alpha).
  • none: Exclude this component from optimization entirely. No parameters are generated for it.
• keys: (Only used if strategy: select) A list of key name strings or wildcard patterns (*) defining which keys within the component should have parameters created for them.
• groups: (Only used if strategy: group) A list of group definitions. Each group needs:
  • name: A unique name for this group (used in parameter naming).
  • keys: A list containing the key names or wildcard patterns belonging to this group. All keys in a group will share the same optimized parameter value(s).

This optional dictionary allows you to override the default optimization bounds (which are often 0.0 to 1.0, but depend on the bounds.py implementation) for specific parameters generated by the components section.

• Parameter Naming Convention: The keys in custom_bounds must match the names generated by bounds.py. The pattern generally is:
  • all/select: key_name_PARAMNAME (e.g., model.diffusion_model.input_blocks.0.0.weight_alpha)
  • group: group_name_PARAMNAME (e.g., my_group_1_k)
  • single: component_name_single_param_PARAMNAME (e.g., unet_single_param_alpha)
  • You can also target all parameters ending with _PARAMNAME by just using PARAMNAME (e.g., alpha: [0.1, 0.9]). More specific names override general ones. (Where PARAMNAME is the name of the optimizable parameter from the merge_method, like alpha, k, constraint, etc.)
• Bound Formats:
  • Range: [min, max]
  • Categorical List: [val1, val2, val3]
  • Binary: [0, 1]
  • Fixed Value: A single number (e.g., 0.75). This parameter will be fixed and not optimized.