Para comparar versões de uma aplicação de IA, registre a seed, a temperatura e a configuração completa de cada execução, junto com os dados de entrada e a resposta original. A seed inicia um gerador de números pseudoaleatórios; a temperatura participa do controle da distribuição usada na geração, quando esse parâmetro é suportado e aplicado. Esses registros ajudam a investigar diferenças, mas não garantem respostas idênticas.
O objetivo de um experimento reproduzível é permitir que outra pessoa repita o procedimento e entenda as condições da comparação. Isso exige separar mudanças intencionais de variações do ambiente. Um relatório que guarda somente a resposta final ou o nome comercial do modelo deixa perguntas essenciais sem resposta quando chega a hora de aprovar uma nova versão.
Resumo rápido
- Congele os casos de teste e defina a mudança que será avaliada.
- Registre parâmetros enviados, valores omitidos e opções não suportadas.
- Preserve modelo, revisão, prompt, dados, ferramentas e ambiente.
- Repita casos com uma lista de seeds definida antes da análise.
- Compare critérios de negócio e variação entre execuções, além do texto literal.
Seed e temperatura são partes diferentes do registro
Usar a mesma seed procura controlar uma fonte de aleatoriedade dentro de condições específicas. Esse número não identifica o modelo, o prompt ou a infraestrutura. Também não significa que uma resposta produzida em um serviço possa ser recriada por outro. Ao comparar versões, trate a seed como um campo do experimento, acompanhado da indicação de onde e como ela foi aplicada.
A temperatura atua sobre probabilidades na geração, conforme o mecanismo implementado. A documentação de geração do Transformers descreve esse parâmetro junto de opções como amostragem, top-k e top-p. Portanto, anotar apenas uma temperatura deixa de fora decisões que também participam da seleção dos tokens, as unidades de texto processadas pelo modelo.
Se a dúvida é escolher parâmetros para uma tarefa, consulte o guia sobre temperatura e parâmetros de geração. Aqui, o foco é preservar evidências para comparar experimentos. Dois testes com o mesmo número no campo temperatura podem continuar incomparáveis quando usam modos de geração diferentes, configurações herdadas ou prompts montados de maneiras distintas.
Registre explicitamente três situações: valor enviado, valor omitido e parâmetro indisponível. Omitir uma opção não equivale necessariamente a enviar zero. Uma camada intermediária também pode substituir o valor recebido. Confira a configuração que efetivamente chegou ao mecanismo de inferência, quando essa informação estiver disponível, e marque como desconhecido aquilo que o serviço não informa.
Crie um manifesto para cada execução
Chame de manifesto o arquivo que descreve as condições do teste. Ele pode ser um JSON acompanhado de referências aos arquivos de entrada e saída. Dê a cada execução um identificador único, vinculado ao lote e ao caso avaliado. Preserve esse registro antes de resumir os resultados em planilhas, para que as evidências individuais continuem acessíveis.
| Grupo | O que registrar | Por que ajuda |
|---|---|---|
| Identidade | Lote, caso, execução, horário e revisão do código | Localiza o procedimento executado |
| Modelo | Identificador, revisão e provedor | Distingue variantes e atualizações |
| Geração | Seed, temperatura, amostragem, limites e demais opções | Expõe mudanças de configuração |
| Contexto | Prompt completo, documentos e ferramentas | Mostra o que chegou ao modelo |
| Ambiente | Bibliotecas, hardware e precisão quando conhecidos | Ajuda a investigar diferenças de execução |
| Resultado | Resposta original, erros, término e avaliação | Preserva a evidência da decisão |
O manifesto deve referenciar versões imutáveis dos arquivos. Um caminho para “base atual” não informa qual conteúdo estava disponível no teste. Use uma identificação de versão e uma soma de verificação quando fizer sentido, preservando o vínculo com o arquivo efetivamente usado. O mesmo vale para mensagens de sistema, exemplos incluídos no prompt e esquemas de saída estruturada.
Registre também o que aconteceu fora da geração. Uma busca documental pode retornar trechos diferentes; uma ferramenta pode consultar um cadastro alterado. Guarde as entradas e saídas dessas etapas, com acesso compatível com os dados tratados. Para testes isolados, prefira respostas de ferramentas previamente preparadas, indicando claramente que o experimento usou esse material controlado.
Congele a comparação antes de olhar os resultados
Comece escrevendo a pergunta do experimento. Por exemplo: “a nova instrução preserva a classificação correta quando o cliente nega uma solicitação?”. Nesse caso, o fator alterado é a versão do prompt. Mantenha as demais condições comparáveis e aplique os mesmos casos às duas versões. Se mudar também o modelo e a busca documental, a conclusão precisa reconhecer esse conjunto de mudanças.
Separe um teste de investigação de um teste de aceitação. Na investigação, você pode explorar seeds e configurações para entender uma falha. Na aceitação, defina antes os casos, critérios e regras para novas tentativas. Isso evita selecionar só as respostas que favorecem a versão preferida. Um caso difícil continua no relatório mesmo quando outras execuções parecem satisfatórias.
Escolha uma lista de seeds antes do teste e use-a de maneira pareada quando o mecanismo permitir: cada caso recebe as mesmas condições nas duas versões. O pareamento organiza a comparação, sem tornar as sequências internas equivalentes entre modelos diferentes. Inclua repetições para observar variação dentro da mesma versão. A quantidade deve refletir o risco e o orçamento do processo, sem um número universal obrigatório.
Congele também a forma de pontuar. Defina o que conta como resposta correta, recusa adequada, campo ausente ou erro crítico. Para classificadores, compare rótulos; para extração, compare campos; para texto livre, use uma rubrica que uma pessoa consiga aplicar. O material sobre avaliação de negação em português oferece um exemplo de recorte que merece casos específicos.
Controle o que está ao seu alcance e declare os limites
Em execução local, guarde versões de bibliotecas, sistema, drivers, dispositivo e precisão numérica. A nota de reprodutibilidade do PyTorch alerta que resultados completamente reproduzíveis não são garantidos entre versões, plataformas ou execuções em CPU e GPU. Ela apresenta controles para fontes de aleatoriedade e algoritmos, com limites próprios.
Não copie um bloco de configuração sem conferir as operações usadas pelo seu sistema. Ativar algoritmos determinísticos pode alterar o comportamento operacional e exigir tratamento de erros. Faça um teste de referência no ambiente que será preservado e documente as opções adotadas. Se o objetivo envolve desempenho, registre também que esse modo faz parte das condições medidas.
Para geração de imagens, o estado do gerador merece atenção. O guia de reprodutibilidade do Diffusers explica o uso de objetos geradores e as diferenças relacionadas a dispositivos. Em sua rotina de teste, defina quando o gerador será reinicializado. Reutilizar um estado já consumido pode não representar a mesma condição inicial, mesmo que o registro mencione a seed original.
Em APIs gerenciadas, parte da infraestrutura fica fora do seu controle. A referência de geração da API Gemini documenta seed e opções de configuração, mas é necessário conferir quais campos o modelo escolhido aplica. Grave o identificador retornado e informações de versão disponíveis, sem supor que um parâmetro aceito teve efeito. Veja também o catálogo de integrações com Google Gemini.
Quando uma informação não estiver disponível, registre essa limitação no relatório. A conclusão pode continuar útil: “a versão candidata passou nos casos sob as condições registradas”. Já uma promessa de repetir exatamente qualquer resposta futura seria maior que a evidência. Mantenha as respostas arquivadas para comparação histórica, inclusive quando o ambiente original não puder mais ser recriado.
Exemplo: uma empresa de suporte em Belo Horizonte
Considere uma empresa de suporte a lojas virtuais em Belo Horizonte que compara duas versões de um classificador de chamados. O caso é ilustrativo e não representa resultados medidos. A equipe quer saber se uma alteração no prompt distingue “quero cancelar” de “não quero cancelar”. O modelo, os exemplos e o conjunto de avaliação ficam identificados no manifesto.
Antes da execução, a responsável define as categorias esperadas, os erros considerados críticos e uma lista de seeds. Cada mensagem passa pelas duas versões sob as condições registradas. As respostas originais ficam guardadas, inclusive aquelas em formato inesperado. Uma falha de rede recebe seu próprio status; ela não entra silenciosamente como erro semântico do classificador nem desaparece do histórico.
Ao revisar o lote, a equipe agrupa as decisões por caso e versão. Se uma mensagem alterna de categoria entre repetições, o relatório mostra essa instabilidade. Se ambas as versões erram sempre o mesmo exemplo, o problema não é tratado como novidade da candidata. A análise verifica se o caso foi rotulado corretamente antes de atribuir a divergência ao modelo.
A aprovação depende dos critérios definidos previamente. Uma candidata que melhora o resultado agregado ainda pode exigir correção se introduzir um erro crítico de cancelamento. O relatório liga cada conclusão às execuções correspondentes e registra quem revisou os casos ambíguos. A equipe consegue repetir o procedimento em outra atualização, sem reconstruir a intenção do teste a partir de mensagens soltas.
Erros comuns
Chamar seed fixa de garantia de determinismo. Ela controla uma parte do processo em condições específicas. Compare a mesma versão consigo mesma antes de atribuir qualquer diferença à candidata. Se a linha de base já varia, essa variação precisa aparecer na interpretação, junto das mudanças de ambiente que não puderam ser controladas.
Registrar somente o parâmetro escolhido na interface. O aplicativo pode enviar outras opções, acrescentar mensagens ou aplicar configurações padrão. Capture o pedido final de forma protegida, sem credenciais, e vincule-o ao manifesto. Quando a interface não expuser o pedido, descreva essa restrição e evite declarar um controle que você não conseguiu observar.
Repetir até obter uma boa resposta. Tentativas adicionais podem servir à investigação, mas precisam ficar identificadas. Para aceitação, siga a regra definida antes do lote. Caso um teste seja invalidado por defeito na infraestrutura, preserve a justificativa e a execução substituta. Essa distinção impede que o relatório esconda variação por meio de seleção manual.
Confundir igualdade textual com qualidade. Duas respostas podem usar frases diferentes e cumprir os mesmos critérios. Também podem repetir exatamente um erro. Separe comparação literal, conformidade com o formato e avaliação do conteúdo. Para integrar esses registros à manutenção do sistema, consulte o guia de testes de regressão para agentes.
Perguntas frequentes
A mesma seed deve produzir a mesma frase em modelos diferentes?
Não há essa garantia. Modelos podem ter vocabulários, distribuições e implementações diferentes. A seed é útil como parte do protocolo de comparação, mas não funciona como uma tradução de escolhas internas entre modelos. Avalie o cumprimento da tarefa e preserve os identificadores completos de cada variante utilizada.
Temperatura zero elimina a necessidade de repetir o teste?
Não trate esse valor como garantia universal. Confira se a opção é suportada e qual modo de geração foi usado. Mesmo com condições de geração controladas, outras etapas podem variar. Repita a linha de base conforme o risco do experimento e registre as divergências encontradas, em vez de presumir que elas são impossíveis.
Posso comparar testes feitos em dias diferentes?
Sim, desde que as condições e limitações estejam documentadas. Uma atualização do serviço ou da base de consulta pode afetar a comparação. Quando possível, execute uma referência junto do novo lote. Se o ambiente mudou, apresente a comparação como histórica e explique quais fatores impedem isolar a alteração pretendida.
O que fazer quando a API não oferece seed?
Registre “não suportada” e controle os fatores disponíveis: entradas, configuração, versão identificável e avaliação. Trabalhe com repetições e mostre a variação observada. Não invente um campo de seed no seu relatório como se ele tivesse sido enviado ao provedor. O protocolo continua válido quando deixa seus limites explícitos.
Preciso guardar dados reais dos clientes?
Prefira casos sintéticos ou sanitizados que preservem o fenômeno avaliado. Se dados reais forem necessários, o acesso e a retenção devem seguir as regras aplicáveis ao seu processo. O manifesto pode referenciar um conjunto protegido, sem copiar seu conteúdo para relatórios amplamente compartilhados. Nunca inclua chaves de API nos registros.
