Recuse-se quando a documentação não disser, e meça os dois tipos de erro
Cerca de 27 minutos min de leitura, com 3 exemplos em 6 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 contar as duas maneiras pelas quais um assistente deixa de responder a partir da sua documentação, ler as duas taxas sobre os seus próprios denominadores e dizer quando uma regra que recusa com mais frequência vale o que custa.
O assistente deste livro responde a perguntas sobre o sablefile, uma ferramenta de linha de comando que mantém os arquivos gerados de um projeto em sintonia com os modelos dos quais eles vêm, e responde a partir da documentação da ferramenta. Quando a documentação não cobre uma pergunta, o assistente deve responder com uma frase fixa, "The docs don't say.", e nada mais. Essa frase parece a resposta segura. Uma equipe que vê uma resposta errada nos seus registros é tentada a fazer o assistente recusar com mais frequência, porque uma recusa parece cuidadosa. Mas uma recusa também pode estar errada. Se a documentação respondia à pergunta, o usuário que recebeu a frase foi prejudicado, e esse erro não aparece em lugar nenhum. Se a documentação não respondia e o assistente respondeu mesmo assim, o usuário tem uma resposta sem nada por trás. Recusar com mais frequência troca um desses erros pelo outro. Uma equipe que conta apenas um deles vai ajustar o sistema em direção a um número que parece bom e esconde o custo do outro.
Este capítulo conta os dois erros nas respostas do próprio livro. Em seguida, testa a correção óbvia, uma salvaguarda que recusa quando a pontuação de busca da seção mais relevante é baixa, na variante sem filtro. Nessa variante, a salvaguarda não ajuda. Esse é o resultado do capítulo, e a maior parte do que segue trata de como esse resultado foi medido e de até onde ele pode ser confiável.
Dois erros, ambos contados
Cada pergunta do conjunto de teste tem um tipo. Uma pergunta respondível é aquela que a documentação da versão consultada responde. Uma pergunta não respondível é aquela que ela não responde. Uma resposta que recusa uma pergunta respondível comete uma recusa falsa, e uma resposta que responde a uma pergunta não respondível comete uma resposta falsa. O primeiro capítulo definiu os dois em sua verificação de recusa, e este capítulo usa as mesmas definições em mais itens.
As duas taxas têm denominadores diferentes, e são os denominadores que carregam o ponto. A taxa de recusa falsa é o número de itens respondíveis recusados, dividido pelo número de itens respondíveis. A taxa de resposta falsa é o número de itens não respondíveis respondidos, dividido pelo número de itens não respondíveis. Se você somar os dois erros sobre um único total, um conjunto com muitos itens respondíveis faz a contagem de recusas parecer pequena, e as respostas que deveriam ter sido recusas se perdem na soma. Cada taxa precisa da sua própria contagem, e cada contagem precisa do seu próprio denominador.
Dois tipos de item ficam fora das duas taxas. Um item dependente de versão pergunta sobre algo que difere entre versões, então sua resposta é julgada em relação à referência da versão consultada, e sua taxa própria, a correção por versão, é tratada no capítulo 9. Um item ambíguo tem duas leituras possíveis e é avaliado pela taxa de aprovação, não por nenhuma das taxas de recusa. Uma recusa em qualquer desses tipos não é erro aqui. O código ainda conta essas recusas e as imprime, para que uma recusa em um deles não passe despercebida.
O código só conta uma resposta como recusa quando ela é exatamente a frase de recusa e nada mais. Uma resposta que dá a frase e depois uma resposta não é uma recusa, e por isso conta como resposta nas duas taxas. O mesmo vale para uma recusa formulada com outras palavras: o código compara a frase exatamente, então uma recusa redigida de forma diferente conta como resposta. Em um item respondível, isso não é um erro de recusa falsa aqui, e em um item não respondível é uma resposta falsa, razão pela qual a frase está fixada no prompt.
Regra prática: Reporte as duas taxas de recusa separadamente, cada uma sobre seu próprio denominador, e deixe os itens dependentes de versão e os ambíguos fora de ambas. Leia os itens por trás de cada taxa, não apenas a taxa, porque uma taxa pode esconder os poucos itens que importam.
O que a linha de base faz
A linha de base é o assistente como o primeiro capítulo o construiu. Ela executa o prompt P1, que pede uma citação para cada afirmação e a frase de recusa quando as seções não respondem. Ela recupera as três seções mais bem classificadas com BM25, somente do índice da versão perguntada. Suas respostas foram registradas uma vez por item, e o exemplo lê essa resposta registrada.
Três variantes mudam uma coisa cada. prompt-b executa o prompt P2, que cita a frase em que a resposta se apoia antes de dar a resposta. k5 fornece ao modelo as cinco seções mais bem classificadas, em vez de três. unfiltered recupera dos índices de todas as versões juntas, com a versão de cada seção indicada no cabeçalho, para que o modelo possa perceber quando uma seção vem de outra versão. Cada variante tem seu próprio registro de respostas para os mesmos itens, de modo que cada comparação é entre respostas às mesmas perguntas.
Contar os dois tipos de erro para cada registro exige um exemplo, decline-rates. Ele lê os quatro registros no conjunto de desenvolvimento e no conjunto de teste reservado, imprime cada taxa com suas contagens e nomeia os itens por trás de cada erro. Sua saída mostra quais itens respondíveis cada registro recusou e quais itens não respondíveis ele respondeu.
1"""Counts the two decline errors for each recording, on dev and on held-out: answerable items declined (false refusals)2and unanswerable items answered (false answers). Each rate line rests on its own count and denominator.34Version-dependent and ambiguous items are left out of both rates; the last line per split counts the declines among5them, which are not errors here."""6import lib # first: fixes the thread counts and seeds before anything else loads78from lib.contract import parse_reply9from lib.prompts import P1_SHA256, P2_SHA25610from lib.replay import ReplayModel11from lib.stats import pct12from lib.testset import load_items1314VARIANTS = ( # label, recording, the sha256 of the prompt it was made from15 ("baseline", "assistant-baseline", P1_SHA256), # P1, k=3, filtered to the asked version16 ("unfiltered", "assistant-unfiltered", P1_SHA256), # P1, k=3, sections from every version17 ("prompt-b", "assistant-prompt-b", P2_SHA256), # P2, k=3, filtered18 ("k5", "assistant-k5", P1_SHA256), # P1, k=5, filtered19)2021for label, recording, prompt_sha256 in VARIANTS:22 model = ReplayModel(recording, prompt_sha256) # refuses a recording made from another prompt23 for split in ("dev", "held-out"):24 items = load_items(split=split)25 declined = {item.id: parse_reply(model.reply(item.id, 0)).declined for item in items} # sample 0 only26 answerable = [item for item in items if item.kind == "answerable"]27 unanswerable = [item for item in items if item.kind == "unanswerable"]28 refused = sorted(item.id for item in answerable if declined[item.id])29 answered = sorted(item.id for item in unanswerable if not declined[item.id])30 other_kinds = ("version-dependent", "ambiguous")31 other = [item.id for item in items if item.kind in other_kinds and declined[item.id]]32 print(f"{label} {split} false refusal rate (answerable declined): {pct(len(refused), len(answerable))}")33 print(f"{label} {split} false refusals: {', '.join(refused) or 'none'}")34 print(f"{label} {split} false answer rate (unanswerable answered): {pct(len(answered), len(unanswerable))}")35 print(f"{label} {split} false answers: {', '.join(answered) or 'none'}")36 for item_id in answered: # what each false answer cites, and its text, so the chapter's claims can be checked37 reply = parse_reply(model.reply(item_id, 0))38 print(f"{label} {split} reply to {item_id} cites: {', '.join(reply.citations) or 'none'}")39 print(f"{label} {split} reply to {item_id} text: {reply.text}")40 print(f"{label} {split} declined, not counted (version-dependent and ambiguous): {len(other)}")
python decline-rates.pybaseline dev false refusal rate (answerable declined): 10.0% (4 of 40)
baseline dev false refusals: q-0052, q-0060, q-0063, q-0079
baseline dev false answer rate (unanswerable answered): 0.0% (0 of 13)
baseline dev false answers: none
baseline dev declined, not counted (version-dependent and ambiguous): 6
baseline held-out false refusal rate (answerable declined): 30.0% (6 of 20)
baseline held-out false refusals: q-0101, q-0102, q-0103, q-0105, q-0111, q-0118
baseline held-out false answer rate (unanswerable answered): 0.0% (0 of 7)
baseline held-out false answers: none
baseline held-out declined, not counted (version-dependent and ambiguous): 2
unfiltered dev false refusal rate (answerable declined): 12.5% (5 of 40)
unfiltered dev false refusals: q-0005, q-0052, q-0058, q-0060, q-0079
unfiltered dev false answer rate (unanswerable answered): 15.4% (2 of 13)
unfiltered dev false answers: q-0018, q-0039
unfiltered dev reply to q-0018 cites: remote-retries
unfiltered dev reply to q-0018 text: Yes, sablefile 1.1 can fetch a remote template from a private URL that needs a login token, as long as the token is included in the request. The retry behavior for such fetches is up to 5 times before giving up, and this applies to `sync` and `diff` operations [sec:remote-retries]. The `check` command does not fetch anything and thus does not apply to such scenarios.
unfiltered dev reply to q-0039 cites: check-exit-status
unfiltered dev reply to q-0039 text: When check finds a drifted file, it prints `DRIFT` and the path, and exits with status 1. [sec:check-exit-status]
unfiltered dev declined, not counted (version-dependent and ambiguous): 9
unfiltered held-out false refusal rate (answerable declined): 45.0% (9 of 20)
unfiltered held-out false refusals: q-0101, q-0102, q-0103, q-0105, q-0106, q-0111, q-0115, q-0116, q-0117
unfiltered held-out false answer rate (unanswerable answered): 0.0% (0 of 7)
unfiltered held-out false answers: none
unfiltered held-out declined, not counted (version-dependent and ambiguous): 3
prompt-b dev false refusal rate (answerable declined): 7.5% (3 of 40)
prompt-b dev false refusals: q-0052, q-0063, q-0079
prompt-b dev false answer rate (unanswerable answered): 0.0% (0 of 13)
prompt-b dev false answers: none
prompt-b dev declined, not counted (version-dependent and ambiguous): 4
prompt-b held-out false refusal rate (answerable declined): 25.0% (5 of 20)
prompt-b held-out false refusals: q-0101, q-0102, q-0103, q-0105, q-0111
prompt-b held-out false answer rate (unanswerable answered): 0.0% (0 of 7)
prompt-b held-out false answers: none
prompt-b held-out declined, not counted (version-dependent and ambiguous): 0
k5 dev false refusal rate (answerable declined): 7.5% (3 of 40)
k5 dev false refusals: q-0052, q-0062, q-0079
k5 dev false answer rate (unanswerable answered): 0.0% (0 of 13)
k5 dev false answers: none
k5 dev declined, not counted (version-dependent and ambiguous): 5
k5 held-out false refusal rate (answerable declined): 30.0% (6 of 20)
k5 held-out false refusals: q-0102, q-0103, q-0105, q-0106, q-0111, q-0116
k5 held-out false answer rate (unanswerable answered): 0.0% (0 of 7)
k5 held-out false answers: none
k5 held-out declined, not counted (version-dependent and ambiguous): 2
A taxa de falsa recusa da linha de base no desenvolvimento é 10.0% (4 of 40). Suas falsas recusas são q-0052, q-0060, q-0063 e q-0079, e cada uma é um item respondível que a documentação cobre. Sua taxa de falsa resposta no desenvolvimento é 0.0% (0 of 13), portanto ela não responde a nenhum dos itens não respondíveis do desenvolvimento. O capítulo 1 também não encontrou nenhuma falsa resposta, em apenas quatro itens não respondíveis, número pequeno demais para dizer muito sobre uma taxa. A linha de base também recusou 6 itens do desenvolvimento que pertencem às duas categorias deixadas de fora de ambas as taxas.
Capítulo 2 conta 10 recusas excessivas para esta linha de base. Essa contagem abrange todos os itens que a documentação responde, inclusive os dependentes de versão, portanto inclui as falsas recusas acima e as recusas em itens dependentes de versão e ambíguos, que esta taxa deixa de fora.
A tabela coloca os quatro registros lado a lado, nos dois conjuntos. Cada célula contém uma taxa com suas contagens.
| Registro | Falsas recusas no desenvolvimento | Falsas respostas no desenvolvimento | Falsas recusas no teste reservado | Falsas respostas no teste reservado |
|---|---|---|---|---|
| baseline | 10.0% (4 of 40) | 0.0% (0 of 13) | 30.0% (6 of 20) | 0.0% (0 of 7) |
| unfiltered | 12.5% (5 of 40) | 15.4% (2 of 13) | 45.0% (9 of 20) | 0.0% (0 of 7) |
| prompt-b | 7.5% (3 of 40) | 0.0% (0 of 13) | 25.0% (5 of 20) | 0.0% (0 of 7) |
| k5 | 7.5% (3 of 40) | 0.0% (0 of 13) | 30.0% (6 of 20) | 0.0% (0 of 7) |
Leia primeiro a linha unfiltered, porque é a única com falsas respostas no desenvolvimento. Sua taxa de falsa recusa é 12.5% (5 of 40). A da linha de base é 10.0% (4 of 40). Unfiltered recusa dois itens respondíveis que a linha de base responde, q-0005 e q-0058, e responde q-0063, que a linha de base recusa. O saldo é um item recusado a mais em quarenta. Cada diferença de recusa em relação à linha de base no desenvolvimento é de um item em quarenta. Nesses itens, um item não é base para uma conclusão sobre qual registro é melhor, e intervalos e tamanho da amostra explica o que uma amostra desse tamanho pode mostrar.
A variante unfiltered também responde a dois itens não respondíveis do desenvolvimento, em que a linha de base não responde nenhum. Sua taxa de falsa resposta é 15.4% (2 of 13). Trata-se de uma contagem de dois itens, sem intervalo, por isso este capítulo a relata como contagem e não como aumento medido. As duas falsas respostas são q-0018 e q-0039.
Ambas as perguntas são sobre o sablefile 1.1, e a documentação 1.1 deixa de fora as duas respostas: se um modelo remoto pode ser obtido de um endereço privado com um token de login, e qual status de saída diff retorna quando encontra diferenças. A linha de base recusa as duas. As respostas unfiltered respondem às duas, e cada uma cita uma seção vizinha. A resposta a q-0018 cita remote-retries, a regra de novas tentativas para obtenções remotas. A resposta a q-0039 cita check-exit-status e dá o status de saída de check, um comando diferente do diff sobre o qual a pergunta pergunta. O exemplo imprime cada citação e o texto de cada resposta, de modo que essas afirmações podem ser verificadas sem abrir o registro. A variante unfiltered muda a recuperação, não o prompt, por isso as citações são o primeiro lugar para olhar.
As variantes que movem as recusas do desenvolvimento no sentido oposto são prompt-b e k5. Cada uma tem uma falsa recusa a menos no desenvolvimento do que a linha de base, e nenhuma responde a um item não respondível do desenvolvimento. A taxa de falsa recusa de prompt-b é 7.5% (3 of 40). Para k5 é 7.5% (3 of 40). Nesses itens, cada uma tem uma a menos que a linha de base, e um item não é base para uma conclusão.
Os números do teste reservado são apresentados para completude. A taxa de falsa recusa de prompt-b é 25.0% (5 of 20). Para k5 é 30.0% (6 of 20). Para a linha de base é 30.0% (6 of 20). A diferença entre prompt-b e a linha de base é de um item em vinte, e nesses itens não é base para uma conclusão. Nenhuma variante é escolhida neste capítulo, porque as diferenças no desenvolvimento são de um único item cada.
Regra prática: Leia à mão cada falsa recusa do conjunto de desenvolvimento antes de alterar um prompt, pois uma delas pode apontar para uma lacuna real na documentação. Compare as variantes nos mesmos itens, e relate um intervalo pareado somente quando um exemplo o imprimir. Quando nenhum for impresso, relate as contagens nesses itens e não tire conclusão sobre qual variante é melhor. Execute o conjunto de teste reservado uma vez, para confirmar uma escolha feita no desenvolvimento. A variante unfiltered é o alerta aqui: no desenvolvimento ela responde a itens não respondíveis que a linha de base recusa. Este capítulo relata isso sem intervalo, portanto é um motivo para verificar, não um aumento medido.
Um guarda sobre respostas gravadas
O guarda repousa numa ideia simples. O BM25 pontua cada seção pelas palavras que ela compartilha com a pergunta. Quando a documentação não tem nada sobre uma pergunta, a seção mais bem pontuada deve compartilhar poucas palavras com ela, de modo que sua pontuação deve ser baixa. Um guarda lê a pontuação da seção mais bem pontuada e recusa quando ela fica abaixo de um limiar. A ideia é uma hipótese, e pode falhar. Uma pergunta pode compartilhar muitas palavras com uma seção que não a responde, e a varredura abaixo é o teste.
O guarda pode ser medido sem executar o modelo novamente. A recuperação é determinística: a mesma pergunta retorna as mesmas seções principais e as mesmas pontuações a cada vez. Assim, a pontuação principal de cada item pode ser calculada a partir do índice, e o guarda se torna uma regra aplicada a respostas que já foram gravadas. A grade e a regra são constantes em lib/guard.py. O guarda só transforma respostas em recusas. Ele nunca pode desfazer uma recusa, por isso pode reduzir respostas falsas e só pode aumentar recusas falsas.
A pontuação do guarda deve vir do índice que produziu as respostas que ele julga, e as respostas sem filtro foram produzidas a partir de seções de todas as versões. Por isso o guarda lê a gravação de unfiltered e toma a maior pontuação BM25 sobre o índice de todas as versões. Uma pontuação do índice da versão consultada seria medida sobre seções que o modelo sem filtro nunca viu. O guarda é testado na variante sem filtro porque a linha de base não responde a nenhum item de desenvolvimento sem resposta, de modo que não há o que um guarda remover ali, enquanto a variante sem filtro responde a dois. Este capítulo não faz nenhuma afirmação sobre um guarda na linha de base.
A grade vai de 0.00 a 10.00 em passos de um quarto, acima de todas as pontuações de desenvolvimento. Para cada limiar, a regra soma as duas taxas, cada uma sobre seu próprio denominador, e escolhe o limiar com a menor soma. Essa ponderação igual é uma escolha, e a seção sobre excessos e faltas retorna a ela. Em caso de empate, vale o limiar mais baixo, porque ele altera menos respostas. A regra está declarada em lib/guard.py e escolhe no desenvolvimento. A divisão de teste não está intocada, pois a primeira tabela em o que a linha de base faz já mostra suas taxas sem guarda. A execução do guarda no teste ocorreu uma única vez, no limiar congelado.
A varredura é executada em tune-guard-dev, que imprime as duas taxas em cada passo da grade e depois a escolha da regra. Ela começa com a verificação que mais importa: as seções gravadas de cada item devem coincidir com o que o índice retorna, ou as pontuações descreveriam uma recuperação que nunca produziu as respostas.
1"""Sweeps the decline guard's threshold over dev replies of the unfiltered recording, printing both rates at each2threshold, and the threshold the dev rule picks. The line for 0.00 is the recorded replies with no guard, since no top3score is below zero; the rule's pick rests on the rate lines below it. Only dev is read here."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.guard import GRID, GUARD_RECORDING, RULE, contexts_match, denominators, errors, pick_threshold, rows7from lib.stats import pct89dev = rows("dev")10answerable, unanswerable = denominators(dev)11print(f"recording: {GUARD_RECORDING} (all versions, dev items)")12print(f"answerable dev items: {answerable}")13print(f"unanswerable dev items: {unanswerable}")1415mismatches = contexts_match("dev")16print(f"dev items whose recorded sections differ from the retrieval: {mismatches}")17assert mismatches == 0, "the scores come from a retrieval that did not make the recorded replies"18highest = max(row.score for row in dev)19print(f"highest top score on dev: {highest:.3f}")20assert highest < GRID[-1], "the grid must reach above every dev score"2122print(f"rule: {RULE}")23for threshold in GRID:24 refusals, answers = errors(dev, threshold)25 print(f"threshold {threshold:.2f}, false refusal rate: {pct(len(refusals), answerable)}")26 print(f"threshold {threshold:.2f}, false answer rate: {pct(len(answers), unanswerable)}")2728refusals, answers = errors(dev, 0.0)29print(f"recorded false refusals (no guard): {', '.join(refusals) or 'none'}")30print(f"recorded false answers (no guard): {', '.join(answers) or 'none'}")31scores = {row.item_id: row.score for row in dev}32for item_id in answers: # the top score of each recorded false answer, so a reader can see where it falls on the grid33 print(f"top score of recorded false answer {item_id}: {scores[item_id]:.3f}")3435chosen = pick_threshold(dev)36assert chosen == 0.0, f"the dev rule now picks {chosen:.2f}, not 0.00"37refusals, answers = errors(dev, chosen)38print(f"threshold chosen by the dev rule: {chosen:.2f}")39print(f"at the chosen threshold, false refusal rate: {pct(len(refusals), answerable)}")40print(f"at the chosen threshold, false answer rate: {pct(len(answers), unanswerable)}")
python tune-guard-dev.pyrecording: assistant-unfiltered (all versions, dev items)
answerable dev items: 40
unanswerable dev items: 13
dev items whose recorded sections differ from the retrieval: 0
highest top score on dev: 9.949
rule: pick the threshold in GRID whose false refusal rate plus false answer rate is smallest, each rate over its own denominator; when two thresholds tie, take the lower one
threshold 0.00, false refusal rate: 12.5% (5 of 40)
threshold 0.00, false answer rate: 15.4% (2 of 13)
threshold 0.25, false refusal rate: 12.5% (5 of 40)
threshold 0.25, false answer rate: 15.4% (2 of 13)
threshold 0.50, false refusal rate: 12.5% (5 of 40)
threshold 0.50, false answer rate: 15.4% (2 of 13)
threshold 0.75, false refusal rate: 12.5% (5 of 40)
threshold 0.75, false answer rate: 15.4% (2 of 13)
threshold 1.00, false refusal rate: 12.5% (5 of 40)
threshold 1.00, false answer rate: 15.4% (2 of 13)
threshold 1.25, false refusal rate: 12.5% (5 of 40)
threshold 1.25, false answer rate: 15.4% (2 of 13)
threshold 1.50, false refusal rate: 12.5% (5 of 40)
threshold 1.50, false answer rate: 15.4% (2 of 13)
threshold 1.75, false refusal rate: 12.5% (5 of 40)
threshold 1.75, false answer rate: 15.4% (2 of 13)
threshold 2.00, false refusal rate: 12.5% (5 of 40)
threshold 2.00, false answer rate: 15.4% (2 of 13)
threshold 2.25, false refusal rate: 15.0% (6 of 40)
threshold 2.25, false answer rate: 15.4% (2 of 13)
threshold 2.50, false refusal rate: 17.5% (7 of 40)
threshold 2.50, false answer rate: 15.4% (2 of 13)
threshold 2.75, false refusal rate: 17.5% (7 of 40)
threshold 2.75, false answer rate: 15.4% (2 of 13)
threshold 3.00, false refusal rate: 20.0% (8 of 40)
threshold 3.00, false answer rate: 15.4% (2 of 13)
threshold 3.25, false refusal rate: 30.0% (12 of 40)
threshold 3.25, false answer rate: 15.4% (2 of 13)
threshold 3.50, false refusal rate: 32.5% (13 of 40)
threshold 3.50, false answer rate: 15.4% (2 of 13)
threshold 3.75, false refusal rate: 37.5% (15 of 40)
threshold 3.75, false answer rate: 15.4% (2 of 13)
threshold 4.00, false refusal rate: 40.0% (16 of 40)
threshold 4.00, false answer rate: 7.7% (1 of 13)
threshold 4.25, false refusal rate: 45.0% (18 of 40)
threshold 4.25, false answer rate: 7.7% (1 of 13)
threshold 4.50, false refusal rate: 55.0% (22 of 40)
threshold 4.50, false answer rate: 7.7% (1 of 13)
threshold 4.75, false refusal rate: 60.0% (24 of 40)
threshold 4.75, false answer rate: 0.0% (0 of 13)
threshold 5.00, false refusal rate: 62.5% (25 of 40)
threshold 5.00, false answer rate: 0.0% (0 of 13)
threshold 5.25, false refusal rate: 70.0% (28 of 40)
threshold 5.25, false answer rate: 0.0% (0 of 13)
threshold 5.50, false refusal rate: 77.5% (31 of 40)
threshold 5.50, false answer rate: 0.0% (0 of 13)
threshold 5.75, false refusal rate: 77.5% (31 of 40)
threshold 5.75, false answer rate: 0.0% (0 of 13)
threshold 6.00, false refusal rate: 80.0% (32 of 40)
threshold 6.00, false answer rate: 0.0% (0 of 13)
threshold 6.25, false refusal rate: 82.5% (33 of 40)
threshold 6.25, false answer rate: 0.0% (0 of 13)
threshold 6.50, false refusal rate: 87.5% (35 of 40)
threshold 6.50, false answer rate: 0.0% (0 of 13)
threshold 6.75, false refusal rate: 87.5% (35 of 40)
threshold 6.75, false answer rate: 0.0% (0 of 13)
threshold 7.00, false refusal rate: 92.5% (37 of 40)
threshold 7.00, false answer rate: 0.0% (0 of 13)
threshold 7.25, false refusal rate: 92.5% (37 of 40)
threshold 7.25, false answer rate: 0.0% (0 of 13)
threshold 7.50, false refusal rate: 92.5% (37 of 40)
threshold 7.50, false answer rate: 0.0% (0 of 13)
threshold 7.75, false refusal rate: 92.5% (37 of 40)
threshold 7.75, false answer rate: 0.0% (0 of 13)
threshold 8.00, false refusal rate: 92.5% (37 of 40)
threshold 8.00, false answer rate: 0.0% (0 of 13)
threshold 8.25, false refusal rate: 95.0% (38 of 40)
threshold 8.25, false answer rate: 0.0% (0 of 13)
threshold 8.50, false refusal rate: 95.0% (38 of 40)
threshold 8.50, false answer rate: 0.0% (0 of 13)
threshold 8.75, false refusal rate: 95.0% (38 of 40)
threshold 8.75, false answer rate: 0.0% (0 of 13)
threshold 9.00, false refusal rate: 97.5% (39 of 40)
threshold 9.00, false answer rate: 0.0% (0 of 13)
threshold 9.25, false refusal rate: 97.5% (39 of 40)
threshold 9.25, false answer rate: 0.0% (0 of 13)
threshold 9.50, false refusal rate: 97.5% (39 of 40)
threshold 9.50, false answer rate: 0.0% (0 of 13)
threshold 9.75, false refusal rate: 97.5% (39 of 40)
threshold 9.75, false answer rate: 0.0% (0 of 13)
threshold 10.00, false refusal rate: 100.0% (40 of 40)
threshold 10.00, false answer rate: 0.0% (0 of 13)
recorded false refusals (no guard): q-0005, q-0052, q-0058, q-0060, q-0079
recorded false answers (no guard): q-0018, q-0039
top score of recorded false answer q-0018: 3.762
top score of recorded false answer q-0039: 4.592
threshold chosen by the dev rule: 0.00
at the chosen threshold, false refusal rate: 12.5% (5 of 40)
at the chosen threshold, false answer rate: 15.4% (2 of 13)
A verificação passa: zero itens de desenvolvimento diferem, e o exemplo afirma que essa contagem é zero. A maior pontuação principal no desenvolvimento é 9.949, que fica abaixo do topo da grade.
Comece pela base da varredura. Em 0.00 nenhuma pontuação fica abaixo do limiar, então a linha mostra as respostas gravadas sem nenhum guarda. A taxa de recusas falsas ali é 12.5% (5 of 40). A taxa de respostas falsas é 15.4% (2 of 13). Todas as linhas até 2.00 mostram o mesmo valor. Em 2.25 as recusas falsas começam a subir, para 15.0% (6 of 40).
As respostas falsas só caem em 4.00, onde a taxa de respostas falsas é 7.7% (1 of 13). Em 4.75 a taxa de respostas falsas é 0.0% (0 of 13), portanto nenhum item de desenvolvimento sem resposta é respondido. A taxa de recusas falsas em 4.75 é 60.0% (24 of 40).
Nenhuma linha da varredura reduz as duas taxas abaixo da linha sem guarda. Cada limiar que reduz as respostas falsas aumenta as recusas falsas, e cada limiar que deixa as recusas intactas deixa as respostas intactas. No desenvolvimento, o guarda faz uma troca e não uma melhoria.
A varredura também mostra o limite da pontuação. A maior pontuação de q-0018 é 3.762, e a maior pontuação de q-0039 é 4.592. Um limiar captura q-0018 somente a partir de 4.00, onde a taxa de recusas falsas já é 40.0% (16 of 40). Captura q-0039 somente a partir de 4.75. Nenhum corte captura ambos os itens respondidos com menos da metade dos itens respondíveis recusados. A causa provável é a própria pontuação: ela conta palavras compartilhadas, e uma seção sobre o mesmo comando pode compartilhar muitas palavras com uma pergunta que essa seção não responde. Essa é uma leitura da varredura, não um fato medido. Testá-la exigiria pontuar os itens à mão, o que este capítulo não faz.
A escolha da regra é 0.00. Nesse limiar a taxa de recusas falsas é 12.5% (5 of 40). A taxa de respostas falsas é 15.4% (2 of 13). Ambas são iguais às respostas gravadas sem nenhum guarda. A escolha é um desempate, não uma descoberta. As linhas de 0.00 a 2.00 têm a mesma soma, e a regra toma a menor delas, de modo que o guarda escolhido pela regra é nenhum guarda.
Regra prática: Construa as pontuações de um guarda a partir do mesmo índice que produziu as respostas, e verifique essa correspondência antes de ler qualquer taxa. Depois leia a varredura inteira, com as duas taxas em cada linha. Uma escolha que empata com não fazer nada diz que a regra não encontrou motivo para alterar nenhuma resposta, e isso é uma resposta que vale guardar.
Recusas em excesso e poucas
A varredura mostra o dilema (trade-off) que uma equipe enfrentaria se acrescentasse o guarda, e mostra o que cada escolha de medida reportaria. Suponha que uma equipe contasse apenas as respostas falsas. O menor limite que interrompe toda resposta falsa no conjunto de desenvolvimento é 4.75, então essa equipe escolheria 4.75 e reportaria que o assistente já não responde a perguntas que não consegue sustentar. A linha de 4.75 de a varredura mostra o preço que esse relatório esconde. Em 4.75 a taxa de recusas falsas é 60.0% (24 of 40). Nada no relatório diria isso, porque a equipe nunca contou o outro erro.
Em produção, essa é a falha a observar. Um usuário que faz uma pergunta que a documentação responde recebe a frase de recusa, e a resposta não dá nenhum sinal de que a frase estava errada. O único lugar onde o custo aparece é na contagem de recusas falsas. Uma equipe que não a conta lê o zero nas respostas falsas e coloca o sistema no ar.
A regra atribui o mesmo peso aos dois erros, e essa é uma escolha que cabe à equipe. Uma equipe pode julgar que uma resposta falsa custa muito mais do que uma recusa falsa, por exemplo quando uma resposta errada e confiante leva o usuário à correção errada. Essa equipe obteria outra escolha no conjunto de desenvolvimento assim que seu peso fosse grande o bastante para mudar a soma, e a varredura mostra a direção: um peso maior para as respostas falsas empurra a escolha para limites que recusam mais. Essa equipe deve registrar seus pesos antes de alguém ler a varredura e só então entregá-los à regra. Este capítulo não reexecuta a regra com outros pesos, e não reabre a divisão reservada para fazê-lo. Escolher um peso depois de ver os números da divisão reservada seria uma segunda rodada de ajuste sobre essa divisão.
O limite também pertence ao assistente que produziu as respostas. As pontuações dependem do índice, que depende de como as seções são divididas e de quais versões estão nele. Se qualquer um desses itens mudar, as pontuações se movem, e o limite precisa ser escolhido de novo no conjunto de desenvolvimento, e a primeira verificação do exemplo precisa passar outra vez antes que alguém leia uma taxa.
Regra prática: Antes de ajustar um limite, escreva o custo de cada erro nos termos da própria equipe e entregue à regra esses pesos antes de alguém ler a varredura.
O que o leitor deve aceitar
A divisão held-out foi executada uma única vez, com o limiar fixado em 0.00. A execução é guard-held-out e, antes de tudo, verifica se a regra de desenvolvimento (descrita em o guarda) ainda escolhe esse valor. Uma mudança nos dados de desenvolvimento ou na regra interrompe a execução antes que qualquer número de teste seja impresso.
1"""Applies the decline guard, with its threshold frozen from dev, to the held-out items of the unfiltered recording, and2prints both rates with 95% bootstrap intervals over items. The threshold is a constant chosen by tune-guard-dev's rule3on dev; the assert checks that the rule still picks it, so a change to the dev data or the rule fails here."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.guard import denominators, errors, guarded, pick_threshold, rows7from lib.stats import bootstrap_mean, interval_pct, pct89# Picked on dev by tune-guard-dev (the rule in lib/guard.py), then frozen. Held-out is not used to change it.10FROZEN_THRESHOLD = 0.01112dev_pick = pick_threshold(rows("dev")) # reads dev only13assert dev_pick == FROZEN_THRESHOLD, f"the dev rule now picks {dev_pick:.2f}, not the frozen {FROZEN_THRESHOLD:.2f}"1415held = rows("held-out")16answerable, unanswerable = denominators(held)17refusals, answers = errors(held, FROZEN_THRESHOLD)18print(f"threshold (frozen from dev): {FROZEN_THRESHOLD:.2f}")19print(f"held-out answerable items: {answerable}")20print(f"held-out unanswerable items: {unanswerable}")21changed = [row.item_id for row in held if guarded(row, FROZEN_THRESHOLD) != row.declined]22print(f"held-out replies the guard changed to declines: {len(changed)} of {len(held)}")2324# One 0/1 flag per item: the bootstrap over these flags is the bootstrap of the rate, over items.25refused_flags = [float(guarded(row, FROZEN_THRESHOLD)) for row in held if row.kind == "answerable"]26answered_flags = [float(not guarded(row, FROZEN_THRESHOLD)) for row in held if row.kind == "unanswerable"]27assert len(refused_flags) == answerable and len(answered_flags) == unanswerable2829refusal_lo, refusal_hi = bootstrap_mean(refused_flags, level=0.95) # 2,000 resamples, seeded (lib/stats.py)30answer_lo, answer_hi = bootstrap_mean(answered_flags, level=0.95)31print(f"false refusal rate: {pct(len(refusals), answerable)} interval {interval_pct(refusal_lo, refusal_hi)}")32print(f"false refusals: {', '.join(refusals) or 'none'}")33print(f"false answer rate: {pct(len(answers), unanswerable)} interval {interval_pct(answer_lo, answer_hi)}")34print(f"false answers: {', '.join(answers) or 'none'}")
python guard-held-out.pythreshold (frozen from dev): 0.00
held-out answerable items: 20
held-out unanswerable items: 7
held-out replies the guard changed to declines: 0 of 27
false refusal rate: 45.0% (9 of 20) interval [25.0%, 70.0%]
false refusals: q-0101, q-0102, q-0103, q-0105, q-0106, q-0111, q-0115, q-0116, q-0117
false answer rate: 0.0% (0 of 7) interval [0.0%, 0.0%]
false answers: none
O guarda congelado altera 0 of 27 respostas do teste, portanto a saída held-out é a saída registrada sem guarda. Na divisão de teste, a taxa de recusas falsas é 45.0% (9 of 20) interval [25.0%, 70.0%]. A taxa de respostas falsas é 0.0% (0 of 7) interval [0.0%, 0.0%].
A taxa de recusas falsas é igual à da variante sem filtro na primeira tabela, e a execução de teste concorda com o desenvolvimento no ponto principal: o guarda não faz nada no limiar escolhido pela regra. Uma equipe que olhasse apenas a taxa de respostas falsas no teste veria zero e concluiria que o assistente não responde o que não consegue sustentar. O erro está nas recusas, e nenhum limiar pode removê-las, porque o guarda apenas acrescenta recusas.
A taxa de respostas falsas no teste é 0.0% (0 of 7) interval [0.0%, 0.0%].
O intervalo impresso não tem largura. O intervalo reamostra os sete itens não respondíveis do teste. Nenhum deles é respondido de forma errada, então toda reamostragem não tem erros, e o bootstrap não consegue variar. Fidedignidade apresenta o raciocínio para esse caso de zero eventos, e este exemplo não imprime um limite exato, portanto o intervalo não deve ser lido como limite. Ele não consegue distinguir uma taxa de respostas falsas igual a zero de uma taxa pequena que esses sete itens simplesmente não capturaram. Sete itens mostram apenas que nenhum deles foi respondido de forma errada.
A divisão de desenvolvimento não é melhor. No desenvolvimento, as respostas sem filtro dão 15.4% (2 of 13) sem guarda. Com 4.00, dão 7.7% (1 of 13), um item a menos.
O intervalo da taxa de recusas falsas é amplo por outro motivo: vinte itens deixam uma faixa de taxas que os dados não conseguem distinguir. O valor do teste é 45.0% (9 of 20) interval [25.0%, 70.0%]. Intervalos e tamanho amostral explica o bootstrap sobre itens que constrói esses intervalos e quantos itens uma diferença pareada precisa. Kohavi e colegas fazem o mesmo ponto para experimentos controlados na web. No guia deles, Experimentos controlados na web: levantamento e guia prático, um teste com poder insuficiente é apontado como um erro comum. Uma divisão de teste com sete itens tem poder insuficiente para uma taxa tão pequena, e o capítulo diz isso em vez de deixar o zero valer como certeza.
Ao todo, os resultados dizem algo específico. Na variante sem filtro, no limiar escolhido pela regra de desenvolvimento, o guarda não altera nenhuma resposta, então este capítulo não o acrescenta. Ambos os erros permanecem nas respostas sem filtro no desenvolvimento. No teste, as recusas falsas são o custo, e nada neste capítulo as reduz. O resultado é uma decisão, e é a que a medição sustenta.
As decisões do capítulo são estas:
- Ambas as taxas de recusa (recusas falsas e respostas falsas) entram em toda comparação, cada uma sobre o seu próprio denominador.
- Itens dependentes de versão e ambíguos ficam de fora das duas taxas, e suas recusas são contadas separadamente.
- Uma regra de recusa é escolhida no desenvolvimento, com seus pesos anotados antes, a varredura completa lida e a escolha congelada antes de o teste ser executado.
- O teste é executado uma vez por regra. Um intervalo sobre zero eventos é relatado com essa ressalva, não como um achado de zero.
- O guarda baseado na pontuação de recuperação não é acrescentado à variante sem filtro. Sua escolha no desenvolvimento não altera nenhuma resposta, e sua execução no teste não altera nenhuma.
Regra prática: Um guarda só se justifica quando sua execução no teste altera respostas na direção que sua varredura no desenvolvimento prometeu. Quando isso não acontece, mantenha o resultado, pois ele mostra quais erros o assistente tem e que um limiar sobre a pontuação de recuperação não os corrige.
Fora deste livro
Este capítulo não trata de ataques. Um usuário que tenta fazer o assistente dizer o que ele não deveria dizer é uma questão de segurança, com ameaças e defesas próprias, e há um livro separado planejado para ela, Securing LLM Applications and Agents. As taxas de recusa aqui medem perguntas honestas sobre a documentação, e nada nelas informa como um assistente se comporta sob pressão de um usuário que está tentando quebrá-lo.
Outros pesquisadores mediram a mesma troca em outros modelos, e vale conhecer as afirmações sem tomar emprestados os seus números. O XSTest é um conjunto de testes de prompts seguros que parecem inseguros. Seus autores o construíram porque modelos recusam prompts seguros que usam uma redação parecida com a de prompts inseguros, ou que tocam em um tema sensível (Röttger and colleagues, 2024). O OR-Bench, publicado na ICML 2025, mediu muitos modelos e relata que a segurança extra de modelos ajustados para segurança muitas vezes veio acompanhada de mais recusas excessivas (Cui and colleagues, 2024). Uma revisão sobre abstenção em modelos de linguagem dá o nome geral para a recusa de um modelo em responder, e a organiza segundo a consulta, o modelo e os valores humanos (Wen and colleagues, 2024). Um benchmark de 2026 na área de saúde relata recusas excessivas de prompts benignos nesse domínio, em um conjunto próprio de prompts (Zhang and colleagues, 2026).
Esses artigos testam outros modelos em outros conjuntos, então suas taxas não se transferem para este assistente. O que se transfere é a forma deles, que é a afirmação que este capítulo testa no seu próprio caso. Neste conjunto, a proteção só consegue reduzir as respostas falsas recusando mais itens respondíveis, o que é uma troca de respostas falsas por recusas falsas. Mudanças no prompt e na recuperação podem mover os dois tipos de erro, e a variante sem filtro fez isso. Os únicos resultados que este capítulo relata são as execuções do próprio livro.
Regra prática: Antes de adotar uma regra de recusa porque um artigo relata que modelos recusam em excesso, meça a regra no seu próprio assistente e nos seus próprios itens, contando os dois tipos de erro. Mantenha os números do artigo fora dos seus resultados e cite o artigo pela ideia que motivou a medição.
Este capítulo, nesta edição
Edição 2026.11.3Exemplos aprovados em 21 de nov de 20263 de 3 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.3.