Comparar versões

O que uma comparação mostra

Uma comparação coloca de 2 a 4 execuções do mesmo projeto lado a lado, normalmente execuções de versões (branches) diferentes do seu modelo. Ela compara o código, não os dados: a ideia é que as entradas continuem as mesmas e só o algoritmo mude.

Cada execução ganha uma coluna com:

• seu status, versão (branch) e commit abreviado;
• os números que você declarou como KPIs, com a variação em relação à base;
• seu tempo de execução e como ela foi executada: quando começou, quem ou o que a acionou, o ambiente e o comando;
• seu dashboard, desenhado ao lado dos outros.

Declare os resultados a comparar

Diga à Harumi quais valores do output/output.json da sua execução vale comparar adicionando entradas [[output.kpi]] ao harumi.toml. Sem elas a página ainda abre, mas mostra apenas os dashboards e avisa que nenhum KPI foi declarado. O template inicial já declara três:

[[output.kpi]]
key       = "objective"
label     = "Total cost"
direction = "min"
unit      = "USD"
primary   = true

[[output.kpi]]
key       = "solver_status"
label     = "Solver status"
direction = "none"

[[output.kpi]]
key       = "gap"
label     = "Optimality gap"
direction = "min"

objective, solver_status e gap são as chaves recomendadas para modelos de otimização: solvers com limite de tempo ou heurística nem sempre devolvem a mesma resposta, então o status e o gap indicam o quanto confiar no objetivo.

Cada execução lê os KPIs do harumi.toml do seu próprio commit, não do último commit da branch. Entre versões, eles são combinados pela key:

• Uma versão que não tem um KPI mostra — nele.
• Se duas versões discordam da direction de um KPI, ou de qual é o primary, a página mostra um aviso e usa a declaração da base.

Um harumi.toml que não pode ser lido (por exemplo, um erro de sintaxe) não bloqueia a comparação. A página avisa e mostra essa coluna sem KPIs.

Abra uma comparação

No dashboard de um projeto, clique em Comparar com… ao lado do seletor de execução. Isso abre Comparar versões com a última execução bem-sucedida da branch live como base e a execução que você estava vendo ao lado dela.

A página é uma fileira de colunas de altura total, uma por execução. Uma coluna sem execução diz Adicionar execução: clique em qualquer ponto dela para escolher uma execução da lista (dá para buscar por versão, commit ou id), e essa execução vira a próxima coluna. Adicionar na barra superior faz o mesmo. Dá para comparar até 4 execuções, e o x de uma coluna tira aquela execução.

Nada é salvo: as execuções escolhidas ficam na URL da página (/projects/<id>/compare?runs=…). Use Copiar link desta visualização para enviar a comparação a outros membros do projeto.

Leia o resultado

• Base. A primeira coluna. Toda variação é medida em relação a ela, em verde quando é melhor e em vermelho quando é pior. Use Mover para a esquerda e Mover para a direita para reordenar; a execução que ficar em primeiro passa a ser a base.
• Vencedora. A execução concluída com o melhor valor do KPI primary. Em caso de empate, vence a coluna mais à esquerda. Execuções que falharam, e execuções sem valor para o KPI principal, mantêm a coluna mas não podem vencer. Se nenhuma se qualifica, a página explica o motivo: por exemplo, que nenhum KPI principal foi declarado.
• Diferenças. Um ponto ao lado de Acionado por, Ambiente ou Comando indica que o valor difere da base, o que muitas vezes explica por que dois resultados diferem. Ative Só diferenças (exige duas execuções) para ocultar as linhas do dashboard que são iguais em todas as execuções.

As execuções usaram as mesmas entradas?

Uma comparação só é justa se todas as execuções leram os mesmos dados. Cada execução registra uma impressão digital das suas entradas quando começa: os arquivos em inputs/ e os CSVs buscados das suas fontes de dados. A página as compara e diz uma de três coisas:

