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.

Edição 2026.11.3 Exemplos aprovados em 21 de nov de 2026 54 de 54 exemplos passam O que mudou

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-expected dispara 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

Última alteração na edição 2026.11.3

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.

format-problems-baseline.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 Aprovado
"""Runs format_problems over the baseline replies to every item, and counts each problem by its fixed name.Dev and held-out items are counted apart, and held-out items appear only as counts. An item can have more than oneproblem, so the counts by name can add up to more than the number of items with a problem."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom collections import Counterfrom lib.answers import Assistantfrom lib.contract import PROBLEMS, format_problemsfrom lib.prompts import P1_SHA256, P1_SYSTEMfrom lib.stats import pctfrom lib.testset import load_itemsassistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)assert len(load_items()) == 120  # the baseline recording holds one reply per item, so every item is countedfor split in ("dev", "held-out"):    items = load_items(split=split)    counts = Counter()    with_problem = 0    for item in items:        problems = format_problems(            assistant.reply(item),            context_ids=assistant.context_ids(item),            expect_decline=item.kind == "unanswerable",  # an unanswerable item must be declined        )        with_problem += bool(problems)        counts.update(problems)    print(f"{split} items: {len(items)}")    print(f"{split} items with a format problem: {pct(with_problem, len(items))}")    for name in PROBLEMS:  # the fixed names, in the order lib.contract lists them        print(f"{split} problem {name}: {counts[name]}")
Saídapython format-problems-baseline.py
dev 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.

format-problems-variants.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 Aprovado
"""Runs the format check and the order check over the unfiltered and second-model replies to the dev items. The baselinehas no problem of either kind (format-problems-baseline), so these two recordings are where the checks fire.Each name is also run once on a fixture reply built to break it, and the example stops if a name does not fire. A zeroon a real split then means the check found nothing, not that it could not fire. Held-out items are not read here."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom lib.answers import Assistantfrom lib.contract import ORDER_PROBLEMS, PROBLEMS, format_problems, order_problems, parse_replyfrom lib.prompts import P1_SHA256, P1_SYSTEMfrom lib.testset import load_itemsVARIANTS = (("unfiltered", "assistant-unfiltered"), ("second-model", "assistant-second-model"))FIXTURE_IDS = frozenset({"example-start"})  # the one section a fixture may citeFIXTURES = (  # name, reply text, whether the item must be declined    ("empty", "", False),    ("declined-with-text", "The docs don't say. [sec:example-start]", False),    ("no-citation", "Run svc start to start the service.", False),    ("unknown-section", "Run svc start to start the service. [sec:made-up]", False),    ("answered-declined-expected", "Run svc start to start the service. [sec:example-start]", True),    ("citation-first", "[sec:example-start] Start the service.\nRun svc start.", False),    ("stray-line", "Run `svc start` [sec:example-start]\nService", False),)items = load_items(split="dev")for label, recording in VARIANTS:    assistant = Assistant(recording, P1_SYSTEM, P1_SHA256)    found = {name: [] for name in (*PROBLEMS, *ORDER_PROBLEMS)}    for item in items:        reply = assistant.reply(item)        for name in format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=item.kind == "unanswerable"):            found[name].append(item.id)        for name in order_problems(reply.text):            found[name].append(item.id)    for name, ids in found.items():        shown = f"{len(ids)} of {len(items)}" + (f" ({', '.join(ids)})" if ids else "")        print(f"{label} {name}: {shown}")for name, raw, must_decline in FIXTURES:    reply = parse_reply(raw)    fired = name in format_problems(reply, context_ids=FIXTURE_IDS, expect_decline=must_decline) or name in order_problems(reply.text)    assert fired, f"the fixture for {name} does not fire the check"    print(f"fixture {name}: fired")
Saídapython format-problems-variants.py
unfiltered 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

Última alteração na edição 2026.11.3

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.

