Guias

Segmentos

Uma taxa global pode se manter estável enquanto uma parte da suíte desmorona. Um segmento é uma parte declarada da suíte, medida por si só, para que o colapso fique visível. Os segmentos vêm com duas disciplinas, porque olhar para muitas partes de uma suíte é a forma como uma avaliação encontra ruído e o chama de descoberta.

Declarando segmentos

Um segmento é indicado em oloproof.yaml. O tipo mais comum lê uma chave do metadata de cada caso:

slices: [metadata.lang, metadata.topic]
min_slice_support: 30

{"id": "c000", "input": {"lang": "en", "topic": "billing", "hard": false, "n": 0}, "expected": {"label": "yes"}, "metadata": {"lang": "en", "topic": "billing"}}

Todos os tipos de segmento que o arquivo aceita:

Segmento	Agrupa casos por	Requer
metadata.<key>	o valor dessa chave no metadata do caso	a chave nos casos
relevant_position	onde a primeira passagem relevante foi recuperada: top_k, beyond_top_k ou not_retrieved	um sistema RAG e expected.relevant
context_truncated	se um orçamento de tokens retirou passagens do contexto	um sistema RAG com um token_budget
first_tool	a ferramenta que um agente chamou primeiro	um registro agent_trajectory/v1
repeated_action	se um agente repetiu uma chamada idêntica	um registro agent_trajectory/v1
route	os agentes que detiveram o controle, escritos como triage>billing	um registro agent_trajectory/v1 cujos passos indicam seus agentes
trajectory_length:4,8	número de passos, agrupado em faixas pelos limites que você declara	um registro agent_trajectory/v1
confidence:0.5	o score que um modelo deu à linha, agrupado em faixas pelos limites que você declara	um bloco predictive:

Um nome que o arquivo não reconhece é recusado antes de qualquer execução:

Configuration error: unknown slice 'lang'; declare metadata.<key>, relevant_position, context_truncated, first_tool, repeated_action, route, trajectory_length:<bounds> or confidence:<bounds>

Segmentos informam e nunca fazem gate

Uma execução exibe seus segmentos sob um título próprio. Um candidato que corrigiu o inglês e quebrou o francês:

│ metadata.lang=de       │ ok     │ 100.0%   │ [95.4%, 100.0%] │ 80 / 80 observed · 0 missing · 0 excluded · exploratory · support 80    │
│ metadata.lang=en       │ ok     │ 100.0%   │ [95.4%, 100.0%] │ 80 / 80 observed · 0 missing · 0 excluded · exploratory · support 80    │
│ metadata.lang=fr       │ ok     │ 32.5%    │ [22.4%, 43.9%]  │ 26 / 80 observed · 0 missing · 0 excluded · exploratory · support 80    │
│ metadata.topic=account │ ok     │ 88.3%    │ [81.2%, 93.5%]  │ 106 / 120 observed · 0 missing · 0 excluded · exploratory · support 120 │
│ metadata.topic=billing │ ok     │ 66.7%    │ [57.4%, 75.1%]  │ 80 / 120 observed · 0 missing · 0 excluded · exploratory · support 120  │

O título da tabela diz Slices (exploratory; never gated), e é exatamente isso. A taxa global dessa execução foi de 77.5%, e seu gate permitiu o lançamento, com o francês em um terço disso. Uma regra de lançamento sobre uma execução indica uma métrica global, e uma regra restrita a um segmento de uma única execução é recusada:

Configuration error: release rule 'fr-floor' targets slice/metadata.lang=fr; a run's slice results are exploratory, and only a comparison rule gates a slice, inside a family with a correction

Essa é a primeira disciplina. Uma suíte dividida de dez formas tem dez chances de mostrar uma diferença por acaso, e um gate que lesse segmentos bloquearia lançamentos por causa de ruído. Segmentos servem para descobrir onde olhar.

Quais segmentos se destacam

A execução também classifica seus segmentos em relação à taxa da própria execução e marca os que diferem, com o procedimento de Benjamini-Yekutieli, para que a proporção de marcações falsas continue controlada, por mais que os segmentos se sobreponham. A tabela de segmentos do terminal mostra cada um na coluna BY mark — marked, not marked, ou em branco para um segmento pequeno demais para ser testado — com o p-valor pelo qual foi classificado. Eles também são armazenados na execução e exportados no run.json do seu pacote:

jq -c '.run.slice_metrics[] | {scope, estimate, fdr_marked, fdr_p_value}' .oloproof/bundles/RUN_ID/run.json

{"scope":"slice/metadata.lang=de","estimate":1.0,"fdr_marked":true,"fdr_p_value":0.0001}
{"scope":"slice/metadata.lang=en","estimate":1.0,"fdr_marked":true,"fdr_p_value":0.0001}
{"scope":"slice/metadata.lang=fr","estimate":0.325,"fdr_marked":true,"fdr_p_value":0.0001}
{"scope":"slice/metadata.topic=account","estimate":0.8833333333333333,"fdr_marked":true,"fdr_p_value":0.0037003540039062493}
{"scope":"slice/metadata.topic=billing","estimate":0.6666666666666666,"fdr_marked":true,"fdr_p_value":0.008582189941406249}