• Todas as execuções usaram as mesmas entradas.
• As execuções não usaram as mesmas entradas, seguido dos arquivos que diferem. Os resultados podem divergir por causa dos dados, não só do código.
• Não é possível saber se as execuções usaram as mesmas entradas. Pelo menos uma execução não tem registro das suas entradas. Execuções anteriores a este recurso não têm esse registro, e ele não é preenchido depois.

Quando os resultados podem estar desatualizados

A página mostra um aviso, com um botão Atualizar comparação, quando o que você vê pode não ser o que essas versões entregam hoje:

• a versão de uma execução tem mudanças mais novas que a execução, ou deixou de existir;
• as execuções não usaram todas as mesmas entradas, ou pelo menos uma não tem registro das suas entradas.

Atualize uma comparação

Para comparar versões que ainda não foram executadas, atualizar uma comparação desatualizada, ou ter certeza de que leem os mesmos dados, clique em Atualizar comparação (na barra superior, ou no aviso acima). As versões das execuções que você está comparando já vêm marcadas, na ordem das colunas; mude se quiser. Dá para marcar de 2 a 4 versões, branches ou tags. A primeira marcada é a base. Uma tag é consultada uma vez, quando a comparação começa, então todas as execuções usam um commit fixo mesmo que a tag se mova nesse meio-tempo.

As versões rodam uma após a outra, não ao mesmo tempo:

1. A base busca suas entradas normalmente e guarda uma cópia delas.
2. Cada versão seguinte lê essa cópia em vez de buscar as suas, então todas as execuções recebem exatamente os mesmos dados.

A página mostra Executando 2/4 enquanto isso acontece, com um botão Cancelar. Cancelar interrompe a execução em andamento e as demais nunca começam; a página mostra as execuções que terminaram. Uma versão que falha ainda ganha sua coluna, e as outras continuam.

O que vale saber:

• Como as execuções acontecem uma de cada vez, uma nova comparação usa sua única execução ativa até terminar. Iniciar outra execução nesse meio-tempo é recusado, e se você conseguir iniciar uma no instante entre duas execuções da comparação, ela para ali.
• Quando uma execução comparada veio de uma tag, a página sinaliza se a tag se moveu ou foi excluída desde então, e o diálogo abre com essa tag já marcada.
• A comparação para, e diz o motivo, se os arquivos enviados forem grandes demais para serem compartilhados entre as execuções, se uma execução não puder começar (por exemplo, créditos insuficientes) ou se você perder o acesso ao projeto.
• Uma versão que consulta uma fonte de dados que a base não declara falha com uma mensagem explicando, já que não há cópia compartilhada para ela ler.

Pergunte ao Chat de IA da Harumi

Peça ao chat para comparar execuções. Ele responde com um cartão que lista cada versão com seu KPI principal e a vencedora, e Abrir comparação leva você a esta página. Se o projeto não tem KPIs declarados, o chat pode propô-los para você revisar.

Compartilhe uma visualização

Uma visualização é uma execução, um dashboard ou uma comparação. O endereço dela guarda tudo o que é preciso para abri-la de novo, então dá para enviá-la:

• Copiar link desta visualização (o ícone de link na barra superior) copia o link do que você está vendo. Envie para outros membros do projeto, que precisam de acesso para abri-lo.
• Em Compartilhar, ative Link para esta visualização e copie um link público: ele abre o visitante direto nessa execução, dashboard ou comparação. Um link cujas permissões não abrem a visualização avisa isso, e o botão de copiar fica desligado.
• Um visitante de um link público tem o mesmo botão. É o link pelo qual ele entrou, apontado para a visualização em que está.

Se um link público cita uma execução que ele não pode mostrar (o link não permite o histórico de execuções, ou a execução não existe mais), o visitante vê a última execução, com um aviso. Uma comparação deixa de fora as execuções que o link não pode mostrar.

Deixe um link público comparar execuções

Um link público de compartilhamento pode comparar execuções quando você ativa Comparações nas configurações do link (harumi share update <LINK_ID> --comparisons na CLI). Vem desligado e exige o Histórico de execuções, porque sem execuções anteriores não há o que comparar. Os visitantes podem escolher, tirar e reordenar as execuções que o link mostra (só as da versão live), mas não podem iniciar uma nova comparação.