check-citation-support.py Python 3.12.15 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 Aprovado
"""Sorts each section ID that a reply cites into one outcome, for three recordings, over the dev items.The outcomes are supported (listed by the item for its asked version), unlisted (a section of the asked version that theitem does not list), wrong-version (a section of another version only) and missing (a section of no version). Thecheck reads IDs, not sentences: whether a listed section supports the sentence is the judge's job, in grounded-answers.An ID that exists in two versions cannot be told apart by the reply, because the citation carries no version. It isjudged against the asked version, so an ID shared by both versions is never wrong-version."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom collections import Counterfrom lib.contract import CITATION_OUTCOMES, citation_outcomes, parse_reply, section_ids_by_versionfrom lib.prompts import P1_SHA256, P2_SHA256from lib.replay import ReplayModelfrom lib.stats import pctfrom lib.testset import load_itemsRECORDINGS = (  # label, recording, the sha256 of the prompt it was made from    ("baseline", "assistant-baseline", P1_SHA256),    ("unfiltered", "assistant-unfiltered", P1_SHA256),  # same prompt; retrieval from every version, versions shown    ("prompt-b", "assistant-prompt-b", P2_SHA256),)ids = section_ids_by_version()items = load_items(split="dev")  # dev only: held-out items are not read here (plan section 3.4)for label, recording, prompt_sha256 in RECORDINGS:    model = ReplayModel(recording, prompt_sha256)    counts = Counter()    for item in items:        reply = parse_reply(model.reply(item.id, 0))        # The item's list for its asked version. An unanswerable item may also list another version: not counted here.        listed = frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)        counts.update(citation_outcomes(reply, item.version, listed, ids))    total = sum(counts.values())    print(f"{label} citations on dev items: {total}")    for outcome in CITATION_OUTCOMES:        print(f"{label} {outcome}: {pct(counts[outcome], total)}")
Saídapython check-citation-support.py
baseline 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 autojunk seja 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 com autojunk=False ela é 0.861.
fuzzy-match.py Python 3.12.15 · numpy 2.5.5 Aprovado
"""Compares three pairs of sablefile answers with an exact match and with difflib's ratio(), a score from 0 to 1.Each pair is a reference and a reply written for this example, not a recorded reply: two file names, a flag with onewrong letter, and a long answer that leaves out its folder sentence. ratio() is printed with the reference first and withthe reply first, because the documentation says the argument order can change the score. With the reference first, thelong reply is the second sequence and is 200 characters or more, so the autojunk heuristic applies to it; the long answeris also scored with autojunk turned off."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom difflib import SequenceMatcherFOLDERS = " Folders are created only with --apply, because a plain sync writes nothing."PLAN = " The plan lines start with create, update or unchanged, and the lock file is written only by the apply run."LONG_REFERENCE = (    "With no flag, sync prints the plan and writes nothing. --apply writes the files and updates the lock file, "    ".sablefile/lock.json." + FOLDERS + PLAN)LONG_REPLY = LONG_REFERENCE.replace(FOLDERS, "")  # the answer leaves out the folder sentencePAIRS = (    ("file names", ".sablefile/lock.json", "sablefile.lock"),    ("flag", "--apply", "--appply"),    ("long answer", LONG_REFERENCE, LONG_REPLY),)for name, reference, reply in PAIRS:    print(f"{name}, exact match: {reply == reference}")    print(f"{name}, ratio: {SequenceMatcher(None, reference, reply).ratio():.3f}")    print(f"{name}, ratio with the reply first: {SequenceMatcher(None, reply, reference).ratio():.3f}")# autojunk=False: the default treats the reply's common characters as junk once it is 200 characters or longer.print(f"long answer, ratio with autojunk off: {SequenceMatcher(None, LONG_REFERENCE, LONG_REPLY, autojunk=False).ratio():.3f}")
Saídapython fuzzy-match.py
file 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.