Um segmento não marcado não fica demonstrado como igual à execução; ele apenas não foi sinalizado. Uma marcação direciona a atenção e não chega a nenhum gate.

Suporte

min_slice_support é o menor número de casos de que um segmento precisa para receber um intervalo. Abaixo dele, a estimativa é exibida e o intervalo é omitido. De um projeto que o definiu como 4:

│ metadata.topic=account          │ answer_correct  │ 100.0%   │                 │ 1 / 1 observed · 0 missing · 0 excluded · exploratory · support 1 │
│                                 │                 │          │                 │ < 4, no interval                                                  │

O padrão é 30. Uma suíte pequena que o reduz obtém intervalos em segmentos pequenos, e esses intervalos são largos o bastante para deixar isso claro por si mesmos.

Gate sobre um segmento, em uma comparação

Quando um segmento realmente não pode regredir, uma regra de comparação pode ser restrita a ele. O escopo é o nome do segmento com o prefixo slice/, e a regra declara o suporte de que precisa antes de qualquer evidência ser lida:

version: 1
rules:
  - {id: overall, metric: ok, kind: non_inferiority, margin: 0.05}
  - {id: fr-not-worse, metric: ok, kind: non_inferiority, margin: 0.05, scope: slice/metadata.lang=fr, min_support: 30}
  - {id: en-not-worse, metric: ok, kind: non_inferiority, margin: 0.05, scope: slice/metadata.lang=en, min_support: 30}
  - {id: de-not-worse, metric: ok, kind: non_inferiority, margin: 0.05, scope: slice/metadata.lang=de, min_support: 30}
families:
  - {id: languages, correction: holm, rules: [fr-not-worse, en-not-worse, de-not-worse]}

Escrito sem o prefixo, o escopo é recusado:

Configuration error: rule 'fr-not-worse' has unknown scope 'metadata.lang=fr'; a comparison rule decides on the global scope or on slice/<name>=<value>

Com ele, o candidato acima comparado com sua linha de base:

oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

Comparison sha256:cd2693b505e645919d397e8d7a87eaf0a841ab0c11c0b95484912363381b72e0 of run_01M3C46CYA163JSMSA5QZ6KAZA against run_01M3C46B3PSNP1ZTC8X05AG0GE · 240 paired cases
ok: -5.0 points [-15.2, +4.9] · 240 paired · 0 missing · 0 excluded
ok [slice/metadata.lang=de]: +8.8 points [-0.5, +21.5] · 80 paired · 0 missing · 0 excluded · exploratory · support 80
ok [slice/metadata.lang=en]: +18.8 points [+7.0, +34.4] · 80 paired · 0 missing · 0 excluded · exploratory · support 80
ok [slice/metadata.lang=fr]: -42.5 points [-60.3, -26.8] · 80 paired · 0 missing · 0 excluded · exploratory · support 80
ok [slice/metadata.topic=account]: +7.5 points [+0.9, +17.1] · 120 paired · 0 missing · 0 excluded · exploratory · support 120
ok [slice/metadata.topic=billing]: -17.5 points [-35.0, -0.1] · 120 paired · 0 missing · 0 excluded · exploratory · support 120
Decisions
  overall  ok  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
    no sample size would make this PASS: the difference itself (-5.0 points) is outside the margin, so more cases would move it toward FAIL
  fr-not-worse  ok  non-inferiority, margin 5.0 points  FAIL  upper_bound_below_margin
  en-not-worse  ok  non-inferiority, margin 5.0 points  PASS  lower_bound_above_margin
  de-not-worse  ok  non-inferiority, margin 5.0 points  PASS  lower_bound_above_margin
Family languages: Holm over 3 rules; adjusted levels 0.01667
Gate: BLOCK (exit 1)

Essa é a segunda disciplina. Uma regra restrita a um segmento só faz gate dentro de uma entrada families:, que lista as regras cujas falhas falsas são controladas em conjunto. holm é a correção: uma regra da família que falha é testada de novo em um nível mais rigoroso, dimensionado pelo número de regras que a família contém, para que três chances de falhar por acaso não somem três vezes o risco. Com um nível de confiança de 0.95 e três regras, a falha mais forte é testada de novo em 0.05 / 3, a seguinte em 0.05 / 2 e a última em 0.05. Só as falhas são testadas de novo: uma aprovação não é uma rejeição e não precisa de correção. Aqui uma regra falhou, foi testada de novo em 0.01667, e o francês continua falhando. A regra global não conseguiu decidir, e a recomendação abaixo dela diz que mais casos só a moveriam em direção a FAIL.

Uma regra de segmento fora de qualquer família é recusada:

Configuration error: slice rule 'fr-not-worse' belongs to no family; slice rules multiply the chances of a false FAIL, so they gate only inside a family with a correction

Próximos passos

Regras de comparação trata dos tipos de regra aos quais um escopo pode ser aplicado.
Avaliação de RAG, Agentes e ferramentas e

Classificadores e regressores usam os segmentos que não são de metadados.