Rastreamento de Experimentos

O acompanhamento de experimentos (experiment tracking) é a prática de registrar o que você executou, como executou e o que aconteceu — para que você possa comparar resultados de forma confiável, reproduzi-los mais tarde e compartilhá-los com colegas de equipe. Em fluxos de trabalho modernos de aprendizado de máquina (machine learning) e modelos de linguagem grandes (LLMs), “o experimento” raramente é apenas um modelo: ele inclui código, dados, configuração, ambiente, métricas, artefatos e contexto (por exemplo, o snapshot do conjunto de dados, o template de prompt, o tipo de GPU e o conjunto de avaliação).

No seu melhor, o acompanhamento de experimentos transforma o desenvolvimento ad-hoc de modelos em um processo disciplinado e auditável, alinhado ao método científico: declarar suposições, executar testes controlados, medir resultados e preservar evidências.

Por que o acompanhamento de experimentos importa

Comparação: iteração mais rápida e melhores decisões

O progresso em aprendizado de máquina costuma ser incremental e multidimensional: a acurácia melhora, mas a latência piora; uma nova técnica de aumento de dados ajuda uma fatia do conjunto de dados, mas prejudica outra. Sem registro consistente, fica difícil responder a perguntas básicas:

  • Qual execução produziu o modelo “melhor” atual e por quê?
  • A execução B é realmente melhor que a execução A, ou foi apenas uma semente aleatória sortuda?
  • Quais hiperparâmetros foram importantes?
  • Os dados mudaram entre os experimentos?

O acompanhamento de experimentos fornece um placar compartilhado: métricas ao longo do tempo, configurações de parâmetros e artefatos que você pode inspecionar e comparar.

Reprodutibilidade: de “funcionou na minha máquina” para reexecuções confiáveis

Reprodutibilidade significa conseguir recriar um resultado (ou pelo menos explicar por que ele difere) sabendo:

  • a versão exata do código
  • a versão do conjunto de dados e o pré-processamento
  • a configuração/hiperparâmetros
  • o ambiente de treinamento (bibliotecas, CUDA, hardware)
  • controle de aleatoriedade (sementes, configurações de determinismo)

Isso se conecta fortemente a Treinamento Reprodutível (Configs, Artefatos) e Versionamento (Dados, Código, Modelos).

Colaboração, governança e prontidão para produção

À medida que as equipes crescem, o acompanhamento de experimentos passa a fazer parte da higiene de MLOps:

  • Permite revisões (“mostre-me evidências de que este modelo é melhor”)
  • Dá suporte a auditoria e conformidade (linhagem e proveniência)
  • Facilita a transferência de trabalho entre pesquisadores e engenheiros
  • Faz a ponte com Registro de Modelos e CI/CD para Modelos

Conceitos centrais e modelo de dados

A maioria dos sistemas de acompanhamento organiza informações em torno de algumas entidades-chave.

Execução

Uma execução é uma execução única de um script de treinamento/avaliação (ou uma etapa de um pipeline). Execuções geralmente têm:

  • um ID de execução único
  • um horário de início/fim e status (concluída, falhou, interrompida)
  • links para parâmetros, métricas e artefatos
  • relacionamentos opcionais de pai/filho (execuções aninhadas, varreduras)

Experimento

Um experimento é um contêiner nomeado que agrupa execuções relacionadas (por exemplo, “resnet50-cifar10-aug-v2”). Algumas ferramentas também usam projetos, workspaces ou equipes.

Parâmetros (também conhecido como config, hiperparâmetros)

Parâmetros descrevem como a execução foi configurada:

  • escolhas de arquitetura do modelo
  • otimizador e agenda de taxa de aprendizado
  • tamanho do lote, número de épocas
  • flags de processamento de dados
  • templates de prompt e configurações de decodificação para LLMs

Boa prática: tratar parâmetros como imutáveis para uma execução. Se você alterá-los, inicie uma nova execução.

Métricas

Métricas são medições numéricas produzidas durante ou após a execução:

  • métricas escalares: acurácia, perda, BLEU, AUC
  • métricas de série temporal: perda vs. passo, vazão vs. tempo
  • métricas derivadas: latência p95, custo por 1k tokens, erro de calibração

Para comparações confiáveis, você precisa de definições consistentes (por exemplo, divisão exata do conjunto de dados e protocolo de avaliação). Isso se conecta a Avaliação em Produção quando métricas são medidas online.

Artefatos

Artefatos são arquivos produzidos ou consumidos por uma execução:

  • checkpoints do modelo e pesos finais
  • ativos de pré-processamento (tokenizadores, vocabulários)
  • gráficos, matrizes de confusão, curvas PR
  • relatórios de avaliação (JSON/HTML)
  • modelos exportados (ONNX, TorchScript)
  • amostras de predições, exemplos mal classificados
  • templates de prompt e contextos recuperados (para apps com LLM)