overlap-misleads.py Python 3.12.15 · numpy 2.5.5 Aprovado
"""Scores a wrong answer that shares most of its words with the reference above a right answer that shares few.Each pair in data/overlap-pairs.json is a question on sablefile 2.0 with its reference, a wrong answer and a right answer.All three pairs are hand-written for this example, not recorded replies. The scores are the textbook formulas, writtenhere in plain Python: ROUGE-1 F1 (unigram overlap, F1 of precision and recall) and a BLEU-style score (clipped 1- to4-gram precision, geometric mean, brevity penalty), with no smoothing. No BLEU or ROUGE package is pinned, and none isused. The reference facts are in examples/data/docs/2.0 (sync.md, quickstart.md, lockfile.md)."""import lib  # first: fixes the thread counts and seeds before anything else loadsimport jsonimport mathimport refrom collections import Counterfrom pathlib import PathPAIRS = json.loads((Path(__file__).resolve().parent / "data" / "overlap-pairs.json").read_text(encoding="utf-8"))def words(text: str) -> list[str]:    """Lowercase runs of letters and digits: `--apply` is the word apply, and `lock.json` is two words."""    return re.findall(r"[a-z0-9]+", text.lower())def rouge_1_f1(candidate: str, reference: str) -> float:    """ROUGE-1 F1: shared words, counted with repeats up to the smaller count, over both lengths."""    cand, ref = words(candidate), words(reference)    overlap = sum((Counter(cand) & Counter(ref)).values())    if overlap == 0:        return 0.0    precision, recall = overlap / len(cand), overlap / len(ref)    return 2 * precision * recall / (precision + recall)def bleu_sentence(candidate: str, reference: str, max_n: int = 4) -> float:    """Sentence BLEU-style score: clipped n-gram precision for n = 1 to 4, geometric mean, brevity penalty.    Without smoothing, a single n-gram order with no match gives 0, as the textbook formula does.    """    cand, ref = words(candidate), words(reference)    precisions = []    for n in range(1, max_n + 1):        cand_grams = Counter(tuple(cand[i : i + n]) for i in range(len(cand) - n + 1))        ref_grams = Counter(tuple(ref[i : i + n]) for i in range(len(ref) - n + 1))        clipped = sum(min(count, ref_grams[gram]) for gram, count in cand_grams.items())  # each n-gram up to the reference's count        if clipped == 0:            return 0.0        precisions.append(clipped / sum(cand_grams.values()))    # Short answers are penalised by the brevity penalty: a candidate shorter than the reference scores less.    brevity = (1.0 if len(cand) > len(ref) else math.exp(1 - len(ref) / len(cand)))    return brevity * math.exp(sum(math.log(p) for p in precisions) / max_n)for number, pair in enumerate(PAIRS, start=1):    print(f"pair {number} (hand-written), question: {pair['question']}")    for label in ("wrong", "right"):        print(f"pair {number}, {label} answer, ROUGE-1 F1: {rouge_1_f1(pair[label], pair['reference']):.3f}")        print(f"pair {number}, {label} answer, BLEU: {bleu_sentence(pair[label], pair['reference']):.3f}")# The claim the prose makes: the wrong answer overlaps the reference more than the right one, in every pair.higher = sum(rouge_1_f1(p["wrong"], p["reference"]) > rouge_1_f1(p["right"], p["reference"]) for p in PAIRS)print(f"pairs where the wrong answer has the higher ROUGE-1 F1: {higher} of {len(PAIRS)}")
Saídapython overlap-misleads.py
pair 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 é supported quando 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.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 4 de 11: Escreva verificações em código para as falhas que você encontrou

  1. O que uma verificação por código consegue ver
  2. Verificações de formato
  3. Verificações de citação
  4. Existência e versão
  5. Suporte
  6. Correspondência exata e correspondência aproximada
  7. Onde o BLEU e o ROUGE induzem a erro
  8. Recusas no código
  9. Executando as verificações e o que elas estabelecem

Voltar ao topoTodos os capítulos