Versione o roteador, acompanhe seus repasses e recorra a pessoas
Cerca de 25 minutos min de leitura, com 4 exemplos em 8 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 nomear um roteador pelas partes que compõem suas respostas, verificar essas partes antes que a rota as carregue, calcular a taxa de repasse para cada janela de mensagens em relação a uma linha de base declarada e dizer para onde vai cada mensagem repassada.
Capítulo 8 colocou o roteador atrás de uma rota, e cada resposta traz uma equipe ou uma marcação que envia a mensagem para uma pessoa. Uma rota que recebe as mensagens de suporte do banco durante meses levanta três perguntas que a rota não consegue responder sozinha. Qual modelo está respondendo? Os seus arquivos são os que foram verificados? As mensagens que ele repassa estão aumentando ou diminuindo? Este capítulo oferece um controle e uma contagem impressa para cada pergunta. Os controles são os próprios do livro.
Este capítulo trata do que executar o seu próprio modelo acrescenta: versões, um recurso de contingência para pessoas e o retreinamento. Acompanhar um serviço em geral, com seus painéis, registros e alertas, é terreno de um livro sobre monitoramento em produção. Este capítulo não repete esse conteúdo.
Nomeie o roteador pelas suas partes
Um roteador é mais do que o seu modelo. Ele é o modelo base, o adaptador treinado sobre esse modelo base, o limiar que encaminha uma mensagem a uma pessoa, e os dados e a receita que produziram o adaptador. Dois roteadores que diferem em qualquer uma dessas partes podem responder à mesma mensagem de maneiras diferentes. Uma linha de log que diz apenas "o roteador" não consegue distingui-los.
Os arquivos do adaptador não incluem o modelo base. O guia de checkpoints do PEFT diz que os pesos salvos contêm apenas os parâmetros do módulo adaptador, nada do modelo base. Por isso, o adaptador precisa nomear o modelo base sobre o qual foi treinado, e esse nome precisa ser exato. Este livro nomeia a base pelo seu commit, o pin em examples/models.toml, porque um hash de commit curto não serve. O guia de download do Hugging Face, na versão v2.4.0 exige o hash completo sempre que um commit for informado. Sem revisão nomeada, o download traz o que estiver no branch main. Um nome de branch, portanto, acompanha o branch que muda, e não é um pin. O capítulo 5 registrou a revisão da base no manifesto do adaptador, ao lado do limiar, do commit dos dados e do hash da receita.
Uma versão é escrita no nome. banking77-lora-v1 é o adaptador LoRA registrado, treinado por uma época com as linhas de treino fora da divisão de desenvolvimento, versão um. Um novo registro da mesma receita é v2, e recebe nome e manifesto próprios. O manifesto não tem campo de versão separado. O nome é a versão, e a rota do capítulo 8 informa a versão como o sufixo do nome do adaptador. Para banking77-lora-v1, esse sufixo é v1. A cópia int8 do capítulo 7 é outro modelo, banking77-lora-v1-int8, e esta rota não a serve. Seu sufixo seria int8, então uma cópia servida pelo nome precisa de um campo de versão próprio.
A primeira verificação lê o manifesto e compara sua revisão da base com o pin. Ela imprime primeiro o nome do adaptador, seguido da comparação:
1"""Show what the adapter check does before a route loads an adapter, and what it does to two edited copies.2The point rests on the "route may load" line and on the two "refused by make_app" lines."""3import os45os.environ["HF_HUB_OFFLINE"] = "1"6os.environ["TRANSFORMERS_OFFLINE"] = "1"7import tempfile # noqa: E4028import warnings # noqa: E4029from pathlib import Path # 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"19# check_adapter hashes the manifest, the outputs and the LoRA settings; pinned is the manifest's digest matching its pin20manifest, s_ok, s_n, f_ok, f_n, pinned = router_lib.check_adapter(RECORDED)21# the base pin in models.toml, compared with the manifest's base revision22base = router_lib.pinned_revision(manifest["model"]) == manifest["model_version"]23print(f"adapter: {manifest['adapter']}")24print(f"base revision matches pin: {'yes' if base else 'no'}")25print(f"manifest matches pin: {'yes' if pinned else 'no'}")26print(f"settings matching: {s_ok}/{s_n}")27print(f"files matching: {f_ok}/{f_n}")28print("route may load: " + ("yes" if base and pinned and s_ok == s_n and f_ok == f_n else "no"))29with tempfile.TemporaryDirectory() as tmp:30 # changes a manifest field that is neither a LoRA setting nor an output file, so only the manifest digest sees it31 threshold = router_lib.edited_copy(RECORDED, Path(tmp) / "threshold", "manifest.json", "handoff_threshold", 0.0)32 # adds a key that LoraConfig does not know, to the config the settings are read from33 extra = router_lib.edited_copy(RECORDED, Path(tmp) / "extra", "adapter/adapter_config.json", "future_key", 1)34 for label, folder in [("threshold copy", threshold), ("extra-key copy", extra)]:35 _, s_ok, s_n, f_ok, f_n, pinned = router_lib.check_adapter(folder)36 print(f"{label}: manifest matches pin {'yes' if pinned else 'no'}, settings {s_ok}/{s_n}, files {f_ok}/{f_n}")37 print(f"{label} refused by make_app: {'yes' if router_lib.refused_by_make_app(folder) else 'no'}")38 with warnings.catch_warnings(record=True) as caught:39 warnings.simplefilter("always")40 router_lib.load_classifier(extra / "adapter")41 named = [w for w in caught if "future_key" in str(w.message)] # only the warning about the extra key42 print(f"warnings naming the extra key while PEFT loads the copy: {len(named)}")43 # the warning's first sentence: the text up to the first ". " in its message44 print(f"that warning: {named[0].category.__name__}: {str(named[0].message).split('. ')[0]}.")
python adapter-manifest-check.pyadapter: banking77-lora-v1
base revision matches pin: yes
manifest matches pin: yes
settings matching: 3/3
files matching: 3/3
route may load: yes
threshold copy: manifest matches pin no, settings 3/3, files 3/3
threshold copy refused by make_app: yes
extra-key copy: manifest matches pin yes, settings 3/3, files 2/3
extra-key copy refused by make_app: yes
warnings naming the extra key while PEFT loads the copy: 1
that warning: UserWarning: Unexpected keyword arguments ['future_key'] for class LoraConfig, these are ignored.
O nome carrega a versão, banking77-lora-v1, e a revisão da base corresponde ao pin (yes). São as duas partes que você pode conferir com os pins antes de ler qualquer arquivo.
Regra prática: Nomeie um roteador pela sua revisão da base, pelo nome do adaptador com a versão nesse nome, pelo seu commit de dados, pelo seu limiar e pelo hash da sua receita, e registre as cinco informações no manifesto do adaptador antes de a rota servi-lo. Compare a revisão da base no manifesto com o pin em examples/models.toml sempre que carregar o adaptador. Um pin que tenha mudado significa um modelo base diferente, e o adaptador precisa de uma nova verificação antes de servir.
Verifique os arquivos do adaptador contra o manifesto
A carga não é uma verificação de versão. O guia de checkpoints do PEFT observa que a maioria das entradas em uma configuração LoRA não é necessária para carregar o modelo, de modo que uma carga pode ter sucesso com uma configuração que alguém alterou manualmente. Uma carga bem-sucedida não mostra que o adaptador é o fixado. A cópia com chave extra abaixo ainda carrega, e essa carga emite um aviso que nomeia a chave extra. Uma base incompatível falha na carga, com um erro de state dict, na sonda de pesquisa; este exemplo não imprime esse caso.
Assim, a verificação compara o adaptador com seu manifesto, em três partes. Ela calcula o SHA-256 de manifest.json por conta própria e o compara com o digest fixado para o nome do adaptador em examples/adapter-pins.json. O fixamento cobre todos os campos que o manifesto contém, incluindo o limiar, a revisão da base e os digests das saídas. Ela calcula o SHA-256 de cada arquivo de saída listado no manifesto e o compara com o digest que o manifesto registra. Também lê os três ajustes LoRA na configuração, o rank, o alpha que define a escala e as camadas-alvo, e os compara com o manifesto. As linhas impressas informam quantos de cada item coincidem e se a rota pode carregar a pasta.
Para o adaptador registrado, o manifesto coincide com seu fixamento (yes), 3/3 ajustes e 3/3 arquivos coincidem, e portanto a rota pode carregá-lo.
A verificação também roda sobre duas cópias editadas, e cada uma recebe sua própria linha. A primeira tem o handoff_threshold alterado para 0 no manifesto, e sua linha é manifest matches pin no, settings 3/3, files 3/3. Seus ajustes e arquivos ainda coincidem, porque o limiar não é um ajuste e nenhum arquivo de saída mudou. Apenas o digest do próprio manifesto percebe a mudança, e por isso a cópia é recusada. A segunda tem uma chave extra adicionada à configuração, e sua linha é manifest matches pin yes, settings 3/3, files 2/3. Seus ajustes ainda coincidem, e a verificação de arquivos a recusa, porque o hash do arquivo de configuração não corresponde mais. O PEFT carrega essa cópia mesmo assim e, entre os avisos que a carga emite, 1 nomeia a chave extra. Por inteiro, ele diz UserWarning: Unexpected keyword arguments ['future_key'] for class LoraConfig, these are ignored. A carga retorna um modelo com a chave ignorada, e esse aviso é tudo o que o PEFT informa a respeito. Um aviso não é uma recusa. Quem recusa a cópia é a verificação.
A rota no capítulo 8 executa esta verificação. Seu make_app chama check_adapter antes de carregar o modelo, e também compara a revisão da base do manifesto com o fixamento. Ela lança um erro em qualquer divergência, de modo que uma cópia que falha é recusada antes de o modelo entrar na memória. A cópia com limiar é recusada por make_app (yes), e a cópia com chave extra também é recusada (yes). A verificação confia no repositório. Seu digest fixado fica em examples/adapter-pins.json, ao lado do código, de modo que um leitor que edita a pasta e não o arquivo de fixamentos é recusado, e um leitor que edita ambos não é. O arquivo de fixamentos, portanto, é revisado como qualquer outro código.
Regra prática: Execute a verificação antes de qualquer rota carregar um adaptador. Fixe o SHA-256 do manifesto junto com o código, conte os ajustes e arquivos que coincidem, imprima cada contagem com seu total e recuse a carga quando qualquer contagem ficar abaixo ou quando o digest do manifesto não corresponder. Obtenha os hashes a partir dos arquivos em disco, e verifique e carregue a partir dos mesmos arquivos, sem que nada os escreva entre as duas etapas.
Acompanhe a taxa de encaminhamento
A taxa de encaminhamento é o número de mensagens abaixo do limiar dividido por todas as mensagens de uma janela. Capítulo 2 definiu essa taxa, e este capítulo a acompanha ao longo do tempo. Um acompanhamento precisa de três coisas: uma janela, uma linha de base e uma regra para decidir quando uma janela se afastou demais da linha de base.
A linha de base é a taxa de encaminhamento na divisão de dev, no limiar do adaptador. dev_handed_off a calcula roteando uma vez todas as mensagens de dev e contando os encaminhamentos, o que resulta em 148/1003 (14.8%). O exemplo de limiar do capítulo 5 imprime a mesma contagem, 148/1003 (14.8%). As duas coincidem, por isso a linha de base é aquela na qual esse capítulo escolheu o limiar.
Uma linha de base obtida em dev não é uma previsão para a caixa de entrada. A divisão de dev é extraída das linhas de treinamento, equipe por equipe. A amostra de teste é extraída da divisão de teste. Nenhuma das duas é uma amostra do tráfego da caixa de entrada, e a mistura de equipes nas mensagens reais não é conhecida. Uma diferença entre uma janela e a linha de base é, portanto, uma pergunta a ser feita, e não responde à pergunta por si mesma.
A regra de desvio é uma escolha deste livro, não um número extraído de uma fonte. Uma janela sofre desvio quando sua taxa de encaminhamento está a mais de um determinado número de pontos da linha de base, para cima ou para baixo. A regra, como impressa, diz more than 10 points from the baseline. Quem conduz o acompanhamento deve escolher um número próprio e registrá-lo por escrito antes de ler as janelas.
A amostra de teste versionada, test_1001, não tem datas, então as janelas são cortadas a partir de suas primeiras 100 mensagens. As duas primeiras janelas, de 25 mensagens cada, são as primeiras mensagens da amostra, na ordem da amostra. As semanas 3 e 4 são uma reprodução, não tráfego novo. Para essas duas semanas, o exemplo pega as próximas mensagens da amostra, ordena-as pela confiança do roteador, da menor para a maior, e divide a lista ordenada em duas partes. O exemplo marca a reprodução como simulada na linha impressa, simulated replay of sample messages 51 to 100. A reprodução é construída para produzir uma dispersão de confianças, de modo que mostra o que a regra faz com uma janela enviesada e, como a linha de base, não diz nada sobre a caixa de entrada.
1"""Watch the router's hand-off rate week by week on a fixed, ordered sample of test_1001, against the dev baseline.2The point rests on the "drift" lines and on the "lowest confidence" and "right" lines of weeks 3 and 4, which the output3labels as a simulated replay."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()19RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"20# the threshold is read from the manifest, not typed here21threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]22tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")2324handed_dev, n_dev = router_lib.dev_handed_off(model, tokenizer, threshold)25base = 100 * handed_dev / n_dev26print(f"dev hand-off rate (baseline): {handed_dev}/{n_dev} ({base:.1f}%)")27print(f"drift rule: more than {router_lib.DRIFT_POINTS:.0f} points from the baseline")28print("weeks 3 and 4: simulated replay of sample messages 51 to 100")29test = router_lib.read_rows("test")30# simulated=True (the default) adds weeks 3 and 4: messages 51 to 100, lowest confidence first, ties by position31for w, (rows, preds, confs) in enumerate(router_lib.watch_weeks(model, tokenizer, threshold), 1):32 n = len(rows)33 handed = sum(router_lib.handoff(c, threshold) for c in confs)34 rate = 100 * handed / n35 # the messages the router keeps, each with its gold team: test row i holds (text, gold team)36 kept = [(p, test[i][1]) for i, p, c in zip(rows, preds, confs) if not router_lib.handoff(c, threshold)]37 right = sum(p == g for p, g in kept)38 print(f"week {w} messages: {n}")39 print(f"week {w} handed off: {handed}/{n} ({rate:.1f}%)")40 # abs makes the rule two-sided, so a fall in the rate drifts as a rise does41 print(f"week {w} drift: {'yes' if abs(rate - base) > router_lib.DRIFT_POINTS else 'no'}")42 print(f"week {w} lowest confidence: {min(confs):.3f}")43 print(f"week {w} right among messages not handed off: {right}/{len(kept)}")
python handoff-windows.pydev hand-off rate (baseline): 148/1003 (14.8%)
drift rule: more than 10 points from the baseline
weeks 3 and 4: simulated replay of sample messages 51 to 100
week 1 messages: 25
week 1 handed off: 6/25 (24.0%)
week 1 drift: no
week 1 lowest confidence: 0.479
week 1 right among messages not handed off: 17/19
week 2 messages: 25
week 2 handed off: 4/25 (16.0%)
week 2 drift: no
week 2 lowest confidence: 0.378
week 2 right among messages not handed off: 19/21
week 3 messages: 25
week 3 handed off: 9/25 (36.0%)
week 3 drift: yes
week 3 lowest confidence: 0.246
week 3 right among messages not handed off: 16/16
week 4 messages: 25
week 4 handed off: 0/25 (0.0%)
week 4 drift: yes
week 4 lowest confidence: 0.981
week 4 right among messages not handed off: 25/25
As janelas são pequenas porque a amostra é pequena, com quatro janelas de 25 mensagens cada. Em uma janela desse tamanho, uma mensagem equivale a 4 pontos da taxa, de modo que uma única mensagem pode levar uma janela para além da linha da regra. Um acompanhamento sobre uma caixa de entrada real precisa de janelas grandes o bastante para que uma mensagem não decida o sinal. O tamanho da janela deve constar no relatório, declarado antes de as janelas serem lidas.
As semanas 1 e 2 permanecem dentro da regra, e a reprodução sofre desvio nos dois sentidos. As quatro janelas saem assim, cada uma com sua contagem e seu sinal.
- A semana 1 encaminha 6/25 (24.0%), e seu sinal de desvio é no.
- A semana 2 encaminha 4/25 (16.0%), e seu sinal de desvio é no.
- A semana 3 encaminha 9/25 (36.0%), e seu sinal de desvio é yes.
- A semana 4 encaminha 0/25 (0.0%), e seu sinal de desvio é yes.
A semana 4 é o caso que o leitor deve examinar com atenção. Uma taxa que cai para zero sofre desvio sob esta regra, porque a regra trata uma queda da mesma forma que trata uma alta. A taxa é zero porque a menor confiança na semana 4 é 0.981, acima do limiar, de modo que nenhuma mensagem da janela é encaminhada. O roteador acertou em 25/25 das mensagens que manteve. A janela é formada por respostas confiantes e corretas, e o sinal de desvio informa que sua taxa de encaminhamento se moveu, não que o roteador cometeu erros.
A semana 3 é o outro tipo de janela. Sua menor confiança é 0.246, seus encaminhamentos sobem para 9/25 (36.0%), e o roteador acerta em 16/16 das mensagens que mantém. Uma alta nos encaminhamentos significa que mais mensagens chegam a uma pessoa. Por si só, ela não mostra qual causa produziu a alta: uma mudança nas mensagens, nas equipes que aparecem ou no modelo. A rota não pode dizer qual delas, porque suas respostas não trazem registro das mensagens, e o capítulo 8 diz o mesmo sobre a taxa que ela devolve.
Regra prática: conte os encaminhamentos em cada janela de mesmo tamanho, imprima cada contagem com seu denominador e compare cada taxa com a linha de base de dev, no limiar do adaptador. Defina a regra de desvio, e seu número de pontos, antes de ler as janelas, e escreva-a no seu relatório. Trate uma janela com desvio como um motivo para ler suas mensagens e suas equipes, não como um veredito sobre o roteador.
Amostras de mensagens encaminhadas a pessoas
O vigilância de encaminhamento conta quantas mensagens são encaminhadas a uma pessoa. Ele deixa duas perguntas em aberto: se o roteador acertou nas mensagens que encaminhou e se acertou nas mensagens que manteve. Esta seção descreve como a primeira seria respondida. Trata-se de um próximo passo. Este capítulo não extrai nenhuma amostra, não relata rótulos e não apresenta nenhum número para ela.
Uma pessoa rotularia uma amostra das mensagens encaminhadas, extraída com uma semente fixa, e os rótulos indicariam qual equipe a pessoa escolhe para cada uma. Comparados com a equipe que o modelo do roteador teria escolhido, mostrariam com que frequência as duas divergem nas mensagens em que o roteador estava inseguro. Um roteador inseguro quanto a uma mensagem é aquele cujas escolhas as pessoas mais devem verificar, por isso essa amostra é a primeira a ser extraída. Quem construir essa amostra pode usar os rótulos de referência (gold) de um conjunto de dados público como substituto dos rótulos de uma pessoa, e deve dizer isso no relatório.
Uma amostra de mensagens encaminhadas não diz como o roteador se sai nas mensagens que mantém. As mensagens mantidas são aquelas cujas respostas a rota devolveu, e o encaminhamento nunca as envia a uma pessoa. A acurácia delas só pode ser estimada quando pessoas também verificarem algumas delas, depois que a rota já tiver respondido. A verificação das mensagens mantidas é uma segunda amostra, extraída do mesmo modo, e não é um subproduto da amostra de mensagens encaminhadas. A medida é a acurácia nas mensagens não encaminhadas, com sua contagem e seu denominador, como o capítulo 5 a definiu.
Regra prática: Ao construir a amostra, extraia-a com uma semente fixa, exiba quantas mensagens foram rotuladas e relate com que frequência a equipe do roteador e a equipe da pessoa concordam, com sua contagem. Rotule uma amostra de mensagens mantidas no mesmo cronograma, e leia a acurácia do roteador nas mensagens mantidas somente a partir dessa amostra. Nunca leia a taxa de acerto nas mensagens mantidas a partir da amostra de mensagens encaminhadas.
Recorra a uma pessoa
A rota devolve uma marcação e nenhuma equipe para uma mensagem encaminhada, como o capítulo 8 a construiu. Algo ainda precisa acontecer com essa mensagem. A regra deste capítulo é que uma mensagem encaminhada sempre vai para uma pessoa. A resposta registrada do substituto, o Qwen3-4B-Instruct-2507, pode acompanhar a mensagem encaminhada como uma sugestão, identificada como sendo do substituto, e a pessoa decide se a usa. As respostas do substituto sobre test_1001 estão registradas em standin-baseline (capítulo 2). A equipe indicada pelo roteador nunca é devolvida para uma mensagem encaminhada.
O JSON da rota tem team, confidence, handed_off, adapter e version, e não tem nenhum campo que diga quem respondeu. Por isso, uma resposta de recurso nunca deve sair nesse formato. Um leitor que queira uma sugestão na resposta acrescenta um campo próprio, de propósito, e diz na resposta o que esse campo é.
O livro não ensina uma chamada a um modelo hospedado como recurso, e não define nenhum limite para o substituto. As respostas dele vêm de uma gravação, que o script de recurso lê. Esse script mede com que frequência a sugestão está certa, e não decide nada a partir dessa medida.
1"""Hand each handed-off message to a person, with the stand-in's recorded answer as a labelled suggestion.2The point rests on the "team returned for a handed-off message" line and the "suggestions right" line."""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"19# the threshold is read from the manifest, not typed here20threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]21tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")22test = router_lib.read_rows("test")23standin = router_lib.standin_rows() # a dict from test row index to the stand-in's answer, for the rows it answered24rows, handed = [], []25# simulated=False keeps weeks 1 and 2 only: the replay belongs to the watch, not to this example26for weekly_rows, _, confs in router_lib.watch_weeks(model, tokenizer, threshold, simulated=False):27 rows += weekly_rows28 handed += [i for i, c in zip(weekly_rows, confs) if router_lib.handoff(c, threshold)]2930# the list of records stands in for the person's queue, which the book does not build31# the suggestion is None where the stand-in has no recorded answer, and the team is always None32queue = [{"index": i, "team": None, "suggestion": standin[i]["label"] if i in standin else None} for i in handed]33suggested = [r for r in queue if r["suggestion"] is not None]34right = sum(r["suggestion"] == test[r["index"]][1] for r in suggested) # index 1 of a test row is its gold team3536print(f"messages routed: {len(rows)}")37print(f"handed off by the router: {len(handed)}/{len(rows)} ({100 * len(handed) / len(rows):.1f}%)")38print(f"sent to a person: {len(queue)}/{len(handed)}")39print(f"suggestions attached: {len(suggested)}/{len(handed)}")40print(f"suggestions right: {right}/{len(suggested)}")41print(f"team returned for a handed-off message: {sum(r['team'] is not None for r in queue)}")
python fallback-to-larger-model.pymessages routed: 50
handed off by the router: 10/50 (20.0%)
sent to a person: 10/10
suggestions attached: 10/10
suggestions right: 4/10
team returned for a handed-off message: 0
O exemplo roteia as duas primeiras janelas, 50 mensagens no total, e o roteador encaminha 10/50 (20.0%) delas. Cada mensagem encaminhada recebe um registro, e a saída conta os registros enviados a uma pessoa. Quando o substituto tem uma resposta registrada, o registro a carrega como sugestão. Dos registros, 10/10 trazem uma sugestão, e a contagem de equipes devolvidas para uma mensagem encaminhada é 0. A lista de registros faz o papel da fila da pessoa. O livro não constrói essa fila, e um leitor que a construir deve manter cada registro junto da sua mensagem.
As sugestões estão certas em 4/10 das mensagens encaminhadas que trazem uma. É menos da metade, e essa é a razão pela qual a sugestão é mostrada a uma pessoa e nunca usada como resposta. O script de recurso não mede o substituto nas mensagens que o roteador mantém. Toda mensagem encaminhada desta amostra traz uma sugestão, e o capítulo não afirma o mesmo para a caixa de entrada.
Regra prática: Envie cada mensagem encaminhada a uma pessoa. Uma resposta registrada do substituto pode acompanhá-la, identificada como sugestão. Nunca devolva uma equipe para ela, e nunca coloque uma sugestão no formato de resposta da rota sem um campo que diga quem respondeu. Conte as sugestões que estão certas, com a contagem e o seu denominador, antes de o leitor decidir quanto peso dar a elas.
Retreinar com um gatilho
Uma janela em deriva é um sinal para olhar, e não inicia, por si só, um retreinamento. O livro define três gatilhos, e esta seção descreve cada um. O primeiro é a deriva, a regra do monitoramento deste capítulo aplicada a janelas consecutivas. O livro retreina quando duas janelas consecutivas entram em deriva, um número que nenhuma fonte fornece, e você pode escolher outro, desde que o declare de antemão. O segundo gatilho é uma equipe acrescentada às 77 que o roteador devolve. O roteador não tem linhas de treinamento para ela, e os rótulos das pessoas a mostrariam como uma equipe fora das 77. O terceiro é um aumento de equipes erradas em mensagens que o roteador mantém, confirmado na amostra de mensagens mantidas da seção anterior. Não se trata da amostra de mensagens encaminhadas, cujas equipes nunca são devolvidas; por isso, equipes erradas ali são esperadas e não causam dano. O script de retreinamento abaixo exercita apenas o primeiro. Os dados gravados não contêm equipe acrescentada nem rótulos de pessoas, de modo que o segundo e o terceiro são regras sem teste aqui.
1"""Decide whether to retrain, as a rule over the weekly drift flags from handoff-windows. The rule is the book's choice,2not a sourced threshold: retrain when two consecutive weeks drift, that is, their hand-off rate is more than3router_lib.DRIFT_POINTS from the dev baseline. The point rests on the "retrain trigger" line."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()19RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"20# the threshold is read from the manifest, not typed here21threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]22tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")23handed_dev, n_dev = router_lib.dev_handed_off(model, tokenizer, threshold)24base = 100 * handed_dev / n_dev2526drifting, run, longest = [], 0, 027# the default simulated=True: weeks 3 and 4 are the replay, the same four windows the watch reads28for rows, _, confs in router_lib.watch_weeks(model, tokenizer, threshold):29 rate = 100 * sum(router_lib.handoff(c, threshold) for c in confs) / len(rows)30 flag = abs(rate - base) > router_lib.DRIFT_POINTS # two-sided, as in the watch31 drifting.append(flag)32 run = run + 1 if flag else 033 longest = max(longest, run)34 print(f"week {len(drifting)} drift: {'yes' if flag else 'no'}")3536print(f"weeks drifting: {sum(drifting)}/{len(drifting)}")37print(f"longest run of drifting weeks: {longest}")38print("rule: retrain when two consecutive weeks drift")39print("retrain trigger: " + ("fired" if longest >= 2 else "not fired"))
python retrain-trigger.pyweek 1 drift: no
week 2 drift: no
week 3 drift: yes
week 4 drift: yes
weeks drifting: 2/4
longest run of drifting weeks: 2
rule: retrain when two consecutive weeks drift
retrain trigger: fired
O script de retreinamento aplica a regra de deriva às mesmas quatro janelas do monitoramento, em ordem, e encontra 2/4 janelas em deriva, com a maior sequência de 2. As semanas 3 e 4 determinam esse resultado, pois são o replay do monitoramento. O gatilho fired por causa da forma como o replay foi montado; assim, a execução mostra a regra funcionando como declarada, e não algo que a caixa de entrada tenha feito.
Quando um retreinamento de fato começa, ele segue o mesmo caminho do primeiro adaptador. É uma gravação em recordings/, como foi o banking77-lora-v1, escrita por um script ali, e grava um manifesto com os mesmos campos. Ele recebe o nome da próxima versão da mesma receita, de modo que o adaptador retreinado é v2. Seu limiar é escolhido novamente no conjunto de desenvolvimento, pela regra do capítulo 5, nunca na amostra de teste. A pasta retreinada então precisa ter o resumo do manifesto acrescentado a examples/adapter-pins.json, como uma mudança no repositório que alguém revisa. Até lá, make_app recusa construir o aplicativo a partir dela. O adaptador antigo permanece no lugar até que make_app construa um aplicativo a partir da nova pasta.
Regra prática: Retreine quando o gatilho que você declarou for atingido, e não por causa de uma única janela em deriva. Escreva o gatilho, seu número e a regra ao lado das janelas que o atingiram. Um adaptador retreinado é uma gravação nomeada como a próxima versão, com seu resumo de manifesto fixado e seu limiar escolhido novamente no desenvolvimento. Mantenha o adaptador anterior até que o novo passe na verificação em make_app.
O que dá errado em produção
- Um manifesto é editado à mão. O digest do manifesto está fixado, então a verificação o recusa. Uma verificação que confia no repositório só pode ser burlada se o arquivo de fixações também for editado, o que é uma mudança que alguém revisa.
- Uma fixação se move. A fixação da base em
examples/models.tomlpode mudar sob um adaptador cujo manifesto ainda cita a revisão antiga.make_appcompara as duas e recusa a construção. - Um fallback encaminha pela escala errada. Uma confiança vinda de um modelo que nunca foi calibrado para o limiar não é um portão. O fallback do livro, portanto, nunca encaminha, e a sugestão só viaja junto com a mensagem de uma pessoa.
- A janela é pequena demais. Em uma janela de 25 mensagens, uma mensagem vale 4 pontos. Um sinalizador então reflete uma ou duas mensagens, e um leitor que age com base nele age sobre ruído.
- A taxa muda e nada a explica. As respostas da rota não trazem registro das mensagens, então a variação da taxa é uma questão a responder a partir das mensagens e de suas equipes, com as amostras que este capítulo descreve como próximos passos.
Você percebe o primeiro tipo de falha quando o app é construído. Uma pasta recusada gera um erro na inicialização, então uma implantação que constrói o app ao iniciar vê uma pasta ruim antes de qualquer mensagem falhar. As outras falhas aparecem nas contagens. Uma taxa de encaminhamento que se deslocou aparece na contagem de uma janela, e a regra de deriva a informa. Um fallback que responde às mensagens erradas aparece na contagem de sugestões, e uma amostra dos rótulos das pessoas mostra o restante.
Regra prática: Imprima a contagem de cada controle onde o leitor possa vê-la, na inicialização e em cada janela, e mantenha no mesmo relatório da taxa que ela explica as contagens que revelariam uma falha.
As decisões deste capítulo
- Uma mensagem encaminhada sempre vai para uma pessoa. A resposta do substituto, quando existe, é uma sugestão rotulada, e o capítulo conta com que frequência ela está certa.
- A verificação de versão fixa o SHA-256 do
manifest.jsonde cada adaptador emexamples/adapter-pins.json, emake_appse recusa a construir em caso de divergência ou de uma fixação de base que tenha sido movida. - A regra de deriva é de 10 pontos em relação à linha de base de desenvolvimento, em qualquer direção, em janelas de 25 mensagens.
- Um retreinamento é necessário quando duas janelas consecutivas apresentam deriva. O segundo e o terceiro gatilhos são regras declaradas, não testadas aqui.
Capítulo 10 usa as mesmas medidas deste capítulo.
Todas as quatro são escolhas do livro; veja a regra de deriva. Em conjunto, os controles verificam qual modelo responde, contam o que ele encaminha e enviam cada mensagem encaminhada a uma pessoa. A regra de contingência segue a regra do capítulo 1, segundo a qual uma mensagem sinalizada vai para uma pessoa. A regra de fixação troca uma revisão do repositório por uma verificação que um carregamento sozinho não consegue fazer.
Regra prática: Escreva cada decisão acima no relatório com seu número e com a indicação de se ela é uma escolha do livro ou um número com fonte. Altere uma decisão somente alterando a regra que ela nomeia, e execute novamente os exemplos que imprimem as contagens dela.
Este capítulo, nesta edição
Edição 2026.11.9Exemplos aprovados em 20 de nov de 20264 de 4 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.9.