Guias

Referência de resultados e execução

O que uma execução envia a um sistema HTTP e o que espera de volta, como cada caso entra no denominador de uma métrica, os estados de decisão e os códigos de motivo que os explicam, os códigos de saída, e quais dados ficam locais ou vão para um espaço de trabalho hospedado. Para as ideias por trás deles leia Conceitos; para os campos da política leia a Referência de configuração.

O contrato do sistema HTTP

Um sistema HTTP (system.http em oloproof.yaml) é chamado uma vez por caso, e uma vez por réplica.

Aspecto	Comportamento
Requisição	POST por padrão (GET e PUT são aceitos). O corpo é o valor input do caso em JSON.
Cabeçalhos e autenticação	Nenhum pode ser configurado. A requisição leva só os padrões do cliente HTTP. Um endpoint que precisa de uma chave deve ficar atrás de um sistema Python callable que a acrescente.
Resposta	Deve ser JSON. output_path seleciona a saída por um caminho com pontos, como result.answer; sem ele, a saída é o corpo inteiro. Um campo de output_path ausente é registrado como erro de execução para aquele caso.
Artefatos	Cada entrada de http.artifacts lê um caminho com pontos da resposta. Um campo declarado que falta em uma resposta é um erro de contrato, e a execução para com saída 2.
Timeout	http.timeout_s por requisição, 30 segundos por padrão.
Novas tentativas	Timeouts, falhas de conexão e HTTP 408, 429 e 5xx são tentados de novo, até quatro tentativas no total, com backoff exponencial com jitter que respeita Retry-After. Outras respostas 4xx não são tentadas de novo.
Depois da última tentativa	A execução do caso é registrada como erro e o caso conta como faltante (ou como falha, com on_execution_error: fail). A execução continua.
Concorrência	No máximo concurrency.system requisições em andamento, 8 por padrão.

A URL, o método, o caminho da saída e o mapeamento de artefatos entram na versão do sistema, mas o que o servidor faz não entra. Mude system.version sempre que o comportamento do servidor mudar; a Referência de configuração explica por quê.

Três vocabulários diferentes

Um resultado tem três tipos de estado, e um nunca substitui o outro.

Tipo	Valores	Responde
Estado de decisão	PASS, FAIL, INSUFFICIENT_EVIDENCE, MANUAL_REVIEW	O que a evidência diz sobre uma regra.
Estado de execução	Status da execução RUN_ERROR ou CANCELLED; completude da execução PARTIAL; execução do caso ERROR ou TIMEOUT	O que aconteceu com a execução ou com a chamada de um caso. Não é um resultado de qualidade.
Ação de lançamento	ALLOW, WARN, BLOCK	O que a sua política faz com cada decisão: estados em block_on bloqueiam, estados em warn_on alertam, os demais liberam.

Uma execução que termina normalmente é DECIDED, ou DECIDED_EARLY quando a parada antecipada a encerrou. Uma execução interrompida por Ctrl-C ou pelo cancelamento da tarefa é CANCELLED; uma cujo harness lançou uma exceção é RUN_ERROR. Nos dois casos a execução fica PARTIAL, mantém os casos que terminaram e deixa a próxima execução reaproveitar os registros em cache deles. Veja Erros.

Para um limiar mínimo T e um intervalo [L, U], uma regra é PASS quando L >= T, FAIL quando U < T, e INSUFFICIENT_EVIDENCE caso contrário. Um limiar máximo é simétrico. Antes de ler o intervalo, uma regra verifica se deve decidir: primeiro os motivos para MANUAL_REVIEW, depois os de INSUFFICIENT_EVIDENCE. O primeiro nível com um motivo decide, e lista todos os motivos que encontrou.

Códigos de motivo

Toda decisão traz um ou mais códigos de motivo.

MANUAL_REVIEW

Código	Significado
policy_requires_review	A regra define requires_manual_review: true.
unsupported_method	Não existe intervalo admitido para esta métrica nesta situação. Veja abaixo.
unsupported_dependence_structure	A suíte declara clusters (group_id) e nenhum método admitido os trata para esta métrica.
approximate_method_not_permitted	O único intervalo é aproximado, e a política não define allow_approximate_methods: true.
evaluator_retired	Um avaliador por trás da métrica foi aposentado.

INSUFFICIENT_EVIDENCE

