# How to Configure the Hydra Training Configuration in Fish-Speech

> Learn to configure the Hydra training configuration in Fish-Speech using modular YAML files. Easily override parameters via command line or custom experiments without touching Python code.

- Repository: [Fish Audio/fish-speech](https://github.com/fishaudio/fish-speech)
- Tags: how-to-guide
- Published: 2026-03-12

---

**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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/fish_speech/utils/instantiators.py) |

Base and experiment configs reside in `fish_speech/configs/`, while instantiators live in [`fish_speech/utils/instantiators.py`](https://github.com/fishaudio/fish-speech/blob/main/fish_speech/utils/instantiators.py).

## How Hydra Loads Configurations

The entry script [`fish_speech/train.py`](https://github.com/fishaudio/fish-speech/blob/main/fish_speech/train.py) initializes the configuration system using the `@hydra.main` decorator:

```python
@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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/my_experiment.yaml).

### Step 2: Inherit the Base Configuration

Start your file with the `defaults` list to load [`base.yaml`](https://github.com/fishaudio/fish-speech/blob/main/base.yaml) before applying your overrides:

```yaml

# 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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/base.yaml) contains universal defaults—directory paths, standard callbacks, and logger configurations—that apply to all training runs. Experiment configs like [`text2semantic_finetune.yaml`](https://github.com/fishaudio/fish-speech/blob/main/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`](https://github.com/fishaudio/fish-speech/blob/main/fish_speech/train.py) within the `train()` function. The code uses `hydra.utils.instantiate` (wrapped in helper functions from [`fish_speech/utils/instantiators.py`](https://github.com/fishaudio/fish-speech/blob/main/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.