How Configs Work

About 3 min

How Configs Work

ESPnet3 keeps most experiment settings in YAML files. Instead of putting many options on the command line, you edit a small set of config files and pass them to run.py.

Important

In ESPnet3, YAML is the main control surface. Do not expect the recipe runner to expose many ad-hoc CLI overrides.

One config per pipeline area

Most recipes follow this layout:

conf/
├── training.yaml
├── inference.yaml
├── metrics.yaml
├── publication.yaml
└── demo.yaml

Each file owns one major part of the workflow:

File	Used for
`training.yaml`	dataset preparation, tokenizer training, stats, training
`inference.yaml`	model loading, inference dataset, output writing
`metrics.yaml`	metric computation
`publication.yaml`	model packaging and upload
`demo.yaml`	demo packaging and upload

Dataset sections are shared by training and inference. See Dataset Config for train, valid, test, data_src, and data_src_args.

Note

Not every recipe needs every config file, but this split is the standard mental model for understanding an ESPnet3 recipe.

parallel is a cross-cutting config block rather than a separate top-level file. It is usually placed inside training.yaml, inference.yaml, or another stage-specific config. See Parallel Config.

How run.py uses them

run.py reads only the configs needed by the requested stages.

python run.py \
  --stages train infer measure \
  --training_config conf/training.yaml \
  --inference_config conf/inference.yaml \
  --metrics_config conf/metrics.yaml

Typical mapping:

Stage	Config
`create_dataset`	`training_config`
`train_tokenizer`	`training_config`
`collect_stats`	`training_config`
`train`	`training_config`
`infer`	`inference_config`
`measure`	`metrics_config`
`pack_model`	`training_config` + `publication_config`
`upload_model`	`publication_config`
`pack_demo`	`demo_config`
`upload_demo`	`demo_config`

If a required config is missing, ESPnet3 raises an error instead of guessing.

Warning

When a stage needs a config, pass it explicitly. ESPnet3 does not try to infer missing config intent from another file.

What usually goes in a config

You do not need to memorize every field at first. The useful mental model is:

training.yaml: model, dataset, dataloader, optimizer, trainer, output dirs
inference.yaml: provider, runner, test sets, output dirs
metrics.yaml: which metrics to compute and where inference outputs live
publication.yaml: which files to pack and where to upload them
demo.yaml: packed model source, UI definition, and demo upload settings

Three important patterns

_target_ selects the Python object

ESPnet3 uses Hydra-style instantiation. When a config contains _target_, that value points to the class or function to construct.

optimizer:
  _target_: torch.optim.Adam
  lr: 0.001

${...} reuses shared values

Configs often build paths from shared variables such as recipe_dir or exp_dir.

recipe_dir: .
exp_tag: my_run
exp_dir: ${recipe_dir}/exp/${exp_tag}

YAML is the main control surface

In ESPnet3, you usually change behavior by editing YAML, not by adding many CLI overrides. This keeps runs easier to reproduce and share inside a recipe.

Hydra-like features you can still use

ESPnet3 does not depend on the full Hydra runtime at launch time, but it does support several Hydra/OmegaConf-style patterns through espnet3/utils/config_utils.py.

defaults composition

You can compose configs with a Hydra-style defaults list.

defaults:
  - model: conformer
  - optim: adam
  - _self_

This lets you split config sections across multiple YAML files and merge them into one final config.

_self_

_self_ controls where the current file is merged in the composition order. That matters when the current file overrides values loaded from defaults.

Custom resolvers

ESPnet3 registers custom OmegaConf resolvers such as:

${load_line:tokens.txt} to load text lines from a file
${self_name:} to reuse the current config name

Example:

exp_tag: ${self_name:}
token_list: ${load_line:tokens.txt}

Relative resolver paths

Resolver paths are resolved relative to the YAML file that contains them. So if a config says ${load_line:tokens.txt}, ESPnet3 rewrites that against the current config directory before resolution.

See Config Resolvers for supported resolver syntax and path behavior.

Template defaults + recipe overrides

When a recipe config is loaded, ESPnet3 merges it with the packaged default config from the matching egs3.TEMPLATE.<task> package. This means your recipe config usually overrides a working template instead of redefining everything from scratch.

What to read next

Use this page as the overview. Then go deeper only when you need details.

Training Config

See the main sections used by dataset preparation and training.

Inference Config

See how model loading, test sets, and inference outputs are configured.

Metrics Config

See how metric computation is configured after inference.

Publication Config

See how model packaging and upload settings are defined.

Demo Config

See how demo packaging and upload settings are defined.

Parallel Config

See how Dask backends are configured for local, local GPU, and HPC runs.

Dataset Config

See train, valid, test, data_src, and data_src_args entries.

Config Resolvers

See load_line, self_name, relative resolver paths, and defaults behavior.