Código	Significado
no_observations	Nenhum caso foi observado para esta métrica.
missingness_exceeds_policy	Faltam mais casos elegíveis do que o max_missing_fraction da regra permite.
missingness_unbounded	O método descarta os casos faltantes em vez de limitá-los, e a regra não declara max_missing_fraction.
evaluator_not_validated	Um juiz baseado em modelo por trás da métrica não foi validado contra rótulos humanos, e require_validated_evaluators está ativo (o padrão).
evaluator_recalibration_required	O juiz foi validado em um modelo servido de onde os veredictos desta execução não vieram.
interval_unavailable	A métrica não tem intervalo para ler.
insufficient_clusters	Menos clusters do que o min_clusters da política.
interval_monte_carlo_uncertain	O limiar cai dentro da incerteza de simulação de um limite por clusters.
interval_overlaps_threshold	O intervalo contém o limiar. Mais casos o estreitariam.
interval_unbounded	O intervalo não tem limite do lado que a regra lê.
missing_could_change_outcome	Uma regra observed_count: os casos faltantes poderiam levar as falhas além de max_failures.
interval_overlaps_zero, interval_overlaps_margin, interval_overlaps_margins	Uma comparação cujo intervalo da diferença atravessa o zero ou uma margem.
insufficient_support	Uma regra de comparação por segmento cujo segmento tem menos casos do que o seu min_support.
family_correction_withheld	Uma regra em uma entrada de families: antes da qual a correção de Holm parou.

PASS e FAIL

Código	Estado
lower_bound_meets_minimum, upper_bound_meets_maximum	PASS
upper_bound_below_minimum, lower_bound_above_maximum	FAIL
observed_failures_within_limit	PASS
observed_failures_exceed_limit	FAIL
difference_above_zero, lower_bound_above_margin, interval_within_margins	PASS (comparação)
difference_below_zero, upper_bound_below_margin, interval_outside_margins	FAIL (comparação)
cost_ceiling_exceeded	Indicado ao lado do estado de uma regra de custo cujo teto declarado foi excedido por uma execução registrada

Apenas espaço de trabalho hospedado

Um espaço de trabalho que decide por conta própria uma execução recebida por push pode reter uma decisão com ppi_not_verified (não verificou o intervalo em que a decisão se apoia), execution_not_verified (as saídas não vieram de um runner registrado) ou workspace_cannot_decide (não tem cópia da política, ou não conseguiu ler a evidência). Veja Gate.

Como cada caso entra no denominador

Toda métrica informa quatro contagens: n_total (casos na suíte), n_eligible, n_observed e n_missing, com n_eligible = n_observed + n_missing. Os casos fora de n_eligible são listados em exclusions com um motivo.

O que aconteceu com o caso	Conta como	No denominador
O avaliador retornou aprovação ou reprovação	observado, sucesso ou falha	sim
O avaliador se declarou não aplicável (por exemplo, nenhum valor esperado para comparar)	excluído, com o motivo	não
A chamada ao sistema deu erro ou timeout	faltante, ou falha com on_execution_error: fail	sim
O avaliador lançou uma exceção, ou a resposta de um juiz não pôde ser lida	faltante	sim
O caso nunca rodou porque a execução foi interrompida	faltante, e a execução é PARTIAL	sim

Um caso faltante é limitado, não descartado. Para uma taxa de aprovação, o limite inferior do intervalo trata cada caso faltante como falha e o limite superior como sucesso, então uma execução com muitos casos faltantes tem um intervalo largo que não pode passar em uma regra exigente; uma média limitada substitui da mesma forma os extremos da sua faixa declarada. Um método que não consegue limitar os casos faltantes (uma estatística de ranking, por exemplo) os descarta e registra a suposição, e uma regra sobre ele mostra missingness_unbounded até declarar max_missing_fraction.

Uma regra observed_count conta as falhas sobre a suíte executada e não lê nenhum intervalo. Ela só passa quando as falhas observadas mais todos os casos faltantes ainda cabem em max_failures.

Métricas sem intervalo admitido

Uma regra só decide sobre um intervalo cujo método foi admitido por auditoria. Onde não existe nenhum, a métrica ainda é calculada e mostrada, e uma regra sobre ela não toma emprestado um método não validado:

