Coloque a avaliação no CI e compare variantes com o tráfego
Cerca de 23 minutos min de leitura, com 4 exemplos em 5 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.3. Leia o original
Ao final deste capítulo, você será capaz de colocar a avaliação em um portão que bloqueia uma mudança somente quando ela for mensuravelmente pior. Você também saberá dizer o que uma comparação ao vivo de duas variantes pode mostrar e o que ela não pode mostrar.
O assistente do sablefile responde com base na documentação da ferramenta, e uma equipe altera seu prompt, sua recuperação ou seu modelo de uma semana para outra. A equipe quer saber, antes de uma mudança ser mesclada, se o assistente piorou. Um portão que falha diante de qualquer queda na taxa de aprovação parece a escolha segura, mas não é. Com 80 itens de desenvolvimento, um único item altera a taxa de aprovação em cerca de 1.3 pontos, de modo que um portão baseado nas taxas brutas bloquearia uma diferença de um ou dois itens. Uma equipe bloqueada por ruído costuma aprender a ignorar o portão, e então o portão não protege nada.
Capítulo 1 executou pela primeira vez a avaliação completa: o conjunto de teste, as verificações, o juiz e as respostas reproduzidas. Este capítulo mantém essa execução no lugar. Ele trata de três partes, em sequência: um portão que respeita o intervalo, os itens cujos veredictos mudam entre amostras e os testes do próprio código da avaliação. Em seguida, relaciona as mesmas partes com os termos de um framework de avaliação, e termina com o que uma comparação de variantes em tráfego real pode e não pode mostrar.
Um portão que respeita o intervalo
Um portão é uma regra que impede uma mudança de ser integrada. Para este livro, a regra se apoia em um único número: a diferença pareada na taxa de aprovação entre um candidato e a linha de base, sobre os mesmos itens de desenvolvimento. A comparação é pareada, como o Capítulo 8 a define. Para cada item, o veredito do candidato menos o veredito da linha de base, com a média tomada sobre os itens, com o intervalo obtido por bootstrap sobre os itens. Como as duas execuções respondem às mesmas perguntas, os itens em que as duas concordam se anulam na diferença.
O portão tem uma única regra. Ele falha somente quando o limite superior do intervalo está abaixo de menos o limiar. O limite superior é a leitura menos negativa que os dados ainda permitem, portanto o portão falha quando até a leitura mais otimista dos dados mostra uma queda maior que o limiar. Um portão ingênuo falharia sempre que a estimativa pontual da diferença estivesse abaixo de menos o limiar, e falharia por causa do ruído. O preço da regra do livro é que ela deixa passar algumas quedas reais que os dados ainda não conseguem comprovar, por isso uma aprovação deve ser lida junto com a sua largura, como explicam os próximos parágrafos.
O limiar é de cinco pontos. O comentário do exemplo diz que ele é uma escolha deste livro, não um padrão. Com o conjunto de desenvolvimento deste tamanho, um item corresponde a cerca de 1.3 ponto, de modo que cinco pontos são quatro itens líquidos.
A primeira execução mostra uma queda grande, tal como este juiz a mede. O segundo modelo, Qwen3-0.6B, é menor que a linha de base de 4B e respondeu aos mesmos itens de desenvolvimento. O juiz é o Qwen3-4B-Instruct-2507, o próprio modelo da linha de base, de modo que a diferença não consegue separar um assistente mais fraco de uma autopreferência. A autopreferência explica por que este livro não pode testar isso. Leia a decisão por último, já que ela decorre do intervalo.
1"""Runs the gate on second-model against the baseline over the eighty dev items: both pass rates with their counts, the paired2difference, its interval, the threshold and the decision. The gate fails only when the upper bound of the interval is below3minus the threshold, so a drop that the interval cannot rule out below the threshold does not fail it."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.calibration import readable_verdicts7from lib.gate import FAIL, gate8from lib.judging import passed9from lib.prompts import REF_SHA25610from lib.stats import interval_points, pct11from lib.testset import load_items1213BASELINE = "judge-answers-baseline"14CANDIDATE = "judge-answers-second-model"15# Five points is this gate's threshold, chosen for the book, not a standard. With eighty dev items one item moves a rate16# by 1.25 points, so five points is four items net: a smaller threshold would ask the gate to see drops the interval17# cannot resolve at this size.18THRESHOLD_POINTS = 5.01920items = [item.id for item in load_items(split="dev")] # eighty dev items, sorted by id21baseline_found, baseline_unreadable = readable_verdicts(BASELINE, items, REF_SHA256)22candidate_found, candidate_unreadable = readable_verdicts(CANDIDATE, items, REF_SHA256)23for label, unreadable in (("baseline", baseline_unreadable), ("second-model", candidate_unreadable)):24 details = "".join(f' ({item_id}, "{first}")' for item_id, first in unreadable)25 print(f"unreadable verdicts, {label}: {len(unreadable)}{details}")26# An item the judge did not give a readable verdict on, under either run, is left out of both sides: a paired27# difference needs the same items under both runs.28excluded = {item_id for item_id, _ in baseline_unreadable + candidate_unreadable}29kept = [item_id for item_id in items if item_id not in excluded]30first = passed({item_id: baseline_found[item_id] for item_id in kept}) # 1.0 or 0.0 per item, in id order31second = passed({item_id: candidate_found[item_id] for item_id in kept})3233result = gate(first, second, threshold_points=THRESHOLD_POINTS)34print(f"dev items compared (n): {result.n}")35print(f"baseline pass rate: {pct(int(first.sum()), result.n)}")36print(f"second-model pass rate: {pct(int(second.sum()), result.n)}")37print(f"difference, second-model minus baseline: {100 * result.difference:+.1f} points")38print(f"{100 * result.level:.0f}% interval of the difference: {interval_points(result.lo, result.hi)}")39print(f"upper bound of the interval: {100 * result.hi:+.1f} points")40print(f"threshold: {THRESHOLD_POINTS:.1f} points")41if result.decision == FAIL:42 print(f"decision: fail, since the upper bound {100 * result.hi:+.1f} is below {-THRESHOLD_POINTS:+.1f}")43else:44 print(f"decision: pass, since the upper bound {100 * result.hi:+.1f} is not below {-THRESHOLD_POINTS:+.1f}")
python gate-real-drop.pyunreadable verdicts, baseline: 1 (q-0043, "VERDICT: PARTIAL")
unreadable verdicts, second-model: 0
dev items compared (n): 79
baseline pass rate: 78.5% (62 of 79)
second-model pass rate: 40.5% (32 of 79)
difference, second-model minus baseline: -38.0 points
95% interval of the difference: [-48.1, -26.6] points
upper bound of the interval: -26.6 points
threshold: 5.0 points
decision: fail, since the upper bound -26.6 is below -5.0
O portão falha, e o motivo está no intervalo, não nas estimativas pontuais. A linha de base aprova 78.5% (62 of 79). O segundo modelo aprova 40.5% (32 of 79).
A comparação cobre 79 itens, não todos os itens de desenvolvimento, porque um item cujo veredito da linha de base era ilegível fica de fora das duas execuções. Uma diferença pareada precisa dos mesmos itens nas duas. A diferença, segundo modelo menos linha de base, é -38.0 points, e o seu intervalo de 95% é [-48.1, -26.6] points.
O limite superior é -26.6 points, e o limiar é 5.0 points, de modo que até o limite superior fica bem abaixo do limiar. Esta queda não é uma que o intervalo consiga explicar, portanto o portão foi construído para falhar diante de uma queda desse tipo, tal como este juiz a mede. A decisão é: fail, since the upper bound -26.6 is below -5.0.
Uma mudança menor dá um resultado diferente. Suponha que a mudança reduza a taxa de aprovação em menos, ou que o conjunto seja menor e o intervalo se alargue, de modo que o limite superior chegue acima de menos cinco pontos. Então o portão passa. Ele não encontrou nenhuma queda maior que o limiar, e isso não mostra que o candidato é tão bom quanto a linha de base. Uma aprovação com intervalo largo é uma aprovação fraca, por isso a largura do intervalo é o motivo para lê-lo, e não apenas a decisão. Quão largo um intervalo fica em um dado tamanho, e quantos itens uma diferença pareada pequena precisa antes de se resolver, é o que o Capítulo 8 examina.
O limite do portão é o seu tamanho. Em 79 itens, o limite superior precisa cair bem abaixo de menos o limiar antes que o portão falhe, de modo que quedas pequenas passam. O Capítulo 8 estima, com o desacordo que assume, que 79 itens bastam para mostrar uma diferença de dez pontos com 80% de poder, e uma diferença de cinco pontos precisa de 316. O portão é um teste mais rigoroso que esse cálculo de poder, de modo que uma queda real de dez pontos ainda pode passar. O limiar e o tamanho do conjunto precisam ser escolhidos juntos.
Alguns portões verificam mais de uma métrica. Cada métrica extra é mais uma chance de o ruído parecer uma queda, por isso o portão leva em conta o número de comparações. Com m métricas, cada intervalo é calculado no nível 1 menos 0.05 dividido por m: 97.5% para duas métricas e cerca de 98.3% para três. Juntas, as verificações mantêm a chance de uma reprovação falsa em no máximo cinco por cento. O nível ajustado é o que o Capítulo 8 apresenta, e o portão usa o mesmo. A quantidade de reamostragens permanece em 2,000, e a semente permanece fixa, de modo que uma nova execução dá o mesmo intervalo.
O portão roda sobre os itens de desenvolvimento a cada mudança, porque um portão precisa rodar a cada vez e a equipe pode ter ajustado os parâmetros com base nesses itens. O conjunto de teste reservado é executado uma vez por decisão de lançamento, contra regras fixadas antes da execução, como explica Conjunto reservado, uma vez. Depois disso, é preciso um novo conjunto reservado.
Para colocar o portão no CI, um job calcula o portão sobre a gravação do candidato e faz a compilação falhar quando a decisão é reprovada. O portão lê apenas os valores por item, de modo que o job não precisa de nenhum outro estado. Um job que não consegue rodar conta como portão reprovado, porque um portão pulado pareceria uma aprovação. Os testes do próprio portão verificam a regra acima. Eles rodam junto com o restante dos testes da avaliação em os testes próprios da avaliação.
Regra prática: Relate cada diferença pareada com o seu intervalo e o seu n, e deixe que a decisão decorra do limite superior. Não chame uma mudança de melhor ou pior a partir de uma estimativa pontual, e não leia uma aprovação com intervalo largo como prova de que o candidato iguala a linha de base.
Marcar itens instáveis, nunca editá-los
Um item oscila quando suas respostas amostradas recebem vereditos diferentes. Cada item de desenvolvimento tem cinco vereditos do conjunto de variância, e um item é instável quando eles não são todos iguais. O conjunto de variância e a taxa de oscilação, a parcela dos itens que oscilam, são apresentados em Variância dentro de um mesmo item. Uma equipe acompanha a taxa de oscilação para ver o quanto os vereditos se movem quando as respostas do assistente se movem.
Cada item marcado vem com sua contagem de APROVADO em cinco, em ordem de id, e a regra à qual ele é submetido aparece impressa ao lado da lista.
1"""The dev items flagged as flaky: the judge's verdict differs across their five variance samples. Each flagged item prints its2PASS count out of five, sorted by id, and the count matches the flip rate in flip-rate.py, since both read the same per-item3counts. A flagged item is kept as it is, so the rule printed last is the whole policy: flagged, never edited or deleted."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.testset import load_items7from lib.variance import VARIANCE_SAMPLES, item_pass_counts89VARIANCE = "judge-answers-variance"10SAMPLES = len(VARIANCE_SAMPLES)1112items = [item.id for item in load_items(split="dev")] # eighty dev items, sorted by id13counts = item_pass_counts(VARIANCE, items)14for row in counts:15 if not row.complete: # an unreadable sample is not a FAIL: the item is named here and not flagged16 samples = ", ".join(str(sample) for sample in row.unreadable)17 print(f"left out, unreadable verdict, {row.item_id}: samples {samples}")18flagged = [row for row in counts if row.flaky]19for row in flagged:20 print(f"{row.item_id}: {row.passes} of {SAMPLES} PASS")21print(f"flagged items: {len(flagged)}")22print(f"dev items compared (n): {sum(1 for row in counts if row.complete)}")23print("rule: flagged, never edited or deleted")
python flaky-items.pyleft out, unreadable verdict, q-0043: samples 1, 4
q-0047: 4 of 5 PASS
q-0058: 1 of 5 PASS
flagged items: 2
dev items compared (n): 79
rule: flagged, never edited or deleted
Poucos itens oscilam neste conjunto. Os itens marcados somam 2 dos 79 itens de desenvolvimento comparados. Vale a pena ler os dois itens marcados.
Em q-0047, os vereditos das suas cinco respostas são 4 of 5 PASS, então a maioria das respostas foi aprovada. Em q-0058, os vereditos são 1 of 5 PASS, então a maioria das respostas foi reprovada.
Um item é posto de lado em vez de ser usado. O item q-0043 fica de fora, pois seu veredito não pôde ser lido em samples 1, 4. Uma amostra ilegível não é uma reprovação. É uma amostra que o exemplo não consegue ler, então o item não é marcado nem contado por esse motivo.
A regra é que um item marcado continua marcado, nunca editado ou excluído. Ele permanece no conjunto com os vereditos que o juiz deu. Editá-lo até que o juiz concorde com mais frequência esconderia justamente o sinal que a marcação existe para mostrar. Excluí-lo reduziria o conjunto e faria a taxa de aprovação parecer mais estável do que é. A marcação cumpre seu papel quando alguém a lê. Um item marcado com uma aprovação em cinco é uma questão sobre o item, a rubrica, o juiz ou as respostas do assistente, e deve ser examinado antes que a próxima mudança seja avaliada com base nele.
A contagem é pequena e descreve este assistente, este juiz e estes itens de desenvolvimento. Ela mostra que poucos itens oscilam neste conjunto. Não mostra que outros assistentes, outras configurações de amostragem ou outros juízes oscilem tão raramente. Uma equipe que mude qualquer um deles deve executar novamente o conjunto de variância antes de confiar em uma taxa de oscilação baixa.
Um item marcado também pode alterar uma diferença pareada de uma execução para a seguinte. Quando um portão falha numa diferença que depende de um item marcado, leia a marcação antes da mudança.
Regra prática: Marque um item cujos vereditos diferem entre suas amostras, imprima sua contagem ao lado da marcação e deixe o item como está. Informe a taxa de oscilação com seu denominador, e diga que uma taxa baixa vale apenas para este assistente, este juiz e este conjunto.
Os testes da própria avaliação
A avaliação é código, e esse código pode estar errado de maneiras que parecem um resultado. Um erro no bootstrap, no leitor de veredictos ou na diferença pareada move um número da mesma forma que uma mudança no assistente faria. Por isso, a avaliação tem testes próprios, em uma pasta de testes dentro da biblioteca do livro, e cada módulo que o livro acrescenta traz os seus testes. Os testes verificam o código de pontuação. Eles não verificam o assistente. Um teste que passa diz que o código conta o que diz que conta. Não diz nada sobre se o assistente responde bem.
Esses testes rodam em um único processo, e os resultados são contados módulo por módulo. O exemplo então imprime o código de saída do pytest, a partir de 9.2.0. A referência de códigos de saída lista 0 como todos os testes coletados e aprovados, e 5 como nenhum teste coletado. Assim, uma execução que não testa nada aparece como 5, e não como uma aprovação silenciosa.
1"""Runs the book's own tests, lib/tests, in this process and prints how many passed and failed in each module, then pytest's2exit code. Exit code 0 means every test was collected and passed. Exit code 5 means nothing was collected, so the example3prints the code it got rather than a silent pass. No paths and no timings are printed: they vary from run to run."""4import lib # first: fixes the thread counts and seeds before anything else loads56from collections import Counter7from pathlib import Path89import pytest1011TESTS = Path(lib.__file__).resolve().parent / "tests" # read here, never printed121314class Outcomes:15 """Counts each test's outcome by module. A failed setup or teardown counts as a failure of its test."""1617 def __init__(self) -> None:18 self.passed = Counter()19 self.failed = Counter()2021 def pytest_runtest_logreport(self, report) -> None:22 # The node id starts with the file's path; keep only the module's name, so no path is printed.23 module = Path(report.nodeid.split("::")[0]).stem24 if report.when == "call" and report.passed:25 self.passed[module] += 126 elif report.failed:27 self.failed[module] += 1282930collector = Outcomes()31# -p no:terminal turns off pytest's own printing, which carries timings. That also removes the -q option, which belongs to32# the terminal reporter, so it is not passed. -p no:cacheprovider keeps .pytest_cache out of the working copy.33exit_code = pytest.main(34 [str(TESTS), "-p", "no:terminal", "-p", "no:cacheprovider"],35 plugins=[collector],36)3738modules = sorted(path.stem for path in TESTS.glob("test_*.py")) # every module, even one with no failures39print("tests by module (passed, failed):")40for module in modules:41 print(f" {module}: {collector.passed[module]} passed, {collector.failed[module]} failed")42print(f"total: {sum(collector.passed.values())} passed, {sum(collector.failed.values())} failed")43print(f"pytest exit code: {int(exit_code)}")
python own-tests-run.pytests by module (passed, failed):
test_bench: 11 passed, 0 failed
test_bias: 14 passed, 0 failed
test_both_orders: 14 passed, 0 failed
test_calibration: 9 passed, 0 failed
test_calibration_bootstrap: 8 passed, 0 failed
test_contract: 5 passed, 0 failed
test_gate: 11 passed, 0 failed
test_guard: 4 passed, 0 failed
test_judging: 3 passed, 0 failed
test_stats: 10 passed, 0 failed
test_support_verdict: 5 passed, 0 failed
test_testset: 5 passed, 0 failed
test_variance: 15 passed, 0 failed
total: 114 passed, 0 failed
pytest exit code: 0
A tabela mostra o resultado de cada módulo, com o que o módulo testa ao lado.
| Módulo | O que testa | Resultado |
|---|---|---|
| test_bench | Os carregadores e pontuadores do benchmark | 11 passed, 0 failed |
| test_bias | As faixas de comprimento, os veredictos ilegíveis, a direção da inversão e a diferença entre faixas | 14 passed, 0 failed |
| test_both_orders | O leitor pareado e as duas ordens: o retorno às respostas e os quatro tipos | 14 passed, 0 failed |
| test_calibration | Contagens do juiz contra humanos, concordância, kappa, TPR, TNR e a taxa de aprovação corrigida | 9 passed, 0 failed |
| test_calibration_bootstrap | O ponto de cruzamento e o intervalo bootstrap da taxa de aprovação corrigida | 8 passed, 0 failed |
| test_contract | Os formatos de resposta e de veredicto que o juiz e o assistente devem manter | 5 passed, 0 failed |
| test_gate | A regra do portão: reprovação somente quando o limite superior estiver abaixo de menos o limiar | 11 passed, 0 failed |
| test_guard | A regra da guarda de recusa e seu limiar, com linhas feitas à mão | 4 passed, 0 failed |
| test_judging | A leitura dos veredictos do juiz e o tipo de diferença pareada | 3 passed, 0 failed |
| test_stats | As funções auxiliares de impressão e o bootstrap com semente | 10 passed, 0 failed |
| test_support_verdict | O leitor de veredictos de fidelidade: SUPPORTED ou UNSUPPORTED na primeira linha | 5 passed, 0 failed |
| test_testset | O carregamento do conjunto de teste e as regras que olham entre os itens | 5 passed, 0 failed |
| test_variance | As contagens de veredictos por item sobre o conjunto de variância | 15 passed, 0 failed |
Os totais vêm por último: 114 passed, 0 failed, e o código de saída é 0, o código de uma execução em que todos os testes coletados passaram.
Leia a tabela como uma verificação dos instrumentos, e não do assistente. Execute esses testes primeiro no job do portão, para que um pontuador quebrado interrompa o job antes de ler uma taxa de aprovação. Nada que varie entre execuções é impresso: nem tempos nem caminhos. Um leitor pode executar o código novamente e comparar a saída linha por linha.
Regra prática: Execute os testes próprios da avaliação antes de qualquer execução que leia um número, e trate o código de saída 5 como falha, e não como aprovação. Um teste que falha no código de pontuação significa que os números ainda não são confiáveis, seja o que for que eles digam.
Executando como uma tarefa de framework
Equipes que já usam um framework de avaliação podem mapear as partes deste livro para os termos dele, e vale ver esse mapeamento uma vez. No Inspect AI 0.3.291, datado de 17 de novembro de 2026 no seu changelog,, uma tarefa é a receita de uma avaliação, composta no mínimo por um dataset, um solver e um scorer, como descreve a documentação do framework nessa versão. Nessa leitura, o conjunto de teste é o dataset, com uma amostra por item. O caminho do assistente, de recuperar e depois responder, é o solver, e as verificações e o juiz formam o scorer. O livro não executa esse mapeamento e não afirma fazê-lo. Em vez disso, o livro mantém um único ambiente de exemplo: um conjunto de arquivos que todos os exemplos de cada capítulo importam, fixados nas mesmas versões, de modo que o modelo de reprodução, as verificações e o portão sejam o mesmo código em todos os capítulos. Este capítulo descreve onde cada parte iria, para que um leitor que use um framework possa levar as partes para lá enquanto os exemplos do livro permanecem como estão.
Regra prática: Ao mapear uma avaliação para um framework, indique a versão do framework e a data de sua documentação. Mantenha o conjunto de teste, as verificações e o modelo de reprodução como os arquivos que os exemplos do livro executam, e trate o mapeamento como uma leitura da documentação até que alguém o execute.
Variantes no tráfego
Offline, o conjunto de teste e as respostas reproduzidas podem indicar qual variante é melhor nos itens que a equipe escreveu. Quando o assistente estiver em produção, uma equipe pode querer comparar duas variantes com perguntas reais, como dois prompts ou dois modelos, enviados cada um a uma parcela dos usuários. Isso é uma comparação, e ela só vale tanto quanto o modo como os usuários foram distribuídos entre as variantes. Se as pessoas que veem uma variante são justamente as que fazem perguntas mais difíceis, a diferença reflete essas pessoas e não a variante. A atribuição aleatória, e um intervalo lido da mesma forma que o restante deste capítulo lê um intervalo, são o que transforma uma comparação em produção em um teste. O guia de Kohavi e colaboradores, que o capítulo 10 cita, recomenda definir o poder e o efeito a detectar, e estimar a variabilidade, antes de o teste começar. Sem isso, uma comparação em produção é apenas uma lista de quem viu qual variante.
A tabela de feedback desta seção não é tráfego. Suas linhas são geradas. O voto de cada item de desenvolvimento é sorteado de um modelo declarado, com uma semente fixa. Uma resposta está certa com probabilidade 0.85. Um usuário que vê uma resposta errada dá um polegar para baixo com probabilidade 0.5 e um polegar para cima com 0.05. Um usuário que vê uma resposta certa dá um polegar para baixo com 0.03 e um polegar para cima com 0.15. A maioria dos itens não recebe nenhum voto. Se cada resposta estava certa é sorteado e depois descartado, como aconteceria em um log real, de modo que a tabela guarda apenas os votos. É um dispositivo didático, e seus números são o que o modelo declarado produz. Eles nada dizem sobre este assistente.
1"""A generated table of thumbs-up and thumbs-down rows over the eighty dev items, with what such a table can show and what it2can't. The rows are generated from a stated model with a fixed seed, not taken from users, so the table is a teaching3device only.45The model: an answer is right with probability 0.85. A user who sees a wrong answer gives thumbs-down with probability 0.5 and6thumbs-up with 0.05; one who sees a right answer gives thumbs-down with 0.03 and thumbs-up with 0.15. Most items get no vote.7The table keeps the votes only: whether each answer was right is drawn and then dropped, as it would be in a real log."""8import lib # first: fixes the thread counts and seeds before anything else loads910import numpy as np1112from lib import SEED13from lib.stats import pct14from lib.testset import load_items1516P_RIGHT = 0.8517P_DOWN_WRONG, P_UP_WRONG = 0.50, 0.0518P_DOWN_RIGHT, P_UP_RIGHT = 0.03, 0.151920rng = np.random.default_rng(SEED) # one generator for the whole table, so the same seed gives the same rows21items = [item.id for item in load_items(split="dev")]22rows = [] # (item id, vote) for each item that got a vote23for item_id in items:24 right = rng.random() < P_RIGHT # hidden: the table has no column for it25 draw = rng.random()26 down, up = (P_DOWN_RIGHT, P_UP_RIGHT) if right else (P_DOWN_WRONG, P_UP_WRONG)27 if draw < down:28 rows.append((item_id, "thumbs-down"))29 elif draw < down + up:30 rows.append((item_id, "thumbs-up"))3132print("generated rows from a stated model, not user feedback (seed 0)")33print("item vote")34for item_id, vote in rows:35 print(f"{item_id} {vote}")3637ups = sum(vote == "thumbs-up" for _, vote in rows)38downs = sum(vote == "thumbs-down" for _, vote in rows)39voted = len({item_id for item_id, _ in rows})40print(f"dev items: {len(items)}")41print(f"items with a vote: {voted}")42print(f"items nobody voted on: {len(items) - voted}")43print(f"thumbs-down among those who voted: {pct(downs, ups + downs)}")44print(f"thumbs-up among those who voted: {pct(ups, ups + downs)}")45print("what the table can show: the share of each kind of vote, among the votes cast, with its n.")46print("what it can't show: anything about the items nobody voted on; whether a thumbs-up answer was right.")
python feedback-table.pygenerated rows from a stated model, not user feedback (seed 0)
item vote
q-0002 thumbs-down
q-0006 thumbs-down
q-0007 thumbs-down
q-0008 thumbs-up
q-0009 thumbs-up
q-0011 thumbs-up
q-0020 thumbs-down
q-0027 thumbs-down
q-0028 thumbs-up
q-0030 thumbs-up
q-0035 thumbs-up
q-0040 thumbs-down
q-0056 thumbs-down
q-0057 thumbs-down
q-0059 thumbs-down
q-0060 thumbs-up
q-0064 thumbs-down
q-0070 thumbs-down
q-0072 thumbs-up
q-0079 thumbs-down
q-0080 thumbs-down
dev items: 80
items with a vote: 21
items nobody voted on: 59
thumbs-down among those who voted: 61.9% (13 of 21)
thumbs-up among those who voted: 38.1% (8 of 21)
what the table can show: the share of each kind of vote, among the votes cast, with its n.
what it can't show: anything about the items nobody voted on; whether a thumbs-up answer was right.
Pelo modelo declarado, apenas 21 dos 80 itens de desenvolvimento recebem um voto, e 59 não recebem nenhum. Assim, a tabela diz pouco sobre os demais itens.
Um voto não é um rótulo de correção, e esta tabela mostra por quê. Pelo modelo declarado, as respostas estão certas 85% das vezes, e ainda assim a maioria dos votos é polegar para baixo, porque uma resposta errada recebe um voto com muito mais frequência. Entre os votos dados, o polegar para baixo é 61.9% (13 of 21). O polegar para cima é 38.1% (8 of 21).
Uma tabela de votos pode mostrar a parcela de cada tipo de voto, entre os votos dados, com a contagem ao lado, e as últimas linhas do exemplo dizem exatamente isso. Ela não consegue mostrar se uma resposta com polegar para cima estava certa, pois a tabela não tem coluna de correção. Ela nada diz sobre os itens em que ninguém votou, e um voto vem de alguém que escolheu votar no que escolheu ler.
Joachims e colaboradores estudaram clicks em resultados de busca em 2005 e constataram que eles são informativos, mas enviesados, de modo que um click não é um julgamento absoluto de relevância. Eles relatam que preferências relativas derivadas de clicks são razoavelmente precisas em média, em seu artigo sobre a interpretação de dados de clickthrough. Este livro usa essa conclusão apenas como analogia, e essa leitura é do próprio livro. Um polegar para cima é um voto, não um rótulo. Uma resposta certa ainda pode receber um polegar para baixo, e a tabela não tem como dizer quais votos são esses.
Dois grupos de usuários são comparados de modo diferente dos itens pareados acima. Cada usuário vê uma variante, portanto os dois grupos são separados, e o intervalo para a diferença entre eles é um cálculo diferente do pareado que este capítulo usa. O capítulo 8 trata da comparação pareada que este capítulo usa. Ele não trata de um intervalo para dois grupos separados.
Uma tabela de votos também não pode comparar variantes a menos que cada voto esteja ligado à variante que o usuário viu. Esta tabela não tem coluna de variante, então não pode comparar nada. Uma comparação em produção precisaria dessa coluna, da atribuição aleatória descrita acima e de um intervalo. Se poucos itens recebem voto, como nesta tabela gerada, o intervalo seria amplo, e a maioria dos itens não teria voto para comparar.
Antes que uma tabela real de votos pudesse ser confiável, ela precisaria de três coisas. Cada voto precisaria estar ligado à variante que o usuário viu. A parcela de itens que recebem voto precisaria ser informada com sua contagem, pois uma tabela de votos fala apenas dos itens que foram votados. E uma amostra de seus votos precisaria ser conferida quanto à correção, para que um polegar para cima ou para baixo possa ser lido em relação ao que deveria medir.
As partes do livro somam uma avaliação para um recurso seu. Um conjunto de teste rotulado vem primeiro (capítulo 3), depois as verificações em código (capítulo 4). Em seguida vêm um juiz com uma rubrica e um erro medido (capítulo 5, capítulo 6). Uma comparação informa seu intervalo e n (capítulo 8), e o portão no CI lê tudo isso. O capítulo 7 diz onde o juiz deixa de ser confiável. O capítulo 9 e o capítulo 10 aplicam as mesmas contagens a fundamentação e a recusa.
O livro deixa três assuntos para outras obras. Uma Introdução à Relevância em Busca trata de métricas de ranqueamento. Harnesses de Agentes trata de tarefas que levam várias etapas. Observabilidade para Aplicações com LLM trata de acompanhar uma requisição única por recuperação e modelo, e de contar o custo de cada requisição. Essa obra está planejada, por isso é citada aqui e não linkada.
Regra prática: Não compare variantes a partir do tráfego sem atribuição aleatória e sem a variante registrada ao lado de cada voto ou resposta. Leia uma tabela de votos como uma parcela dos votos dados, com sua contagem, e nunca como medida de correção.
Este capítulo, nesta edição
Edição 2026.11.3Exemplos aprovados em 21 de nov de 20264 de 4 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.3.