Reencontrar a evidência por trás de cada resultado.

Distinguir campanha, configuração e execução

Uma campanha carrega uma pergunta, por exemplo comparar uma referência a uma adaptação. Uma configuração descreve as escolhas técnicas. Um run é uma tentativa de execução dessa configuração, com uma seed, um início, um fim e um status. Duas tentativas idênticas mantêm, portanto, dois identificadores, mesmo que a segunda substitua um ensaio interrompido.

Adicione um identificador de avaliação quando o mesmo artefato é avaliado em vários conjuntos ou com uma nova métrica. Isso evita confundir um novo modelo com uma nova leitura do modelo existente. Ligue a tentativa de retomada à que a precedeu e ao checkpoint carregado.

O MLflow também organiza o acompanhamento em torno de runs, parâmetros, métricas e artefatos. Essa distinção é útil mesmo em um dossiê de arquivos simples. Você pode aplicá-la com sua ferramenta habitual; nenhuma plataforma de acompanhamento específica é necessária para começar.

Fontes técnicas: MLflow — runs, parâmetros, métricas e artefatos

Escrever o manifesto realmente executado

Mantenha os parâmetros resolvidos após a aplicação dos valores padrão e dos argumentos de lançamento. O arquivo de configuração original pode omitir um batch padrão ou uma opção alterada em tempo de execução. Registre o que foi efetivamente usado, com uma cópia do código ou uma revisão imutável e o estado das modificações não salvas.

O manifesto também liga versões do modelo e do tokenizer, ambiente de software, GPU efetivamente usada, precisão, dados, seeds e definição das métricas. Ele descreve o ensaio, sem se tornar um tutorial de instalação. Anote as unidades: segundos, bytes, tokens, pontos ou proporção de 0 a 1 conforme a medida.

Na inicialização, o status é em andamento; ao final, ele se torna concluído, falhou ou interrompido conforme o que você constatou. Não complete depois uma versão esquecida pela que está instalada no momento. Marque a informação desconhecida e limite a conclusão que depende dela.

Identificar os dados além de um nome de pasta

Um caminho como dados/final não designa uma versão estável. Mantenha o inventário dos arquivos ou dos exemplos, os splits e o procedimento de transformação. Se você corrigir labels ou filtrar linhas, crie uma nova versão e mantenha a relação com a anterior. O score antigo deve continuar apontando para seus dados antigos.

O Hugging Face Datasets associa fingerprints ao estado de um conjunto e às suas transformações para gerenciar o cache. Esse mecanismo é útil, mas é preciso manter também a origem dos dados e o pré-processamento. Uma transformação não hasheável pode, em particular, levar a um fingerprint aleatório: o identificador de cache não substitui por si só o seu dossiê de proveniência.

Para os artefatos congelados, adicione tamanho e hash do arquivo. Um digest SHA-256 calculado antes e depois de uma cópia permite verificar que os bytes correspondem à referência mantida. Ele não prova nem a qualidade dos labels, nem os direitos de uso, nem a ausência de vazamento entre os splits.

Fontes técnicas: Hugging Face Datasets — fingerprints e transformações · Python 3.14 — hashes de arquivos com hashlib

Ligar métricas, previsões e artefatos

Uma linha de métrica deve identificar o run, o artefato avaliado, o conjunto de avaliação, a versão da métrica e seu escopo. Especifique se o valor se refere a um checkpoint intermediário, ao modelo final ou a um subgrupo. Uma curva não basta se não se sabe mais qual arquivo corresponde ao ponto escolhido.

Guarde as previsões com seu identificador de entrada, seu status e as informações necessárias para a avaliação. As referências esperadas podem ficar em um arquivo separado versionado. Para uma saída estruturada, diferencie resultado bruto, resultado parseado e veredito: corrigir o parsing não deve sobrescrever a saída inicial.

O MLflow permite vincular métricas a modelos e a dados. Com arquivos, aplique o mesmo princípio por meio de identificadores explícitos. Mantenha um inventário legível dos artefatos: pesos ou adaptador, parâmetros de geração, saídas, relatório de avaliação e nota de decisão. Não presuma que uma captura de tela substitua esses arquivos.

Fontes técnicas: MLflow — vincular métricas, modelos e conjuntos de dados

Exemplo: seis runs e uma duplicata que esconde uma falta

Consideremos um exemplo de classificação com duas configurações e três seeds. Ele produz seis runs previstos. Cada um deve prever os mesmos 300 identificadores de avaliação: a pasta completa espera, portanto, 6 × 300 = 1.800 pares únicos (run_id, input_id). Esse cálculo descreve um inventário esperado, não uma experiência realmente executada.

Suponhamos que um arquivo contenha 300 linhas, mas que o identificador doc-042 apareça duas vezes e doc-117 esteja ausente. O total de linhas parece correto; no entanto, há apenas 299 identificadores únicos. Esse run falha na verificação de cobertura até que a anomalia seja explicada e corrigida.

Se cada run for então avaliado no corpus completo e em seu subgrupo de textos longos, você obtém doze linhas de métrica para uma dada métrica. Isso continua sendo seis runs, não doze treinamentos independentes. A chave de avaliação deve incluir o escopo para preservar essa distinção.

Fechar o dossiê com uma decisão legível

Antes de declarar um run concluído, verifique a presença e a abertura dos arquivos, a correspondência dos identificadores, as métricas recalculáveis e o status de cada erro. Uma tentativa tecnicamente concluída pode continuar rejeitada por qualidade insuficiente. Mantenha esses dois estados separados.

A nota de decisão reúne a questão, as variantes comparadas, o critério anunciado, os resultados retidos e os motivos de exclusão. Cite os run_id e os caminhos dos artefatos em vez de "o último modelo". Acrescente as limitações: poucas repetições, subgrupo insuficiente, versão não encontrada ou comparação que se tornou impossível.

Uma correção posterior deve deixar um rastro: nova avaliação, novo relatório e motivo da mudança. Conserve a conclusão antiga como versão histórica identificada, sem deixá-la aparecer como decisão atual. Por fim, verifique se a cópia exportada abre a partir de sua pasta de destino.

Evitar a coleta inútil e as promessas de reprodução

Colete os campos necessários à prova, não todas as variáveis de ambiente nem o histórico do terminal. Uma configuração ou uma URL pode conter um token; prepare uma versão compartilhável sem segredos e mantenha os dados que devem permanecer privados em seu local autorizado. Os identificadores técnicos de teste não precisam incluir um nome de pessoa.

Um dossiê completo melhora a possibilidade de refazer e compreender uma experiência. Ele não garante uma igualdade numérica entre plataformas ou versões: o PyTorch documenta esses limites de reprodutibilidade. Diferencie recuperar o protocolo, recarregar o artefato e reproduzir exatamente os números.

O caderno IteraGPU pode guardar seus objetivos, parâmetros e decisões, com as referências úteis. Ele não inicia os runs nem coleta automaticamente os arquivos ou a telemetria. Use-o como índice do seu raciocínio e mantenha o dossiê de artefatos em seus próprios backups.

Fontes técnicas: PyTorch 2.14 — limites de reprodutibilidade entre ambientes

Perguntas práticas