Ajuste fino de uma cabeça de classificação com LoRA
Cerca de 21 minutos min de leitura, com 5 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.9. Leia o original
Ao final deste capítulo, você será capaz de treinar uma cabeça de classificação com as mensagens rotuladas usando LoRA, contar os parâmetros que o treinamento altera, escolher um limiar de encaminhamento no conjunto de desenvolvimento por meio de uma regra declarada e registrar esse limiar junto aos resultados que ele produziu.
Até aqui, o roteador executa o substituto, que escreve sua resposta como texto no lugar de um modelo hospedado, com um limiar provisório, 0.5, que ninguém escolheu e que toda saída rotula como tal. A resposta precisa ser uma equipe, e o limiar precisa ser escolhido. Por isso, este capítulo substitui essa resposta por uma cabeça que devolve uma equipe e uma confiança em uma única passagem direta, e escolhe o limiar no conjunto de desenvolvimento antes que qualquer resultado de teste seja relatado. O treinamento precisa de mensagens rotuladas para as equipes do roteador, e elas vêm do BANKING77, um conjunto de dados público. O capítulo 3 escolheu o SmolLM2-135M-Instruct como modelo base, e este capítulo ajusta esse modelo e nenhum outro: o de 360M continua sendo uma comparação, como o capítulo 3 afirmou. O roteador é medido nas amostras que o capítulo 2 fixou.
Este capítulo não compara o adaptador com o de 360M e não destila nem quantiza nada. Os capítulos 6, 7 e 9 destilam, quantizam e versionam o adaptador.
Esta parte ainda não foi traduzida, por isso está em inglês.
A head that scores the teams
The stand-in writes its answer as text, and a grammar limits that text to the 77 team names while it decodes (chapter 4). A classification head works differently from the stand-in: it keeps the language model's layers and adds one output layer with 77 outputs, one for each team. For each message, the model produces 77 scores. Softmax turns the scores into 77 probabilities that sum to one. The router returns the team with the highest probability, and the confidence is that probability.
The answer is an index into the 77 teams, so it is always one of them. Chapter 4 reaches the same guarantee for a prompted model by constraining its text. This head never writes text, so it has nothing to constrain.
A message costs one forward pass: one run of the network from input to scores, with no loop that writes tokens one at a time. The team and the confidence come from that same pass. This matters for the hand-off. The flag that sends a message to a person is computed from the same probabilities as the team it protects, so the two cannot drift apart between two calls. A separate scoring call would need its own check that the two agree.
The confidence here has a narrower meaning than the stand-in's. In chapter 1, a confidence was the probability the stand-in's recorded answer had, which is not a softmax over teams. In this chapter, the confidence is the softmax probability of the chosen team. The two numbers are both called confidence, and both are compared with a threshold, but they are not the same quantity, so a threshold chosen for one is not a threshold for the other.
When two teams tie, router_lib's classify function takes the lower label index. That follows from torch's argmax, whose documentation says: "If there are multiple maximal values then the indices of the first maximal value are returned." (torch 2.15.0+cpu documentation). A fixed rule for ties keeps the output reproducible.
Working rule: Read the team and the confidence from one forward pass, and take the team as the output with the highest probability. Keep both in one function, so that a hand-off decision and the team it protects come from the same answer. Do not set a head's confidence beside a stand-in's as though they measured the same thing.
Os adaptadores treinam uma pequena parte do modelo
O ajuste fino completo altera cada peso do modelo base. O LoRA segue outro caminho. O artigo que apresentou o LoRA, Hu et al. (2021), afirma que ele congela os pesos pré-treinados e injeta matrizes de baixo rank treináveis nas camadas do Transformer, e as matrizes LoRA treinadas são o adaptador. O modelo base permanece como estava, e o adaptador é a parte que este livro armazena, carrega e versiona.
O rank, r, é o tamanho interno de cada matriz acrescentada, e ele é mantido pequeno. O peft escala a atualização acrescentada por lora_alpha dividido por r (peft 0.21.3, src/peft/tuners/lora/layer.py, linha 281: self.scaling[adapter_name] = lora_alpha / r), então lora_alpha define com que força a atualização conta. Este livro usa um rank de 8, com lora_alpha definido como 16. As matrizes acrescentadas vão nas camadas de projeção chamadas q_proj e v_proj em cada bloco de atenção. O resumo não nomeia essas camadas, então essa escolha é do livro, e não algo que o artigo prescreve. Recomendamos isso como ponto de partida, e o adaptador registrado abaixo é o teste dessa recomendação nesta tarefa. Outros alvos são uma escolha a ser medida, não um fato sobre o método.
O head também é treinado. O peft faz isso para a configuração deste livro: um modelo construído como classificador de sequências lista suas camadas classifier e score em modules_to_save (peft 0.21.3, src/peft/peft_model.py, linha 1830: classifier_module_names = ["classifier", "score"]), então o treinamento move a camada de 77 saídas e o adaptador juntos. Se você contar apenas as matrizes do adaptador, obterá um número menor do que o que o código treina, e a diferença é o head. A execução da próxima seção conta a divisão a partir do modelo carregado: 460800 no adaptador e 44352 no head, que juntos somam 505152.
O manifesto do adaptador registra a revisão do modelo base, então você pode conferir essa revisão em models.toml antes de pontuar.
Regra prática: Defina o rank, a escala e as camadas-alvo em uma única configuração, e conte os parâmetros treináveis a partir do modelo carregado antes de o treinamento começar. Exiba o total com o head incluído. Uma contagem que deixa o head de fora relata apenas parte do que o treinamento altera, e não corresponderá ao que o otimizador atualiza.
Trinta passos não bastam
Antes que o livro use uma gravação, ele mostra o que uma execução curta faz com a mesma receita. A execução abaixo usa 30 passos, com tamanho de lote 8 e semente 0, nas linhas de treinamento fora do conjunto dev, e depois pontua test_200, as primeiras 200 entradas da amostra fixa que o capítulo 2 sorteou. Trata-se de uma falha, e o livro a apresenta como tal. A execução curta verifica que o pipeline funciona de ponta a ponta, e essa é sua única função aqui.
1"""Train for 30 steps on the recorded recipe, then score test_200 at the placeholder threshold of 0.5.2Read the three step losses against the uniform-guess loss, then the hand-off line at that threshold. The recording runs 1,125 steps."""34import math56import torch78torch.set_num_threads(2)910import router_lib # noqa: E4021112router_lib.setup_runtime()13REPO = "HuggingFaceTB/SmolLM2-135M-Instruct"14STEPS, BATCH, SEED = 30, 8, 01516train, order = router_lib.training_rows(SEED) # the seed sets the shuffled order of the training rows, the one the recording used17tok, model = router_lib.new_classifier(REPO) # SmolLM2 with a 77-way head, LoRA rank 8, lora_alpha 16, on q_proj and v_proj18lora, head = router_lib.parameter_split(model) # LoRA tensors have "lora_" in their names; every other trainable tensor is the head19print(f"trainable parameters: {lora + head}")20print(f"LoRA parameters: {lora}")21print(f"head parameters: {head}")2223losses = router_lib.train_steps(model, tok, train, order, STEPS, BATCH) # AdamW at learning rate 1e-3, router_lib's default24print(f"training steps: {STEPS}")25print(f"batch size: {BATCH}")26print(f"seed: {SEED}")27for step in (10, 20, 30):28 print(f"loss at step {step}: {losses[step - 1]:.2f}") # train_steps returns one loss per step, from step 1 at index 0, so step 10 is index 929print(f"loss of a uniform guess over 77 teams: {math.log(77):.2f}")3031result = router_lib.score_test_sample(model, tok, "test_200", 0.5) # 0.5 is chapter 1's placeholder; this run chooses no threshold32n = result["n"]33print(f"messages on test_200: {n}")34print(f"accuracy on test_200: {result['correct']}/{n} ({result['accuracy']:.1%})")35print(f"handed off at placeholder 0.50: {result['handed_off']}/{n} ({result['handoff_rate']:.1%})")36if result["accuracy_not_handed_off"] is None: # None when no message is kept, so there is no accuracy to print37 print("accuracy on messages not handed off: not defined (0 messages not handed off)")38else:39 m = result["not_handed_off"]40 print(f"accuracy on messages not handed off: {result['correct_not_handed_off']}/{m} ({result['accuracy_not_handed_off']:.1%})")
python lora-thirty-steps.pytrainable parameters: 505152
LoRA parameters: 460800
head parameters: 44352
training steps: 30
batch size: 8
seed: 0
loss at step 10: 4.13
loss at step 20: 6.12
loss at step 30: 4.38
loss of a uniform guess over 77 teams: 4.34
messages on test_200: 200
accuracy on test_200: 5/200 (2.5%)
handed off at placeholder 0.50: 200/200 (100.0%)
accuracy on messages not handed off: not defined (0 messages not handed off)
Trinta passos não bastam para rotear. A cabeça que esta execução treina acerta 5/200 (2.5%) em test_200, e, no limiar de placeholder, entrega cada mensagem a uma pessoa: 200/200 (100.0%). Um roteador que entrega toda mensagem não dá nenhuma mensagem a uma equipe, de modo que os rótulos que ele prevê nunca chegam a quem liga. Como nenhuma mensagem é retida, a acurácia nas mensagens não entregues não está definida, como a saída indica.
A perda não cai de forma constante ao longo dos três passos impressos: ela é 4.13 no passo 10, 6.12 no passo 20 e 4.38 no passo 30. A perda no passo 20 é maior que no passo 10, e a do passo 30 é menor que a do passo 20, mas maior que a do passo 10. Três pontos de uma execução de 30 passos não formam uma curva de aprendizado. A perda no passo 30 fica perto do palpite uniforme de 4.34, então, nesse ponto, a cabeça ainda está próxima do acaso. Um palpite uniforme dá a cada equipe a mesma probabilidade, um em 77, e por isso sua perda é o logaritmo natural de 77. A gravação usada na seção sobre o adaptador gravado executa a mesma receita por muito mais passos, e a acurácia dela é a que este livro relata.
Pontuar test_200 aqui apenas registra a falha, e nada é escolhido a partir dela: a receita é fixada antes da execução, e o limiar é escolhido depois, no conjunto dev. Para ver se o treinamento funciona, leia a perda e as medidas do conjunto dev, e não a amostra de teste, regra que o capítulo 2 estabeleceu para toda amostra. Ajustar uma receita contra a amostra de teste não deixa nenhum número limpo para relatar, e a amostra deixa de ser um teste.
Regra prática: Execute um treinamento curto para verificar que o pipeline funciona de ponta a ponta, e não roteie com a cabeça dele. Avalie uma cabeça ajustada (fine-tuned) no conjunto dev, com as medidas definidas no capítulo 2, após uma execução longa o bastante para alcançá-las. Não leia uma curva de perda de poucos pontos como evidência de que a cabeça aprende.
Treine apenas com as linhas de treinamento, nunca com as linhas de teste
O arquivo de treinamento contém mensagens rotuladas, e o capítulo 2 extraiu a divisão de dev dele, equipe por equipe, com uma semente fixa. O treinamento usa as linhas de treinamento que não foram reservadas para dev. O arquivo de teste nunca é lido durante o treinamento. A ordem de treinamento em trinta passos não são suficientes é montada a partir das linhas que sobram depois que dev é removido, embaralhadas com a semente 0, de modo que é a mesma em todas as execuções.
A divisão de dev é a que carrega as decisões. Ela contém 1003 mensagens de train.csv, o arquivo de treinamento. Nenhuma etapa de treinamento as lê, e elas são usadas apenas para escolher o limiar e verificar a calibração na última seção.
A receita está escrita no manifesto do adaptador, para que você possa ver em que o adaptador foi treinado: a revisão fixada do modelo base, o commit dos dados, o tamanho do lote, a semente e o número de passos. Repetir o treinamento exige esses valores, e verificar que um resultado veio de uma divisão limpa exige o commit dos dados.
A regra importa mais quando um resultado parece bom. Uma execução de treinamento que lê a amostra de teste já viu as mensagens com as quais será avaliada depois, então sua acurácia de teste não mede nada sobre mensagens novas. Manter dev e teste separados é o que faz da acurácia de teste da próxima seção um relato justo.
Regra prática: Treine somente com linhas de treinamento que estejam fora de dev. Registre a semente, o tamanho do lote, o número de passos e o commit dos dados no manifesto. Quando dev for pequeno demais para decidir um limiar, extraia mais mensagens do arquivo de treinamento, nunca do arquivo de teste, como diz o capítulo 2.
Use o adaptador gravado
O roteador em uso usa banking77-lora-v1: o adaptador da execução completa gravada, versão 1, escrito por recordings/lora_full.py. Esse script treinou o adaptador uma única vez, com a receita descrita em a seção sobre as linhas de treinamento, e gravou seus arquivos e um manifesto. O manifesto contém a revisão do modelo base, o commit dos dados, o limiar, o hash da receita e os hashes dos arquivos de saída. Offline, o adaptador é carregado e pontua test_200 com o limiar do seu manifesto, e nada é treinado.
Use o adaptador como foi gravado. Uma receita diferente se torna uma nova execução, chamada v2; o livro não edita o adaptador à mão. Manter a gravação fixa é o que permite a você conferir os números deste capítulo com os arquivos que baixou.
1"""Load the recorded adapter banking77-lora-v1 and score test_200 at the threshold in its manifest; no training runs here.2Read the accuracy line with the two hand-off lines printed under it."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import json # noqa: E4021011import torch # noqa: E4021213torch.set_num_threads(2)1415import router_lib # noqa: E4021617router_lib.setup_runtime()18RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"19manifest = json.loads((RECORDED / "manifest.json").read_text())20threshold = manifest["handoff_threshold"] # the threshold the recording chose on dev; this script chooses none2122tokenizer, model = router_lib.load_classifier(RECORDED / "adapter") # the base model comes from the adapter's config, at its revision in models.toml23test = router_lib.read_rows("test")24sample = router_lib.read_sample("test_200")25golds = [test[i][1] for i in sample]26preds, confs = router_lib.classify(model, tokenizer, [test[i][0] for i in sample]) # a tie goes to the lower label index2728result = router_lib.metrics(preds, golds, confs, threshold) # a message is handed off when its confidence is below the threshold29n = result["n"]30print(f"adapter: {manifest['adapter']}")31print(f"handoff threshold from manifest: {threshold:.2f}")32print(f"messages on test_200: {n}")33print(f"accuracy on test_200: {result['correct']}/{n} ({result['accuracy']:.1%})")34print(f"handed off: {result['handed_off']}/{n} ({result['handoff_rate']:.1%})")35if result["accuracy_not_handed_off"] is None: # None when no message is kept, so there is no accuracy to print36 print("accuracy on messages not handed off: not defined (0 messages not handed off)")37else:38 m = result["not_handed_off"]39 print(40 f"accuracy on messages not handed off: {result['correct_not_handed_off']}/{m} "41 f"({result['accuracy_not_handed_off']:.1%})"42 )
python lora-recorded-adapter.pyadapter: banking77-lora-v1
handoff threshold from manifest: 0.63
messages on test_200: 200
accuracy on test_200: 172/200 (86.0%)
handed off: 33/200 (16.5%)
accuracy on messages not handed off: 156/167 (93.4%)
O adaptador gravado acerta 172/200 (86.0%) das mensagens, contra 9/200 (4.5%) do modelo de 135M com prompt, que o capítulo 4 mediu nas mesmas 200. A execução de 30 passos, com 5/200 (2.5%), fica abaixo do modelo com prompt. Uma mensagem encaminhada conta como errada quando a sua equipe está errada. A saída ao lado deste parágrafo fornece a contagem de encaminhamentos e a acurácia nas mensagens não encaminhadas, cada uma com sua contagem e seu denominador, como exige o capítulo 2.
O limiar não é escolhido nesta amostra. Ele vem do manifesto, que a seção sobre a escolha do limiar explica. É o limiar que as contagens de encaminhamento do adaptador gravado em test_200 usam: 0.63. Lê-lo do manifesto mantém a escolha no dev, onde a regra a fez.
O adaptador gravado é o modelo do roteador, e o substituto é a linha de base. Os dois foram medidos com limiares diferentes, então suas contagens de encaminhamento não são o mesmo tipo de resultado. Compare-os nas mesmas mensagens, com cada limiar indicado ao lado da sua contagem. A comparação abaixo faz isso para test_200, lendo as respostas gravadas do substituto para as mesmas mensagens.
1"""Set the stand-in's recorded answers beside the recorded adapter's live predictions on the same 200 test messages.2The last two lines count where the models disagree."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import json # noqa: E40210import math # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()19STANDIN_THRESHOLD = 0.5 # chapter 1's placeholder; the stand-in's own threshold is never chosen on dev20ADAPTER = router_lib.HERE / "data" / "recorded" / "lora-full"2122with open(router_lib.HERE / "data" / "recorded" / "standin-baseline" / "answers.jsonl") as f:23 answers = {row["index"]: row for row in map(json.loads, f)} # keyed by the test-row index that read_sample returns24threshold = json.loads((ADAPTER / "manifest.json").read_text())["handoff_threshold"]2526test = router_lib.read_rows("test")27sample = router_lib.read_sample("test_200")28golds = [test[i][1] for i in sample]29standin_preds = [answers[i]["label"] for i in sample]30standin_confs = [math.exp(answers[i]["logprob"]) for i in sample] # the recording stores log-probabilities; exp turns one back into the probability its answer had3132tokenizer, model = router_lib.load_classifier(ADAPTER / "adapter")33adapter_preds, adapter_confs = router_lib.classify(model, tokenizer, [test[i][0] for i in sample])3435standin = router_lib.metrics(standin_preds, golds, standin_confs, STANDIN_THRESHOLD)36adapter = router_lib.metrics(adapter_preds, golds, adapter_confs, threshold)37n = standin["n"]38s_right = [p == g for p, g in zip(standin_preds, golds)]39a_right = [p == g for p, g in zip(adapter_preds, golds)]4041print(f"messages on test_200: {n}")42print(f"stand-in correct: {standin['correct']}/{n} ({standin['accuracy']:.1%})")43print(f"adapter banking77-lora-v1 correct: {adapter['correct']}/{n} ({adapter['accuracy']:.1%})")44print(f"stand-in placeholder threshold: {STANDIN_THRESHOLD:.2f}")45print(f"stand-in handed off: {standin['handed_off']}/{n} ({standin['handoff_rate']:.1%})")46print(f"adapter threshold from manifest: {threshold:.2f}")47print(f"adapter handed off: {adapter['handed_off']}/{n} ({adapter['handoff_rate']:.1%})")48print(f"right for the adapter, wrong for the stand-in: {sum(a and not s for a, s in zip(a_right, s_right))}/{n}")49print(f"right for the stand-in, wrong for the adapter: {sum(s and not a for a, s in zip(a_right, s_right))}/{n}")
python compare-with-standin.pymessages on test_200: 200
stand-in correct: 109/200 (54.5%)
adapter banking77-lora-v1 correct: 172/200 (86.0%)
stand-in placeholder threshold: 0.50
stand-in handed off: 9/200 (4.5%)
adapter threshold from manifest: 0.63
adapter handed off: 33/200 (16.5%)
right for the adapter, wrong for the stand-in: 69/200
right for the stand-in, wrong for the adapter: 6/200
Comparar as duas mensagem por mensagem mostra quais mensagens cada um erra. As respostas do substituto vêm da sua gravação, e o adaptador roda ao vivo nas mesmas 200 mensagens. A confiança do substituto é a probabilidade que sua resposta gravada tinha, a partir da log-probabilidade da gravação. O limiar do substituto é o marcador do capítulo 1, 0.50, e a saída o rotula como tal. Sua contagem de encaminhamentos, 9/200 (4.5%), mostra o que esse marcador faz com o substituto, e nada sobre o limiar próprio do substituto, que nunca foi escolhido no dev. O adaptador encaminha 33/200 (16.5%) com 0.63.
O adaptador acerta 172/200 (86.0%) dessas mensagens, o substituto 109/200 (54.5%). Onde os dois discordam, somente o adaptador acerta 69/200, e somente o substituto acerta 6/200. Duas acurácias podem ser iguais enquanto os dois modelos erram mensagens diferentes, e as contagens de discordância mostram onde isso acontece.
A comparação é uma amostra de 200 mensagens. O capítulo 1 disse que sua pequena amostra pode mostrar que um roteador falha, mas não pode distinguir dois roteadores com confiança. A amostra do capítulo 1 era menor. As contagens discordantes aqui, 69/200 contra 6/200, são evidência mais forte do que aquela amostra poderia oferecer. Para uma afirmação mais firme, execute a mesma comparação na amostra completa de test_1001, que a gravação do substituto também cobre.
Regra prática: Compare dois modelos somente nas mesmas mensagens, e indique o limiar que cada um usou ao lado da sua contagem. Quando um limiar for um marcador, diga isso ao lado da sua contagem, e não leia a contagem de encaminhamentos dele como resultado próprio do modelo.
Escolha o limiar no dev
O limiar é o corte que envia uma mensagem a uma pessoa. O capítulo 2 definiu suas medidas, e o capítulo 1 o deixou como um marcador provisório. A regra do livro escolhe o limiar apenas na divisão de dev: o menor limiar de confiança, em uma grade de 0.01, no qual a acurácia nas mensagens não encaminhadas é pelo menos a meta de 0.90. A regra está escrita no manifesto com o seu valor, para que você veja a regra e também o número que ela produziu. A amostra de teste não participa, como exige o capítulo 2.
1"""Find the hand-off threshold on dev by the manifest's rule, then check it against the manifest's value.2Read the chosen threshold beside the three threshold lines. test_200 is not read here."""34import json56import torch78torch.set_num_threads(2)910import router_lib # noqa: E4021112router_lib.setup_runtime()13RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"14manifest_threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]15TARGET = 0.90 # the book's target accuracy on messages not handed off: a choice the book makes, not one the data sets1617tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")18rows = router_lib.read_rows("train")19dev = router_lib.read_sample("dev")20golds = [rows[i][1] for i in dev]21preds, confs = router_lib.classify_by_length(model, tokenizer, [rows[i][0] for i in dev]) # batches by length to pad less; results come back in dev order22n = len(dev)23chosen = router_lib.choose_threshold(preds, golds, confs, TARGET) # the rule lives in router_lib: the lowest 0.01 grid value that meets TARGET; None if no value meets it, and the prints below would then fail2425print(f"dev messages: {n}")26print(f"target accuracy on messages not handed off: {TARGET:.2f}")27print(f"chosen threshold: {chosen:.2f}")28print(f"threshold in manifest: {manifest_threshold:.2f}")29print(f"chosen threshold matches manifest: {'yes' if chosen == manifest_threshold else 'no'}") # both come from the same 0.01 grid, so equal means the same threshold30for t in sorted({0.50, chosen, 0.90}): # 0.50 is chapter 1's placeholder; a set drops the chosen value if it is one of the other two31 r = router_lib.metrics(preds, golds, confs, t)32 print(f"threshold {t:.2f} handed off: {r['handed_off']}/{n} ({r['handoff_rate']:.1%})")33 print(f"threshold {t:.2f} accuracy on messages not handed off: {r['correct_not_handed_off']}/{r['not_handed_off']} ({r['accuracy_not_handed_off']:.1%})")
python choose-threshold-on-dev.pydev messages: 1003
target accuracy on messages not handed off: 0.90
chosen threshold: 0.63
threshold in manifest: 0.63
chosen threshold matches manifest: yes
threshold 0.50 handed off: 80/1003 (8.0%)
threshold 0.50 accuracy on messages not handed off: 811/923 (87.9%)
threshold 0.63 handed off: 148/1003 (14.8%)
threshold 0.63 accuracy on messages not handed off: 770/855 (90.1%)
threshold 0.90 handed off: 352/1003 (35.1%)
threshold 0.90 accuracy on messages not handed off: 620/651 (95.2%)
Pontuar o dev com o adaptador registrado e aplicar a regra dá um limiar de 0.63. A verificação contra o valor do manifesto imprime yes, e uma divergência significaria que o manifesto e a regra não concordam.
Três limiares mostram a troca, e a tabela abaixo os coloca lado a lado, com cada contagem e taxa. Elevar o limiar nunca encaminha menos mensagens, e a regra escolhe o menor valor que atinge a meta. Cada linha se refere ao mesmo adaptador nas mesmas mensagens de dev, de modo que só o limiar muda.
| Limiar | Encaminhadas, no dev | Acurácia nas mensagens não encaminhadas, no dev |
|---|---|---|
| 0.50 | 80/1003 (8.0%) | 811/923 (87.9%) |
| 0.63, escolhido | 148/1003 (14.8%) | 770/855 (90.1%) |
| 0.90 | 352/1003 (35.1%) | 620/651 (95.2%) |
Com 0.50, o roteador mantém mais mensagens, mas as mensagens que mantém são menos acuradas, e a meta não é atingida. Com 0.90, as mensagens mantidas são as mais acuradas dos três, mas é com 0.90 que o maior número de mensagens de dev vai para uma pessoa. O valor escolhido é o menor dos três limiares que atinge a meta, de modo que encaminha mais mensagens que 0.50 e menos que 0.90. A tabela mostra o que ele custa em encaminhamentos e o que compra em acurácia. Onde fixar a meta é uma escolha de negócio que a regra não pode fazer. O livro usa 0.90 de acurácia nas mensagens mantidas, e um banco que execute seu próprio roteador leria sua meta a partir desta troca.
O adaptador permanece o mesmo em produção, mas as mensagens que ele vê não. Suponha que um problema de produto envie muitas mensagens sobre uma equipe em uma semana. O limiar foi escolhido sobre a mistura de mensagens de dev, então a taxa de encaminhamento pode mudar por conta própria enquanto o adaptador continua exatamente igual. Um aumento de encaminhamentos sem mudança no adaptador é o sinal para verificar primeiro a mistura de mensagens. Ajustar o limiar a olho até que a taxa de encaminhamento pareça certa abre mão da propriedade para a qual a regra foi escolhida: pelo menos a acurácia-meta nas mensagens de dev que o roteador mantém.
A confiança não é uma probabilidade de que a equipe esteja certa. Guo et al. (2017) relatam que suas redes são "mal calibradas", o que significa que a confiança delas não corresponde à frequência com que acertam. Este livro verifica o próprio adaptador no dev. As mensagens de dev se dividem em cinco faixas de confiança, e cada faixa recebe uma contagem, uma acurácia e uma confiança média, as duas quantidades que Guo et al. comparam ao medir a calibração. Agrupar o dev por confiança mostra se um 0.9 significa nove em cada dez.
1"""Group the dev messages into five bands by the adapter's confidence, and print each band's count, accuracy and mean confidence.2Read the top band's mean confidence against its accuracy. Only dev is read."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import torch # noqa: E4021011torch.set_num_threads(2)1213import router_lib # noqa: E4021415router_lib.setup_runtime()16RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"17BANDS = [(0.0, 0.2), (0.2, 0.4), (0.4, 0.6), (0.6, 0.8), (0.8, 1.0)]1819tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")20rows = router_lib.read_rows("train")21dev = router_lib.read_sample("dev")22golds = [rows[i][1] for i in dev]23preds, confs = router_lib.classify_by_length(model, tokenizer, [rows[i][0] for i in dev]) # results come back in dev order, so index i matches golds[i]2425print(f"dev messages: {len(dev)}")26counted = 027for lo, hi in BANDS:28 last = hi == 1.029 members = [i for i, c in enumerate(confs) if lo <= c < hi or (last and c == 1.0)] # lower edges are in, upper edges out; the top band also takes 1.0, so each message is counted once30 counted += len(members)31 name = f"band {lo:.1f}-{hi:.1f}"32 print(f"{name} messages: {len(members)}")33 if members:34 correct = sum(preds[i] == golds[i] for i in members)35 print(f"{name} correct: {correct}/{len(members)} ({correct / len(members):.1%})")36 print(f"{name} mean confidence: {sum(confs[i] for i in members) / len(members):.1%}")37 else:38 print(f"{name} correct: not defined (0 messages)")39 print(f"{name} mean confidence: not defined (0 messages)")40print(f"messages in bands: {counted}")
python calibration-bands-on-dev.pydev messages: 1003
band 0.0-0.2 messages: 1
band 0.0-0.2 correct: 1/1 (100.0%)
band 0.0-0.2 mean confidence: 19.9%
band 0.2-0.4 messages: 41
band 0.2-0.4 correct: 10/41 (24.4%)
band 0.2-0.4 mean confidence: 32.9%
band 0.4-0.6 messages: 92
band 0.4-0.6 correct: 49/92 (53.3%)
band 0.4-0.6 mean confidence: 51.0%
band 0.6-0.8 messages: 123
band 0.6-0.8 correct: 84/123 (68.3%)
band 0.6-0.8 mean confidence: 70.6%
band 0.8-1.0 messages: 746
band 0.8-1.0 correct: 693/746 (92.9%)
band 0.8-1.0 mean confidence: 96.4%
messages in bands: 1003
A maior parte das mensagens de dev cai na faixa superior, de 0.8 a 1.0, que contém 746 delas. A faixa inferior, de 0.0 a 0.2, contém 1, poucas demais para que sua acurácia diga algo sobre baixa confiança.
No dev, a confiança ordena as mensagens de forma útil, mas no topo ela fica acima da acurácia: a confiança média da faixa superior é 96.4%, contra uma acurácia de 693/746 (92.9%). Quatro das cinco faixas têm acurácia dentro de seu intervalo, e a faixa inferior é a única exceção, com sua única mensagem. A partir da segunda faixa, a acurácia sobe. Nas duas faixas do meio, acurácia e confiança média ficam próximas, enquanto na faixa de 0.2 a 0.4 a confiança média está bem acima da acurácia.
As faixas não podem mostrar mais: a faixa de 0.2 a 0.4 contém 41 mensagens. Todos os números aqui vêm da mesma amostra de dev que também escolheu o limiar, então nenhum deles mostra quão calibrado o adaptador será em mensagens novas.
O roteador que a regra escolhe é um corte empírico no dev, registrado com sua regra e seus dados. É um corte, não um modelo das mensagens, então seus números descrevem a mistura de dev. O leitor toma a taxa de encaminhamento e a acurácia nas mensagens mantidas como o resultado do roteador, e refaz a verificação da regra no dev quando a mistura de mensagens muda.
Regra prática: Escolha o limiar na divisão de dev pela regra declarada, e escreva seu valor e a regra no manifesto do adaptador. Informe a taxa de encaminhamento ao lado da acurácia nas mensagens mantidas, cada uma com sua contagem, e mostre pelo menos um valor de limiar de cada lado do escolhido. Verifique a calibração no dev antes de confiar na confiança como corte, e quando a mistura de mensagens mudar, escolha o limiar novamente em uma nova amostra de dev extraída do arquivo de treinamento.
Este capítulo, nesta edição
Edição 2026.11.9Exemplos aprovados em 20 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.9.