Verifique se as respostas se apoiam nos documentos citados, na versão pedida
Cerca de 25 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.3. Leia o original
Ao final deste capítulo, você saberá contar se as citações de uma resposta sustentam o que ela afirma, se cada afirmação repousa nas seções que o assistente recebeu, se a resposta está correta para a versão que o leitor pediu e se a recuperação alcançou a seção certa no caminho.
Uma resposta correta ainda pode ser uma resposta ruim. O assistente deste livro responde a perguntas sobre o sablefile a partir da sua documentação, e uma resposta é aprovada quando corresponde à resposta de referência para a versão a que a pergunta se refere. Uma resposta pode passar nesse teste e, mesmo assim, citar uma seção que não diz o que a sua frase diz, acrescentar um detalhe que nenhuma seção traz ou tirar seus fatos de outra versão da documentação. Uma taxa de aprovação não enxerga nada disso. Um leitor que confere a citação ao lado de uma afirmação consegue perceber, e é por isso que o assistente é solicitado a citar.
Quatro verificações acompanham a taxa de aprovação, e cada uma tem sua própria contagem sobre seu próprio denominador. A precisão das citações pergunta se cada citação nomeia uma seção que o item lista como de apoio. A fidelidade pergunta se cada afirmação está nas seções que foram mostradas ao assistente. A correção de versão pergunta se a resposta se ajusta à versão pedida. O resultado frente ao caminho pergunta se uma aprovação veio com a seção em mãos e se uma reprovação a tinha. A precisão das citações e a fidelidade deixam de fora as recusas, pois uma recusa não faz afirmação alguma a verificar. A correção de versão e a tabela de recuperação mantêm as recusas, como faz a taxa de aprovação, e cada uma informa quantas recusas contém.
O que significa "fundamentada" aqui
Uma resposta é fundamentada quando um leitor que segue as suas citações encontra a afirmação onde a citação diz que ela está, na versão sobre a qual ele perguntou. Três coisas precisam valer para isso. A citação precisa existir naquela versão e sustentar a frase a que está ligada. Toda afirmação da resposta precisa decorrer das seções que o assistente leu. E a resposta precisa estar certa para aquela versão, e não apenas certa para alguma outra versão que usa as mesmas palavras.
Imagine um leitor que pergunta quanto tempo uma busca remota espera antes de desistir. Suponha que a resposta dê uma resposta plausível e cite a seção sobre a busca de modelos remotos, mas essa seção nunca diz quanto dura a espera. Um leitor tomaria a resposta como fundamentada, e a citação parece correta. O leitor que abre a seção não encontra nada que sustente o número. Uma taxa de acerto contaria essa resposta como correta se o número coincidisse com a referência. A fidelidade é a verificação que lê as seções, por meio de um juiz. A verificação de citações lê apenas identificadores, e deixa isso claro.
Essas falhas são diferentes, e cada uma precisa de sua própria contagem. Uma resposta pode ter uma citação que a sustenta e, ainda assim, afirmar um detalhe que a seção deixa de fora; portanto, a precisão das citações não mostra fidelidade. Uma resposta pode ser fiel a uma seção de uma versão e estar errada para outra versão; portanto, a fidelidade não mostra a correção para a versão. E uma resposta pode estar certa e bem citada enquanto a etapa de recuperação nunca chegou à seção em que ela se apoia. O resultado comparado ao caminho existe para encontrar esse caso.
Regra prática: Dê a cada verificação a sua própria contagem sobre o seu próprio denominador, e trate uma aprovação como o início da leitura, e não como o fim dela.
Precisão das citações
Uma citação é uma afirmação sobre a documentação: esta seção, nesta versão, sustenta a frase a que está anexada. Como qualquer afirmação, ela pode estar errada. A seção pode existir e dizer outra coisa. Pode pertencer a outra versão. Ou a resposta pode citar uma seção que o item não lista. O Primer trata da verificação no nível da frase, verificando o que um item citado sustenta, e verificando citações contra o contexto trata do contexto que um modelo recebeu. A verificação deste livro é mais simples, e verificações de citação no capítulo 4 apresenta seus quatro resultados. Ela compara cada ID citado com a lista de seções de sustentação do item para a versão consultada. Nunca lê a seção, por isso não diz nada sobre a frase.
O código imprime duas contagens a partir das mesmas respostas. A taxa de citação conta cada citação sustentada em itens respondidos. A taxa de itens conta um item respondido uma única vez se pelo menos uma de suas citações for sustentada, de modo que uma boa citação basta para o item. Uma citação a uma seção da versão consultada que o item não lista é impressa como não listada. Essa seção pode perfeitamente estar correta, por isso a verificação não a chama de errada, e não abre a seção para descobrir. Ler uma citação não listada é uma decisão manual. Se a seção sustenta a frase, a lista de seções de sustentação do item está incompleta, e o responsável pelo conjunto de teste deve acrescentá-la. Se não sustenta, a citação está errada, e a resposta deve ser lida como uma citação falha.
Execute-a nas duas divisões e leia a linha do item antes da linha de citação.
1"""Counts the baseline's answered items that cite a supporting section of the asked version, dev and held-out apart.23An item counts once, and only if one of its citations is supported; its other citations sit in the citation lines. A decline4is not an answer, so it is left out of every count. The check matches each cited ID against the item's listed supporting5section IDs for its asked version. It never reads the section's text, so it does not check what the sentence says.6The first line of each split is the point: the item rate."""7import lib # first: fixes the thread counts and seeds before anything else loads89from lib.contract import citation_outcomes, parse_reply, section_ids_by_version10from lib.prompts import P1_SHA25611from lib.replay import ReplayModel12from lib.stats import pct13from lib.testset import load_items1415ids = section_ids_by_version() # every version's section IDs, read from the docs, for telling wrong-version from missing16model = ReplayModel("assistant-baseline", P1_SHA256) # the baseline's replies, sample 0, made from prompt P1171819def supporting_ids(item):20 """The item's supporting section IDs in its asked version. Another version's listed sections are not counted here."""21 return frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)222324for split in ("dev", "held-out"):25 declined = 026 results = {} # item id -> its citation outcomes, for each answered item27 for item in load_items(split=split):28 reply = parse_reply(model.reply(item.id, 0))29 if reply.declined:30 declined += 131 else:32 results[item.id] = citation_outcomes(reply, item.version, supporting_ids(item), ids)33 # An answer to an unanswerable item lists no section of its asked version, so it can never count as supported here.34 outcomes = [outcome for found in results.values() for outcome in found] # every citation, in item order35 with_support = [item_id for item_id, found in results.items() if "supported" in found]36 no_support = sorted(set(results) - set(with_support))37 print(f"{split} declined items, left out: {declined}")38 print(f"{split} answered items: {len(results)}")39 print(f"{split} answered items citing a supporting section of the asked version: {pct(len(with_support), len(results))}")40 print(f"{split} answered items with no supported citation: {len(no_support)}")41 print(" " + (", ".join(no_support) or "none"))42 print(f"{split} citations: {len(outcomes)}")43 print(f"{split} citations that are supported: {pct(outcomes.count('supported'), len(outcomes))}")44 print(f"{split} citations that are unlisted: {pct(outcomes.count('unlisted'), len(outcomes))}")45 print(f"{split} citations that are wrong-version or missing: "46 f"{pct(outcomes.count('wrong-version') + outcomes.count('missing'), len(outcomes))}")
python citation-accuracy-counts.pydev declined items, left out: 23
dev answered items: 57
dev answered items citing a supporting section of the asked version: 94.7% (54 of 57)
dev answered items with no supported citation: 3
q-0005, q-0057, q-0058
dev citations: 60
dev citations that are supported: 93.3% (56 of 60)
dev citations that are unlisted: 6.7% (4 of 60)
dev citations that are wrong-version or missing: 0.0% (0 of 60)
held-out declined items, left out: 15
held-out answered items: 25
held-out answered items citing a supporting section of the asked version: 96.0% (24 of 25)
held-out answered items with no supported citation: 1
q-0090
held-out citations: 33
held-out citations that are supported: 93.9% (31 of 33)
held-out citations that are unlisted: 6.1% (2 of 33)
held-out citations that are wrong-version or missing: 0.0% (0 of 33)
No desenvolvimento, a taxa de itens é 94.7% (54 of 57).
No desenvolvimento, 3 itens respondidos não têm nenhuma citação sustentada, e a saída os nomeia. No conjunto de teste reservado, a contagem é 1.
A taxa de citação no desenvolvimento é 93.3% (56 of 60). As citações não listadas no desenvolvimento são 6.7% (4 of 60), que a saída relata e não conta como erros.
No conjunto reservado, a taxa de itens é 96.0% (24 of 25), e a taxa de citação é 93.9% (31 of 33). O conjunto reservado tem apenas 25 itens respondidos, de modo que um único item altera muito a sua taxa. Uma diferença entre os conjuntos exigiria um intervalo antes que alguém a considerasse real, e intervalos e tamanho da amostra explica como construir um.
As citações que estão em versão errada ou ausentes são as que estariam erradas por um motivo que a verificação consegue nomear. No desenvolvimento, são 0.0% (0 of 60). No conjunto reservado, são 0.0% (0 of 33). Assim, as taxas de citação ficam abaixo de 100% por causa das citações não listadas, e uma pessoa precisa lê-las
As duas taxas podem divergir por um motivo simples. Um item com uma citação sustentada e uma citação não listada entra na taxa de itens e reduz a taxa de citação. Ler as duas mostra se as falhas estão em itens inteiros ou em citações isoladas dentro de itens que, de resto, se sustentam.
A ideia por trás da verificação foi estudada fora deste livro. Gao e colaboradores (2023), no EMNLP 2023 e no arXiv, construíram um benchmark para citações em respostas geradas, e relataram que muitas respostas de modelos fortes não estavam totalmente sustentadas pelas passagens citadas. A configuração deles não era a deste livro, por isso nenhum número é transportado deles. O artigo é citado pela ideia.
Regra prática: Leia a taxa de itens e a taxa de citação em conjunto, e leia cada citação não listada antes de alterar um prompt. Uma citação não listada é uma questão para a documentação, não um erro a contar.
Fidelidade
A precisão das citações roda sem modelo, mas suas contagens mostram quantas citações apontam para uma seção listada, não se cada frase se sustenta. Fidelidade é a pergunta seguinte, e é a que captura afirmações que não têm citação alguma.
A precisão das citações verifica apenas as frases que trazem uma citação. Uma afirmação que a resposta faz sem citação escapa a essa verificação, e também escapa uma afirmação que uma seção citada apoia só em parte. A fidelidade faz uma pergunta mais ampla: toda afirmação da resposta decorre das seções que o assistente recebeu?
O Ragas (Es e colaboradores, 2023, também um preprint) pontua a fidelidade como a proporção das afirmações de uma resposta que o contexto sustenta. Ele divide a resposta em afirmações e verifica cada uma. Este livro faz uma pergunta por resposta. O prompt de fidelidade em lib/prompts.py entrega ao juiz as seções e a resposta. O juiz lê a resposta afirmação por afirmação e escreve VERDICT: SUPPORTED na primeira linha somente se todas as afirmações se sustentarem. Caso contrário, escreve VERDICT: UNSUPPORTED, seguido de uma frase com o motivo.
A diferença em relação à precisão das citações aparece no meio de uma resposta. Suponha que uma resposta tenha duas frases. A primeira traz uma citação para uma seção que a apoia, e a segunda não tem nenhuma, porque acrescenta um detalhe que a seção não cobre. A precisão das citações pontua a primeira frase e nada diz sobre a segunda. A fidelidade lê a resposta inteira, então pode marcar a resposta como não sustentada apenas pela segunda frase. Nenhuma das duas verificações substitui a outra, e por isso ambas são mantidas.
Ninguém comparou os veredictos deste juiz com os de uma pessoa, então toda taxa de fidelidade aqui é não calibrada. O juiz também é o próprio modelo do assistente, Qwen3-4B-Instruct-2507, portanto avalia respostas que esse mesmo modelo escreveu. A autopreferência explica por que isso importa, e por que este livro não consegue testá-la. Calibrar o juiz exigiria avaliações humanas dessas respostas, que este livro não possui. A calibre o juiz descreve o método, que compara o juiz com avaliações feitas à mão. Como essas taxas não são calibradas, não há nada que a premissa de transferência possa transportar, e os limites em onde parar valem para elas por inteiro.
1"""The faithfulness rate of assistant-baseline's answered items, as judged in judge-faithfulness-baseline, dev and held-out apart.23An answered item is one the baseline did not decline and whose reply is not empty; a decline is left out. The judge writes4SUPPORTED or UNSUPPORTED on its first line. A reply that is neither is printed by item ID and left out of the denominator,5never counted as UNSUPPORTED. The judge is uncalibrated: this book has no human ratings for it, so the rates are not6corrected for its errors and are not a calibrated measure. When every readable verdict is the same, the percentile7bootstrap cannot vary, so the example says so and prints the exact binomial bound for n of n instead."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.contract import parse_reply11from lib.judging import parse_support_verdict12from lib.prompts import FAITH_SHA256, P1_SHA25613from lib.replay import ReplayModel14from lib.stats import bootstrap_mean, interval_pct, pct15from lib.testset import load_items1617answers = ReplayModel("assistant-baseline", P1_SHA256) # the baseline's replies, sample 0, made from prompt P118judge = ReplayModel("judge-faithfulness-baseline", FAITH_SHA256) # the judge's replies, made from the faithfulness prompt1920print("judge: judge-4b, uncalibrated (no human ratings in this book)")21for split in ("dev", "held-out"):22 answered = []23 for item in load_items(split=split):24 reply = parse_reply(answers.reply(item.id, 0))25 if not reply.declined and reply.text:26 answered.append(item.id)27 readable = {} # item id -> 1.0 for SUPPORTED, 0.0 for UNSUPPORTED28 for item_id in answered:29 raw = judge.reply(item_id, 0)30 verdict = parse_support_verdict(raw)31 if verdict is None:32 line = next((ln.strip().strip("*`").strip() for ln in raw.splitlines() if ln.strip()), "")33 print(f'{split} unreadable verdict, left out: {item_id} ("{line}")')34 else:35 readable[item_id] = 1.0 if verdict == "SUPPORTED" else 0.036 scores = list(readable.values())37 lo, hi = bootstrap_mean(scores) # level 0.95; seed SEED, 2,000 resamples38 print(f"{split} answered items: {len(answered)}")39 print(f"{split} unreadable verdicts: {len(answered) - len(readable)}")40 print(f"{split} faithfulness rate: {pct(int(sum(scores)), len(scores))}")41 print(f"{split} 95% interval of the faithfulness rate: {interval_pct(lo, hi)}")42 if len(set(scores)) == 1: # every readable verdict is the same, so resampling cannot vary43 print(f"{split} bootstrap interval is degenerate: all {len(scores)} readable verdicts are the same")44 if sum(scores) == len(scores):45 print(f"{split} exact 95% lower bound for {len(scores)} of {len(scores)}: {100 * 0.025 ** (1 / len(scores)):.1f}%")46 if split == "dev":47 unfaithful = sorted(item_id for item_id, score in readable.items() if score == 0.0)48 print(f"dev unfaithful items, first five: {', '.join(unfaithful[:5])}")
python faithfulness-rate.pyjudge: judge-4b, uncalibrated (no human ratings in this book)
dev answered items: 57
dev unreadable verdicts: 0
dev faithfulness rate: 94.7% (54 of 57)
dev 95% interval of the faithfulness rate: [87.7%, 100.0%]
dev unfaithful items, first five: q-0013, q-0029, q-0055
held-out answered items: 25
held-out unreadable verdicts: 0
held-out faithfulness rate: 100.0% (25 of 25)
held-out 95% interval of the faithfulness rate: [100.0%, 100.0%]
held-out bootstrap interval is degenerate: all 25 readable verdicts are the same
held-out exact 95% lower bound for 25 of 25: 86.3%
O exemplo pega os itens respondidos da linha de base, deixa de fora as recusas e pergunta ao juiz sobre cada um. Ele imprime uma taxa apenas sobre os veredictos que consegue ler. Uma resposta que não é nem SUPPORTED nem UNSUPPORTED é impressa item por item e fica fora do denominador. Ela nunca é contada como falha, como explica veredicto primeiro.
A taxa de fidelidade não calibrada no dev é 94.7% (54 of 57). Seu intervalo é [87.7%, 100.0%]. O topo desse intervalo fica na borda superior da escala de taxas, porque um bootstrap não consegue reamostrar além dela. O intervalo continua largo, o que é a leitura honesta de 57 itens respondidos.
A taxa de fidelidade não calibrada no held-out é 100.0% (25 of 25). O intervalo impresso é [100.0%, 100.0%], mas isso não é um intervalo. A saída diz que o bootstrap é degenerado: all 25 readable verdicts are the same. Uma reamostragem de itens que todos passam só pode devolver a mesma taxa, então o bootstrap não diz nada sobre onde a taxa está.
O limite inferior exato de 95% é 86.3%. Se a taxa verdadeira estivesse abaixo desse limite, a aprovação de todas as respostas do held-out aconteceria com probabilidade inferior a 2.5%. O limite é 0.025 elevado a 1/n. Ele mostra que o juiz aprovou essas respostas, numa divisão pequena demais para indicar onde a taxa está. Não leia o número do held-out como uma constatação de que o assistente é fiel.
As duas verificações imprimem suas próprias listas. A saída de citações nomeia os itens sem citação sustentada, e a saída de fidelidade nomeia os primeiros itens infiéis do dev. Leia as duas listas lado a lado, já que este capítulo não presume que nomeiem os mesmos itens.
Regra prática: Coloque "não calibrada" ao lado de cada taxa de fidelidade, e leia os primeiros itens infiéis antes de confiar na taxa. Uma verificação de fidelidade mostra onde o juiz diz que uma afirmação não é sustentada. Ela não mostra que o juiz está certo.
Correção por versão
O sablefile tem três versões de sua documentação, 1.0, 1.1 e 2.0, e algumas perguntas têm respostas diferentes em cada uma delas. Uma resposta pode estar fundamentada em uma seção da 1.1 e ainda assim estar errada para um leitor que usa a 2.0. O livro chama esses casos de itens dependentes de versão. Cada um tem uma resposta de referência para a versão que o leitor perguntou, e sua verificação pergunta se a resposta coincide com essa referência. São 17 deles no dev e 8 no held-out.
Os itens dependentes de versão entram na taxa de acerto junto com todos os outros itens, e também têm contagem própria, ao lado dela. Uma resposta a um desses itens é julgada pela referência da versão perguntada, de modo que uma resposta correta para outra versão é considerada falha. Esse erro pareceria um assistente fraco se fosse apenas misturado à taxa geral. A taxa de respostas julgadas corretas é a contagem apenas dos itens dependentes de versão, de modo que um erro de versão aparece em uma linha própria, e uma equipe pode ver se uma mudança na recuperação alterou esse número. As recusas permanecem nesse denominador, como ocorre na taxa de acerto, e cada divisão informa quantas delas contém.
Uma citação de versão errada é uma contagem separada. Trata-se de uma citação a uma seção que existe apenas em outra versão. Uma resposta pode estar correta para a versão perguntada e ainda assim citar uma seção de outra versão, e um leitor que copiar essa citação chegará à documentação errada.
Esta verificação enxerga apenas o que o identificador informa. Uma citação traz um identificador, não uma versão. A maioria dos identificadores se repete entre versões, de modo que um identificador de seção que aparece na 1.0, na 1.1 e na 2.0 parece igual em cada uma delas. Um identificador presente em todas as versões nunca pode ser sinalizado como de versão errada, qualquer que seja a versão perguntada pelo leitor. A verificação só pode sinalizar uma citação quando a versão perguntada não possui o identificador e outra versão o possui. O índice também importa. Uma citação a outra versão só é possível quando as seções dessa versão estão no índice a partir do qual a resposta foi construída, de modo que a contagem precisa ser relida quando o índice muda, e um zero obtido com um índice antigo não diz nada sobre um índice novo.
Aqui são lidas duas variantes. A linha de base recupera informações apenas do índice da versão perguntada. A variante sem filtro recupera a partir dos índices de todas as versões juntas, e mostra a versão de cada seção no cabeçalho dela, para que o modelo possa ver de onde vem cada seção. A variante sem filtro é a que poderia citar outra versão, já que recebe essas seções.
1"""Reads the 25 version-dependent items for two variants: whether the judge passed the answer for the asked version, and whether a2citation names a section that exists only in another version.34The judge's verdict for each variant is read from its own recording, and an unreadable verdict is printed and left out of the5pass rate, never counted as a fail. A declined reply has a verdict like any other reply, so it stays in the denominator; its6count is printed beside each rate. A wrong-version citation is counted per item, over every item, so a zero shows as 0 of 25.7The last lines list the items where the two variants disagree, to read item by item."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.calibration import readable_verdicts11from lib.contract import citation_outcomes, parse_reply, section_ids_by_version12from lib.prompts import P1_SHA256, REF_SHA25613from lib.replay import ReplayModel14from lib.stats import pct15from lib.testset import load_items1617ids = section_ids_by_version() # every version's section IDs, so a section of another version is known as one18# label, the assistant's recording, the judge's recording of that assistant's replies19VARIANTS = (("baseline", "assistant-baseline", "judge-answers-baseline"), ("unfiltered", "assistant-unfiltered", "judge-answers-unfiltered"))20items = [item for item in load_items() if item.kind == "version-dependent"]21item_ids = [item.id for item in items]22listed = {item.id: frozenset(s.section_id for s in item.supporting_sections if s.version == item.version) for item in items}23verdict, wrong = {}, {} # label -> {item id: PASS or FAIL, readable only}; label -> item ids with a wrong-version citation24for label, assistant, judge in VARIANTS:25 verdict[label], unreadable = readable_verdicts(judge, item_ids, REF_SHA256)26 for item_id, first in unreadable:27 print(f'{label} unreadable verdict, left out: {item_id} ("{first}")')28 replies = ReplayModel(assistant, P1_SHA256)29 wrong[label] = {item.id for item in items30 if "wrong-version" in citation_outcomes(parse_reply(replies.reply(item.id, 0)), item.version, listed[item.id], ids)}31 for split in ("dev", "held-out"):32 split_items = [item for item in items if item.split == split]33 readable = [item.id for item in split_items if item.id in verdict[label]]34 passed = sum(verdict[label][item_id] == "PASS" for item_id in readable)35 print(f"{label} {split} version-dependent items: {len(split_items)}")36 print(f"{label} {split} declined replies, counted in the denominator: "37 f"{sum(parse_reply(replies.reply(item.id, 0)).declined for item in split_items)}")38 print(f"{label} {split} judged correct for the asked version: {pct(passed, len(readable))}")39 print(f"{label} {split} citing a wrong-version section: "40 f"{pct(sum(item.id in wrong[label] for item in split_items), len(split_items))}")41 print(f"{label} all version-dependent items citing a wrong-version section: {pct(len(wrong[label]), len(items))}")4243both = [item_id for item_id in item_ids if item_id in verdict["baseline"] and item_id in verdict["unfiltered"]]44print(f"items with a readable verdict in both variants: {len(both)}")45differ = [i for i in both if verdict["baseline"][i] != verdict["unfiltered"][i]]46print(f"items where the verdicts differ: {len(differ)}")47print(" " + (", ".join(differ) or "none"))48flag_differ = [i for i in item_ids if (i in wrong["baseline"]) != (i in wrong["unfiltered"])]49print(f"items where the wrong-version flag differs: {len(flag_differ)}")50print(" " + (", ".join(flag_differ) or "none"))
python version-correct-answers.pybaseline dev version-dependent items: 17
baseline dev declined replies, counted in the denominator: 4
baseline dev judged correct for the asked version: 64.7% (11 of 17)
baseline dev citing a wrong-version section: 0.0% (0 of 17)
baseline held-out version-dependent items: 8
baseline held-out declined replies, counted in the denominator: 2
baseline held-out judged correct for the asked version: 75.0% (6 of 8)
baseline held-out citing a wrong-version section: 0.0% (0 of 8)
baseline all version-dependent items citing a wrong-version section: 0.0% (0 of 25)
unfiltered dev version-dependent items: 17
unfiltered dev declined replies, counted in the denominator: 5
unfiltered dev judged correct for the asked version: 52.9% (9 of 17)
unfiltered dev citing a wrong-version section: 0.0% (0 of 17)
unfiltered held-out version-dependent items: 8
unfiltered held-out declined replies, counted in the denominator: 2
unfiltered held-out judged correct for the asked version: 75.0% (6 of 8)
unfiltered held-out citing a wrong-version section: 0.0% (0 of 8)
unfiltered all version-dependent items citing a wrong-version section: 0.0% (0 of 25)
items with a readable verdict in both variants: 25
items where the verdicts differ: 6
q-0003, q-0021, q-0022, q-0033, q-0082, q-0085
items where the wrong-version flag differs: 0
none
Em todos os itens dependentes de versão, a proporção de citações de versão errada é 0.0% (0 of 25) na linha de base e 0.0% (0 of 25) na variante sem filtro. Um zero diz apenas que a verificação não sinalizou nenhum identificador. O próximo exemplo mostra quão poucos identificadores ela poderia ter sinalizado.
1"""The two counts behind the version check, and the version-dependent items where the variants' verdicts differ, by split.23A wrong-version citation is one whose ID exists only in another version, so an ID that several versions share cannot be4attributed to one of them. This prints how many section IDs are found in one version only, then how many citations to the5version-dependent items name a shared ID, for each variant. The last lines list the items where the verdicts differ, by split."""6import lib # first: fixes the thread counts and seeds before anything else loads78from collections import Counter910from lib.calibration import readable_verdicts11from lib.contract import parse_reply, section_ids_by_version12from lib.prompts import P1_SHA256, REF_SHA25613from lib.replay import ReplayModel14from lib.stats import pct15from lib.testset import load_items1617ids = section_ids_by_version()18shared = Counter(i for found in ids.values() for i in found) # how many versions each section ID appears in19print("section IDs found in one version only, by version: "20 + ", ".join(f"{v} {sum(shared[i] == 1 for i in found)}" for v, found in ids.items()))21items = [item for item in load_items() if item.kind == "version-dependent"]22split_of = {item.id: item.split for item in items}23verdict = {} # label -> {item id: PASS or FAIL}, readable only24for label, assistant, judge in (("baseline", "assistant-baseline", "judge-answers-baseline"),25 ("unfiltered", "assistant-unfiltered", "judge-answers-unfiltered")):26 replies = ReplayModel(assistant, P1_SHA256)27 cited = [cid for item in items for cid in parse_reply(replies.reply(item.id, 0)).citations]28 print(f"{label} citations to a section ID found in more than one version: "29 f"{pct(sum(shared[cid] > 1 for cid in cited), len(cited))}")30 verdict[label], _ = readable_verdicts(judge, list(split_of), REF_SHA256)31differ = [i for i in verdict["baseline"] if i in verdict["unfiltered"] and verdict["baseline"][i] != verdict["unfiltered"][i]]32for split in ("dev", "held-out"):33 part = [i for i in differ if split_of[i] == split]34 print(f"{split} items where the verdicts differ: {len(part)}")35 print(" " + (", ".join(part) or "none"))
python version-check-detail.pysection IDs found in one version only, by version: 1.0 0, 1.1 0, 2.0 4
baseline citations to a section ID found in more than one version: 87.0% (20 of 23)
unfiltered citations to a section ID found in more than one version: 63.2% (12 of 19)
dev items where the verdicts differ: 4
q-0003, q-0021, q-0022, q-0033
held-out items where the verdicts differ: 2
q-0082, q-0085
Os identificadores de seção encontrados em apenas uma versão, contados por versão, são 1.0 0, 1.1 0, 2.0 4. Um identificador encontrado em mais de uma versão ainda pode ser sinalizado, mas apenas para um leitor em uma versão que não o possui. Na linha de base, a proporção de citações a itens dependentes de versão que apontam um identificador compartilhado é 87.0% (20 of 23). Na variante sem filtro, é 63.2% (12 of 19).
As taxas de respostas julgadas corretas diferem, embora cada uma seja lida sobre uma divisão pequena. No dev, a linha de base é julgada correta em 64.7% (11 of 17).
A variante sem filtro é julgada correta em 52.9% (9 of 17). Nesses itens, a variante sem filtro passa em menos casos.
No held-out, a linha de base é julgada correta em 75.0% (6 of 8). A variante sem filtro tem a mesma taxa, mas passa em itens diferentes. Os vereditos vão em direções opostas em q-0082 e q-0085, e os demais itens do held-out concordam.
Nas duas variantes, os vereditos diferem em 6 itens, de um total de 25 com veredito legível em ambas. No dev, 4 deles diferem, e no held-out, 2. A saída lista esses itens por divisão.
Não é calculado nenhum intervalo para essas diferenças, e uma divisão de dev deste tamanho é pequena. Por isso este capítulo relata as contagens e não afirma que nenhuma das variantes seja melhor ou pior. As contagens dizem três coisas: nesses itens, a variante sem filtro passou em menos casos, nenhuma citação foi sinalizada como de versão errada em nenhuma das variantes, e os vereditos divergentes são o primeiro lugar a ser lido.
Regra prática: Leia o identificador de cada citação junto com a versão da resposta ao lado. Um zero nesta verificação significa nenhum identificador sinalizado, não ausência de citação de versão errada. Mantenha os itens dependentes de versão em uma contagem própria, ao lado da taxa de acerto, para que um erro de versão apareça em uma linha própria.
Resultado e caminho
Resultado é se a resposta foi aprovada. Caminho é o que as etapas anteriores à resposta alcançaram. Neste livro, o caminho é curto: uma recuperação e depois uma resposta. Duas combinações exigem as duas contagens. Uma aprovação cuja seção de apoio nunca chegou ao modelo veio de outra fonte, talvez do próprio conhecimento do modelo, e isso é um alerta mesmo quando o veredito está correto. Uma reprovação com a seção recuperada é o caso que as demais verificações existem para explicar.
Execuções com várias etapas têm caminhos mais longos. Agent Harnesses conta uma tarefa por meio do seu caminho, e esse livro é o lugar para ler sobre isso. Este capítulo avalia a única etapa que o assistente tem.
A etapa de recuperação
A recuperação é BM25 sobre as seções da versão consultada. Ela é determinística: a mesma pergunta recebe sempre as mesmas seções do topo. Por isso, esta etapa não precisa de registro. O código calcula as seções do topo para cada item a partir do índice, e as compara com o veredito que o juiz deu à resposta da linha de base.
Os itens de desenvolvimento sem seção de apoio na versão consultada ficam de fora da tabela. São os itens sem resposta, já que nenhuma seção da versão consultada existe para a recuperação encontrar. A contagem deles é 13.
1"""Sets the baseline's judge verdict against whether a supporting section reached the top k, for each dev item that has one.23Retrieval is BM25 over the asked version, so it is the same on every run and needs no recording; k is the baseline's, read from4its manifest. The two diagonal cells are the expected pairs. The two off-diagonal cells are the ones to read: a pass without the5right section retrieved, and a fail with it retrieved. Unanswerable items are left out, since they have no section of their asked6version to retrieve; their count is printed. An unreadable verdict is printed and left out, never counted as a fail. A declined reply is counted in its cell like any7other reply; the count of declines is printed. The FAIL cell is split into declines and answers in fail-with-section."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.answers import Assistant11from lib.calibration import readable_verdicts12from lib.contract import parse_reply13from lib.prompts import P1_SHA256, P1_SYSTEM, REF_SHA25614from lib.replay import ReplayModel15from lib.testset import load_items1617RECORDING = "assistant-baseline"18k = ReplayModel(RECORDING, P1_SHA256).manifest["k"] # the top k the baseline's prompt was built from, read from its manifest19assistant = Assistant(RECORDING, P1_SYSTEM, P1_SHA256, k=k) # its retriever only; the recording is not read here20replies = ReplayModel(RECORDING, P1_SHA256) # the baseline's replies, sample 0, made from prompt P1, for the decline check2122dev = load_items(split="dev")23has_support = [item for item in dev if any(s.version == item.version for s in item.supporting_sections)]24print(f"top k: {k}")25print(f"dev items: {len(dev)}")26print(f"dev items with no supporting section of the asked version, left out: {len(dev) - len(has_support)}")2728verdicts, unreadable = readable_verdicts("judge-answers-baseline", [item.id for item in has_support], REF_SHA256)29for item_id, first in unreadable:30 print(f'unreadable verdict, left out: {item_id} ("{first}")')3132# Keyed by (retrieved, passed): the four cells of the 2 by 2 table, each a list of item ids in sorted order.33cells = {(True, True): [], (True, False): [], (False, True): [], (False, False): []}34declined = set() # item ids whose reply is a decline; they sit in their cells like any other reply35for item in has_support:36 if item.id not in verdicts:37 continue38 listed = {s.section_id for s in item.supporting_sections if s.version == item.version}39 top = {section.section_id for section in assistant.sections(item)} # the top k sections, by BM25 rank40 cells[(bool(listed & top), verdicts[item.id] == "PASS")].append(item.id)41 if parse_reply(replies.reply(item.id, 0)).declined:42 declined.add(item.id)4344print(f"items in the table: {sum(len(ids) for ids in cells.values())}")45print(f"declined items in the table, counted in their cells: {len(declined)}")46print(f"right section in the top {k}, PASS: {len(cells[(True, True)])}")47print(f"right section in the top {k}, FAIL: {len(cells[(True, False)])}")48print(f"right section not in the top {k}, PASS: {len(cells[(False, True)])}")49print(f"right section not in the top {k}, FAIL: {len(cells[(False, False)])}")50print("passed without the right section retrieved: " + (", ".join(cells[(False, True)]) or "none"))51print("failed with the right section retrieved: " + (", ".join(cells[(True, False)]) or "none"))
python retrieval-path.pytop k: 3
dev items: 80
dev items with no supporting section of the asked version, left out: 13
unreadable verdict, left out: q-0043 ("VERDICT: PARTIAL")
items in the table: 66
declined items in the table, counted in their cells: 10
right section in the top 3, PASS: 49
right section in the top 3, FAIL: 10
right section not in the top 3, PASS: 0
right section not in the top 3, FAIL: 7
passed without the right section retrieved: none
failed with the right section retrieved: q-0019, q-0023, q-0025, q-0029, q-0033, q-0045, q-0046, q-0048, q-0063, q-0074
O top k é 3, lido do manifesto da linha de base. A tabela tem 66 itens, e 10 deles são recusas. Uma recusa fica na sua célula como qualquer outra resposta, já que o juiz lhe deu um veredito. Cada célula combina um veredito com a informação de se uma seção de apoio chegou ao top k.
| Veredito | Seção de apoio no top k | Sem seção de apoio no top k |
|---|---|---|
| PASS | 49 | 0 |
| FAIL | 10 | 7 |
Leia primeiro a linha PASS. A célula de acertos com a seção no top k tem 49 acertos, e a célula de acertos sem ela tem 0. Isso é coerente com acertos vindos da documentação. Não mostra que vieram, porque a tabela conta com que frequência duas coisas ocorrem juntas, e não qual delas causou a outra. A contagem de acertos também é uma verificação da referência. Um acerto sem seção recuperada pode vir de uma resposta que repete um fato comum, ou de uma resposta de referência que o leitor poderia adivinhar, e a tabela não consegue dizer qual dos dois. Ler esses itens consegue.
A linha FAIL é onde entram as outras verificações. Entre as falhas com a seção no top k, 5 são recusas, e as demais são respostas. Recusar quando a documentação não diz explica o que significa uma recusa quando a documentação contém a resposta. O exemplo abaixo divide a célula.
1"""The dev items the baseline failed although a listed section of the asked version was in its top k, split into declines and answers.23For each answer it prints whether the reply cites a listed section, and the faithfulness judge's verdict on it. A decline has no4faithfulness verdict, because the judge reads only answers. An unreadable verdict is printed and left out, never counted as a fail."""5import lib # first: fixes the thread counts and seeds before anything else loads67import re89from lib.answers import Assistant10from lib.calibration import readable_verdicts11from lib.contract import citation_outcomes, parse_reply, section_ids_by_version12from lib.prompts import FAITH_SHA256, P1_SHA256, P1_SYSTEM, REF_SHA25613from lib.replay import ReplayModel14from lib.testset import load_items1516RECORDING = "assistant-baseline"17k = ReplayModel(RECORDING, P1_SHA256).manifest["k"] # the baseline's top k, as in retrieval-path18assistant = Assistant(RECORDING, P1_SYSTEM, P1_SHA256, k=k) # its retriever only19replies = ReplayModel(RECORDING, P1_SHA256) # the baseline's replies, sample 0, made from prompt P120faith = ReplayModel("judge-faithfulness-baseline", FAITH_SHA256)21ids = section_ids_by_version()22VERDICT = re.compile(r"^VERDICT:\s*(SUPPORTED|UNSUPPORTED)$")232425def listed(item):26 """The item's supporting section IDs in its asked version."""27 return frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)282930dev = load_items(split="dev")31verdicts, unreadable = readable_verdicts("judge-answers-baseline", [item.id for item in dev], REF_SHA256)32for item_id, first in unreadable:33 print(f'unreadable verdict, left out: {item_id} ("{first}")')34fails = [item for item in dev if verdicts.get(item.id) == "FAIL" and listed(item) & {s.section_id for s in assistant.sections(item)}]35declined = [item for item in fails if parse_reply(replies.reply(item.id, 0)).declined]36answered = [item for item in fails if item not in declined]37print(f"right section in the top {k}, FAIL, declined: {len(declined)}")38print(f"right section in the top {k}, FAIL, answered: {len(answered)}")39print(f"answered FAIL with the section, citing a listed section: "40 f"{sum('supported' in citation_outcomes(parse_reply(replies.reply(item.id, 0)), item.version, listed(item), ids) for item in answered)}")41judged = {} # item id -> SUPPORTED, UNSUPPORTED or unreadable, for each answered fail42for item in answered:43 line = next((ln.strip().strip("*`").strip() for ln in faith.reply(item.id, 0).splitlines() if ln.strip()), "")44 match = VERDICT.match(line)45 judged[item.id] = match.group(1) if match else "unreadable"46print(f"answered FAIL with the section, faithfulness SUPPORTED: {sum(v == 'SUPPORTED' for v in judged.values())}")47print(f"answered FAIL with the section, faithfulness UNSUPPORTED: {sum(v == 'UNSUPPORTED' for v in judged.values())}")48print(" " + (", ".join(i for i, v in judged.items() if v == "UNSUPPORTED") or "none"))49print(f"answered FAIL with the section, faithfulness unreadable: {sum(v == 'unreadable' for v in judged.values())}")
python fail-with-section.pyunreadable verdict, left out: q-0043 ("VERDICT: PARTIAL")
right section in the top 3, FAIL, declined: 5
right section in the top 3, FAIL, answered: 5
answered FAIL with the section, citing a listed section: 5
answered FAIL with the section, faithfulness SUPPORTED: 4
answered FAIL with the section, faithfulness UNSUPPORTED: 1
q-0029
answered FAIL with the section, faithfulness unreadable: 0
Das falhas com resposta, 5 citam uma seção listada no item. O juiz de fidelidade aprova 4 delas e marca 1 como não sustentadas, que é o caso de q-0029. Os números aqui não mostram se as recusas indevidas, as falhas de versão ou os erros do juiz de respostas explicam o restante. Ler as respostas consegue.
Um veredito aparece como PARTIAL, e não como PASS nem FAIL. O veredito do juiz sobre q-0043 é PARTIAL, por isso a tabela o deixa de fora. Um veredito ilegível nunca é contado como falha.
Regra prática: trate a recuperação como um filtro para os acertos e como uma pista para as falhas. Um acerto sem a seção de apoio precisa de uma explicação, e uma falha com ela aponta para a resposta.
Onde os harnesses de agentes assumem
Quando uma tarefa exige várias etapas, cada uma pode chamar uma ferramenta e alterar o que a etapa seguinte enxerga. O resultado pode ser aprovado mesmo que uma etapa intermediária tenha falhado, por isso a contagem precisa ser feita sobre o caminho inteiro. Este livro avalia uma recuperação e uma resposta, então a contagem de caminho é, para cada item, um sim ou um não. A seção sobre uma tarefa contada por um caminho em Agent Harnesses explica como avaliar execuções desse tipo, e este capítulo não a repete.
Regra prática: Neste livro o caminho é uma recuperação e uma resposta, então leia a contagem de recuperações ao lado do veredito de cada item.
A qualidade da recuperação pertence a outro livro
O quão bem a recuperação ordena as seções, e quanto do contexto ela preenche, é uma questão de ranqueamento, e pertence a A Primer on Search Relevance. Sua seção escolhendo uma métrica de ranqueamento cobre recall em k, rank recíproco médio e nDCG, e como escolher entre elas. Medindo o contexto cobre o contexto que um modelo recebe. Leia as duas antes de escolher uma métrica para este assistente.
A contagem do caminho de recuperação faz uma pergunta sobre cada item: a seção de apoio da versão consultada está entre os k primeiros? Ela responde sim ou não, portanto não é uma métrica de ranqueamento. Não consegue dizer a que profundidade da lista essa seção está, e é para isso que serve uma métrica de ranqueamento. O k é lido do manifesto da linha de base e não é escolhido neste capítulo, então uma mudança em k altera a tabela, e a tabela precisa ser lida novamente.
Tomadas em conjunto, as quatro verificações dizem que uma taxa de aprovação neste assistente esconde três maneiras diferentes de errar. A resposta pode citar a coisa errada, afirmar o que nenhuma seção diz, ou responder para a versão errada. Cada uma precisa de sua própria contagem, seu próprio denominador e seu próprio termo para o que encontrou. As decisões que decorrem dos resultados são estas:
- Cada resposta é verificada quanto a citações, fidelidade e versão, e cada verificação mantém sua própria contagem.
- Toda taxa de fidelidade é impressa como não calibrada até que alguém compare o juiz com pessoas.
- Os itens que dependem da versão mantêm sua própria contagem ao lado da taxa de aprovação, e sua própria verificação de versão.
- A recuperação funciona como portão para as aprovações e como pista para as reprovações. Uma aprovação cuja seção não foi recuperada é lida antes de ser contada como fundamentada.
Regra prática: Antes de considerar uma resposta fundamentada, leia sua citação, suas afirmações e sua versão, e leia a recuperação que a precedeu.
Este capítulo, nesta edição
Edição 2026.11.3Exemplos aprovados em 21 de nov de 20266 de 6 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.3.