Artefatos são cruciais porque métricas sozinhas raramente contam a história completa.

Tags e metadados

Tags são rótulos pesquisáveis que adicionam contexto:

  • git_commit, branch, author
  • dataset_version, feature_set
  • gpu_type, num_gpus
  • purpose=baseline ou release_candidate=true

Metadados transformam uma lista de execuções em algo que você pode consultar como um conjunto de dados.

O que registrar para reprodutibilidade significativa

Um checklist prático “mínimo viável”:

Identidade do código

  • Hash do commit do Git (e se a árvore de trabalho estava suja)
  • URL do repositório
  • Ponto de entrada (nome do script, módulo, notebook)

Identidade dos dados

  • Nome do conjunto de dados e versão/snapshot
  • Identificadores de divisão treino/val/teste
  • Versão do pré-processamento (hash do pipeline de features, versão do tokenizador)

Se você não consegue versionar os dados brutos, registre no mínimo uma impressão digital (fingerprint) (contagens de linhas, hash do esquema, timestamp de geração de dados). Para abordagens sistemáticas, veja Versionamento (Dados, Código, Modelos).

Configuração

  • Config completa como um blob serializado (YAML/JSON)
  • Hiperparâmetros (também como campos individuais para filtragem)

Ambiente

  • Versão do Python, SO
  • versões de bibliotecas (pip freeze / conda env export)
  • versões de CUDA/cuDNN, modelo(s) de GPU
  • digest da imagem de contêiner (se aplicável)

Controles de aleatoriedade e determinismo

  • semente(s) global(is)
  • configurações de determinismo do framework (flags de determinismo do PyTorch/CUDA)
  • número de workers do dataloader
  • quaisquer operações não determinísticas das quais você depende

A reprodutibilidade perfeita pode ser difícil (treinamento distribuído e kernels de GPU podem introduzir não determinismo), mas registrar esses detalhes torna as diferenças explicáveis.

Resultados e evidências

  • métricas (finais + curvas)
  • amostras de saídas (inspeção qualitativa frequentemente é decisiva)
  • artefato do modelo + relatório de avaliação usado para justificar decisões

Exemplo prático: acompanhando uma execução do scikit-learn com MLflow

Abaixo está um exemplo mínimo que registra parâmetros, métricas e um artefato de modelo. Ele também registra o commit do Git e o shape dos dados de treinamento como proveniência simples.

import os
import subprocess
import mlflow
import mlflow.sklearn
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from sklearn.metrics import roc_auc_score
from sklearn.linear_model import LogisticRegression

def git_commit():
    try:
        return subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
    except Exception:
        return "unknown"

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

params = {
    "C": 0.5,
    "penalty": "l2",
    "solver": "liblinear",
    "random_state": 42,
}

mlflow.set_experiment("breast-cancer-logreg")

with mlflow.start_run(run_name="baseline-logreg"):
    mlflow.log_params(params)
    mlflow.set_tags({
        "git_commit": git_commit(),
        "dataset": "sklearn_breast_cancer",
        "train_rows": str(X_train.shape[0]),
        "test_rows": str(X_test.shape[0]),
    })

    model = LogisticRegression(**params, max_iter=200)
    model.fit(X_train, y_train)

    proba = model.predict_proba(X_test)[:, 1]
    auc = roc_auc_score(y_test, proba)
    mlflow.log_metric("test_auc", auc)

    # Log the trained model as an artifact (serializes the estimator)
    mlflow.sklearn.log_model(model, artifact_path="model")

Próximos passos comuns:

  • Executar uma varredura de hiperparâmetros (diferentes C, solver, pré-processamento) e comparar test_auc.
  • Registrar um gráfico da curva ROC como um artefato.
  • Registrar a matriz de confusão e a análise de limiar como JSON.

Exemplo prático: acompanhando uma execução de avaliação de LLM (prompts + métricas)

Em aplicações com LLMs, “acompanhamento de experimentos” frequentemente inclui versões de prompt, configurações de recuperação (retrieval) e métricas de custo/latência — áreas que se sobrepõem a PromptOps e Observabilidade para Apps de LLM.

Um padrão simples é registrar:

  • versão (ou hash) do template de prompt
  • nome do modelo e parâmetros de decodificação
  • versão do conjunto de dados de avaliação
  • métricas de qualidade (acurácia, pontuação por rubrica) além de latência e contagens de tokens
  • uma pequena amostra de entradas/saídas para revisão qualitativa

Pseudo-código (agnóstico de ferramenta):

import time
import json
from hashlib import sha256

def hash_text(s: str) -> str:
    return sha256(s.encode("utf-8")).hexdigest()[:12]

prompt_template = """You are a helpful assistant.
Answer the question concisely.

Question: {question}
"""

