Escreva verificações em código para as falhas que você encontrou
Cerca de 26 minutos min de leitura, com 5 exemplos em 9 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 escrever as verificações de formato e de citação que rodam em cada resposta sem custo, de dizer quais das falhas do capítulo 2 cada uma consegue ou não consegue detectar, e de mostrar onde duas métricas padrão de sobreposição classificam uma resposta errada acima de uma certa.
O capítulo 2 codificou 240 respostas de desenvolvimento, 80 de cada uma de três variantes, e classificou cada uma pelo seu principal defeito em sete modos de falha. Alguns desses modos deixam uma marca no texto de uma resposta. Uma citação a uma seção que o prompt nunca apresentou é uma delas, e uma resposta a uma pergunta que a documentação não cobre é outra. Um programa consegue encontrar ambas lendo a resposta em comparação com o item a que ela responde. Outros modos não deixam nenhuma marca que um programa consiga ler. Uma resposta pode estar certa sobre uma versão e errada sobre outra, com a citação correta, e nada no seu texto indica qual versão ela tem em vista.
Uma equipe que escreve verificações apenas para as marcas que consegue ver relata uma execução limpa e deixa passar as falhas que nunca procurou. Este capítulo separa as verificações pelo que elas conseguem ver, constrói as que rodam em código e explica o que cada uma deixa de fora. O conjunto de teste por trás de todos os números aqui tem 80 itens de desenvolvimento e 40 itens de teste reservados. Somente os itens de desenvolvimento são lidos neste capítulo. Os itens reservados aparecem como contagens em um exemplo, e o capítulo 10 apresenta suas taxas de recusa.
O que uma verificação por código consegue ver
Uma verificação por código lê duas coisas: o texto da resposta e os dados do próprio item, que contêm a resposta de referência e a lista de seções que a sustentam. Ela dá a mesma resposta em todas as execuções, e não custa nada rodá-la de novo sobre um novo lote de respostas. Essas são as suas forças. O seu limite é que ela lê forma e pertencimento, nunca significado. Ela consegue dizer se uma resposta tem uma citação, se o ID citado estava no prompt e se a resposta é exatamente a frase de recusa. Não consegue dizer se a seção citada afirma o que a resposta diz.
Aqui está a lista de modos do capítulo 2, cada um com o que uma verificação por código consegue ver dele.
- Recusa em excesso. Uma verificação que conta a frase de recusa vê as recusas que a usam. Uma recusa em outras palavras passa por resposta. É assim que o q-0080 escapa de uma verificação por frases, como mostra o capítulo 2.
- Respostas com a versão errada. Uma verificação consegue ver se cada citação pertence à versão perguntada. Não consegue ver se a afirmação corresponde à referência dessa versão.
- Respostas erradas. Não visível para o código. Saber se uma afirmação está certa exige uma leitura da afirmação contra a referência.
- Recusas perdidas. Uma verificação pode exigir a frase de recusa em todo item sem resposta possível, e
answered-declined-expecteddispara para qualquer resposta a um desses itens, qualquer que seja a citação. Ela depende do rótulo do item, então um item que a documentação não cobre, mas que o conjunto de teste considera respondível, escapa dela. - Respostas incompletas. Não visível para o código neste capítulo. Saber se a resposta cobre a pergunta inteira cabe ao juiz, segundo as regras da rubrica.
- Problemas de citação. Visíveis em duas partes: uma citação fora do prompt e uma citação a uma seção que o item não lista. A segunda parte exige um leitor, como explica a seção de suporte.
- Respostas malformadas. Em parte. Respostas vazias, recusas com texto, respostas sem citação e respostas cujas partes saem na ordem errada podem ser encontradas. A verificação de ordem da próxima seção encontra o último tipo.
Regra prática: Escreva uma verificação por código para uma falha somente quando a resposta e o item já contêm o fato de que a verificação precisa. Para uma falha cuja evidência é a própria afirmação, envie-a a um juiz com uma rubrica escrita, como faz o capítulo 5, e mantenha a verificação por código para as partes da falha que podem ser lidas.
Verificações de formato
A verificação de formato pergunta se uma resposta tem a forma que o prompt pede, antes que alguém leia o que ela diz. A função format_problems em lib/contract.py devolve uma lista ordenada de nomes fixos, um para cada defeito que encontra. São cinco. empty é uma resposta sem texto. declined-with-text é uma resposta que contém a frase de recusa junto com outro texto. no-citation é uma resposta que não cita nada. unknown-section é uma citação a uma seção que o prompt não forneceu. answered-declined-expected é uma resposta a um item que tem de ser recusado. Uma segunda função, order_problems, lê a ordem das linhas de uma resposta e devolve dois nomes: citation-first, para uma resposta cuja primeira linha começa com uma citação, e stray-line, para uma linha que não termina nenhuma frase depois que suas citações são retiradas.
A verificação de formato lê a resposta, a lista de seções que o prompt forneceu e se o item não é respondível. A verificação de ordem lê apenas as linhas da resposta. Nenhuma das duas lê o que a resposta afirma, então uma resposta correta e uma errada com a mesma forma passam igualmente.
Execute a verificação de formato sobre a resposta da linha de base a cada item, e conte cada nome, mantendo separados os itens de desenvolvimento e os itens reservados.
1"""Runs format_problems over the baseline replies to every item, and counts each problem by its fixed name.23Dev and held-out items are counted apart, and held-out items appear only as counts. An item can have more than one4problem, so the counts by name can add up to more than the number of items with a problem."""5import lib # first: fixes the thread counts and seeds before anything else loads67from collections import Counter89from lib.answers import Assistant10from lib.contract import PROBLEMS, format_problems11from lib.prompts import P1_SHA256, P1_SYSTEM12from lib.stats import pct13from lib.testset import load_items1415assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)16assert len(load_items()) == 120 # the baseline recording holds one reply per item, so every item is counted1718for split in ("dev", "held-out"):19 items = load_items(split=split)20 counts = Counter()21 with_problem = 022 for item in items:23 problems = format_problems(24 assistant.reply(item),25 context_ids=assistant.context_ids(item),26 expect_decline=item.kind == "unanswerable", # an unanswerable item must be declined27 )28 with_problem += bool(problems)29 counts.update(problems)30 print(f"{split} items: {len(items)}")31 print(f"{split} items with a format problem: {pct(with_problem, len(items))}")32 for name in PROBLEMS: # the fixed names, in the order lib.contract lists them33 print(f"{split} problem {name}: {counts[name]}")
python format-problems-baseline.pydev items: 80
dev items with a format problem: 0.0% (0 of 80)
dev problem answered-declined-expected: 0
dev problem declined-with-text: 0
dev problem empty: 0
dev problem no-citation: 0
dev problem unknown-section: 0
held-out items: 40
held-out items with a format problem: 0.0% (0 of 40)
held-out problem answered-declined-expected: 0
held-out problem declined-with-text: 0
held-out problem empty: 0
held-out problem no-citation: 0
held-out problem unknown-section: 0
A linha de base não tem nenhum problema de formato nos itens de desenvolvimento, 0.0% (0 of 80), nem nos itens reservados, 0.0% (0 of 40). Um zero só conta se a verificação pudesse ter disparado, e o próximo exemplo mostra que essas verificações disparam, em outras gravações.
1"""Runs the format check and the order check over the unfiltered and second-model replies to the dev items. The baseline2has no problem of either kind (format-problems-baseline), so these two recordings are where the checks fire.34Each name is also run once on a fixture reply built to break it, and the example stops if a name does not fire. A zero5on a real split then means the check found nothing, not that it could not fire. Held-out items are not read here."""6import lib # first: fixes the thread counts and seeds before anything else loads78from lib.answers import Assistant9from lib.contract import ORDER_PROBLEMS, PROBLEMS, format_problems, order_problems, parse_reply10from lib.prompts import P1_SHA256, P1_SYSTEM11from lib.testset import load_items1213VARIANTS = (("unfiltered", "assistant-unfiltered"), ("second-model", "assistant-second-model"))14FIXTURE_IDS = frozenset({"example-start"}) # the one section a fixture may cite15FIXTURES = ( # name, reply text, whether the item must be declined16 ("empty", "", False),17 ("declined-with-text", "The docs don't say. [sec:example-start]", False),18 ("no-citation", "Run svc start to start the service.", False),19 ("unknown-section", "Run svc start to start the service. [sec:made-up]", False),20 ("answered-declined-expected", "Run svc start to start the service. [sec:example-start]", True),21 ("citation-first", "[sec:example-start] Start the service.\nRun svc start.", False),22 ("stray-line", "Run `svc start` [sec:example-start]\nService", False),23)2425items = load_items(split="dev")26for label, recording in VARIANTS:27 assistant = Assistant(recording, P1_SYSTEM, P1_SHA256)28 found = {name: [] for name in (*PROBLEMS, *ORDER_PROBLEMS)}29 for item in items:30 reply = assistant.reply(item)31 for name in format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=item.kind == "unanswerable"):32 found[name].append(item.id)33 for name in order_problems(reply.text):34 found[name].append(item.id)35 for name, ids in found.items():36 shown = f"{len(ids)} of {len(items)}" + (f" ({', '.join(ids)})" if ids else "")37 print(f"{label} {name}: {shown}")3839for name, raw, must_decline in FIXTURES:40 reply = parse_reply(raw)41 fired = name in format_problems(reply, context_ids=FIXTURE_IDS, expect_decline=must_decline) or name in order_problems(reply.text)42 assert fired, f"the fixture for {name} does not fire the check"43 print(f"fixture {name}: fired")
python format-problems-variants.pyunfiltered answered-declined-expected: 2 of 80 (q-0018, q-0039)
unfiltered declined-with-text: 1 of 80 (q-0080)
unfiltered empty: 0 of 80
unfiltered no-citation: 0 of 80
unfiltered unknown-section: 1 of 80 (q-0019)
unfiltered citation-first: 0 of 80
unfiltered stray-line: 0 of 80
second-model answered-declined-expected: 2 of 80 (q-0034, q-0036)
second-model declined-with-text: 1 of 80 (q-0001)
second-model empty: 0 of 80
second-model no-citation: 9 of 80 (q-0001, q-0007, q-0047, q-0058, q-0060, q-0063, q-0065, q-0071, q-0080)
second-model unknown-section: 0 of 80
second-model citation-first: 1 of 80 (q-0030)
second-model stray-line: 2 of 80 (q-0007, q-0030)
fixture empty: fired
fixture declined-with-text: fired
fixture no-citation: fired
fixture unknown-section: fired
fixture answered-declined-expected: fired
fixture citation-first: fired
fixture stray-line: fired
A variante sem filtro responde a q-0018 e q-0039, que não são respondíveis, então answered-declined-expected os conta: 2 of 80 (q-0018, q-0039). As respostas do segundo modelo trazem mais problemas. A contagem de no-citation delas é 9 of 80 (q-0001, q-0007, q-0047, q-0058, q-0060, q-0063, q-0065, q-0071, q-0080).
A verificação de ordem sinaliza a resposta do segundo modelo a q-0030. Essa resposta começa com sua citação, então é citation-first: 1 of 80 (q-0030). Sua primeira linha também contém um fragmento de título, que é um stray-line. Uma resposta cuja última linha não termina nenhuma frase recebe esse nome também, e um dos dois casos é q-0007, cujo texto é cortado no meio de uma frase repetida: 2 of 80 (q-0007, q-0030).
A verificação de formato aprova essa resposta de q-0030. format_problems conta citações e não lê onde elas aparecem, então uma resposta pode citar apenas seções que o prompt forneceu e ainda ter suas partes fora de ordem. É para essa lacuna que serve a verificação de ordem. O exemplo também executa uma resposta de fixture para cada nome, e para se algum nome não disparar, de modo que cada zero acima significa que a verificação olhou e não encontrou nada.
Uma verificação que nunca dispara sobre a linha de base ainda merece seu lugar, porque não custa nada e pega o próximo prompt que quebre uma forma.
Regra prática: Execute a verificação de formato e a verificação de ordem em cada resposta antes que um juiz a leia, e informe a contagem de cada nome em cada divisão. Um zero conta como resultado apenas quando a verificação poderia ter disparado, então mantenha a execução de fixtures junto com o relatório. Quando uma contagem subir, leia as respostas por trás dela antes de alterar a verificação, porque um nome indica qual forma quebrou, e não por que quebrou.
Verificações de citação
Capítulo 1 fez a primeira verificação de citação: todo ID que uma resposta cita precisa ser um dos que o prompt forneceu. Essa verificação diz se uma citação está dentro do prompt. Ela não diz se a citação é a correta para o item. Esta seção faz duas outras perguntas a cada ID citado. Ele existe na documentação da versão a que o item se refere? E é uma seção que o item lista como sustentando a resposta?
citation_outcome atribui a cada ID citado um dos quatro resultados. supported significa que o ID está na lista do item para a versão consultada. unlisted significa uma seção da versão consultada que o item não lista. wrong-version significa uma seção que existe apenas em outra versão. missing significa que nenhuma versão tem uma seção com o ID citado. Duas regras valem para os quatro. Uma resposta carrega IDs e não versões, então um ID que aparece em duas versões não pode ser de versão errada, e é julgado pela versão consultada. E unlisted nunca é classificado como errado. A lista do item foi escrita à mão, e uma seção que ela não lista pode, ainda assim, sustentar a resposta.
A verificação roda sobre os itens de desenvolvimento de três gravações: a linha de base; a variante sem filtro, que usa o mesmo prompt, mas recupera de todas as versões e mostra as versões ao modelo; e prompt-b, o prompt P2 de citação primeiro do capítulo 1 (dois prompts), que pede ao modelo que primeiro cite a frase em que sua resposta se apoia e que cite o ID em cada linha. Suas 117 citações vêm dos mesmos itens, então suas proporções são por citação. As citações de cada gravação são classificadas da mesma forma.
1"""Sorts each section ID that a reply cites into one outcome, for three recordings, over the dev items.23The outcomes are supported (listed by the item for its asked version), unlisted (a section of the asked version that the4item does not list), wrong-version (a section of another version only) and missing (a section of no version). The5check reads IDs, not sentences: whether a listed section supports the sentence is the judge's job, in grounded-answers.67An ID that exists in two versions cannot be told apart by the reply, because the citation carries no version. It is8judged against the asked version, so an ID shared by both versions is never wrong-version."""9import lib # first: fixes the thread counts and seeds before anything else loads1011from collections import Counter1213from lib.contract import CITATION_OUTCOMES, citation_outcomes, parse_reply, section_ids_by_version14from lib.prompts import P1_SHA256, P2_SHA25615from lib.replay import ReplayModel16from lib.stats import pct17from lib.testset import load_items1819RECORDINGS = ( # label, recording, the sha256 of the prompt it was made from20 ("baseline", "assistant-baseline", P1_SHA256),21 ("unfiltered", "assistant-unfiltered", P1_SHA256), # same prompt; retrieval from every version, versions shown22 ("prompt-b", "assistant-prompt-b", P2_SHA256),23)2425ids = section_ids_by_version()26items = load_items(split="dev") # dev only: held-out items are not read here (plan section 3.4)2728for label, recording, prompt_sha256 in RECORDINGS:29 model = ReplayModel(recording, prompt_sha256)30 counts = Counter()31 for item in items:32 reply = parse_reply(model.reply(item.id, 0))33 # The item's list for its asked version. An unanswerable item may also list another version: not counted here.34 listed = frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)35 counts.update(citation_outcomes(reply, item.version, listed, ids))36 total = sum(counts.values())37 print(f"{label} citations on dev items: {total}")38 for outcome in CITATION_OUTCOMES:39 print(f"{label} {outcome}: {pct(counts[outcome], total)}")
python check-citation-support.pybaseline citations on dev items: 60
baseline supported: 93.3% (56 of 60)
baseline unlisted: 6.7% (4 of 60)
baseline wrong-version: 0.0% (0 of 60)
baseline missing: 0.0% (0 of 60)
unfiltered citations on dev items: 59
unfiltered supported: 84.7% (50 of 59)
unfiltered unlisted: 15.3% (9 of 59)
unfiltered wrong-version: 0.0% (0 of 59)
unfiltered missing: 0.0% (0 of 59)
prompt-b citations on dev items: 117
prompt-b supported: 93.2% (109 of 117)
prompt-b unlisted: 6.8% (8 of 117)
prompt-b wrong-version: 0.0% (0 of 117)
prompt-b missing: 0.0% (0 of 117)
A maioria das citações em todas as gravações aponta para uma seção que o item lista. A proporção listada é 93.3% (56 of 60) para a linha de base, 84.7% (50 of 59) para a variante sem filtro e 93.2% (109 of 117) para prompt-b.
Existência e versão
A verificação de versão não encontra nada nessas gravações. Uma citação de versão errada, conforme definida acima, é aquela que aponta apenas para uma seção de outra versão. Para a linha de base, a parcela de versão errada é 0.0% (0 of 60). Para a variante sem filtro, é 0.0% (0 of 59). Para o prompt-b, é 0.0% (0 of 117). O resultado de citação ausente também não aparece em nenhuma das três gravações. Isso é uma afirmação apenas sobre as citações. Não mostra que o assistente responde a todas as perguntas para a versão pedida.
A variante sem filtro é a que merece atenção, porque o contexto dela contém as seções de todas as versões. Se alguma gravação citasse a versão errada, seria esta. Ela não cita nenhuma. Os erros que importam estão nas afirmações. Capítulo 2 classifica a resposta da linha de base para q-0023 como uma resposta de versão errada. Ela dá o resultado da versão 2.0 para uma entrada ignore na versão 1.0, e cita uma seção da versão 1.0. A citação está na versão pedida, então esta verificação a aprova. A afirmação precisa ser lida em comparação com a referência da versão 1.0 antes que o erro apareça.
Regra prática: Relate os resultados de versão errada e de citação ausente como taxas próprias, e nunca deixe que um zero ali passe por uma resposta correta. Para cada item que depende da versão, leia a afirmação em comparação com a referência da versão pedida. Respostas fundamentadas incorpora essa leitura em uma taxa própria.
Suporte
O resultado não listado é onde esta verificação faz o seu trabalho, e ele exige um leitor. Uma citação a uma seção não listada da versão consultada não é um erro segundo as regras desta verificação, porque a lista do item foi escrita à mão e pode estar incompleta. A resposta do baseline à q-0057 é um exemplo: ela cita remote-retries, que o item não lista. O código classifica essa citação como não listada, e o capítulo 2 codifica a resposta como um problema de citação, de modo que cabe a um leitor decidir se a citação é de fato um problema. O capítulo 2 também enuncia o candidato como uma regra segundo a qual toda citação deve ser uma que o item lista. Este capítulo flexibiliza essa regra, porque a lista é escrita à mão e quem decide é um leitor, e não a lista.
As proporções de não listadas são 6.7% (4 of 60) para o baseline, 15.3% (9 of 59) para a variante sem filtro e 6.8% (8 of 117) para o prompt-b. A variante sem filtro tem a maior proporção de não listadas. Cada uma de suas citações não listadas é uma questão para um leitor: esta seção sustenta a frase para a qual foi citada?
Um resultado supported significa apenas que o ID está na lista. Uma seção listada pode, ainda assim, não sustentar a frase para a qual foi citada, porque esta verificação lê IDs e não frases. Saber se uma seção listada sustenta sua frase é um juízo, e esta verificação não o faz. Respostas fundamentadas reutiliza os quatro resultados definidos aqui como sua precisão de citação, que também lê apenas IDs, e acrescenta um juiz de fidelidade no nível da resposta, descrito em um juiz com uma rubrica.
Regra prática: Conte uma citação como sustentada somente quando seu ID estiver na lista do item, e nunca como correta. Leia cada citação não listada contra a sua seção antes de classificá-la como problema. Informe as não listadas separadamente das de versão errada e das ausentes, porque uma lista mais completa transferiria algumas das citações não listadas para sustentadas.
Correspondência exata e correspondência aproximada
A maioria das verificações de strings deste livro usa uma de duas comparações. Uma correspondência exata pergunta se duas strings são iguais, e serve para qualquer texto fixo. A verificação de recusa do Capítulo 1 é um exemplo. Uma resposta só conta como recusa quando o texto inteiro é igual à frase de recusa, que é o que o campo declined de uma resposta analisada guarda. Um ID de seção, um nome de flag e um nome de arquivo são fixos da mesma forma. Uma correspondência exata dá um sim ou um não, e nunca devolve uma quase-coincidência.
Uma correspondência aproximada mede o quanto duas strings se parecem. A biblioteca padrão do Python, difflib, faz isso. Sua classe SequenceMatcher fornece a pontuação como ratio(), que a documentação define como o dobro do número de elementos correspondentes dividido pelo número total de elementos nas duas sequências. Três pontos sobre essa pontuação importam para uma verificação.
- Ela depende da ordem dos argumentos. A documentação alerta que o resultado de uma chamada de
ratio()pode depender da ordem dos argumentos, por isso uma verificação deve passar a referência na mesma posição sempre. No par longo do exemplo, a pontuação é 0.480 com a referência primeiro e 0.861 com a resposta primeiro. - Ela conta correspondências, não significado. Um erro de digitação de uma letra em uma flag obtém 0.933 em relação à flag correta, embora a flag esteja errada. Uma resposta pode manter uma pontuação alta enquanto o seu único fato errado muda.
- Ela pode pular partes de strings longas. Para sequências de 200 itens ou mais, a documentação trata um item como lixo quando suas repetições somam mais de um por cento da sequência, a menos que
autojunkseja desativado. Para strings, os itens são caracteres, então uma resposta de 200 caracteres ou mais pode ser afetada. A heurística é construída a partir do segundo argumento, que é a resposta quando a referência vem primeiro. No par longo, a pontuação padrão é 0.480, e comautojunk=Falseela é 0.861.
1"""Compares three pairs of sablefile answers with an exact match and with difflib's ratio(), a score from 0 to 1.23Each pair is a reference and a reply written for this example, not a recorded reply: two file names, a flag with one4wrong letter, and a long answer that leaves out its folder sentence. ratio() is printed with the reference first and with5the reply first, because the documentation says the argument order can change the score. With the reference first, the6long reply is the second sequence and is 200 characters or more, so the autojunk heuristic applies to it; the long answer7is also scored with autojunk turned off."""8import lib # first: fixes the thread counts and seeds before anything else loads910from difflib import SequenceMatcher1112FOLDERS = " Folders are created only with --apply, because a plain sync writes nothing."13PLAN = " The plan lines start with create, update or unchanged, and the lock file is written only by the apply run."14LONG_REFERENCE = (15 "With no flag, sync prints the plan and writes nothing. --apply writes the files and updates the lock file, "16 ".sablefile/lock.json." + FOLDERS + PLAN17)18LONG_REPLY = LONG_REFERENCE.replace(FOLDERS, "") # the answer leaves out the folder sentence19PAIRS = (20 ("file names", ".sablefile/lock.json", "sablefile.lock"),21 ("flag", "--apply", "--appply"),22 ("long answer", LONG_REFERENCE, LONG_REPLY),23)2425for name, reference, reply in PAIRS:26 print(f"{name}, exact match: {reply == reference}")27 print(f"{name}, ratio: {SequenceMatcher(None, reference, reply).ratio():.3f}")28 print(f"{name}, ratio with the reply first: {SequenceMatcher(None, reply, reference).ratio():.3f}")29# autojunk=False: the default treats the reply's common characters as junk once it is 200 characters or longer.30print(f"long answer, ratio with autojunk off: {SequenceMatcher(None, LONG_REFERENCE, LONG_REPLY, autojunk=False).ratio():.3f}")
python fuzzy-match.pyfile names, exact match: False
file names, ratio: 0.765
file names, ratio with the reply first: 0.765
flag, exact match: False
flag, ratio: 0.933
flag, ratio with the reply first: 0.933
long answer, exact match: False
long answer, ratio: 0.480
long answer, ratio with the reply first: 0.861
long answer, ratio with autojunk off: 0.861
Os três pares foram escritos para este exemplo, então as pontuações mostram o que cada propriedade faz, e não com que frequência uma resposta a quebra.
Regra prática: Use uma correspondência exata sempre que o texto esperado for fixo. Use uma razão aproximada apenas para ordenar respostas para leitura, nunca como aprovação ou reprovação, até que uma execução registrada mostre onde um limite deve ficar para as respostas deste livro. Ao chamar ratio(), passe a referência primeiro sempre, e diga na docstring da verificação qual string é qual.
Onde o BLEU e o ROUGE induzem a erro
Duas pontuações de sobreposição de palavras, emprestadas de outras tarefas, podem ser usadas para verificar textos gerados. O BLEU veio da tradução automática, e o ROUGE, da sumarização. Ambas são baratas de calcular.
Papineni e colaboradores propuseram o BLEU em 2002 como uma forma rápida e barata de avaliar a tradução automática. Ele usa a precisão modificada de n-gramas (Papineni e colaboradores, 2002). A revisão de Reiter sobre o quanto o BLEU acompanha o julgamento humano concluiu que as evidências o sustentam para a avaliação diagnóstica de sistemas de tradução automática. Ela não o sustenta fora da tradução automática, para a avaliação de textos individuais, nem para o teste de hipóteses (Reiter, 2018). Uma pontuação que vale para sistemas não vale, por isso, para uma única resposta.
Lin definiu o ROUGE-N como uma revocação de n-gramas: a parcela das sequências de palavras da referência que o candidato cobre (Lin, 2004). Esse artigo trata de resumos. Um estudo separado testou métricas emprestadas da tradução automática em respostas de diálogo, não em respostas de documentação. Ele constatou que elas se correlacionam muito fracamente com o julgamento humano em um conjunto de dados de conversa geral, e não se correlacionam em absoluto em um conjunto técnico, os dados de ajuda do Ubuntu (Liu e colaboradores, 2016). Trata-se de um estudo de uma tarefa. As respostas do Sablefile são técnicas, de modo que o resultado é um alerta, e não uma medição deste assistente.
Três perguntas sobre o sablefile 2.0 mostram o problema com mais clareza. Cada uma tem uma resposta de referência escrita, uma resposta errada que copia a maior parte das palavras da referência e uma resposta certa que diz o mesmo com poucas dessas palavras. As respostas foram escritas para este exemplo, não tiradas de uma gravação, de modo que mostram que a falha pode acontecer, não com que frequência acontece. A pontuação no estilo BLEU toma a precisão truncada (clipped) de n-gramas de 1 a 4, sua média geométrica e uma penalidade de brevidade. O ROUGE-1 F1 conta palavras isoladas. As duas fórmulas estão escritas no código do exemplo. Nenhum pacote de BLEU ou ROUGE está fixado neste livro, e o exemplo relata o F1, que combina revocação e precisão, não a revocação definida por Lin.
1"""Scores a wrong answer that shares most of its words with the reference above a right answer that shares few.23Each pair in data/overlap-pairs.json is a question on sablefile 2.0 with its reference, a wrong answer and a right answer.4All three pairs are hand-written for this example, not recorded replies. The scores are the textbook formulas, written5here in plain Python: ROUGE-1 F1 (unigram overlap, F1 of precision and recall) and a BLEU-style score (clipped 1- to64-gram precision, geometric mean, brevity penalty), with no smoothing. No BLEU or ROUGE package is pinned, and none is7used. The reference facts are in examples/data/docs/2.0 (sync.md, quickstart.md, lockfile.md)."""8import lib # first: fixes the thread counts and seeds before anything else loads910import json11import math12import re13from collections import Counter14from pathlib import Path1516PAIRS = json.loads((Path(__file__).resolve().parent / "data" / "overlap-pairs.json").read_text(encoding="utf-8"))171819def words(text: str) -> list[str]:20 """Lowercase runs of letters and digits: `--apply` is the word apply, and `lock.json` is two words."""21 return re.findall(r"[a-z0-9]+", text.lower())222324def rouge_1_f1(candidate: str, reference: str) -> float:25 """ROUGE-1 F1: shared words, counted with repeats up to the smaller count, over both lengths."""26 cand, ref = words(candidate), words(reference)27 overlap = sum((Counter(cand) & Counter(ref)).values())28 if overlap == 0:29 return 0.030 precision, recall = overlap / len(cand), overlap / len(ref)31 return 2 * precision * recall / (precision + recall)323334def bleu_sentence(candidate: str, reference: str, max_n: int = 4) -> float:35 """Sentence BLEU-style score: clipped n-gram precision for n = 1 to 4, geometric mean, brevity penalty.3637 Without smoothing, a single n-gram order with no match gives 0, as the textbook formula does.38 """39 cand, ref = words(candidate), words(reference)40 precisions = []41 for n in range(1, max_n + 1):42 cand_grams = Counter(tuple(cand[i : i + n]) for i in range(len(cand) - n + 1))43 ref_grams = Counter(tuple(ref[i : i + n]) for i in range(len(ref) - n + 1))44 clipped = sum(min(count, ref_grams[gram]) for gram, count in cand_grams.items()) # each n-gram up to the reference's count45 if clipped == 0:46 return 0.047 precisions.append(clipped / sum(cand_grams.values()))48 # Short answers are penalised by the brevity penalty: a candidate shorter than the reference scores less.49 brevity = (1.0 if len(cand) > len(ref) else math.exp(1 - len(ref) / len(cand)))50 return brevity * math.exp(sum(math.log(p) for p in precisions) / max_n)515253for number, pair in enumerate(PAIRS, start=1):54 print(f"pair {number} (hand-written), question: {pair['question']}")55 for label in ("wrong", "right"):56 print(f"pair {number}, {label} answer, ROUGE-1 F1: {rouge_1_f1(pair[label], pair['reference']):.3f}")57 print(f"pair {number}, {label} answer, BLEU: {bleu_sentence(pair[label], pair['reference']):.3f}")58# The claim the prose makes: the wrong answer overlaps the reference more than the right one, in every pair.59higher = sum(rouge_1_f1(p["wrong"], p["reference"]) > rouge_1_f1(p["right"], p["reference"]) for p in PAIRS)60print(f"pairs where the wrong answer has the higher ROUGE-1 F1: {higher} of {len(PAIRS)}")
python overlap-misleads.pypair 1 (hand-written), question: In version 2.0, what does a plain sablefile sync do to your files?
pair 1, wrong answer, ROUGE-1 F1: 0.815
pair 1, wrong answer, BLEU: 0.540
pair 1, right answer, ROUGE-1 F1: 0.167
pair 1, right answer, BLEU: 0.000
pair 2 (hand-written), question: In version 2.0, when does sync create a target's missing folder?
pair 2, wrong answer, ROUGE-1 F1: 0.720
pair 2, wrong answer, BLEU: 0.484
pair 2, right answer, ROUGE-1 F1: 0.211
pair 2, right answer, BLEU: 0.000
pair 3 (hand-written), question: Where does version 2.0 keep its lock file?
pair 3, wrong answer, ROUGE-1 F1: 0.952
pair 3, wrong answer, BLEU: 0.905
pair 3, right answer, ROUGE-1 F1: 0.286
pair 3, right answer, BLEU: 0.000
pairs where the wrong answer has the higher ROUGE-1 F1: 3 of 3
A resposta errada supera a certa no ROUGE-1 F1 em 3 of 3 pares. No primeiro par, a resposta errada obtém 0.815, e a resposta certa obtém 0.167.
Leia as linhas do BLEU com cuidado. A fórmula que o código escreve não tem suavização, de modo que a pontuação é zero sempre que alguma das quatro ordens de n-grama não tem nenhuma correspondência. Cada resposta certa compartilha palavras isoladas com sua referência, mas nenhuma sequência de duas palavras, de modo que a precisão de duas palavras é zero, e o BLEU também. Esse é o comportamento da fórmula, e ele não diz nada sobre se a resposta é boa.
O ROUGE-1 F1 conta palavras isoladas e ignora a ordem delas. Uma resposta errada que repete a maior parte das palavras da referência recebe a maior parte da pontuação, quaisquer que sejam as palavras em que erra. O terceiro par mostra isso. Sua resposta errada obtém 0.952. Essa resposta nomeia o arquivo da versão 1.1, onde a referência nomeia .sablefile/lock.json. Todas as palavras da resposta errada aparecem na referência, e a única palavra da referência que ela não tem é json. O nome do arquivo é a parte da resposta que importa, e a pontuação não consegue distinguir essa parte do resto.
Regra prática: não use o BLEU nem o ROUGE como critério de aprovação para uma resposta com uma única forma correta. Se você os relatar, informe a fórmula e diga se ela é suavizada. Leia toda resposta cuja sobreposição seja alta e cuja afirmação esteja em dúvida, pois os pares acima mostram que a sobreposição premia uma resposta errada que copia a referência. Verifique a afirmação com um juiz, como descreve o capítulo 5.
Recusas no código
O capítulo 1 já traz uma verificação de código para as recusas. Ela conta dois erros em relação à frase exata de recusa: um item respondível que o assistente recusou, e um item não respondível que ele respondeu. O verificador de formato deste capítulo acrescenta um formato, a frase de recusa acompanhada de outro texto na mesma resposta, e executa a verificação de item não respondível em todos os itens de ambas as divisões, onde o capítulo 1 a executou em vinte. Os números de erros de formato da linha de base são zero nas duas divisões, como mostra verificações de formato. Nos vinte itens do capítulo 1, a verificação de recusa não encontrou nenhum erro. Este capítulo não a executa novamente nos itens de desenvolvimento. O capítulo 10 apresenta a taxa de falsas recusas da linha de base sobre eles.
Ambas as verificações leem o texto da resposta, e ambas têm um limite que decorre disso. Uma recusa dita de outra maneira não é a frase exata, então passa como resposta, como mostra o item q-0080 no capítulo 2. As taxas de recusa também deixam de fora os itens que dependem da versão, e o item q-0004 mostra o custo disso, como explica o capítulo 1. A linha de base recusa esse item, mas a documentação 2.0 o responde na seção de placeholders. A taxa de recusa não conta isso como falsa recusa. Respostas fundamentadas constrói a taxa de correção por versão que faz essa contagem.
Se uma recusa está certa em um item que a documentação não cobre é uma questão de julgamento, não uma verificação de código. Se a documentação diz o suficiente para responder é a pergunta tratada em recusar quando a documentação não diz.
Regra prática: Conte os dois erros de recusa em cada divisão, e leia à mão cada recusa dependente da versão contra a documentação da versão correspondente, pois a taxa de recusa deixa esses itens de fora.
Executando as verificações e o que elas estabelecem
Em produção, as verificações rodam em cada resposta, de modo que uma mudança no prompt ou no modelo altera, no mesmo relatório, as contagens de formato, as taxas de recusa e a parcela fora da lista. Uma mudança que deixa todas essas medidas estáveis enquanto os usuários relatam respostas erradas é o sinal de que as verificações não enxergam a falha. Classifique cada resposta pelo seu principal defeito, como descreve o capítulo 2, e escreva uma verificação para o modo que se encaixa.
O que o capítulo estabelece é restrito. Uma verificação em código pode manter honesta a forma de uma resposta, a pertinência das suas citações e a frase de recusa, e pode fazê-lo em cada resposta sem custo. O que uma resposta significa ainda exige um leitor ou um juiz. Por isso, classifique cada resposta pelo seu principal defeito, limite cada verificação aos defeitos que ela consegue ver e envie ao leitor ou ao juiz o que ela não consegue ver, para que uma contagem limpa nunca seja tomada como uma resposta limpa.
O capítulo tomou estas decisões:
- A verificação de formato é uma guarda com cinco nomes, executada antes de qualquer juiz.
- A verificação de formato conta as citações e não lê a sua ordem, por isso aprova a segunda resposta do modelo para q-0030. A verificação de ordem sinaliza essa resposta.
- Uma citação é
supportedquando o seu ID está na lista do item, e nunca porque a frase ao redor dela está correta. - A verificação de versão nas citações não encontra nenhuma citação de versão errada nestas três gravações, e o capítulo não apresenta isso como uma verificação das versões das respostas.
- As pontuações de sobreposição vêm das próprias fórmulas do exemplo, e nenhuma pontuação é usada como nota de aprovação.
- As propriedades de correspondência aproximada são mostradas nas respostas do sablefile, e nenhuma razão é usada como nota de aprovação.
- Os itens de teste reservados aparecem apenas como contagens na verificação de formato, e o capítulo 10 os analisa.
Este capítulo, nesta edição
Edição 2026.11.3Exemplos aprovados em 21 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.3.