How to Configure the Hydra Training Configuration in Fish-Speech

Fish-Speech leverages Hydra to manage training configurations through modular YAML files in fish_speech/configs/, allowing you to override parameters via command-line arguments or custom experiment configs without modifying Python code.

Fish-Speech is an open-source text-to-speech system that uses Hydra to handle every aspect of the training pipeline. To configure the Hydra training configuration, you work with a hierarchy of YAML files located under fish_speech/configs/, starting with a base configuration and extending it through experiment-specific files or inline overrides. The entry point fish_speech/train.py uses the @hydra.main decorator to load and merge these configurations at runtime.

Core Concepts of Hydra Configuration

Fish-Speech organizes training parameters into a composable system of YAML files. Understanding these four core concepts is essential to configure the Hydra training configuration effectively.

Concept	Purpose	Key File
Base config	Defines default paths, trainer settings, callbacks, and loggers shared across all experiments.	fish_speech/configs/base.yaml
Experiment config	Inherits from base and overrides specific sections for a task (e.g., data module, model architecture).	fish_speech/configs/text2semantic_finetune.yaml
Hydra overrides	Command-line key-value pairs that temporarily replace any config field.	CLI arguments
Instantiators	Helper functions wrapping hydra.utils.instantiate to convert config nodes into Python objects.	fish_speech/utils/instantiators.py

Base and experiment configs reside in fish_speech/configs/, while instantiators live in fish_speech/utils/instantiators.py.

How Hydra Loads Configurations

The entry script fish_speech/train.py initializes the configuration system using the @hydra.main decorator:

@hydra.main(version_base="1.3", config_path="./configs", config_name="llama_pretrain.yaml")
def main(cfg: DictConfig) -> Optional[float]:
    train(cfg)

This decorator instructs Hydra to:

1. Search for configs in the ./configs directory relative to the script.
2. Load llama_pretrain.yaml as the default entry point.
3. Merge any additional configs or CLI overrides into the cfg object.

Inside the train(cfg) function, the code accesses the merged configuration and instantiates components using hydra.utils.instantiate. All objects—including the data module, model, trainer, callbacks, and loggers—are created from their respective config sections.

Creating a Custom Training Configuration

To configure the Hydra training configuration for a new experiment, create a dedicated YAML file that inherits from the base configuration.

Step 1: Create the Experiment File

Create a new file in fish_speech/configs/, for example my_experiment.yaml.

Step 2: Inherit the Base Configuration

Start your file with the defaults list to load base.yaml before applying your overrides:

# fish_speech/configs/my_experiment.yaml

defaults:
  - base        # loads base.yaml

  - _self_      # allows overrides in this file to take effect

project: my_fine_run
trainer:
  max_steps: 15000
  precision: 16-mixed
data:
  batch_size: 8
  num_workers: 2
model:
  optimizer:
    lr: 3e-5
callbacks:
  model_checkpoint:
    every_n_train_steps: 2000

Step 3: Launch Training

Reference your custom config using the + prefix:

python -m fish_speech.train +my_experiment.yaml

The + tells Hydra to add this config on top of the defaults, merging it with any other specified files.

Overriding Configuration via Command Line

You can configure the Hydra training configuration without creating new files by passing overrides directly to the train command.

Basic Override Syntax

Provide key-value pairs after the script name:

python -m fish_speech.train \
    +project=quick_test \
    trainer.max_steps=5000 \
    data.batch_size=4 \
    model.optimizer.lr=1e-4 \
    callbacks.model_checkpoint.every_n_train_steps=500

Combining Config Files and Overrides

Use a full experiment config and tweak specific values:

python -m fish_speech.train \
    +text2semantic_finetune.yaml \
    trainer.max_steps=20000 \
    model.optimizer.lr=2e-5

Hydra merges configurations in this order: base.yaml → experiment config → CLI overrides.

Key Configuration Parameters

When you configure the Hydra training configuration, these are the most commonly modified sections:

Section	Parameter	Description	Example
project	project	Human-readable name for output directories	+project=my_finetune
trainer	max_steps	Total number of training steps	trainer.max_steps=20000
trainer	precision	Numerical precision (bf16-mixed, 16-mixed, 32)	trainer.precision=16-mixed
data	batch_size	Samples per GPU	data.batch_size=8
model	optimizer.lr	Learning rate	model.optimizer.lr=5e-5
callbacks	model_checkpoint.every_n_train_steps	Checkpoint saving frequency	callbacks.model_checkpoint.every_n_train_steps=1000
logger	tensorboard.save_dir	TensorBoard log directory	logger.tensorboard.save_dir=./my_logs

All parameters support both YAML file configuration and CLI override syntax.

Summary

• Fish-Speech uses Hydra to manage training configurations through composable YAML files in fish_speech/configs/.
• The base config (base.yaml) provides shared defaults for paths, trainer settings, and logging.
• Experiment configs inherit from base and override specific sections like data modules, model architecture, and optimization parameters.
• You can launch training with custom configs using the + prefix or override individual values via CLI arguments without creating new files.
• The train.py entry point uses hydra.utils.instantiate to convert configuration nodes into concrete Python objects for the data module, model, trainer, and callbacks.

Frequently Asked Questions

How do I change the learning rate without editing YAML files?

Pass the learning rate as a command-line override when launching training. Use dot notation to access nested parameters: python -m fish_speech.train model.optimizer.lr=5e-5. Hydra will merge this value into the loaded configuration at runtime, overriding any value specified in the YAML files.

What is the difference between base.yaml and experiment configs like text2semantic_finetune.yaml?

base.yaml contains universal defaults—directory paths, standard callbacks, and logger configurations—that apply to all training runs. Experiment configs like text2semantic_finetune.yaml inherit these defaults via the defaults: list and then override specific sections such as the data module, model architecture, or training duration for a particular task. This separation allows you to define common infrastructure once and tweak only the relevant parts for each experiment.

Where does the configuration get converted into actual Python objects?

The conversion happens in fish_speech/train.py within the train() function. The code uses hydra.utils.instantiate (wrapped in helper functions from fish_speech/utils/instantiators.py) to transform configuration nodes into concrete instances of the data module, model, Lightning trainer, callbacks, and loggers. This instantiation approach allows the entire training pipeline to be defined declaratively in YAML while remaining fully flexible.

Can I use multiple config files together?

Yes, Hydra supports composing multiple configuration files. You can include additional configs by adding them to the defaults: list in your YAML file or by using the + prefix on the command line. For example, python -m fish_speech.train +base +my_custom loads both configurations and merges them, with later configs overriding earlier ones. This composability enables you to mix shared infrastructure with task-specific settings without duplication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}