run = {
    "model": "gpt-4.1-mini",
    "temperature": 0.2,
    "max_tokens": 256,
    "prompt_hash": hash_text(prompt_template),
    "eval_set": "qa_eval_v3",
    "metrics": {},
    "samples": [],
}

questions = [
    {"id": "q1", "question": "What is experiment tracking in ML?"},
    {"id": "q2", "question": "Why do random seeds matter?"},
]

start = time.time()
correct = 0

for ex in questions:
    # llm_call(...) is your model invocation
    output = llm_call(
        model=run["model"],
        prompt=prompt_template.format(question=ex["question"]),
        temperature=run["temperature"],
        max_tokens=run["max_tokens"],
    )

    # judge(...) can be a rules-based check or an LLM-as-judge rubric
    is_correct = judge(ex, output)
    correct += int(is_correct)

    run["samples"].append({
        "id": ex["id"],
        "question": ex["question"],
        "output": output,
        "is_correct": is_correct,
    })

elapsed = time.time() - start
run["metrics"]["accuracy"] = correct / len(questions)
run["metrics"]["wall_time_sec"] = elapsed

# Persist the run record + samples as a JSON artifact in your tracking system
with open("llm_eval_run.json", "w") as f:
    json.dump(run, f, indent=2)

Mesmo que você mais tarde migre para uma plataforma completa, essa estrutura esclarece o que “reprodutibilidade” significa para experimentos com LLMs: entradas, prompt, configurações de modelo/decodificação e protocolo de avaliação.

Como o acompanhamento de experimentos se encaixa em sistemas de MLOps

O acompanhamento de experimentos fica no meio do ciclo de vida de ML:

  • Antes do treinamento: validação de dados e verificações de esquema (Validação de Dados)
  • Durante o treinamento: registrar métricas e artefatos continuamente
  • Após o treinamento: selecionar modelos candidatos, registrá-los (Registro de Modelos)
  • Implantação: monitorar comportamento e drift (Monitoramento)
  • Em produção: avaliar online e executar experimentos seguros (Avaliação em Produção)

Um modo comum de falha é tratar o acompanhamento como “apenas para pesquisa”. Na realidade, os mesmos metadados que ajudam a iterar na pesquisa tornam-se críticos ao depurar regressões em produção.

Panorama de ferramentas (o que os rastreadores normalmente oferecem)

A maioria dos rastreadores de experimentos maduros inclui:

Uma API/SDK de acompanhamento

Para registrar:

  • params/config
  • métricas (escalares e séries temporais)
  • artefatos (arquivos, diretórios)
  • tags e metadados

Um armazenamento de backend

  • banco de dados de metadados (execuções, params, métricas)
  • armazenamento de artefatos (armazenamento de objetos como S3/GCS/Azure Blob, ou local/NFS)
  • autenticação e controle de acesso (frequentemente necessário em equipes)

Uma interface (UI) para comparação

  • gráficos e curvas de métricas
  • tabelas de execuções com filtragem
  • diffs de parâmetros lado a lado
  • navegação de artefatos

Integrações

  • frameworks de treinamento (PyTorch Lightning, Hugging Face Trainer)
  • orquestradores (Airflow, Prefect, Kubeflow)
  • sistemas de CI e notebooks

Opções populares incluem MLflow, Weights & Biases, TensorBoard (especialmente para deep learning), Neptune, Comet, ClearML e ofertas cloud-native (por exemplo, SageMaker Experiments). A escolha da ferramenta geralmente depende de:

  • facilidade de adoção no seu stack
  • necessidades de armazenamento de artefatos e escala
  • requisitos de governança e segurança
  • se você também quer recursos de versionamento de conjunto de dados/modelo

Projetando experimentos para comparações confiáveis

Registrar é necessário, mas não suficiente. Comparações ainda podem ser enganosas se os experimentos não forem controlados.

Controle variáveis e isole mudanças

Quando possível, mude uma coisa por vez:

  • mesma divisão de dados
  • mesmo orçamento de treinamento (épocas/passos)
  • mesmo script de avaliação
  • mesma(s) semente(s)

Se múltiplas mudanças forem agrupadas, o rastreador deve refletir isso explicitamente em tags e notas (por exemplo, change=aug+lr_schedule).

Use *baselines* e testes repetidos

Como o treinamento é estocástico, uma única execução pode ser um outlier. Para decisões importantes:

  • executar múltiplas sementes
  • comparar média e variância (ou intervalos de confiança)
  • registrar métricas agregadas (média/desvio padrão entre sementes)

Acompanhe o orçamento de treinamento

Se uma execução treina por mais tempo ou usa mais computação, pode não ser uma comparação justa. Registre:

  • total de passos/épocas
  • tempo de relógio (wall-clock time)
  • horas de GPU (ou custo estimado) Isso se conecta a Custo/Desempenho.

