Configure Placeholders

Parameter placeholders give you precise control over how parameters are passed to your training scripts and commands. Instead of manually crafting command-line arguments, you define them once in your valohai.yaml and let Valohai handle the parameter injection.

This approach makes hyperparameter optimization seamless and ensures all parameter values are tracked for reproducibility.

When to Use Parameter Placeholders

Use parameter placeholders when you need to:

• Track parameters automatically for hyperparameter optimization

• Avoid hardcoding values in your training scripts

• Pass different parameter formats to various tools (e.g., --lr=0.001 vs lr 0.001)

• Handle multiple parameter values in a single execution

Core Placeholder Types

{parameters} - Inject All Parameters

The {parameters} placeholder injects all defined parameters into your command at once.

YAML Configuration:

- step:
    name: train-model
    image: python:3.11
    command: python train.py {parameters}
    parameters:
      - name: max-steps
        type: integer
        description: Number of training steps
        default: 300
      - name: learning-rate
        type: float
        pass-as: --lr={v}
        description: Initial learning rate  
        default: 0.001
      - name: architecture
        type: string
        pass-as: --arch={v}
        default: resnet50
        optional: true

Generated Command:

python train.py --max-steps=300 --learning-rate=0.001 --architecture=resnet50

💡 Parameters only appear if they have values. Optional parameters with no value are skipped.

{parameter:} - Use Specific Parameters

Target individual parameters using {parameter:<NAME>} syntax. This is useful for multi-step commands or when you need parameters in specific positions.

YAML Configuration:

- step:
    name: preprocess-and-train  
    image: python:3.11
    command:
      - python preprocess.py {parameter:train-split}
      - python train.py {parameter:learning-rate}
    parameters:
      - name: train-split
        type: integer
        pass-as: --split={v}
        default: 80
      - name: learning-rate
        type: float
        pass-as: --lr={v}
        default: 0.001

Generated Commands:

python preprocess.py --split=80
python train.py --lr=0.001

{parameter-value:} - Raw Values Only

Use {parameter-value:<NAME>} to pass only the parameter value, ignoring any pass-as formatting.

YAML Configuration:

- step:
    name: preprocess
    image: python:3.11
    command: python preprocess.py {parameter-value:train-split} {parameter-value:style}
    parameters:
      - name: train-split
        type: integer  
        default: 80
      - name: style
        type: string
        pass-as: --style={v}  # This gets ignored
        default: nested

Generated Command:

python preprocess.py 80 nested

Advanced Use Cases

Parameters in Input Paths

Parameter placeholders work in input definitions, enabling dynamic data loading based on parameter values.

- step:
    name: train-model
    image: python:3.11
    command: python train.py
    parameters:
      - name: device-id
        type: integer
        default: 455
      - name: experiment
        type: string
        default: "baseline"
    inputs:
      - name: dataset
        default: s3://ml-data/{parameter:device-id}/train/*
      - name: model-config
        default: datum://config-{parameter:experiment}
      - name: sensor-data  
        default: dataset://sensors-{parameter:experiment}/{parameter:device-id}

Multiple Value Parameters

Handle lists of values with multiple parameter configuration.

Comma-Separated Values:

- step:
    name: train-ensemble
    image: python:3.11
    command: python train.py {parameters}
    parameters:
      - name: seed-values
        type: integer
        multiple: separate
        multiple-separator: ","
        default: [455, 922, 1344]

Generated Command:

python train.py --seed-values=455,922,1344

Repeated Arguments:

- step:
    name: train-ensemble
    image: python:3.11  
    command: python train.py {parameters}
    parameters:
      - name: seed-values
        type: integer
        multiple: repeat
        default: [455, 922, 1344]

Generated Command:

python train.py --seed-values=455 --seed-values=922 --seed-values=1344

Alternative: Configuration Files

For complex parameter structures, read parameters from JSON or YAML configuration files instead of command placeholders.

Python (Standard Library):

import json

with open("/valohai/config/parameters.json") as f:
    params = json.load(f)

print(params["seed_values"])  # [455, 922, 1344]

Python (valohai-utils):

import valohai

# Note: Don't use {parameters} placeholders if reading from files
epochs = valohai.parameters("epochs").value
learning_rate = valohai.parameters("learning-rate").value

💡 Learn more about available configuration files in System Configuration Files.

Best Practices

Combine placeholder types freely:

command:
  - python setup.py {parameter:config-file}
  - python train.py {parameters}
  - python evaluate.py --model-path={parameter-value:output-dir}/model.pkl

Use descriptive parameter names that match your script's argument parser.

Set reasonable defaults so executions work without manual parameter tuning.

Use optional: true for parameters that shouldn't appear when undefined.

Parameter placeholders make your ML workflows more flexible and your experiments more reproducible. They're essential for automated hyperparameter optimization and tracking parameter impact on model performance.