Hydra Stranger Things

Configurando experiments com Hydra: guia prático

Hydra é uma biblioteca da Meta para gerenciar configuração de aplicações em Python. O foco é permitir que você itere rápido em experiments sem acabar com vinte arquivos .json espalhados pelo projeto. Se você já tentou rodar um script que depende de três variáveis de ambiente e um arquivo de config em outro diretório, sabe o que eu estou falando. O que a maioria das pessoas não entende no começo é que o Hydra não é só um parser de YAML bonitinho. Ele muda a forma como você versiona configs, roda grid search e organiza outputs. A parte mais útil, na prática, é o compose API e o sistema de override via linha de comando.

hydra stranger things: um exemplo real

Eu estava configurando um pipeline de treino pra um projeto interno que chamamos de Stranger Things. Não tem nada a ver com a série. Era um code name evenós que ninguém lembra mais. O problema era que cada membro da equipe precisava de hyperparâmetros diferentes, e a branch de configuração cresceu descontroladamente em duas semanas. A solução foi migrar pro Hydra com uma estrutura de config hierárquica. Aqui tá como ficou a árvore de diretórios depois:

config/
config.yaml
model/
base.yaml
transformer.yaml
lstm.yaml
training/
default.yaml
fast_debug.yaml
db/
sqlite.yaml
postgres.yaml Chamei de hydra stranger things porque virou o nome interno do setup. A estrutura em si é o padrão recomendado pela documentação, mas a forma como você organiza os grupos faz toda diferença quando o time cresce.

Instalação e setup inicial

A instalação é simples. pip install hydra-core. Versão estável atual é 1.3.x. Evite usar a versão 1.1 se possível, porque o sistema de config groups mudou significativamente entre a 1.1 e a 1.2, e a documentação ainda tem referências misturadas. Depois de instalado, você precisa configurar o Hydra no seu script principal. Algo assim:

@hydra.main(config_path="config", config_name="config", version_base=None) o version_base=None é importante. Sem ele, o Hydra vai dar warning em tudo que você fazer, e esses warnings acumulam até virar ruído impossivel de filtrar.

O arquivo config.yaml raiz é o ponto de partida. Ele define os valores padrão que todos os overrides herdam. Recomendo manter o máximo possível dele vazio e delegar pra sub-configs. Um config.yaml raiz com cinquenta linhas já é sinal de que a estrutura tá errada.

Como funciona na prática

O compose API é o coração do Hydra. Ele resolve a hierarquia de configs antes do seu código rodar. Quando você sobreescreve um parâmetro via linha de comando, o Hydra combina automaticamente com os valores padrão: python main.py model=transformer training.lr=0.001 +db=postgres

O prefixo + adiciona chaves que não existem no config base. Isso evita o erro clássico de sobrescrever um campo que não foi definido em lugar nenhum, algo que acontece frequentemente quando se trabalha com múltiplos devs modificando configs simultaneamente. Uma coisa que a documentação não destaca bastante: o Hydra gera um timestamp automático em outputs/. Cada execução cria um subdiretório com data e hora, e lá dentro fica o log completo, o arquivo de config resolvido e qualquer output do seu programa. Isso resolve metade dos problemas de reproducibilidade sem você precisar escrever uma linha extra de código.

O problema que eu encontrei e o workaround

No projeto Stranger Things, tivemos um problema específico: precisávamos carregar um modelo pretrained que tinha seus próprios hyperparâmetros embutidos em pickle. O Hydra tentava sobrescrever esses parâmetros quando rodávamos grid search, e o modelo simplesmente falhava porque os shapes não batiam mais. A solução foi criar um grupo de config chamado model_weights com merge_children=false, que diz pro Hydra pra não mesclar recursiveamente com configs pai. Assim, os pesos carregados do pickle permanecem intactos enquanto o resto da config continua sendo sobrescrita normalmente. Ficou assim:

@hydra.core.global_hydra.GlobalHydra.instance().clear() hydra.initialize(config_path="config", version_base=None)

cfg = hydra.compose(config_name="config", overrides=["+model_weights=/caminho/do/pickle"]) Isso provavelmente não é o uso pretendido do Hydra, mas funciona. Se você tiver um problema semelhante com configs aninhados que precisam permanecer imutáveis, o merge_children=false é o caminho.

Pitfalls que ninguém comenta

O primeiro é o cache de imports. O Hydra faz import dinâmico de módulos Python baseados nos valores de config. Se você mudar um valor num config e o módulo correspondente não foi reloadado, o Hydra continua usando a versão antiga. Reiniciar o processo sempre resolve, mas em desenvolvimento iterativo isso vira rotina diária. O segundo é o limite de profundidade de sobrescrita. Overrides via linha de comando suportam talvez cinco níveis de profundidade antes de ficar ilegível. Se você precisa de mais camadas que isso, provavelmente a estrutura de config tá errada e deveria ser refatorada em grupos separados.

O terceiro, e mais importante: Hydra não é um sistema de secrets. Se você colocar chaves de API nos seus arquivos YAML, elas vão pros logs automaticamente porque o Hydra imprime a config resolvida em cada execução. Use a variável de ambiente HYDRA_FULL_ERROR=1 só quando estiver debugando, porque ela imprime stack trace completo com a config, o que pode vazar informações sensíveis em CI/CD.

Quando não usar Hydra

Se o seu projeto tem menos de três arquivos de configuração, o Hydra adiciona complexidade desnecessária. Um simple .yaml ou .env resolve mais rápido. Se você precisa de configurações que mudam durante a execução do programa (runtime config updates), o Hydra não foi feito pra isso. Ele resolve a config uma vez no início e mantém imutável. Para cenários dinâmicos, considere usar omegaconf com atualização manual ou simplesmente plain dicts.

Para projetos que já usam outra ferramente de orquestração como Airflow ou Prefect, integrar Hydra pode criar conflitos de namespace. Teste antes de adotar em larga escala.

Download e recursos

O Hydra tá no PyPI e no GitHub. Repositório oficial é facebookresearch/hydra. A documentação principal é hydra.cc. Para o caso específico do projeto Stranger Things, não temos um repositório público porque era interno, mas a estrutura de config que descrevi aqui segue o padrão documentado. Se quiser ver um exemplo completo funcionando, o repositório do Hydra tem vários examples em examples/configure_hydra/. O tutorial_basic e o todo_app são os mais didáticos. Levam cerca de 20 minutos pra rodar em uma máquina padrão.