Boas práticas de artefatos (o que armazenar e como)

Armazene “artefatos de decisão”

Para qualquer modelo que você possa colocar em produção, você deve conseguir recuperar:

  • o checkpoint exato do modelo
  • o relatório de avaliação usado para selecioná-lo
  • a configuração usada para o treinamento
  • o ponteiro/versão do conjunto de dados

Mantenha os artefatos imutáveis e endereçáveis por conteúdo quando possível

Imutabilidade reduz “drift silencioso”. Muitas equipes armazenam artefatos em armazenamento de objetos com:

  • caminhos baseados no ID da execução
  • hashes/digests nos metadados

Registre amostras pequenas e representativas

Para depuração e verificações qualitativas:

  • algumas predições com entradas e rótulos
  • exemplos de pior desempenho
  • exemplos por fatias (por exemplo, por idioma, categoria)

Atenção: amostras podem conter dados sensíveis — veja Privacidade em Logs.

Armadilhas comuns (e como evitá-las)

Armadilha: registrar pouco demais (apenas acurácia final)

Correção:

  • registrar configs, curvas, ambiente e artefatos
  • incluir versão dos dados e versão do script de avaliação

Armadilha: registrar demais (ruído inutilizável, alto custo)

Correção:

  • definir um esquema padrão e uma cadência de registro
  • fazer downsample de métricas de alta frequência
  • armazenar grandes checkpoints intermediários de forma seletiva (por exemplo, melhor-k ou a cada N épocas)

Armadilha: definições inconsistentes de métricas

Correção:

  • centralizar o código de avaliação
  • registrar a versão do cálculo de métricas (por exemplo, eval_commit)
  • armazenar o snapshot do conjunto de dados de avaliação

Armadilha: a “melhor execução” não é reproduzível

Correção:

  • capturar commit do Git e versões de dependências
  • registrar sementes e configurações de determinismo
  • registrar o artefato exato usado (hash do checkpoint)

Armadilha: vazamento de segredos ou dados sensíveis de usuários

Correção:

  • nunca registrar chaves de API, prompts brutos de usuários ou PII por padrão
  • adicionar redação e allowlists/denylists
  • alinhar com Privacidade em Logs

Escalando: varreduras, pipelines e treinamento distribuído

Varreduras de hiperparâmetros

A maioria das plataformas suporta varreduras onde um controlador lança muitas execuções. Boas práticas:

  • registrar a configuração da varredura como um artefato
  • marcar execuções com sweep_id e identificadores do espaço de busca
  • registrar falhas (uma execução com falha ainda é informativa)

Acompanhamento em nível de pipeline

Em pipelines de treinamento de nível de produção, cada etapa (preparação de dados, treinamento, avaliação) pode produzir sua própria execução, conectada via linhagem. Isso facilita responder:

  • “Qual etapa de pré-processamento produziu essas features?”
  • “Qual execução gerou o conjunto de dados usado por aquela execução de treinamento?”

Isso se conecta naturalmente a Registro de Modelos e CI/CD para Modelos.

Considerações sobre treinamento distribuído

Em treinamento multi-GPU/multi-nó:

  • garanta que apenas o rank-0 registre (ou agregue métricas antes de registrar)
  • registre o world size e configurações de paralelismo
  • tenha cuidado com sincronização de métricas (médias vs. somas)

Um esquema simples de acompanhamento que você pode padronizar

Muitas equipes se beneficiam de um pequeno padrão interno para cada execução:

  • Identidade
    • run_id, experiment_name, run_name
    • user, timestamp
  • Versões
    • git_commit, code_dirty
    • dataset_version
    • docker_image (ou artefato pip_freeze)
  • Config
    • artefato config.yaml + principais parâmetros pesquisáveis
  • Recursos
    • gpu_type, num_gpus, cpu, ram
  • Métricas
    • curvas de treinamento (loss, lr)
    • métricas de avaliação (primárias + secundárias)
    • métricas de latência/custo se relevante
  • Artefatos
    • checkpoint(s) do modelo
    • relatório de avaliação
    • amostras de predições

Padronização é o que transforma o acompanhamento de experimentos de “anotações pessoais” em memória organizacional.

Resumo

O acompanhamento de experimentos é a espinha dorsal do desenvolvimento disciplinado de ML: ele registra execuções, artefatos e métricas para que você possa comparar modelos, entender trade-offs e reproduzir resultados. Na prática, um bom acompanhamento captura não apenas números, mas contexto: versões de código e dados, ambiente, sementes, protocolo de avaliação e os artefatos que justificam decisões. À medida que sistemas de ML amadurecem, o acompanhamento de experimentos se conecta diretamente a práticas mais amplas de MLOps como Registro de Modelos, Monitoramento, Avaliação em Produção e Versionamento (Dados, Código, Modelos).