Julgue respostas e detecte regressões
Cerca de 36 minutos min de leitura, com 6 exemplos em 8 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.15. Leia o original
Nesta página
- Avalie uma execução além da acurácia
- Julgue apenas o que não pode ser comparado
- Calibrate the judge against reference labels
- Repita as execuções para ver a variância
- Bloqueie uma mudança no CI
- Detecte uma mudança de esquema antes que os usuários a percebam
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você será capaz de pontuar uma execução do agente em várias medidas ao mesmo tempo, usar um modelo como juiz apenas onde os resultados não podem ser comparados diretamente, calibrar esse juiz com rótulos de referência que qualquer pessoa pode recalcular, verificar o quanto uma pontuação varia de uma execução para outra e barrar, no CI, com base em execuções gravadas, uma mudança em prompts, contexto ou métricas que piore os resultados.
Quase todo capítulo alterou o agente da loja. O capítulo 4 acrescentou contexto ao prompt, e o capítulo 6 passou o agente para as métricas da camada semântica. O capítulo 8 então reescreveu o prompt para que ele recuse com um motivo. Cada mudança foi pontuada na divisão de desenvolvimento das perguntas de referência, as 48 perguntas da loja com respostas verificadas, com uma execução por pergunta, o que pode mostrar uma mudança grande, mas não uma pequena. O novo prompt do capítulo 8 corrigiu uma pergunta de desenvolvimento e quebrou outra, gq-008, receita total em 2025, e o capítulo 8 só pôde afirmar que uma única inversão desse tipo "pode ser acaso".
Este capítulo constrói as medidas que resolvem perguntas como essa. Ele relata uma execução com base em mais do que a acurácia, acompanhada de um intervalo que indica o quanto o número é confiável. Acrescenta um juiz, uma chamada de modelo que avalia o que a comparação com a referência não consegue avaliar, e mede o juiz antes de confiar nele. Executa as perguntas cinco vezes para observar a variância e transforma tudo isso em uma barreira de qualidade (gate) que uma tarefa de CI pode executar a cada mudança, offline, a partir de gravações.
Avalie uma execução além da acurácia
Um único valor de acurácia responde a uma pergunta, com que frequência o agente acertou, e oculta três outras que importam tanto: o que ele fez quando errou, o que cada resposta custou e quanto esse valor se moveria em outra amostra de perguntas. Um agente que dá um número errado e outro que recusa perdem ambos um ponto de acurácia, mas só um deles põe um número errado em uma apresentação. Por isso, um scorecard informa separadamente os números errados, as recusas e as falhas, as medidas de recusa do capítulo 8, e o custo em chamadas ao modelo e tokens de prompt, ao lado da acurácia.
A figura também precisa de um intervalo. Em um conjunto do tamanho de uma divisão golden, cada pergunta vale vários pontos, e o intervalo que a maioria das pessoas aprende primeiro, o intervalo de Wald, se comporta mal em conjuntos pequenos. Brown, Cai e DasGupta recomendam "o intervalo de Wilson ou o intervalo de Jeffreys com priori de cauda igual para n pequeno" (Brown et al.). Em palavras, o intervalo de Wilson inverte o teste de uma proporção: ele contém todas as acurácias verdadeiras que a acurácia observada não rejeitaria no nível escolhido, e por isso nunca fica abaixo de 0 ou acima de 1. Para k acertos em n, com p = k / n e z = 1.96 para cerca de 95%:
centre = (p + z² / 2n) / (1 + z² / n)
half = z × √( p(1 − p) / n + z² / 4n² ) / (1 + z² / n)
interval = centre − half to centre + half
wilson() em lib/regressions.py calcula esse intervalo em poucas linhas. O statsmodels implementa o mesmo intervalo como proportion_confint(method="wilson") (statsmodels); as versões fixadas do livro não incluem o statsmodels, então o exemplo não o chama. replay() executa um dos agentes do livro sobre perguntas golden de suas gravações, e Scorecard pontua as execuções. O scorecard a seguir pontua 3 agentes nas 21 perguntas de resposta e de recusa de cada divisão: o SQL apenas com o esquema do capítulo 3, o agente que usa métricas primeiro do capítulo 6 e o agente que recusa do capítulo 8. As perguntas proibidas ficam de fora, porque o capítulo 9 decide sobre elas abaixo do modelo.
A divisão de teste fica reservada, e o livro a pontua apenas para um número que ele informa. Os capítulos 3 e 6 registraram seus agentes no teste uma única vez. Este capítulo registrou o agente que recusa no teste uma única vez, na gravação decline-runs-test, com o prompt do capítulo 8 inalterado, e não mudou nada depois disso. Estes são os números finais de teste do livro para os seus agentes.
1"""Score the book's agents on more than accuracy, on dev to compare them and on the held-out test split once.2The chapter's points rest on the dev and test lines for correct answers, wrong numbers and decline recall,3and on the fixed and broken lines for the declining prompt."""4from lib.golden import load_golden5from lib.regressions import Scorecard, replay6from lib.semantic import load7from lib.warehouse import connect89con, layer = connect(), load()10# Answer and decline questions; forbidden questions are decided below the model, by chapter 9's policies.11questions = [q for q in load_golden() if q.kind in ("answer", "decline")]12for split in ("dev", "test"):13 in_split = [q for q in questions if q.split == split]14 print(f"{split} questions: {len(in_split)}")15 runs = {agent: replay(con, layer, agent, in_split) for agent in ("schema-only", "metrics-first", "declining")}16 for agent, agent_runs in runs.items():17 print("\n".join(Scorecard(agent_runs).lines(f"{split} {agent}")))18 for label, was, now in (("fixed", False, True), ("broken", True, False)):19 # both agents' runs follow the same question order, so zip pairs one question's two outcomes20 ids = [a.question.question_id for a, b in zip(runs["metrics-first"], runs["declining"])21 if (a.outcome == "correct") == was and (b.outcome == "correct") == now]22 print(f"{split} {label} by the declining prompt: {', '.join(ids) or 'none'}")
python scorecard.pydev questions: 21
dev schema-only correct: 2 of 21
dev schema-only accuracy: 0.10 (95% interval 0.03 to 0.29)
dev schema-only wrong numbers: 11
dev schema-only errors or step limits: 8
dev schema-only decline recall: 0.00
dev schema-only decline precision: no declines
dev schema-only coverage: 0.62
dev schema-only selective risk: 0.85
dev schema-only model calls per question: 1.0
dev schema-only prompt tokens per question: 827
dev metrics-first correct: 15 of 21
dev metrics-first accuracy: 0.71 (95% interval 0.50 to 0.86)
dev metrics-first wrong numbers: 5
dev metrics-first errors or step limits: 1
dev metrics-first decline recall: 0.75
dev metrics-first decline precision: 1.00
dev metrics-first coverage: 0.81
dev metrics-first selective risk: 0.29
dev metrics-first model calls per question: 1.8
dev metrics-first prompt tokens per question: 2,196
dev declining correct: 15 of 21
dev declining accuracy: 0.71 (95% interval 0.50 to 0.86)
dev declining wrong numbers: 4
dev declining errors or step limits: 1
dev declining decline recall: 1.00
dev declining decline precision: 0.80
dev declining coverage: 0.71
dev declining selective risk: 0.27
dev declining model calls per question: 1.9
dev declining prompt tokens per question: 2,602
dev fixed by the declining prompt: gq-020
dev broken by the declining prompt: gq-008
test questions: 21
test schema-only correct: 3 of 21
test schema-only accuracy: 0.14 (95% interval 0.05 to 0.35)
test schema-only wrong numbers: 10
test schema-only errors or step limits: 8
test schema-only decline recall: 0.00
test schema-only decline precision: no declines
test schema-only coverage: 0.62
test schema-only selective risk: 0.77
test schema-only model calls per question: 1.0
test schema-only prompt tokens per question: 829
test metrics-first correct: 9 of 21
test metrics-first accuracy: 0.43 (95% interval 0.24 to 0.63)
test metrics-first wrong numbers: 5
test metrics-first errors or step limits: 1
test metrics-first decline recall: 1.00
test metrics-first decline precision: 0.40
test metrics-first coverage: 0.48
test metrics-first selective risk: 0.50
test metrics-first model calls per question: 1.5
test metrics-first prompt tokens per question: 1,854
test declining correct: 8 of 21
test declining accuracy: 0.38 (95% interval 0.21 to 0.59)
test declining wrong numbers: 4
test declining errors or step limits: 3
test declining decline recall: 0.75
test declining decline precision: 0.33
test declining coverage: 0.43
test declining selective risk: 0.44
test declining model calls per question: 1.9
test declining prompt tokens per question: 2,622
test fixed by the declining prompt: none
test broken by the declining prompt: gq-043
Na divisão dev, ambos os agentes acertam 15 of 21, uma acurácia de 0.71 (95% interval 0.50 to 0.86), mas não nas mesmas perguntas. O prompt de recusa corrigiu gq-020 e quebrou gq-008, as 2 inversões que o capítulo 8 encontrou.
A diferença está nos erros. O agente que recusa deu 4 números errados, contra 5 do agente que usa métricas primeiro, e seu recall de recusas é 1.00, contra 0.75.
Ele paga por isso em cobertura, 0.71 contra 0.81, e em tokens de prompt, 2,602 contra 2,196 por pergunta.
O SQL apenas com o esquema acerta 2 of 21, e, entre os números que dá, a parcela errada, ou seja, seu risco seletivo, é 0.85.
No teste, o prompt de recusa não corrigiu nenhuma pergunta e quebrou uma, gq-043, "Qual foi a receita no Q2?", que o agente do capítulo 6 respondeu com uma pergunta de volta e que o agente que recusa não conseguiu responder, por ter esgotado as chamadas ao modelo. O agente que recusa obtém 8 of 21, contra 9 of 21 do agente que usa métricas primeiro, e o SQL apenas com o esquema obtém 3 of 21.
Seus números errados caíram de 5 para 4, porque uma resposta errada virou uma execução que atingiu o limite de passos, e não uma resposta certa. Os intervalos dos 2 agentes se sobrepõem quase por completo nas duas divisões. Quando 2 totais têm intervalos sobrepostos, eles não dizem se uma mudança ajudou, e por isso o gate compara as mesmas perguntas em pares.
Regra prática: Informe cada execução como um scorecard: acertos com um intervalo de Wilson, números errados, recusas com seu recall e sua precisão, falhas por tipo, e chamadas e tokens por pergunta. Compare os agentes nas mesmas perguntas, na mesma tabela. Pontue a divisão de teste uma única vez, quando informar um número final, e diga que fez isso. Quando os intervalos de 2 agentes se sobrepõem, não declare nenhum deles melhor com base nos totais.
Julgue apenas o que não pode ser comparado
results_match(), a comparação que o capítulo 3 construiu, compara um número com um resultado de referência. Grande parte do que o agente diz não é um número. O motivo de uma recusa, a frase que diz à pessoa por que nenhum número foi dado, não tem resultado de referência com o qual se possa comparar: duas boas justificativas podem não compartilhar nenhuma palavra, e um motivo fluente pode ser falso. Para textos assim, a ferramenta comum é um juiz, uma chamada de modelo que avalia uma resposta segundo uma rubrica e devolve um veredito. Um juiz é barato e incansável, e tem vieses conhecidos. Zheng e colegas, que descobriram que juízes fortes concordaram com preferências humanas quase tanto quanto humanos concordaram entre si, também citam "vieses de posição, de verbosidade e de autovalorização" (Zheng et al.): um juiz pode favorecer a resposta apresentada primeiro, a resposta mais longa e a sua própria. Um estudo posterior que catalogou doze vieses potenciais descobriu que juízes fortes ainda apresentam viés significativo em tarefas específicas (Ye et al.).
Por isso, use um juiz apenas quando um resultado não puder ser comparado diretamente, e projete cada chamada de modo que um viés apareça. O juiz da loja é o próprio modelo do livro, o mesmo que o agente usa, chamado com um prompt separado, JUDGE_PAIR em lib/prompts.py. Ele recebe uma pergunta e duas justificativas para recusá-la, rotuladas A e B, e indica a melhor delas, ou um empate, em JSON. A rubrica pede uma justificativa que diga com precisão por que os dados da loja não podem responder e o que a pessoa poderia perguntar em vez disso. Os casos são todas as perguntas de referência, em qualquer das divisões, que tanto o agente orientado por métricas do capítulo 6 quanto o agente que recusa do capítulo 8 recusaram: 8 pares. Apenas 3 deles, gq-021, gq-042 e gq-045, são perguntas de recusa. Os outros 5, gq-032, gq-033, gq-034, gq-037 e gq-041, são perguntas de resposta que o armazém pode responder, as lacunas na camada que o capítulo 6 encontrou, e ambos os agentes recusaram erroneamente. Nesses casos, a resposta certa era um número, de modo que o juiz compara duas recusas erradas. Cada par é julgado duas vezes, uma com a justificativa de cada agente em primeiro lugar, para que um veredito que segue a posição e não o texto mude com a ordem. parse_verdict() em lib/judge.py lê cada resposta, e o registro judge-verdicts guarda cada chamada.
1"""Judge only what can't be compared: two reasons for declining the same question, shown in both orders.2The points about position, length and which reasons won rest on the same-verdict, consistent-winner and3won-in-both-orders lines, and the answerable lines show which reasons say the data lacks what was asked."""4import re56from lib.judge import judge_pairs, recorded_cases7from lib.model import RecordedModel8from lib.semantic import load9from lib.warehouse import connect1011con, layer = connect(), load()12_, pairs = recorded_cases(con, layer)13results = judge_pairs(RecordedModel("judge-verdicts"), pairs)14GROUPS = {"decline": "decline questions", "answer": "answerable questions both agents declined"}15AGENTS = ("metrics-first", "declining")16# a reason that says the data does not include or contain what was asked17BLAMES_DATA = re.compile(r"\bdata (does not|doesn't) (include|contain)")18# words a reply uses to offer a path forward or reframe the question19ALTERNATIVE = ("alternative", "instead", "reframe", "path forward")20for r in results:21 print(f"{r.case.question.question_id} ({r.case.question.kind}): metrics-first first -> {r.first.label}; "22 f"declining first -> {r.second.label}")23n = len(results)24print(f"pairs: {n}")25for group, name in GROUPS.items():26 print(f"pairs on {name}: {sum(r.case.question.kind == group for r in results)}")27# second_as_first maps the second order's label back to the first order's labels28print(f"same verdict in both orders: {sum(r.first.label == r.second_as_first for r in results)} of {n}")29print(f"first reason won in both orders: {sum(r.first.label == r.second.label == 'A' for r in results)} of {n}")30print(f"second reason won in both orders: {sum(r.first.label == r.second.label == 'B' for r in results)} of {n}")31for agent in AGENTS:32 print(f"{agent} reason won in both orders: {sum(r.winner == agent for r in results)}")33for group, name in GROUPS.items():34 for agent in AGENTS:35 print(f"{name}, {agent} reason won in both orders: "36 f"{sum(r.winner == agent and r.case.question.kind == group for r in results)}")37# longer_won compares the winning reason's length with the losing reason's, in characters38print(f"consistent winner was the longer reason: {sum(r.longer_won for r in results)}")39answerable = [r.case for r in results if r.case.question.kind == "answer"]40for agent, reasons in (("metrics-first", [c.first for c in answerable]), ("declining", [c.second for c in answerable])):41 said = sum(bool(BLAMES_DATA.search(x)) for x in reasons)42 print(f"answerable questions, {agent} reasons that say the data lacks it: {said} of {len(answerable)}")43replies = [v for r in results for v in (r.first, r.second)]44suggests = sum(any(w in v.reason.lower() for w in ALTERNATIVE) for v in replies)45print(f"judge replies that suggest an alternative or a reframe: {suggests} of {len(replies)}")
python judge-an-explanation.pygq-021 (decline): metrics-first first -> A; declining first -> A
gq-032 (answer): metrics-first first -> B; declining first -> A
gq-033 (answer): metrics-first first -> A; declining first -> B
gq-034 (answer): metrics-first first -> A; declining first -> B
gq-037 (answer): metrics-first first -> A; declining first -> B
gq-041 (answer): metrics-first first -> A; declining first -> B
gq-042 (decline): metrics-first first -> B; declining first -> A
gq-045 (decline): metrics-first first -> A; declining first -> B
pairs: 8
pairs on decline questions: 3
pairs on answerable questions both agents declined: 5
same verdict in both orders: 7 of 8
first reason won in both orders: 1 of 8
second reason won in both orders: 0 of 8
metrics-first reason won in both orders: 5
declining reason won in both orders: 2
decline questions, metrics-first reason won in both orders: 1
decline questions, declining reason won in both orders: 1
answerable questions both agents declined, metrics-first reason won in both orders: 4
answerable questions both agents declined, declining reason won in both orders: 1
consistent winner was the longer reason: 6
answerable questions, metrics-first reasons that say the data lacks it: 1 of 5
answerable questions, declining reasons that say the data lacks it: 5 of 5
judge replies that suggest an alternative or a reframe: 9 of 16
O juiz deu o mesmo veredito nas duas ordens em 7 of 8 pares, e o único que mudou, gq-021, o custo de envio, seguiu a justificativa que vinha primeiro. Isso é viés de posição no único lugar em que um par estava equilibrado, já que as duas justificativas dizem quase a mesma coisa.
Dos vereditos consistentes, a justificativa do capítulo 6 venceu 5 vezes e a do capítulo 8, 2, e a justificativa mais longa venceu 6 deles. Isso é o que prevê o viés de verbosidade, embora 8 pares não consigam separá-lo de justificativas mais longas serem melhores.
Os dois grupos de pares contam histórias diferentes. Nas perguntas respondíveis, o juiz preferiu a justificativa do capítulo 6 em 4 dos 5 pares, e a do capítulo 8 em 1.
As justificativas do capítulo 8 dizem que os dados não contêm o que foi pedido em 5 of 5, o que é falso: o armazém guarda raw.customers.email para gq-037 e fct_orders.discount_eur para gq-041. As justificativas do capítulo 6 dizem isso em 1 of 5; as outras dizem que as métricas não incluem o que foi pedido, o que é verdade para a camada semântica. Portanto, nesses pares, o juiz pode ter preferido a justificativa mais precisa, a do capítulo 6, e precisão e comprimento apontam na mesma direção.
Nas perguntas de recusa, o caso para o qual a rubrica foi escrita, a justificativa do capítulo 6 venceu em 1 dos 3 pares, a do capítulo 8 em 1, e o terceiro mudou com a ordem. São poucos pares para dizer de quem são as melhores justificativas.
Ler os vereditos mostra um problema maior que a ordem. Das respostas do juiz, 9 of 16 elogiam uma justificativa por "oferecer um caminho construtivo", uma alternativa ou uma forma de reformular a pergunta, ou censuram uma por não ter isso, e nenhuma das justificativas dos dois agentes faz isso em nenhum desses pares. Em gq-032, a margem bruta, o juiz preferiu a justificativa do capítulo 8 por explicar o cálculo, e o cálculo que essa justificativa dá, receita bruta menos receita líquida, dividida pela receita bruta, não é uma margem bruta: o SQL de referência subtrai da receita líquida o custo unitário dos produtos. O juiz recompensou uma definição errada dita com segurança. Um veredito sobre texto só vale o quanto o juiz domina os fatos por trás dele, e por isso a próxima seção mede o juiz onde os fatos são conhecidos.
Regra prática: Use um juiz apenas para o que não pode ser comparado com um resultado, como justificativas, explicações e perguntas de volta, e mantenha results_match() para todo número. Julgue cada par nas duas ordens e conte os vereditos que mudam, registre cada veredito e leia uma amostra das justificativas do juiz, não apenas os seus rótulos. Não deixe a preferência de um juiz entre dois textos decidir uma liberação antes de ter medido esse juiz em casos com respostas conhecidas.
Esta parte ainda não foi traduzida, por isso está em inglês.
Calibrate the judge against reference labels
A judge's verdicts on reasons can't be checked against a golden result, so measure the judge first on a task where they can. The shop's golden questions offer one. Ask the same model to grade the agent's answers to answer questions as correct or incorrect, without showing it the golden result, and compare its verdicts with labels that results_match() computes from the golden result. Reference labels computed by results_match() are nobody's opinion: anyone can recompute them from questions.toml and the recordings, and when one looks wrong, the fix is to the golden question, where it's open to correction like the rest of the book. Calibrating a judge against reference labels measures how often the judge agrees with a check you trust, and in which direction it errs.
Agreement needs a chance correction. If most answers are wrong, a judge that calls everything wrong agrees most of the time and has learned nothing; Artstein and Poesio describe the case where raw agreement is high and chance-corrected agreement can still be low (Artstein and Poesio). Cohen's kappa and Scott's pi both subtract the agreement that chance would give, and differ only in how they estimate it: Cohen's kappa estimates chance agreement from each rater's own label shares, and Scott's pi estimates chance agreement from the two raters' shares pooled. Thakur and colleagues dropped kappa for pi in a study of judges, because with kappa "the chance agreement adjusts for the observed average differences between raters, which is in fact part of what we intend to measure" (Thakur et al.). A judge that says "correct" more often than the reference is exactly what you want the statistic to catch, so we report both, and read the lower. In formulas, with p_o the observed agreement:
p_o = cases where the judge and the reference agree / cases
chance, κ = Σ over labels (reference's share of the label × judge's share of the label)
chance, π = Σ over labels (the label's share of both raters' labels pooled)²
kappa, pi = (p_o − chance) / (1 − chance)
agreement() in lib/judge.py computes all three; scikit-learn's cohen_kappa_score uses the same definition of kappa (scikit-learn). The prompt, JUDGE_ANSWER, gives the judge the shop's glossary, the question, the role, the metric and SQL behind the answer and its result. The cases are every distinct answer with a number that schema-only SQL, the metrics-first agent and the declining agent gave to an answer question, on both splits, from their recordings: 56 in all. The judge prompts were written once, and no verdict changed them. What the judge is shown changed once. Schema-only SQL's query for gq-009 has no ORDER BY, so its rows came back in another order on replay, and the prompt built from them no longer matched its recording. shown() in lib/judge.py now sorts the rows of any query without ORDER BY before the judge sees them. The recording made before that fix was set aside, and every judge call was recorded again from scratch with the fix in place, as the manifest of judge-verdicts says. Every reply matched the set-aside recording's, so no number in this chapter moved.
1"""Calibrate the judge: its verdicts on the book's recorded answers against labels from results_match().2The overall and per-agent agreement lines, and the one-verdict kappa ranges, are the figures the chapter's points rest on."""3from lib.judge import agreement, answer_messages, kappa_one_verdict, parse_verdict, recorded_cases4from lib.model import RecordedModel5from lib.semantic import load6from lib.warehouse import connect78con, layer = connect(), load()9judge = RecordedModel("judge-verdicts")10cases, _ = recorded_cases(con, layer) # every distinct answer with a number, with its reference label11judged = {c.case_id: parse_verdict(judge.complete(answer_messages(c.question, c.answer))) for c in cases}12verdicts = {case_id: v.label for case_id, v in judged.items()}13print(f"cases: {len(cases)}")14print(f"reference correct: {sum(c.reference == 'correct' for c in cases)}")15print(f"judge correct: {list(verdicts.values()).count('correct')}")16print(f"judge unparsed: {list(verdicts.values()).count('unparsed')}")17# a case ID ends with the agent that gave the answer, so the metric agents' cases are all the rest18subsets = {"all": cases, "schema-only": [c for c in cases if c.case_id.endswith("schema-only")],19 "metric agents": [c for c in cases if not c.case_id.endswith("schema-only")]}20for name, subset in subsets.items():21 a = agreement([c.reference for c in subset], [verdicts[c.case_id] for c in subset])22 print(f"{name} cases: {a.n}")23 print(f"{name} cases the reference labels correct: {sum(c.reference == 'correct' for c in subset)}")24 print(f"{name} observed agreement: {a.observed:.2f}")25 print(f"{name} Cohen's kappa: {a.kappa:.2f}")26 print(f"{name} Scott's pi: {a.pi:.2f}")27 # kappa with each single verdict flipped in turn, to show how far one case moves it28 low, high = kappa_one_verdict([c.reference for c in subset], [verdicts[c.case_id] for c in subset])29 print(f"{name} kappa with any one verdict changed: {low:.2f} to {high:.2f}")30for reference, verdict, label in (("incorrect", "correct", "wrong answers the judge called correct"),31 ("correct", "incorrect", "right answers the judge called incorrect")):32 ids = [c.case_id for c in cases if c.reference == reference and verdicts[c.case_id] == verdict]33 print(f"{label}: {len(ids)} of {sum(c.reference == reference for c in cases)}")34 print(f"{label}, cases: {', '.join(ids)}")35# Read the reasons: how many rejections of right answers say a year's filter keeps only its first day?36first_day = [c.case_id for c in cases if c.reference == "correct" and judged[c.case_id].label == "incorrect"37 and any(w in judged[c.case_id].reason for w in ("January 1", "first day"))]38print(f"right answers rejected for reading a year's filter as January 1: {len(first_day)}")
python judge-agreement.pycases: 56
reference correct: 26
judge correct: 20
judge unparsed: 0
all cases: 56
all cases the reference labels correct: 26
all observed agreement: 0.75
all Cohen's kappa: 0.49
all Scott's pi: 0.48
all kappa with any one verdict changed: 0.45 to 0.53
schema-only cases: 23
schema-only cases the reference labels correct: 5
schema-only observed agreement: 0.74
schema-only Cohen's kappa: 0.10
schema-only Scott's pi: 0.09
schema-only kappa with any one verdict changed: -0.14 to 0.31
metric agents cases: 33
metric agents cases the reference labels correct: 21
metric agents observed agreement: 0.76
metric agents Cohen's kappa: 0.51
metric agents Scott's pi: 0.50
metric agents kappa with any one verdict changed: 0.44 to 0.58
wrong answers the judge called correct: 4 of 30
wrong answers the judge called correct, cases: gq-002 schema-only, gq-004 schema-only, gq-018 metrics-first, gq-035 metrics-first
right answers the judge called incorrect: 10 of 26
right answers the judge called incorrect, cases: gq-014 schema-only, gq-016 schema-only, gq-027 schema-only, gq-031 schema-only, gq-003 metrics-first, gq-006 metrics-first, gq-008 metrics-first, gq-015 metrics-first, gq-027 metrics-first, gq-029 metrics-first
right answers rejected for reading a year's filter as January 1: 6
The overall kappa, 0.49, looks moderate, but it hides a split by agent. On schema-only SQL's answers, most of them wrong, observed agreement is 0.74 and kappa only 0.10: the judge agreed mostly by calling wrong answers wrong, and rarely picked out the few right ones. Changing one of its verdicts on those answers moves kappa anywhere from -0.14 to 0.31.
The metric agents' kappa is higher, at 0.51, and changing one verdict moves it within 0.44 to 0.58. Read the first decimal of these kappas, not the second. Kappa and pi barely differ here, 0.49 against 0.48 overall, because the judge and the reference use each label about as often; when a judge leans hard one way, they part.
The direction of the errors matters more than the totals. The judge called 4 of 30 wrong answers correct, among them gq-018, chapter 6's near-miss refund metric. It called 10 of 26 right answers incorrect, and 6 of those rejections say that the SQL keeps only January 1 of the year, a misreading of the semantic layer's DATE_TRUNC('YEAR', …) = '2025-01-01'. The others reject schema-only answers that filter on placed_at rather than the local order day: the judge grades the method, and on those questions the number happened to come out the same. So the shop's judge leans strict, not lenient, as Thakur and colleagues report of the judges they studied (Thakur et al.), and it can't read the compiled SQL it's shown.
The judge is also the model that wrote every answer here. Self-preference, a judge that "scores its own outputs higher than others' while human annotators consider them of equal quality" (Panickssery et al.), is a known bias, and familiarity, text that has low perplexity for the judge, is one explanation of it (Wataoka et al.). With one model writing every answer, this measurement can't separate self-preference from other errors. It measures the net bias against a check that doesn't depend on the model; it doesn't remove the bias.
Working rule: Before you use a judge on text, measure it on cases whose answers a check can label, with labels anyone can recompute. Report observed agreement with Cohen's kappa and Scott's pi, split by the kinds of answer you'll judge, list the errors in each direction, and say how far one case moves kappa when the cases number a few dozen. Thresholds such as 0.8 are conventions, not results (Artstein and Poesio); at a kappa like the one measured here, use the judge to choose what a person reads, never to pass or fail a release on its own.
Repita as execuções para ver a variância
Até aqui, cada pontuação veio de uma única execução por pergunta, e cada execução é uma amostra. As gravações do livro amostram cada resposta na temperatura de 0.7 recomendada para o Qwen, com uma semente fixa reiniciada antes de cada chamada; por isso, uma reexecução devolve sempre a mesma resposta, e uma semente diferente pode devolver outra. Uma pontuação obtida com uma semente é um sorteio entre as pontuações que o agente poderia obter. Miller recomenda tratar uma avaliação como um experimento e "reduzir a variância reamostrando respostas" várias vezes por pergunta (Miller). A alternativa, baixar a temperatura até que as execuções concordem, mede um modelo diferente do que você serve.
A gravação repeat-runs traz as mesmas 12 perguntas de desenvolvimento executadas com mais quatro sementes, de 1 a 4, tanto para o agente de métricas primeiro do capítulo 6 quanto para o agente de recusa do capítulo 8, com os mesmos prompts, ferramentas, configurações de amostragem e limite de quatro chamadas de suas gravações originais. Nas execuções originais, feitas com a semente 2718, cada pergunta tem cinco execuções por agente. SeededRecording em lib/regressions.py reexecuta as chamadas de um agente para uma semente. As 12 perguntas são todas as perguntas de desenvolvimento de resposta ou de recusa que algum dos agentes errou em sua execução original, mais as cinco primeiras das demais em ordem de ID; por isso, são mais difíceis que a média da divisão, e suas taxas de inversão representam um limite superior. A gravação também executa o agente de recusa mais uma vez com a própria semente 2718, para medir algo que o livro até aqui supôs: que uma execução com a mesma semente se reexecuta byte a byte neste ambiente de execução.
1"""Five runs of 12 dev questions per agent, one per seed: how much a score moves, and which questions flip.2The flipping, across-seeds and always-or-never lines and the seed check are the printed lines the chapter's points rest on."""3from lib.golden import load_golden4from lib.model import RecordedModel5from lib.regressions import ORIGINAL_SEED, SeededRecording, replay6from lib.semantic import load7from lib.warehouse import connect89con, layer = connect(), load()10QUESTIONS = ("gq-001", "gq-002", "gq-003", "gq-004", "gq-005", "gq-007", "gq-008", "gq-012", "gq-016", "gq-017",11 "gq-018", "gq-020") # the 12 questions repeat-runs holds12questions = [q for q in load_golden() if q.question_id in QUESTIONS]13seeds = (ORIGINAL_SEED, 1, 2, 3, 4) # 2718 replays the original recordings14for agent in ("metrics-first", "declining"):15 per_question = {q.question_id: 0 for q in questions}16 scores = []17 for seed in seeds:18 runs = replay(con, layer, agent, questions, seed=seed)19 scores.append(sum(r.outcome == "correct" for r in runs))20 for r in runs:21 per_question[r.question.question_id] += r.outcome == "correct"22 print(f"{agent} seed {seed}: {scores[-1]} of {len(questions)} correct")23 spread = f"{min(scores)} to {max(scores)}" if min(scores) < max(scores) else f"{min(scores)} at every seed"24 print(f"{agent} correct across seeds: {spread}")25 # a question flips when some seeds get it right and others wrong26 flips = [f"{q} ({n} of 5)" for q, n in per_question.items() if 0 < n < 5]27 print(f"{agent} questions that flip: {len(flips)}")28 print(f"{agent} flipping: {', '.join(flips)}")29 print(f"{agent} always correct: {sum(n == 5 for n in per_question.values())}")30 print(f"{agent} never correct: {sum(n == 0 for n in per_question.values())}")3132# Does a run replay byte for byte? The declining agent ran again with seed 2718; compare it with decline-runs.33again, original = SeededRecording("declining", ORIGINAL_SEED).calls, RecordedModel("decline-runs").calls34same = sum(key in original and call["reply"] == original[key]["reply"] for key, call in again.items())35print(f"seed {ORIGINAL_SEED} again: {same} of {len(again)} calls identical to decline-runs")
python seed-variance.pymetrics-first seed 2718: 6 of 12 correct
metrics-first seed 1: 6 of 12 correct
metrics-first seed 2: 6 of 12 correct
metrics-first seed 3: 6 of 12 correct
metrics-first seed 4: 5 of 12 correct
metrics-first correct across seeds: 5 to 6
metrics-first questions that flip: 1
metrics-first flipping: gq-008 (4 of 5)
metrics-first always correct: 5
metrics-first never correct: 6
declining seed 2718: 6 of 12 correct
declining seed 1: 6 of 12 correct
declining seed 2: 6 of 12 correct
declining seed 3: 6 of 12 correct
declining seed 4: 6 of 12 correct
declining correct across seeds: 6 at every seed
declining questions that flip: 0
declining flipping:
declining always correct: 6
declining never correct: 6
seed 2718 again: 24 of 24 calls identical to decline-runs
A verificação de reexecução vem primeiro, porque tudo o mais depende dela: seed 2718 again: 24 of 24 calls identical to decline-runs. Neste ambiente de execução, llama.cpp na CPU com uma requisição por vez e a semente reiniciada antes de cada chamada, a segunda execução com a semente 2718 coincidiu com a primeira em todas as chamadas. Trata-se de um agente, em 12 perguntas, em uma única máquina; isso não garante nada para todo ambiente de execução, mas mostra que as diferenças entre sementes, aqui, vêm da amostragem, e não do ambiente de execução. Isso condiz com a causa que um laboratório identificou para a variação na temperatura 0 em modelos servidos, resultados que dependem de como as requisições são agrupadas em lotes (He et al.), algo que uma única requisição local evita; uma API servida não oferece tal garantia.
Por pergunta, as execuções são mais estáveis do que se poderia temer com a temperatura de 0.7: apenas 1 pergunta com inversão, gq-008 (4 of 5), e somente no agente de métricas primeiro. Entre as cinco sementes, o total do agente de métricas primeiro variou entre 5 to 6, e o do agente de recusa ficou em 6 at every seed.
O resultado do agente de recusa nunca mudou com a semente: 6 perguntas foram sempre corretas e 6 nunca. O capítulo 8 se perguntou se a pergunta gq-008, a receita total em 2025, era fruto do acaso, e as repetições respondem a essa dúvida. Com o prompt de recusa, ela esteve errada em todas as execuções; portanto, a falha não é acaso: o novo prompt afastou o modelo da receita líquida nessa pergunta, levando-o à receita bruta que o capítulo 8 observou em sua única execução.
Acreditamos que a estabilidade vem do desenho da loja. A maior parte das escolhas do agente se dá entre poucos nomes de métricas, e a camada semântica transforma cada escolha no mesmo SQL todas as vezes; por isso, pequenas diferenças de redação não chegam ao resultado. Um modelo que escreve SQL tem muitas outras maneiras de diferir. Estudos com modelos hospedados encontraram oscilações maiores, "variações de acurácia de até 15% entre execuções naturalmente ocorrentes" em configurações destinadas a ser determinísticas (Atil et al.), em outras tarefas e APIs. Cinco execuções de 12 perguntas também são uma amostra pequena da loja.
Regra prática: Execute cada pergunta de referência várias vezes com as configurações de amostragem que você serve, com as sementes fixadas no manifesto da gravação, e confirme uma vez que uma semente se reexecuta exatamente. Informe as inversões por pergunta, e não apenas a dispersão do total, porque um total pode permanecer igual enquanto as perguntas trocam de lugar. Nunca baixe a temperatura para fazer as execuções concordarem, a menos que essa seja a configuração que você vai servir.
Bloqueie uma mudança no CI
Um job de CI que pontua cada mudança nas perguntas de ouro transforma as medições feitas até aqui em uma decisão: integrar ou não integrar. O cartão de pontuação mostrou por que essa decisão não pode se apoiar em totais: o prompt que faz o modelo recusar responder deixou a acurácia do dev inalterada. Miller recomenda "conduzir inferência estatística sobre as diferenças pareadas no nível das perguntas" (Miller): pontue as duas configurações nas mesmas perguntas e teste a média das diferenças por pergunta. O pareamento elimina a variação entre perguntas, que é muito maior que a de uma mudança.
Comparison em lib/regressions.py obtém, para cada pergunta, a fração de execuções corretas sob a base e sob o candidato, e a diferença entre elas. Ele informa a média das diferenças pareadas com um intervalo t, isto é, o erro padrão multiplicado pelo t de Student com um grau de liberdade a menos que o número de perguntas; conta as perguntas corrigidas e as quebradas; e executa um teste do sinal exato nas perguntas que mudaram. As premissas de erro de Miller supõem muitas perguntas; com 12, em sua maioria inalteradas, o intervalo t é apenas um guia aproximado, e somente o teste do sinal não supõe nada. gate() aplica duas regras de nossa escolha: ele reprova uma quebra estável, ou seja, uma pergunta que a base acertou em pelo menos quatro das cinco execuções e o candidato em no máximo uma; e reprova quando todo o intervalo da diferença média fica abaixo de zero. A primeira detecta uma regressão que uma média esconderia; a segunda, várias pequenas. Submetemos o prompt do capítulo 8 ao do capítulo 6, primeiro com uma execução por pergunta e depois com cinco, nas 12 perguntas de repeat-runs, que super-representam as respostas erradas; por isso os números do portão descrevem essas perguntas, e não a divisão de dev.
1"""Gate a prompt change on paired, per-question differences over five recorded runs of each question.2The one-run sign test, the five-run lines and the gate's reasons are the printed lines the chapter's points rest on."""3from lib.golden import load_golden4from lib.regressions import ORIGINAL_SEED, Comparison, gate, replay, smallest_detectable, t_quantile5from lib.semantic import load6from lib.warehouse import connect78con, layer = connect(), load()9QUESTIONS = ("gq-001", "gq-002", "gq-003", "gq-004", "gq-005", "gq-007", "gq-008", "gq-012", "gq-016", "gq-017",10 "gq-018", "gq-020") # the 12 questions repeat-runs holds11questions = [q for q in load_golden() if q.question_id in QUESTIONS]12seeds = (ORIGINAL_SEED, 1, 2, 3, 4)13correct = {agent: {q.question_id: [] for q in questions} for agent in ("metrics-first", "declining")}14for agent, runs in correct.items():15 for seed in seeds:16 for run in replay(con, layer, agent, questions, seed=seed):17 runs[run.question.question_id].append(run.outcome == "correct")1819# One run each, as a CI job that runs every question once would see it.20once = Comparison({q: r[:1] for q, r in correct["metrics-first"].items()},21 {q: r[:1] for q, r in correct["declining"].items()})22fixed, broken = once.moved()23print(f"one run: fixed {len(fixed)} ({', '.join(fixed)}), broken {len(broken)} ({', '.join(broken)})")24print(f"one run sign test p: {once.sign_test():.2f}")25print(f"one run stable breaks: {', '.join(once.stable_breaks()) or 'none'}") # with one run, every flip is "stable"2627five = Comparison(correct["metrics-first"], correct["declining"])28for q in five.questions:29 print(f"{q}: metrics-first {sum(five.base[q])} of 5, declining {sum(five.candidate[q])} of 5")30fixed, broken = five.moved()31print(f"five runs: fixed {len(fixed)} ({', '.join(fixed) or 'none'}), broken {len(broken)} ({', '.join(broken) or 'none'})")32low, high = five.interval()33print(f"five runs mean paired difference: {five.mean_difference:+.2f}")34print(f"five runs 95% interval: {low:+.2f} to {high:+.2f}")35# one degree of freedom goes to estimating the spread of the differences from the same questions36print(f"t multiplier, {len(five.questions) - 1} degrees of freedom: {t_quantile(0.975, len(five.questions) - 1):.2f}")37print(f"five runs interval half-width: {five.half_width():.2f}")38k = smallest_detectable(len(five.questions))39print(f"fewest clean flips the mean rule detects: {k} of {len(five.questions)}")40print(f"smallest mean change the mean rule detects: {k / len(five.questions):.2f}")41print(f"five runs sign test p: {five.sign_test():.2f}")42passed, reasons = gate(five)43print(f"gate: {'pass' if passed else 'fail'}")44print("\n".join(f"gate reason: {r}" for r in reasons))
python regression-gate.pyone run: fixed 1 (gq-020), broken 1 (gq-008)
one run sign test p: 1.00
one run stable breaks: gq-008
gq-001: metrics-first 5 of 5, declining 5 of 5
gq-002: metrics-first 5 of 5, declining 5 of 5
gq-003: metrics-first 5 of 5, declining 5 of 5
gq-004: metrics-first 5 of 5, declining 5 of 5
gq-005: metrics-first 5 of 5, declining 5 of 5
gq-007: metrics-first 0 of 5, declining 0 of 5
gq-008: metrics-first 4 of 5, declining 0 of 5
gq-012: metrics-first 0 of 5, declining 0 of 5
gq-016: metrics-first 0 of 5, declining 0 of 5
gq-017: metrics-first 0 of 5, declining 0 of 5
gq-018: metrics-first 0 of 5, declining 0 of 5
gq-020: metrics-first 0 of 5, declining 5 of 5
five runs: fixed 1 (gq-020), broken 1 (gq-008)
five runs mean paired difference: +0.02
five runs 95% interval: -0.23 to +0.26
t multiplier, 11 degrees of freedom: 2.20
five runs interval half-width: 0.25
fewest clean flips the mean rule detects: 4 of 12
smallest mean change the mean rule detects: 0.33
five runs sign test p: 1.00
gate: fail
gate reason: stable break: gq-008
Com uma execução cada, a mudança corrigiu gq-020 e quebrou gq-008, e o teste do sinal dá p = 1.00. Com uma única execução, toda oscilação conta como estável, de modo que uma execução não consegue distinguir uma quebra de uma oscilação ao acaso. Cinco execuções separam as duas: gq-008 é uma quebra estável (gq-008: metrics-first 4 of 5, declining 0 of 5), e a correção de gq-020 é igualmente constante (gq-020: metrics-first 0 of 5, declining 5 of 5).
A diferença média pareada é +0.02, com multiplicador t de 2.20 e intervalo de -0.23 to +0.26; em média, portanto, a mudança não produziu efeito mensurável.
O portão indica fail, pelo motivo stable break: gq-008. O prompt corrigiu uma pergunta e quebrou outra de forma confiável, e alguém precisa escolher, ou corrigi-lo, antes que ele seja integrado.
O portão também tem um ponto cego. A meia largura do intervalo, 0.25 aqui, pertence a esta comparação, pois depende de quanto as diferenças variam. O que a regra da média consegue detectar decorre da própria regra: o menor número de perguntas que precisa passar de sempre errada para sempre certa, mantendo-se as demais inalteradas, para que o intervalo exclua o zero, é 4 of 12, o que corresponde a uma mudança média de 0.33. As quebras são o espelho disso. Qualquer efeito menor passa pela regra da média nos dois sentidos, e só a regra de quebra estável e a leitura, por uma pessoa, das perguntas que mudaram se opõem a ele. Um prompt alterado reprova no portão com MissingRecording até ser registrado, e esse é o momento de registrá-lo cinco vezes, e não uma.
Regra prática: Submeta uma mudança em prompts, contexto ou métricas ao portão com base em diferenças pareadas por pergunta, em execuções repetidas, nunca em uma diferença de totais. Reprove qualquer quebra estável e qualquer diferença média cujo intervalo fique abaixo de zero; registre ambas as regras como sua escolha e calcule a menor mudança que elas conseguem detectar no seu conjunto. Quando o portão reprovar, leia as perguntas que mudaram antes de tocar nas regras.
Detecte uma mudança de esquema antes que os usuários a percebam
O armazém de dados também muda sob o agente: uma coluna renomeada na origem, uma tabela reconstruída, um tipo restringido. Três verificações detectam uma mudança de esquema sem chamar um modelo: o SQL de cada pergunta dourada ainda executa, cada métrica da camada semântica ainda compila e executa, e cada execução gravada do agente ainda é reproduzida. A última funciona porque RecordedModel busca as respostas pelo hash das mensagens exatas: quando uma ferramenta retorna um erro que o modelo nunca viu, o prompt seguinte não tem gravação, e a reprodução falha de forma explícita com MissingRecording em vez de passar.
Esta execução aplica uma migração que uma equipe da origem poderia publicar, renomeando analytics.fct_orders.net_revenue_eur para net_revenue_ex_tax_eur, em uma nova cópia do armazém da loja, construída por migrated() em lib/regressions.py. schema_checks() executa as três verificações. Em seguida, o código faz a correção, uma linha na expr da métrica, em uma cópia do YAML da camada semântica, e executa as verificações novamente.
1"""An upstream rename of one column, caught by three checks that need no model, and the one-line fix.2The golden, metric and replay lines before the fix are the printed lines the chapter's points rest on."""3import shutil4import tempfile5from pathlib import Path67from lib.golden import load_golden8from lib.regressions import migrated, schema_checks9from lib.semantic import SEMANTIC_DIR, load1011RENAME = "ALTER TABLE analytics.fct_orders RENAME COLUMN net_revenue_eur TO net_revenue_ex_tax_eur"12con = migrated(RENAME)13golden = load_golden()14dev = [q for q in golden if q.split == "dev"]1516failed = schema_checks(con, load(), golden)17print(f"golden SQL that fails: {len(failed['golden SQL'])} of {sum(bool(q.golden_sql) for q in golden)}")18print(f"golden questions affected: {', '.join(failed['golden SQL'])}")19print(f"metrics that fail: {', '.join(failed['metrics'])}")20# forbidden questions are decided below the model, so they have no recording to replay21replays = schema_checks(con, load(), dev)["replays"]22print(f"recorded dev runs that no longer replay: {len(replays)} of {sum(q.kind != 'forbidden' for q in dev)}")23print(f"runs that stop: {', '.join(replays)}")2425# The fix: the metric's expr names the new column. A copy of the YAML stands in for the commit that changes it.26fixed = Path(tempfile.mkdtemp()) / "semantic"27shutil.copytree(SEMANTIC_DIR, fixed)28metrics = fixed / "metrics.yml"29metrics.write_text(metrics.read_text().replace("expr: net_revenue_eur", "expr: net_revenue_ex_tax_eur"))30after = schema_checks(con, load(fixed), dev)31print(f"after the fix, metrics that fail: {', '.join(after['metrics']) or 'none'}")32print(f"after the fix, recorded dev runs that no longer replay: {len(after['replays'])}")33shutil.rmtree(fixed.parent)
python renamed-column-caught.pygolden SQL that fails: 16 of 34
golden questions affected: gq-001, gq-002, gq-003, gq-006, gq-007, gq-008, gq-009, gq-010, gq-011, gq-012, gq-017, gq-025, gq-026, gq-034, gq-038, gq-040
metrics that fail: net_revenue, average_order_value
recorded dev runs that no longer replay: 8 of 21
runs that stop: gq-001, gq-002, gq-003, gq-006, gq-009, gq-010, gq-011, gq-017
after the fix, metrics that fail: none
after the fix, recorded dev runs that no longer replay: 0
Cada verificação detecta a renomeação. 16 of 34 perguntas douradas falham ao executar. As métricas net_revenue, average_order_value falham, porque o YAML da camada semântica referencia a coluna antiga. E 8 of 21 das execuções gravadas de desenvolvimento do agente em declínio param com MissingRecording: gq-001, gq-002, gq-003, gq-006, gq-009, gq-010, gq-011, gq-017. gq-008 e gq-012 continuam sendo reproduzidas, porque o agente as respondeu com receita bruta, que a renomeação não altera. Uma reprodução que passa indica que nada do que a execução tocou mudou, não que a execução esteja correta.
Depois da correção, nenhuma métrica falha e todas as execuções gravadas são reproduzidas: after the fix, recorded dev runs that no longer replay: 0. O agente nunca vê o nome de uma coluna, apenas métricas, então seus prompts são os mesmos e as gravações continuam válidas. O SQL dourado referencia a coluna diretamente, então as perguntas douradas que falham precisam da mesma renomeação, que é o custo do SQL dourado escrito sobre tabelas: é uma segunda cópia das definições, e precisa mudar junto com elas. Nenhuma das verificações precisa do modelo, então o CI pode executá-las a cada mudança nos modelos do armazém.
Regra prática: Execute o SQL dourado, todas as métricas e todas as reproduções gravadas no CI tanto nas mudanças do armazém quanto nas do agente, e trate MissingRecording como falha, nunca como motivo para pular uma pergunta. Quando uma verificação falhar após uma mudança de esquema, corrija a definição na camada semântica antes de gravar qualquer coisa novamente.
O que dá errado em produção
As medições da loja se apoiam em gravações de um modelo pequeno e de 48 perguntas. Quando um agente real substituir as gravações, o juiz, o portão e as pontuações se movem de maneiras que as gravações nunca mostraram, e cada um tem um sinal que você pode observar.
O juiz muda quando o modelo dele muda. Uma nova versão do modelo, um novo prompt do juiz ou uma nova rubrica são um novo juiz, e a concordância dele com os rótulos de referência precisa ser medida de novo. Mantenha os casos de calibração e os rótulos no repositório, ao lado do prompt do juiz, e refaça a medição da concordância sempre que qualquer um dos dois mudar. Um kappa que se move sem nenhuma mudança no agente indica que o juiz mudou.
O juiz não consegue ler o que julga. O juiz da loja interpretou mal o filtro de ano compilado pela camada semântica e rejeitou respostas corretas por causa disso. Um juiz que recebe SQL que não consegue interpretar avalia a aparência do SQL, não o seu significado. Forneça ao juiz o que ele consegue verificar, como o nome da métrica e os filtros, em vez do SQL compilado, e leia os motivos das rejeições antes de ler a pontuação.
Execuções ao vivo variam de maneiras que as reproduções não variam. Uma execução reproduzida é sempre igual, por isso o CI sobre gravações é determinístico. Um modelo ao vivo não é, mesmo com temperatura 0 em uma API servida: um estudo observou "variações de acurácia de até 15% entre execuções que ocorrem naturalmente" (Atil et al.), e um laboratório atribuiu grande parte disso a um servidor cujos resultados dependem de quantas requests compartilham um lote (He et al.). Registre execuções repetidas ao gravar, e trate uma pontuação ao vivo que difere da pontuação gravada como variância, até que as repetições mostrem o contrário.
Baixar a temperatura esconde a variância em vez de eliminá-la. É tentador definir temperatura 0 para que as execuções concordem. Miller recomenda não fazer isso "a menos que o objetivo seja estudar o modelo na nova temperatura" (Miller): o modelo que você mede não é, então, aquele que você serve. Meça nas configurações que você serve, e refaça a amostragem.
Um portão que sempre reprova é desligado. Com uma dúzia de perguntas, uma regra rígida dispara com ruído, e as pessoas aprendem a fazer merge passando por cima dele. Defina as regras do portão junto com as pessoas que respondem pelos números, registre o que o portão consegue e o que não consegue detectar, e revise seus falsos alarmes todo mês.
Regravar vira ajuste. Toda mudança no prompt exige novas gravações, e gravar a divisão de desenvolvimento repetidamente durante o ajuste torna o dev otimista, como o capítulo 6 registrou. Informe em cada manifesto quantas vezes uma divisão foi gravada, e grave a divisão de teste uma única vez, depois que o ajuste terminar.
Regra prática: Antes que um portão proteja um agente em produção, mantenha os casos de calibração do juiz ao lado do prompt do juiz e refaça a medição a cada mudança em qualquer um dos dois, mostre ao juiz o que ele consegue verificar, grave execuções repetidas nas configurações que você serve, combine as regras do portão com as pessoas que respondem pelos números, e conte em cada manifesto quantas vezes uma divisão foi gravada.
Decisões tomadas neste capítulo
- Uma execução é reportada como um placar, e não como uma acurácia: acertos com intervalo de Wilson, números errados, falhas, as medidas de recusa do capítulo 8, e chamadas ao modelo e tokens de prompt por pergunta, para cada agente nas mesmas perguntas.
- O conjunto de teste foi avaliado uma única vez para os números finais. O agente de recusa do capítulo 8 foi registrado no teste uma vez, em
decline-runs-test, com seu prompt inalterado, ao lado das execuções de teste que os capítulos 3 e 6 registraram. - Um juiz avalia apenas o que
results_match()não consegue: os motivos para recusar, comparados em pares, com cada par nas duas ordens. Números são sempre comparados com o resultado de referência. - O juiz é o próprio modelo do livro, com prompts próprios, e todo veredito é registrado em
judge-verdicts. Depois queshown()foi corrigido para ordenar linhas sem ordem, todo o registro foi refeito do zero. - Os rótulos de referência do juiz vêm de
results_match(), para que qualquer pessoa possa recalculá-los, em vez de vir das notas de uma pessoa. Eles medem se o número está certo, e não se o método está. - A concordância é reportada como concordância observada, kappa de Cohen e pi de Scott, no total e separada por agente, com os erros em cada direção listados. Cada kappa se apoia em algumas dezenas de casos, por isso o exemplo mostra o quanto um único veredito altera esse valor. Com um kappa como o medido aqui, o juiz escolhe o que uma pessoa lê e nunca libera uma versão sozinho.
- A variância vem de cinco execuções por pergunta, o registro original e mais quatro sementes, com as configurações de amostragem que todo registro usa, nas 12 perguntas de desenvolvimento de
repeat-runs, escolhidas para incluir todos os erros. - O portão compara configurações em pares, pergunta por pergunta, ao longo de execuções repetidas: ele falha diante de uma quebra estável ou de uma diferença média pareada cujo intervalo t fica abaixo de zero. As duas regras são escolha do livro, e, com 12 perguntas, a regra da média não detecta nada menor do que 4 of 12 perguntas mudando por completo.
- O CI também verifica o warehouse: as consultas SQL de referência são executadas, toda métrica compila e roda, e toda execução registrada é reproduzida, com
MissingRecordingtratado como falha.
Este capítulo, nesta edição
Edição 2026.11.15Exemplos aprovados em 19 de nov de 20266 de 6 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.15.