Situação	O que uma regra sobre ela mostra
Uma métrica de pontuação (média) sem faixa declarada, como um avaliador de pontuação personalizado sem score_range	MANUAL_REVIEW, unsupported_method
Uma métrica de média, quantil, ranking ou custo em uma suíte que declara group_id	MANUAL_REVIEW, unsupported_dependence_structure
Uma taxa de aprovação em uma suíte com clusters	um intervalo aproximado: MANUAL_REVIEW a menos que allow_approximate_methods: true, e então as verificações de clusters acima
Uma métrica de quantil ou ranking com replicates acima de 1	MANUAL_REVIEW, unsupported_method
Qualquer métrica em uma suíte com group_id e réplicas ao mesmo tempo	MANUAL_REVIEW, unsupported_dependence_structure
Uma comparação em uma suíte com clusters	MANUAL_REVIEW
Um segmento abaixo de min_slice_support	nenhum intervalo, mas segmentos nunca chegam ao gate
Métricas human_score, human_preference ou cost_per_accepted	recusadas quando o arquivo é lido, saída 2

Códigos de saída

oloproof gate, oloproof run com uma política e os outros comandos que decidem usam todos os mesmos códigos.

Código	Significado
0	Nada em que a política bloqueia: todas as regras passaram, ou as que não passaram estão fora de block_on.
1	Uma regra em block_on falhou.
2	A configuração ou a invocação estava errada, ou um sistema quebrou o seu contrato; nada foi decidido.
3	Uma regra em block_on mostrou INSUFFICIENT_EVIDENCE.
4	Uma regra em block_on mostrou MANUAL_REVIEW.
5	A execução não terminou e block_on_partial_run está ativo (o padrão).

Quando vários se aplicam, o código informado é o primeiro entre 1, 5, 4, 3. Um estado deixado fora de block_on não pode mudar o código de saída: com block_on: [FAIL] e warn_on: [INSUFFICIENT_EVIDENCE], uma regra indecisa alerta e o gate sai com 0. A saída 0 significa, portanto, apenas que nada em que a sua política bloqueia ocorreu, não que todas as regras passaram. Veja Gate.

Onde o trabalho roda e para onde vão os dados

Local, o padrão

oloproof run, oloproof gate e o SDK rodam na sua máquina. Todo registro (casos, saídas, artefatos, julgamentos, métricas e decisões) é gravado em .oloproof/store.sqlite ao lado de oloproof.yaml, ou em OLOPROOF_HOME quando definida. Nada é enviado ao Oloproof. O único tráfego de rede é o que a sua configuração causa: chamadas à URL do seu sistema HTTP, e chamadas que um juiz baseado em modelo ou um classificador baseado em modelo faz ao seu provedor, que recebe o conteúdo dos casos que julga e cobra você por isso.

Push para um espaço de trabalho hospedado

oloproof push envia a evidência de uma execução ao espaço de trabalho que você conectou com oloproof login. Por padrão envia métricas, intervalos, decisões e segmentos agregados, e a identidade, o status, os tempos e o uso de cada registro, mas não o seu conteúdo. O conteúdo bruto é ocultado campo a campo antes que qualquer coisa saia da máquina, e um registro ocultado diz quais categorias foram retidas. Uma categoria só vai quando egress: em oloproof.yaml a lista:

Categoria	O que cobre
raw_inputs	Entradas dos cenários, valores esperados e metadados dos casos: as linhas do dataset
raw_outputs	O que o sistema em teste retornou para cada caso
judge_rationales	O texto que um juiz escreveu explicando um veredicto, que cita a saída
artifacts	Contexto de recuperação, citações e trajetórias registrados durante uma execução
error_detail	Mensagens e detalhes de exceções, que muitas vezes trazem a entrada literalmente
system_config	A configuração declarada do sistema em teste e dos seus avaliadores
label_notes	A nota que uma pessoa escreveu ao lado de um rótulo, que muitas vezes cita a saída
span_names	Nomes de traces, spans, ferramentas e agentes que uma instrumentação registrou

Os digests dos registros não são recalculados depois da ocultação, então um registro hospedado ainda nomeia a evidência original, que fica na sua máquina. Ocultação não é criptografia, e uma métrica sobre um segmento muito pequeno ainda pode identificar os casos por trás dela.

Quando revisores rotulam casos na fila de revisão hospedada, o navegador deles busca o conteúdo dos casos em oloproof collect rodando do seu lado; ele não passa pelo espaço de trabalho. As chaves de provedor que um espaço de trabalho usa são armazenadas com oloproof credentials set, e oloproof credentials list mostra os nomes delas, nunca os valores. Um job gerenciado roda em um worker operado pelo Oloproof, que não executa o seu código Python; oloproof job informa o resultado e sai conforme o seu gate.

Em um espaço de trabalho hospedado o engine nunca reaproveita execuções, julgamentos ou análises em cache, porque um push pode gravar esses caches; ele os recalcula.