hydra-zen

Aperçu

hydra-zen est une couche Python-first au-dessus de Hydra qui élimine la majeure partie du boilerplate spécifique à Hydra et supprime les configs YAML manuscrites. Elle génère dynamiquement des configs de dataclass structurées à partir de fonctions, classes et signatures d'appel, puis les intègre dans les workflows Hydra. Utilisez cette skill quand vous voulez une configuration d'expérience typée, composable et reproductible sans maintenir de grandes structures YAML.

Quand utiliser cette skill

Cette skill doit être utilisée quand :

• Vous voulez les bénéfices de Hydra sans écrire manuellement des configs YAML
• Vous avez besoin d'une configuration d'expérience type-safe et pilotée par dataclass
• Vous voulez générer des configs directement à partir de signatures d'appel Python
• Vous voulez réduire le boilerplate Hydra dans les codebases ML/recherche
• Vous avez besoin d'APIs launch/store pythoniques pour les workflows configurables
• Vous construisez des scripts d'entraînement reproductibles avec une paramétrisation complexe

Capacités principales

1. Installation

pip install hydra-zen

2. builds() — Générer des configs à partir de callables

from hydra_zen import builds
from torch.optim import AdamW

AdamWConf = builds(AdamW, lr=1e-3, weight_decay=1e-2)

# AdamWConf is a dataclass config that Hydra can instantiate

Vous pouvez créer des configs pour :

• des classes
• des fonctions
• des callables
• des graphes d'objets imbriqués

3. instantiate() — Matérialiser à partir d'une config

from hydra_zen import builds, instantiate
from torch.optim import AdamW

AdamWConf = builds(AdamW, lr=1e-3, weight_decay=1e-2)
optimizer = instantiate(AdamWConf)

4. make_config() — Configs ad hoc typées

from hydra_zen import make_config

TrainConfig = make_config(
    learning_rate=1e-3,
    batch_size=64,
    max_epochs=20,
    model_name="resnet50",
)

cfg = TrainConfig()
print(cfg.learning_rate)

Utile quand vous avez juste besoin d'un objet config typé sans définir une dataclass complète manuellement.

5. store() — Enregistrer des configs avec Hydra

from hydra_zen import store, builds
from torch.optim import AdamW, SGD

store(group="optimizer")(
    builds(AdamW, lr=1e-3),
    name="adamw"
)

store(group="optimizer")(
    builds(SGD, lr=0.1, momentum=0.9),
    name="sgd"
)

Cela vous donne le comportement des groupes de config Hydra sans maintenir des fichiers YAML.

6. zen() — Wrapper pour les fonctions de tâche

from hydra_zen import zen

def train(model, optimizer, epochs: int = 10):
    print(model, optimizer, epochs)

train_task = zen(train)
train_task(model="resnet50", optimizer="adamw", epochs=20)

zen() aide à faire le pont entre les fonctions Python normales et l'exécution configurable par Hydra.

7. Exemple de bout en bout

from hydra_zen import builds, store, zen
from torch.optim import AdamW
from torchvision.models import resnet50

ModelConf = builds(resnet50, pretrained=False, num_classes=10)
OptimConf = builds(AdamW, lr=1e-3)

store(group="model", name="resnet50")(ModelConf)
store(group="optimizer", name="adamw")(OptimConf)

@zen
def train(model, optimizer, epochs=10):
    print("Model:", model)
    print("Optimizer:", optimizer)
    print("Epochs:", epochs)

if __name__ == "__main__":
    train.hydra_main(
        config_name=None,
        version_base="1.3",
    )

8. launch() — Exécutions Hydra programmatiques

from hydra_zen import builds, launch

def train(lr: float, batch_size: int):
    return {"lr": lr, "batch_size": batch_size}

Conf = builds(train, lr=1e-3, batch_size=64)
job = launch(Conf)
print(job.return_value)

Utile pour les workflows de notebook, les tests et l'orchestration programmatique des sweeps.

9. Composition de config imbriquée

from hydra_zen import builds, instantiate
from torch.optim import AdamW
from torchvision.models import resnet18

ModelConf = builds(resnet18, num_classes=100)
OptimConf = builds(AdamW, lr=1e-4)

ExperimentConf = builds(
    dict,
    model=ModelConf,
    optimizer=OptimConf,
    seed=42,
    hydra_convert="all",
)

exp = instantiate(ExperimentConf)
print(exp["seed"])

10. Motif de workflow ML

from hydra_zen import builds, store, zen
from pytorch_lightning import Trainer

TrainerConf = builds(
    Trainer,
    max_epochs=50,
    accelerator="auto",
    devices=1,
)

store(group="trainer", name="default")(TrainerConf)

@zen
def run_training(trainer, model, datamodule):
    trainer.fit(model, datamodule)

Cela fonctionne particulièrement bien pour :

• PyTorch Lightning
• les registries optimizer / scheduler
• les registries de familles de modèles
• les launchers d'expériences
• l'expérimentation pilotée par notebook

Motifs clés

1. Préférez builds() aux YAML manuscrits pour les projets Python-heavy.
2. Utilisez store() pour recréer les groupes de config Hydra avec moins de maintenance.
3. Utilisez zen() pour wrapper les fonctions de tâche normales dans des workflows pilotés par config.
4. Utilisez launch() dans les tests/notebooks quand Hydra CLI semble lourd.
5. hydra-zen brille quand votre source de vérité est le code Python, pas les fichiers de config.

Références

• Documentation hydra-zen
• Référence API
• Tutoriel PyTorch Lightning
• Repository