Meça um assistente antes de alterá-lo
Cerca de 29 minutos min de leitura, com 11 exemplos em 11 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 medir um assistente de documentação com um conjunto fixo de perguntas, interpretar o resultado com o seu intervalo e dizer quando vinte perguntas são poucas para distinguir dois prompts.
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 sincronia com os modelos dos quais eles vêm. Os usuários perguntam como executar um comando ou o que faz uma configuração, e o assistente responde a partir da documentação da ferramenta, citando a seção que embasa cada afirmação. Suponha que alguém da equipe queira um prompt diferente. Ele o testa em três perguntas, as respostas parecem melhores e ele o coloca em produção. Três perguntas não mostram se a mudança ajudou. Ninguém tampouco consegue dizer como o assistente se comportava antes da mudança, porque nada foi registrado.
Por isso, a primeira coisa a construir é uma medição: um conjunto de perguntas com as respostas que elas deveriam receber, uma forma de executar o assistente sobre elas sempre do mesmo modo e um número que venha acompanhado de sua margem de incerteza. As alterações vêm depois. Este capítulo constrói a medição em sua forma mais simples e termina mostrando onde essa forma deixa de funcionar.
A ferramenta e a sua documentação
Uma avaliação só é tão estável quanto aquilo que ela mede. A documentação do sablefile vem em três versões, 1.0, 1.1 e 2.0, e elas divergem em alguns pontos. Uma resposta correta para uma versão pode estar errada para outra, por isso toda pergunta precisa nomear a sua versão antes de qualquer outro detalhe ser definido.
Comece pela documentação. Carregue as três versões, conte as seções de cada uma e conte os IDs de seção que as três têm em comum.
1"""Loads the three doc versions and prints each one's section count, and how many section IDs all three share.23The shared IDs are the sections whose concept keeps one ID across versions (plan section 2.2)."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.docs import load_sections, versions78sections = load_sections() # every version, sorted by version and section ID9all_versions = versions() # the version labels present, sorted10for version in all_versions:11 print(f"sections in version {version}: {sum(1 for s in sections if s.version == version)}")1213ids = {version: {s.section_id for s in sections if s.version == version} for version in all_versions}14shared = set.intersection(*ids.values()) # IDs present in every version15print(f"section IDs in all {len(all_versions)} versions: {len(shared)}")16print(f"section IDs in 2.0 but in neither 1.0 nor 1.1: {len(ids['2.0'] - ids['1.0'] - ids['1.1'])}")
python list-the-docs.pysections in version 1.0: 35
sections in version 1.1: 36
sections in version 2.0: 40
section IDs in all 3 versions: 35
section IDs in 2.0 but in neither 1.0 nor 1.1: 4
A saída começa com a contagem de seções: 35 na 1.0, 36 na 1.1 e 40 na 2.0.
A maioria das seções mantém os seus IDs entre as versões, já que 35 IDs aparecem nas três. A última linha é a mais importante para o que vem a seguir. 4 IDs existem somente na 2.0, de modo que um assistente que responda a partir das páginas mais antigas não tem o que citar para eles.
As versões também diferem no que a ferramenta faz, e a diferença que importa aqui está em sync, o comando que grava os arquivos gerados. A documentação da 1.1 diz que sync sem flags grava os arquivos e registra cada um deles em sablefile.lock, o arquivo de lock na raiz do projeto. A documentação da 2.0 diz que sync sem flag imprime um plano e não grava nada, que --apply grava os arquivos e que o arquivo de lock fica em .sablefile/lock.json. Uma pergunta sobre sync tem uma resposta correta para a 1.1 e outra para a 2.0. Um assistente que lê a página da versão errada soa seguro de si e está errado.
Este livro mede respostas. Ranqueamento de recuperação, rastreamento, custo, latência, ataques e conjuntos de tarefas de agentes pertencem a outros livros, citados onde surgirem.
Regra prática: Escreva a versão em cada pergunta e deixe que a documentação dessa própria versão seja a única fonte para a sua resposta. Quando duas versões usam a mesma redação e dão respostas diferentes, transforme-as em dois itens, um para cada versão. Nunca deixe a página da versão mais nova tomar o lugar de uma versão mais antiga.
Os vinte itens
Um conjunto de teste é uma lista de perguntas, cada uma com a resposta que deveria obter. Vinte itens é um número propositalmente pequeno. Você consegue ler cada um, conferir sua resposta esperada com a documentação e explicar por que ele está ali. Um conjunto que ninguém lê não consegue dizer o que está medindo.
Os itens se dividem em quatro tipos. Os itens respondíveis têm a resposta na própria página. Os itens não respondíveis perguntam sobre algo que a documentação não cobre, e a resposta correta é a recusa. Os itens dependentes da versão têm uma resposta que muda de uma versão para outra, e vários deles têm um gêmeo: a mesma pergunta feita sobre outra versão. Os itens ambíguos podem ter dois sentidos, e a resposta de referência cobre ambas as leituras.
Cada item é impresso em ordem de ID, com sua versão, seu tipo, seu gêmeo e se foi plantado.
1"""Prints the twenty chapter items in id order: version, kind, planted flag and question, then the counts by kind.23The counts are the set's make-up that the chapter describes (plan section 3.4)."""4import lib # first: fixes the thread counts and seeds before anything else loads56from collections import Counter78from lib.answers import chapter_items910items = chapter_items() # sorted by id11for item in items:12 twin = item.twin_of if item.twin_of else "none"13 planted = f"planted ({item.planted_why})" if item.planted else "not planted"14 print(f"{item.id} | version {item.version} | {item.kind} | {planted} | twin {twin} | {item.question}")1516kinds = Counter(item.kind for item in items)17for kind in ("answerable", "unanswerable", "version-dependent", "ambiguous"):18 print(f"items of kind {kind}: {kinds[kind]}")19print(f"planted items: {sum(1 for item in items if item.planted)}")20print(f"items in the dev split: {sum(1 for item in items if item.split == 'dev')}")
python twenty-questions.pyq-0001 | version 1.1 | version-dependent | not planted | twin q-0002 | In sablefile 1.1, if I run sync with no flags, are the target files written straight away?
q-0002 | version 2.0 | version-dependent | not planted | twin q-0001 | In sablefile 2.0, if I run sync with no flags, are the target files written?
q-0003 | version 1.0 | version-dependent | planted (version-swap) | twin q-0004 | In sablefile 1.0, is ${project} the right way to insert the project name into a template?
q-0004 | version 2.0 | version-dependent | not planted | twin q-0003 | In sablefile 2.0, is ${project} the right way to insert the project name into a template?
q-0005 | version 2.0 | answerable | planted (near-miss-term) | twin none | Does sablefile 2.0 still read sablefile.lock in my project root?
q-0006 | version 2.0 | answerable | not planted | twin none | Is there a way to make check exit with status 0 even when a file has drifted in 2.0?
q-0007 | version 1.1 | answerable | not planted | twin none | In 1.1, will an ignore entry of docs/**/*.tmp catch a file two folders down, like docs/x/y/a.tmp?
q-0008 | version 2.0 | answerable | not planted | twin none | In 2.0, is there a way to re-include something that an earlier ignore line had excluded?
q-0009 | version 1.0 | answerable | not planted | twin none | What does one line of the 1.0 lock file hold?
q-0010 | version 2.0 | answerable | not planted | twin none | Will syncing the same content twice in 2.0 produce a different lock file each time?
q-0011 | version 1.1 | answerable | not planted | twin none | How many times does 1.1 retry a remote template fetch that keeps failing, and can a flag change that?
q-0012 | version 2.0 | answerable | not planted | twin none | I want sync to retry a slow remote template only twice in 2.0. What do I pass?
q-0013 | version 1.0 | answerable | not planted | twin none | In 1.0, which table in sablefile.toml holds the values a placeholder can name?
q-0014 | version 1.1 | answerable | not planted | twin none | What does sablefile init put into a new sablefile.toml in 1.1?
q-0015 | version 1.0 | unanswerable | planted (false-premise) | twin none | In sablefile 1.0, what does the --dry-run flag on sync print?
q-0016 | version 2.0 | unanswerable | not planted | twin none | Does sablefile 2.0 run on Windows?
q-0017 | version 2.0 | unanswerable | not planted | twin none | How fast is sablefile check on a project with several thousand generated files?
q-0018 | version 1.1 | unanswerable | not planted | twin none | Can sablefile 1.1 fetch a remote template from a private URL that needs a login token?
q-0019 | version 2.0 | ambiguous | planted (ambiguous-target) | twin none | If I edit the file and then run check, will it fail?
q-0020 | version 2.0 | ambiguous | not planted | twin none | Does sync change the lock file?
items of kind answerable: 10
items of kind unanswerable: 4
items of kind version-dependent: 4
items of kind ambiguous: 2
planted items: 4
items in the dev split: 20
As últimas linhas mostram a composição do conjunto por tipo, e os itens respondíveis são o maior grupo. 4 itens são plantados. Um item plantado foi escrito para capturar um erro específico, e o conjunto o rotula, de modo que uma falha nesse item pode ser lida em relação à sua armadilha.
Cada armadilha é simples. q-0003 pergunta se ${project} é o marcador correto na versão 1.0, em que a sintaxe é {{project}}. Seu gêmeo, q-0004, faz a mesma pergunta sobre a versão 2.0, em que ${project} é o correto. q-0005 pergunta se a 2.0 ainda lê sablefile.lock na raiz do projeto, que usa o nome de arquivo da 1.x em uma versão em que esse nome importa apenas para a migração. q-0015 pergunta o que a opção --dry-run faz na 1.0, e a documentação da 1.0 não menciona opção alguma com esse nome. q-0019 pergunta se um arquivo falha em uma verificação depois que você o edita, sem dizer qual arquivo, e por isso admite duas leituras.
Regra prática: Escreva cada item com sua versão, seu tipo e sua resposta esperada antes de executar o assistente, e rotule qualquer item escrito para capturar um erro específico. Mantenha o conjunto pequeno o bastante para ser lido de uma só vez, e nunca altere uma resposta esperada para que ela combine com o que o assistente disse.
Recuperar, depois responder
O assistente não lê todos os documentos para cada pergunta. Para cada pergunta, ele pega as três seções com maior probabilidade de conter a resposta, a partir do índice da versão que a pergunta indica, e responde apenas com base nessas três. Uma resposta errada pode, portanto, vir de dois lugares: a seção certa nunca foi recuperada, ou o modelo interpretou mal a seção que recebeu. Uma medição que não consegue distinguir essas duas situações não consegue indicar o que deve ser corrigido.
O índice é construído com BM25, que pontua cada seção pelas palavras que ela compartilha com a pergunta. A pontuação é feita por meio do bm25s em 0.3.16. Considere uma pergunta: se uma entrada de ignore como docs/**/*.tmp captura um arquivo duas pastas abaixo na 1.1. Sua saída mostra as palavras que o índice mantém da pergunta e as três seções mais bem classificadas, ordenadas pela pontuação e depois pelo ID da seção.
1"""Shows BM25 retrieval for one question (q-0007, version 1.1): the words kept, then the top three sections.23The sections come from the version's own index, ranked by score and then by section ID, so a tie has one order.4The tokeniser drops one-letter words, so the `3` of `3.5mm` is lost and only `5mm` is matched."""5import lib # first: fixes the thread counts and seeds before anything else loads67import bm25s89from lib.docs import load_sections10from lib.retrieval import Retriever11from lib.testset import load_items1213item = next(item for item in load_items() if item.id == "q-0007")14print(f"question {item.id} (version {item.version}): {item.question}")1516# The words the index actually matches on: the same tokeniser, stopwords and token pattern as lib.retrieval.17kept = bm25s.tokenize([item.question], stopwords="en", return_ids=False, show_progress=False)[0]18print(f"words kept for matching: {' '.join(kept)}")19dropped = bm25s.tokenize(["a 3.5mm jack"], stopwords="en", return_ids=False, show_progress=False)[0]20print(f"words kept from the text 'a 3.5mm jack': {' '.join(dropped)}")2122hits = Retriever(load_sections(item.version)).retrieve(item.question, 3) # top 3 of the version's index23for rank, hit in enumerate(hits, start=1):24 print(f"rank {rank}: {hit.section_id} | score {hit.score:.3f}")
python retrieve-top-sections.pyquestion q-0007 (version 1.1): In 1.1, will an ignore entry of docs/**/*.tmp catch a file two folders down, like docs/x/y/a.tmp?
words kept for matching: ignore entry docs tmp catch file two folders down like docs tmp
words kept from the text 'a 3.5mm jack': 5mm jack
rank 1: ignore-recursive | score 9.156
rank 2: sync-create-dirs | score 3.386
rank 3: ignore-syntax | score 3.348
Leia as duas linhas de palavras mantidas antes do ranking. O tokenizador descarta todo token de um caractere. O a da pergunta sai, e também os dois 1 de 1.1, de modo que o número da versão nunca chega ao índice. Isso não causa problema aqui, porque cada pergunta é pesquisada apenas no índice de sua própria versão. A mesma regra retira o 3 de 3.5mm: o que sobra de a 3.5mm jack é 5mm jack, de modo que uma pergunta sobre um conector de 3.5 mm só pode coincidir em 5mm. Nenhuma dessas perdas gera erro, e a segunda muda o que o índice consegue encontrar.
O ranking coloca ignore-recursive em primeiro lugar, a seção sobre entradas de ignore recursivas, e as duas seguintes são a seção sobre criação de pastas e a de sintaxe de ignore. Empates são resolvidos pelo ID da seção, de modo que a mesma pergunta produz as mesmas três seções em todas as execuções.
Regra prática: Verifique a recuperação antes de verificar a resposta. Para cada item, registre as seções que o assistente recebeu ao lado de sua resposta. Uma resposta errada que não contém a seção certa é um problema de recuperação, e uma resposta errada que tinha a seção certa é um problema do prompt ou do modelo. Mantenha a redação das perguntas simples, porque um tokenizador que descarta tokens de um caractere perderá uma medição ou um número de versão.
Reproduzir as respostas
A resposta de um modelo à mesma pergunta pode mudar conforme o seu ambiente de execução, as suas configurações e o hardware em que roda. Se cada medição chamar o modelo de novo, cada uma mede algo ligeiramente diferente, e uma mudança no número pode ser apenas ruído. Por isso, o livro registra cada resposta uma única vez, a partir de um modelo aberto fixado, e reproduz o registro. Uma reprodução devolve sempre o mesmo texto.
O registro é uma pasta de respostas, uma por item. Ele foi feito com uma versão de 4 bits do Qwen3-4B-Instruct-2507, um modelo aberto fixado em um arquivo e em uma revisão específicos, executado com temperatura zero em uma CPU. Ele contém uma resposta para cada item do conjunto completo, e este capítulo lê vinte delas pelo ID. Reproduza uma delas: a resposta para q-0006, que pergunta se check pode terminar com status 0 quando um arquivo tiver sofrido desvio no 2.0.
1"""Replays the recorded baseline reply to q-0006 and parses it: the sections it was given, the reply, its citations.23Nothing is generated here: the reply is the recorded text, read back as the same string."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.answers import Assistant, chapter_items7from lib.contract import format_problems8from lib.prompts import P1_SHA256, P1_SYSTEM910assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256) # the prompt hash must match the manifest11item = next(item for item in chapter_items() if item.id == "q-0006")12print(f"question {item.id} (version {item.version}, {item.kind}): {item.question}")13for rank, section in enumerate(assistant.sections(item), start=1): # the top 3, in rank order14 print(f"section in context, rank {rank}: {section.section_id}")1516reply = assistant.reply(item)17print("recorded reply:")18print(reply.text)19print(f"citations, in order: {' '.join(reply.citations)}")20print(f"format problems: {', '.join(format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=False)) or 'none'}")21# A reply to an answerable item must answer and cite; this is the one fact the prose relies on here.22assert reply.citations and not reply.declined, "q-0006 should be answered, with at least one citation"
python replay-one-answer.pyquestion q-0006 (version 2.0, answerable): Is there a way to make check exit with status 0 even when a file has drifted in 2.0?
section in context, rank 1: check-exit-status
section in context, rank 2: no-fail-flag
section in context, rank 3: quickstart-check
recorded reply:
Yes, there is a way to make `check` exit with status 0 even when a file has drifted in 2.0. Use the `--no-fail` flag with `sablefile check`. This flag ensures that the check exits with status 0 even when files have drifted, without changing which files are reported. [sec:no-fail-flag]
citations, in order: no-fail-flag
format problems: none
A saída lista as três seções que foram dadas ao assistente, em ordem de classificação, e depois imprime a resposta exatamente como foi registrada. A resposta diz que sim, e cita no-fail-flag, que estava entre as três. Confira a citação com essa lista. A resposta cita uma seção que lhe foi fornecida, portanto não buscou nada fora do seu contexto. Uma asserção também exige que a resposta seja uma resposta com pelo menos uma citação, já que uma recusa neste item respondível seria um erro.
Para colocar um modelo ao vivo no lugar do registro, passe live=True para Assistant. Isso carrega o Qwen3-0.6B fixado na CPU e responde a cada pergunta no momento em que ela é feita. Trata-se de um modelo menor do que a versão de 4B com que o registro foi feito, então as suas respostas ao vivo, e qualquer taxa construída sobre elas, serão diferentes das registradas. Este livro não cita respostas ao vivo. Os seus números vêm do registro, de modo que você pode conferir cada um deles em um arquivo.
Regra prática: Reproduza para toda comparação. Registre de novo somente quando o modelo, o prompt ou as seções que o assistente vê tiverem mudado, e anote no registro o que mudou. Cada registro nomeia o seu prompt por hash, e o exemplo confere esse hash com o manifesto do registro, de modo que um único registro não pode substituir um prompt diferente.
Duas verificações em código
Alguns erros não precisam de juiz. Uma citação a uma seção que não estava no prompt, ou uma recusa que também dá uma resposta, podem ser encontradas lendo o texto da resposta. Verificações em código não custam nada para executar e dão o mesmo resultado sempre, por isso o livro executa as duas antes que qualquer modelo seja solicitado a julgar uma resposta.
Citações
O assistente deve citar cada afirmação na forma de citação, um ID de seção entre colchetes, e só pode citar os IDs que recebeu. Uma citação pode falhar de duas maneiras. O ID pode não existir de forma alguma, ou pode existir em outra versão, que é o erro que os itens de troca de versão foram escritos para provocar. A verificação marca como unknown-section qualquer citação a uma seção que não estava no prompt, seja qual for a forma como deu errado. Ela também sinaliza uma resposta que não tem nenhuma citação.
A verificação de citações e de formato é executada sobre as vinte respostas de referência, e a saída conta cada tipo de falha.
1"""Runs the citation and format checks on the baseline replies to the twenty chapter items, and counts each problem.23A citation is a problem when its section was not in the item's prompt, which covers a section of another version."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.answers import Assistant, chapter_items7from lib.contract import PROBLEMS, format_problems, parse_reply, section_ids_by_version8from lib.prompts import P1_SHA256, P1_SYSTEM9from lib.stats import pct1011assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)12items = chapter_items()13counts = {name: 0 for name in PROBLEMS} # items with each problem, by its fixed name14items_with_problems = 015answered = 016answered_uncited = 017citations = 018citations_outside = 0 # cited IDs that were not in the item's prompt19for item in items:20 reply = assistant.reply(item)21 problems = format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=item.kind == "unanswerable")22 items_with_problems += bool(problems)23 for name in problems:24 counts[name] += 125 if not reply.declined and reply.text:26 answered += 127 answered_uncited += not reply.citations28 citations += len(reply.citations)29 citations_outside += sum(1 for cid in reply.citations if cid not in assistant.context_ids(item))30assert citations_outside == 0, "every citation must point at a section that was in its item's prompt"31# A zero rate shows nothing unless the check can fire: a 1.1 section cited for a 2.0 item must be flagged as unknown.32planted_item = next(item for item in items if item.version == "2.0")33planted = sorted(section_ids_by_version()["1.1"] - assistant.context_ids(planted_item))[0]34planted_problems = format_problems(parse_reply(f"Yes. [sec:{planted}]"), context_ids=assistant.context_ids(planted_item), expect_decline=False)35assert "unknown-section" in planted_problems, "the check must fire on a planted bad citation"3637print(f"items: {len(items)}")38print(f"items with a format problem: {pct(items_with_problems, len(items))}")39for name in sorted(counts): # sorted by problem name40 print(f"items with problem {name}: {counts[name]}")41print(f"answered items: {answered}")42print(f"answered items with no citation: {pct(answered_uncited, answered)}")43print(f"citations: {citations}")44print(f"citations to a section not in the prompt: {pct(citations_outside, citations)}")
python check-citations.pyitems: 20
items with a format problem: 0.0% (0 of 20)
items with problem answered-declined-expected: 0
items with problem declined-with-text: 0
items with problem empty: 0
items with problem no-citation: 0
items with problem unknown-section: 0
answered items: 15
answered items with no citation: 0.0% (0 of 15)
citations: 16
citations to a section not in the prompt: 0.0% (0 of 16)
A referência deu 16 citações no total, e cada uma aponta para uma seção que recebeu. A saída apresenta taxas sobre isso: as citações a uma seção fora do prompt chegam a 0.0% (0 of 16), e os itens respondidos sem nenhuma citação chegam a 0.0% (0 of 15).
Regra prática: Execute a verificação de citações em cada resposta e informe suas taxas separadamente da taxa de respostas, já que as duas contam erros diferentes. Uma taxa de zero só é um resultado se a verificação pudesse ter encontrado um problema, por isso mantenha uma resposta de teste que cite fora do seu prompt, e execute a verificação sobre ela, para mostrar que a verificação continua disparando.
Recusas
Quando a documentação não responde a uma pergunta, o assistente deve responder com a frase de recusa, "The docs don't say.", e nada mais. Quando a documentação responde, ele não deve usar essa frase. Trata-se de dois erros diferentes, por isso cada um tem sua própria taxa. Uma recusa falsa é um item respondível recusado, e uma resposta falsa é um item não respondível respondido. Itens dependentes de versão e itens ambíguos ficam de fora das duas taxas. Um item dependente de versão tem uma taxa própria, a correção de versão, que o capítulo 9 constrói. Um item ambíguo é avaliado apenas pela taxa de aprovação, pois o texto de uma resposta, por si só, não mostra qual versão ou qual leitura era pretendida.
Ambos os erros de recusa são contados sobre as respostas da linha de base.
1"""Counts the two decline errors over the baseline replies: answerable items declined, and unanswerable items answered.23Version-dependent and ambiguous items are left out of both rates: a version-dependent item is scored by its own rate,4version-correctness, and an ambiguous item has no rate yet. The last lines name any excluded item the baseline declined."""5import lib # first: fixes the thread counts and seeds before anything else loads67from lib.answers import Assistant, chapter_items8from lib.prompts import P1_SHA256, P1_SYSTEM9from lib.stats import pct1011assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)12items = chapter_items()13answerable = [item for item in items if item.kind == "answerable"]14unanswerable = [item for item in items if item.kind == "unanswerable"]1516false_refusals = [item.id for item in answerable if assistant.reply(item).declined] # already in id order17false_answers = [item.id for item in unanswerable if not assistant.reply(item).declined]18print(f"answerable items: {len(answerable)}")19print(f"false refusal rate (answerable items declined): {pct(len(false_refusals), len(answerable))}")20for item_id in false_refusals:21 print(f"false refusal: {item_id}")22print(f"unanswerable items: {len(unanswerable)}")23print(f"false answer rate (unanswerable items answered): {pct(len(false_answers), len(unanswerable))}")24for item_id in false_answers:25 print(f"false answer: {item_id}")26print(f"items not counted here (version-dependent and ambiguous): {len(items) - len(answerable) - len(unanswerable)}")27excluded = [item for item in items if item.kind in ("version-dependent", "ambiguous")]28declined_excluded = [item.id for item in excluded if assistant.reply(item).declined] # the decline is not counted29print(f"declined, not counted here: {', '.join(declined_excluded) or 'none'}")
python check-declines.pyanswerable items: 10
false refusal rate (answerable items declined): 0.0% (0 of 10)
unanswerable items: 4
false answer rate (unanswerable items answered): 0.0% (0 of 4)
items not counted here (version-dependent and ambiguous): 6
declined, not counted here: q-0004
Entre os itens respondíveis e não respondíveis, a linha de base não comete nenhum dos dois erros. A taxa de recusa falsa é 0.0% (0 of 10) dos 10 itens respondíveis. A taxa de resposta falsa é 0.0% (0 of 4) dos 4 itens não respondíveis, de modo que todo item não respondível recebeu a recusa, inclusive q-0015.
As taxas deixam de fora 6 itens, e a última linha identifica o único deles que a linha de base recusou: q-0004. O item q-0004 pergunta se ${project} é o placeholder correto na 2.0, e de fato é. A linha de base respondeu com a frase de recusa, mas a documentação da 2.0 responde à pergunta, na seção placeholders, de modo que a recusa é uma resposta incorreta. A taxa acima não a conta como recusa falsa, porque essa taxa cobre apenas itens respondíveis. A correção de versão a conta como falha.
Regra prática: Mantenha as duas taxas de recusa separadas e deixe os itens dependentes de versão e os ambíguos fora de ambas. Uma resposta só conta como recusa correta quando for a frase de recusa e nada mais, de modo que uma resposta que dê a frase e depois uma resolução conta como o erro que é. Leia cada recusa falsa à mão antes de alterar o prompt, pois uma delas pode apontar para uma lacuna real na documentação. Leia também cada recusa a um item dependente de versão, já que a taxa não conta esses itens.
Um juiz
Citações e recusas verificam a forma de uma resposta. Elas não conseguem verificar se a resposta está certa, e essa é a pergunta com que a equipe se preocupa. Para isso, o livro usa um juiz: um modelo que lê a pergunta, uma resposta de referência escrita e a resposta do assistente, e devolve PASS ou FAIL. O juiz aqui é o Qwen3-4B-Instruct-2507, o mesmo modelo que escreveu as respostas. Um juiz e um assistente que são o mesmo modelo podem compartilhar pontos cegos, e então o juiz deixa passar os erros que o assistente comete pelo mesmo motivo. Este livro não consegue testar isso com essa configuração. O que ele faz em vez disso é verificar o mesmo modelo, sob uma rubrica de calibração, contra avaliações humanas públicas, e dizer o que se pressupõe ao transferir essas taxas para este juiz, no capítulo 6.
As regras do juiz são curtas, e vale lê-las por inteiro. Uma resposta só está correta se disser o que a referência diz. Outras palavras são aceitáveis, e também detalhes extras que não contradigam a referência. Uma resposta que afirme algo que a referência não sustenta, ou que a contradiga, falha. Se a referência admite mais de uma leitura, a resposta precisa responder a todas, e uma resposta parcial falha. Se a referência for "none", a documentação não responde, e a única resposta correta é a recusa. Uma resposta que dá uma resposta e também a frase de recusa falha. O juiz escreve seu veredito na primeira linha e, depois, um breve motivo. O prompt pede uma frase, e o juiz nem sempre para aí.
Aqui está o veredito do juiz sobre q-0005, o quase acerto. A resposta do assistente diz que 2.0 não lê sablefile.lock, e aponta vagamente para a migração.
1"""Reads the reference-guided judge's verdict on the baseline reply to q-0005, a planted near-miss item, from its recording.23The judge sees the question, the written reference and the reply; the first line of its reply is the verdict."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.answers import Assistant, chapter_items7from lib.contract import parse_verdict8from lib.prompts import P1_SHA256, P1_SYSTEM, REF_SHA2569from lib.replay import ReplayModel1011assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)12item = next(item for item in chapter_items() if item.id == "q-0005")13print(f"question {item.id} (version {item.version}, {item.kind}, planted: {item.planted_why}): {item.question}")14print(f"reference answer: {item.reference_answer}")15reply = assistant.reply(item)16print(f"assistant reply: {reply.text}")1718judge = ReplayModel("judge-answers-baseline", REF_SHA256) # the prompt hash must match the judge's manifest19raw = judge.reply(item.id, 0)20verdict = parse_verdict(raw)21assert verdict is not None, "the judge's first line must be a verdict"22print(f"judge verdict: {verdict}")23reason = [line.strip() for line in raw.splitlines() if line.strip()][1:] # the line after the verdict24print(f"judge reason: {reason[0] if reason else 'none'}")
python judge-one-answer.pyquestion q-0005 (version 2.0, answerable, planted: near-miss-term): Does sablefile 2.0 still read sablefile.lock in my project root?
reference answer: Only as a fallback. If the new file is missing and an old sablefile.lock is present, a 2.0 command reads the old file but warns you about it. Once the new file exists, 2.0 reads only that one, and sablefile never deletes the old file.
assistant reply: No, sablefile 2.0 does not read `sablefile.lock` in the project root. Version 2.0 moves the lock file to a new place. The first 2.0 command that reads an older lock file handles it as described in lock-migration. [sec:install-upgrade]
judge verdict: FAIL
judge reason: The response incorrectly states that sablefile 2.0 "does not read `sablefile.lock`" and that it "moves the lock file to a new place," which contradicts the reference answer that says sablefile 2.0 reads the old lock file as a fallback and only reads the new file once it exists. The reference explicitly states that it reads the old file as a fallback and warns users, not that it moves or stops reading it.
A resposta de referência diz outra coisa: a 2.0 lê o arquivo antigo apenas como alternativa, quando não existe arquivo novo, e avisa você quando faz isso. O veredito do juiz é FAIL, e o motivo diz que a resposta contradiz a referência. A seção de migração para a 2.0 da documentação diz o que a referência diz, então neste item o juiz está certo. Um veredito correto, porém, não mostra que o juiz é confiável.
Por isso o juiz precisa ser verificado contra pessoas. Um juiz que concorda com os seus próprios rótulos não está, por isso, calibrado. O estudo de Shankar e colegas, Who Validates the Validators? (2024), é uma pesquisa com nove participantes, e descobriu que as pessoas refinam seus critérios de avaliação enquanto avaliam as saídas, de modo que os critérios em que se fixam mudam conforme leem mais saídas. Uma rubrica escrita uma única vez pode se afastar daquilo que seus avaliadores passam a entender. O capítulo 5 explica como colocá-la por escrito, e isso vale a pena por um motivo próprio: uma rubrica escrita é aquilo com que um segundo leitor pode conferir um veredito, e aquilo com que vereditos posteriores podem ser comparados. A verificação contra avaliações humanas está no capítulo 6.
Regra prática: Dê ao juiz uma referência escrita para cada item, e leia seus vereditos FAIL com a mesma atenção que seus vereditos PASS antes de confiar em uma taxa construída sobre eles. Não considere a concordância com seus próprios rótulos como calibração. Até que um juiz tenha sido verificado contra avaliações humanas, informe a taxa dele como a taxa do juiz, não como uma medida da qualidade do assistente.
Uma taxa de aprovação e seu intervalo
Uma taxa de aprovação é uma contagem dividida por um denominador, e o denominador decide o que a taxa significa. A mesma taxa em um conjunto muito maior é uma afirmação diferente, e um conjunto de vinte itens oscila bastante quando um único item muda. Aqui o denominador é todo item do conjunto, e uma recusa correta conta como aprovação.
pass rate = passed items / items
Um intervalo responde a uma pergunta diferente da taxa de aprovação: quanto a taxa se moveria se o conjunto tivesse sido outros vinte itens sorteados da mesma forma? O método é um bootstrap percentílico. O bootstrap em si é de Efron: seu artigo de 1979 Bootstrap Methods: Another Look at the Jackknife, publicado nos Annals of Statistics, apresentou a reamostragem como uma maneira de estimar o quanto uma estatística varia. O bootstrap percentílico é o intervalo mais simples construído sobre reamostragem, os 95% centrais das taxas reamostradas. O procedimento sorteia itens do conjunto com reposição, sem considerar o tipo, de modo que um sorteio pode conter qualquer mistura de tipos. Ele calcula a taxa de aprovação de cada sorteio e repete os sorteios muitas vezes. O intervalo mostra o quanto vinte itens poderiam dizer.
Calcule a taxa e seu intervalo para a linha de base e, em seguida, separe a taxa por tipo.
1"""The baseline's pass rate over the twenty chapter items, judged by the reference-guided judge, with its 95% interval.23Every item is in the denominator, and a correct decline counts as a pass. The interval resamples items."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.answers import chapter_items7from lib.judging import passed, verdicts8from lib.stats import bootstrap_mean, interval_pct, pct910items = chapter_items()11found = verdicts("judge-answers-baseline", [item.id for item in items]) # keyed in sorted id order12scores = passed(found) # 1.0 for PASS, 0.0 for FAIL, in the same order13print(f"items: {len(items)}")14print(f"pass rate: {pct(int(scores.sum()), len(items))}")15lo, hi = bootstrap_mean(scores) # level 0.95 for one comparison; seed SEED, 2,000 resamples16print(f"95% interval of the pass rate: {interval_pct(lo, hi)}")1718kind_of = {item.id: item.kind for item in items}19for kind in ("answerable", "unanswerable", "version-dependent", "ambiguous"):20 ids = [item_id for item_id in found if kind_of[item_id] == kind]21 passes = sum(1 for item_id in ids if found[item_id] == "PASS")22 print(f"pass rate, {kind}: {pct(passes, len(ids))}")
python pass-rate-interval.pyitems: 20
pass rate: 85.0% (17 of 20)
95% interval of the pass rate: [70.0%, 100.0%]
pass rate, answerable: 90.0% (9 of 10)
pass rate, unanswerable: 100.0% (4 of 4)
pass rate, version-dependent: 75.0% (3 of 4)
pass rate, ambiguous: 50.0% (1 of 2)
A taxa de aprovação da linha de base é 85.0% (17 of 20). Seu intervalo de 95% é [70.0%, 100.0%]. O intervalo fica a mesma distância para cima e para baixo da taxa. Seu limite superior fica no teto para qualquer taxa. Ele atinge o teto porque mais de 2.5% dos sorteios não contêm nenhum item com falha, de modo que o topo dos 95% centrais é esse teto. Isso significa que o intervalo não consegue descartar um assistente que nunca falha, o que é justamente o que o número único esconde.
Os itens respondíveis são aprovados em 90.0% (9 of 10), os itens não respondíveis em 100.0% (4 of 4), os itens dependentes de versão em 75.0% (3 of 4), e os itens ambíguos em 50.0% (1 of 2). As três falhas caem em três tipos diferentes. A única falha em item respondível é q-0005, lida acima. A única falha em item dependente de versão é a recusa em q-0004, lida acima. A única falha em item ambíguo é q-0019, que o juiz reprova diante da resposta da linha de base, como mostra o exemplo da próxima seção.
Somente o tipo respondível tem mais do que alguns itens: 10 deles. Cada um dos outros tipos reúne 4 itens ou menos, então suas linhas são observações sobre poucos itens, não resultados.
O intervalo cobre apenas a dispersão que vem de sortear itens. Ele não diz nada sobre se os vinte itens representam as perguntas que usuários reais fazem, e nenhum intervalo consegue dizer isso. O Capítulo 3 trata do que um conjunto precisa conter antes que uma pontuação nele signifique algo, e por que este foi escrito a partir da documentação em vez de amostrado de usuários.
Regra prática: Informe toda taxa de aprovação com seu denominador, seu intervalo e sua taxa para cada tipo de item. Trate um tipo com apenas alguns itens como uma observação, não como um resultado, e diga em quantos itens ele se apoia.
Dois prompts
O prompt proposto pela equipe é a mudança a ser medida. P1 é o prompt de referência. P2 mantém as mesmas regras básicas e muda a forma da resposta: pede ao modelo que primeiro cite a frase em que sua resposta se apoia, e só depois dê a resposta, com a citação em cada linha. A pergunta é se a citação ajuda. Duas taxas de aprovação sobre itens diferentes medem sobretudo os itens, por isso a comparação precisa passar os mesmos itens pelos dois prompts. Cada item recebe então dois veredictos, e a diferença é calculada item a item. Isso é uma comparação pareada.
Os dois prompts são executados sobre os mesmos vinte itens, e a saída informa a diferença com seu intervalo.
1"""Compares the baseline prompt (P1) with prompt-b (P2) on the twenty chapter items: each pass rate, the paired difference, its interval and n.23The word 'better' is used only when the whole interval is above zero, and 'worse' only when it is below zero. A difference4whose interval includes zero is reported as no difference detected."""5import lib # first: fixes the thread counts and seeds before anything else loads67from lib.answers import chapter_items8from lib.judging import paired9from lib.stats import interval_points, pct1011result = paired("judge-answers-baseline", "judge-answers-prompt-b", [item.id for item in chapter_items()])12first, second = result.first, result.second # 1.0 or 0.0 per item, in id order13print(f"P1 (baseline) pass rate: {pct(int(first.sum()), result.n)}")14print(f"P2 (prompt-b) pass rate: {pct(int(second.sum()), result.n)}")15print(f"items that P2 passes and P1 fails: {int(((second == 1) & (first == 0)).sum())}")16print(f"items that P1 passes and P2 fails: {int(((second == 0) & (first == 1)).sum())}")17print(f"paired items (n): {result.n}")18print(f"difference, P2 minus P1: {100 * result.difference:+.1f} points")19print(f"95% interval of the difference: {interval_points(result.diff_lo, result.diff_hi)}")20if result.diff_lo > 0:21 reading = f"P2 is better at n = {result.n}"22elif result.diff_hi < 0:23 reading = f"P2 is worse at n = {result.n}"24else:25 reading = f"no difference detected at n = {result.n}"26print(f"reading: {reading}")27# The two prompts tie: the same number of items pass under each, so the pass rates and the reading say the same thing.28assert int(first.sum()) == int(second.sum()), "the two prompts must tie: the same pass count under each"
python compare-two-prompts.pyP1 (baseline) pass rate: 85.0% (17 of 20)
P2 (prompt-b) pass rate: 85.0% (17 of 20)
items that P2 passes and P1 fails: 1
items that P1 passes and P2 fails: 1
paired items (n): 20
difference, P2 minus P1: +0.0 points
95% interval of the difference: [-15.0, +15.0] points
reading: no difference detected at n = 20
Nesse conjunto os dois prompts empatam. P1 aprova 85.0% (17 of 20) dos itens, e P2 aprova 85.0% (17 of 20).
A visão pareada mostra o que está por baixo do empate. P2 aprova 1 item que P1 reprova, e P1 aprova 1 item que P2 reprova. Esses são os veredictos do juiz, não fatos sobre os prompts. O primeiro é q-0019, e a aprovação do juiz nele quebra a regra 3 do próprio juiz. A diferença, P2 menos P1, é +0.0 points, e seu intervalo é [-15.0, +15.0] points. O intervalo inclui zero, portanto, neste tamanho, o exemplo informa nenhuma diferença detectada.
Aqui os veredictos do juiz sobre q-0019 são lidos sob os dois prompts, e a regra que a aprovação quebra é impressa ao lado deles.
1"""Shows one judge verdict that breaks the judge's own rule: on q-0019, the judge passes P2's reply, which answers only one of the2two readings in the reference. The rule it breaks is rule 3 of the judge's prompt, printed below from that prompt.34The hand verdict is a person's reading, written into this file. It is printed beside the judge's verdict and is the only5number here that is not a recorded one; the count of passes with it is taken from the judge's own verdicts."""6import lib # first: fixes the thread counts and seeds before anything else loads78from lib.answers import Assistant, chapter_items9from lib.judging import verdicts10from lib.prompts import P1_SHA256, P1_SYSTEM, P2_SHA256, P2_SYSTEM, REF_SYSTEM11from lib.replay import ReplayModel1213ITEM_ID = "q-0019"14HAND = {"q-0019": "FAIL"} # read by hand against rule 3: the reply answers reading 1 and not reading 21516item = next(item for item in chapter_items() if item.id == ITEM_ID)17print(f"question {item.id} (version {item.version}, {item.kind}, planted: {item.planted_why}): {item.question}")18print(f"reference answer: {item.reference_answer}")19print(f"P2 reply: {Assistant('assistant-prompt-b', P2_SYSTEM, P2_SHA256).reply(item).text}")2021raw = ReplayModel("judge-answers-prompt-b", None).reply(item.id, 0) # the judge's recorded reply to P2's answer22print(f"judge verdict on P2's reply: {verdicts('judge-answers-prompt-b', [item.id])[item.id]}")23reason = [line.strip() for line in raw.splitlines() if line.strip()][1:] # the line after the verdict24print(f"judge reason: {reason[0] if reason else 'none'}")25print(f"judge verdict on P1's reply to the same item: {verdicts('judge-answers-baseline', [item.id])[item.id]}")26print(f"hand verdict on P2's reply, under rule 3: {HAND[item.id]}")27rule_3 = next(line for line in REF_SYSTEM.splitlines() if line.startswith("3. "))28print(f"rule it breaks: {rule_3}")2930ids = [item.id for item in chapter_items()]31judged = verdicts("judge-answers-prompt-b", ids)32passes = sum(verdict == "PASS" for verdict in judged.values())33by_hand = passes - sum(1 for item_id in HAND if judged[item_id] == "PASS" and HAND[item_id] == "FAIL")34print(f"P2 passes, as judged: {passes} of {len(ids)}")35print(f"P2 passes, with {ITEM_ID} read by hand: {by_hand} of {len(ids)}")
python judge-gets-one-wrong.pyquestion q-0019 (version 2.0, ambiguous, planted: ambiguous-target): If I edit the file and then run check, will it fail?
reference answer: Reading 1: if you edited a generated file (a target), check prints DRIFT and the path for it and exits with status 1, because its hash no longer matches the lock.
Reading 2: if you edited a template, check prints nothing and exits with status 0, since a template change is not drift.
P2 reply: Quote: "Run `sablefile check` after a sync. If no output appears, no generated file has drifted since the last sync. To see what drift looks like, open a generated file, change one line, and run the check again. The check prints `DRIFT` and the path of the file." [sec:quickstart-check]
Answer: Yes, if you edit the file and then run check, it will print `DRIFT` and the path of the file, indicating a drift [sec:quickstart-check].
judge verdict on P2's reply: PASS
judge reason: The response correctly identifies that editing a generated file and running check will result in a DRIFT message and path output, aligning with Reading 1 of the reference. It does not contradict or omit any part of the reference.
judge verdict on P1's reply to the same item: FAIL
hand verdict on P2's reply, under rule 3: FAIL
rule it breaks: 3. If the reference has several readings, the response must answer every reading. A partial answer is incorrect.
P2 passes, as judged: 17 of 20
P2 passes, with q-0019 read by hand: 16 of 20
Leia esta saída como um registro dos veredictos do juiz. A referência para q-0019 admite duas leituras, e a resposta de P2 responde apenas à primeira. A regra 3 do prompt do juiz diz que uma resposta parcial é reprovada, e o juiz reprova a resposta de P1 para o mesmo item, que também responde apenas à primeira leitura. Na resposta de P2 ele aprova, e sua justificativa diz que a resposta cobre a referência e não omite nada. Lido à mão, P2 aprova 16 of 20 itens, não 17 of 20. O empate está a um erro do juiz de deixar de ser um empate. Por isso as taxas aqui são as taxas do juiz, e por isso o capítulo 6 verifica o juiz contra avaliações humanas públicas.
Regra prática: Compare prompts sobre os mesmos itens, de forma pareada, e informe a diferença com seu intervalo. Considere um prompt melhor somente quando o intervalo inteiro estiver acima de zero, e pior somente quando estiver inteiramente abaixo de zero. Quando o intervalo incluir zero, diga que nenhuma diferença foi detectada neste tamanho, o que não é o mesmo que afirmar que os prompts são iguais.
O que vinte perguntas não conseguem mostrar
Este último exemplo usa os mesmos dois prompts e pergunta o que os vinte itens podem mostrar sobre eles. Vinte itens acabam dizendo muito pouco sobre esses dois prompts.
1"""Shows that twenty items cannot tell the two prompts apart: the interval of the paired difference includes zero.23The assert is the chapter's claim, checked against the numbers; the example prints no verdict word."""4import lib # first: fixes the thread counts and seeds before anything else loads56from lib.answers import chapter_items7from lib.judging import paired8from lib.stats import interval_points910result = paired("judge-answers-baseline", "judge-answers-prompt-b", [item.id for item in chapter_items()])11print(f"paired items (n): {result.n}")12differing = int((result.first != result.second).sum())13print(f"items where the two verdicts differ: {differing}")14print(f"difference, P2 minus P1: {100 * result.difference:+.1f} points")15print(f"95% interval of the difference: {interval_points(result.diff_lo, result.diff_hi)}")16print(f"interval width: {100 * (result.diff_hi - result.diff_lo):.1f} points")17# Zero inside the interval is the claim: no difference that twenty items can show.18assert result.diff_lo <= 0.0 <= result.diff_hi, "the interval of the difference must include zero"19# Two items carry the whole comparison: the pass rates differ only where these two verdicts differ.20assert differing == 2, "exactly two items must have differing verdicts"
python twenty-cannot-tell.pypaired items (n): 20
items where the two verdicts differ: 2
difference, P2 minus P1: +0.0 points
95% interval of the difference: [-15.0, +15.0] points
interval width: 30.0 points
Apenas 2 itens recebem vereditos diferentes dos dois prompts, então a diferença só pode variar em passos grosseiros, um item de cada vez. O intervalo da diferença tem largura de 30.0 points. Uma asserção no código exige que o intervalo inclua o zero, de modo que a afirmação falha de maneira explícita se os números deixarem de sustentá-la. Um intervalo tão largo só consegue detectar uma mudança grande, e uma mudança menor, mas que ainda importa para os usuários, pode se esconder dentro dele.
Em produção, o mesmo erro aparece de três formas: confiar em um número que não consegue sustentar a afirmação feita sobre ele. Uma equipe escolhe o prompt com o número mais alto nos vinte itens que escreveu primeiro, e o relatório deixa de fora o intervalo, de modo que ninguém vê o quão pouco o número sustenta. Um juiz passa a ser confiável porque seus vereditos parecem sensatos, e ninguém confere os motivos de FAIL dele contra a referência. Um conjunto de respostas gravadas, mantido depois que as seções que o assistente vê foram alteradas, mede o sistema antigo enquanto seus números continuam parecendo bons. Você percebe o primeiro quando um relatório traz um intervalo ao lado de cada taxa. Você percebe o segundo quando alguém confere os motivos de FAIL do juiz contra as referências a cada execução. O terceiro só aparece se a gravação também calcular o hash dos documentos que recebeu. Os manifestos deste livro calculam o hash do prompt e do conjunto de testes, de modo que uma mudança de prompt é recusada na reprodução, mas uma mudança nas seções passa despercebida.
Dois capítulos posteriores dão os próximos passos. Capítulo 3 constrói o conjunto maior que este capítulo não tem, e Capítulo 8 calcula quantos itens uma diferença precisa para poder aparecer.
O capítulo tomou estas decisões:
- Cada pergunta indica sua versão, e sua resposta vem somente dos documentos dessa versão.
- O conjunto deste capítulo tem vinte itens, lidos por inteiro, com os itens plantados identificados.
- Cada gravação é feita uma vez por modelo, prompt e documentos, e reproduzida em cada comparação.
- As citações e as recusas são verificadas no código antes que qualquer juiz leia uma resposta.
- O juiz avalia contra uma referência escrita, e sua taxa vale como taxa do juiz até que a calibração a verifique.
- Uma taxa de aprovação vem acompanhada de seu denominador, de seu intervalo e de sua taxa para cada tipo de item.
- Os prompts são comparados nos mesmos itens, e só um intervalo inteiramente de um lado do zero torna um deles melhor ou pior.
Regra prática: Informe o intervalo ao lado de cada comparação. Vinte itens conseguem encontrar respostas quebradas; não conseguem ordenar dois prompts.
Este capítulo, nesta edição
Edição 2026.11.3Exemplos aprovados em 21 de nov de 202611 de 11 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.3.