Mover Exemplos para um Dataset

Problema

Os exemplos do prompt vivem no código, cresceram sem curadoria e só mudam com deploy. São os smells Acúmulo de Exemplos e Exemplos Chumbados.

A triagem do banco classifica tickets de Pix, boleto, acesso e cartão. Alguém colou três exemplos no classifier.py no primeiro mês. Cada ticket mal classificado ganhou mais um. Hoje são 31. O prompt manda os 31 em toda chamada. Ops não consegue acrescentar o caso de “boleto venceu e o acesso bloqueou” sem abrir um pull request de engenharia. E 12 dos 60 casos do eval são cópia dos exemplos: a acurácia de 94% está medindo memorização.

O destino desta refatoração é o Seletor de Exemplos, alimentado por um Dataset de Ouro que não se mistura com o eval.

Solução

Tire os exemplos do código e leve-os para um conjunto versionado, com dono, motivo e data de cada um. Na hora do pedido, escolha os exemplos mais parecidos com a entrada, em vez de mandar todos.

Antes e depois

-# classifier.py
-FEW_SHOTS = [
-    ("Não consigo acessar o painel", "acesso"),
-    ... [31 exemplos]
-]
-prompt = SYSTEM + render(FEW_SHOTS)
+# examples/triage.jsonl  (versionado, editado por pull request, revisado por ops)
+# {"id": "ex-041", "input": "boleto venceu e o acesso bloqueou", "label": "cobranca",
+#  "added_by": "ops/marina", "reason": "bloqueio por inadimplência é cobrança", "since": "2026-05"}
+
+EXAMPLES = ExampleSet.load("examples/triage.jsonl")      # embeddings calculados no build
+chosen = EXAMPLES.select(ticket_text, k=4, diversity=0.3)
+prompt = SYSTEM + render(chosen)
+trace.set("few_shot.ids", [e.id for e in chosen])

Antes: todos os exemplos, fixos no código.

flowchart LR
  C[("1. 31 exemplos no código")]:::store --> P(["2. Prompt com todos"]):::llm
  IN(["Ticket"]):::io --> P

Depois: um conjunto curado fora do código, e só os relevantes em cada chamada.

flowchart LR
  D[("1. Conjunto versionado e curado")]:::store --> S["2. Selecionar os 4 mais parecidos"]:::tool
  IN(["Ticket"]):::io --> S
  S --> P(["3. Prompt com os escolhidos"]):::llm
  P --> T[("4. Trace com os ids usados")]:::store

1. Os exemplos ficam num arquivo ou tabela com histórico, editável por quem conhece o domínio.
2. Uma busca por similaridade escolhe poucos exemplos para cada entrada.
3. O prompt tem tamanho fixo.
4. O trace registra quais exemplos foram usados, para rastrear exemplos ruins.

Exemplo trabalhado

Suponha que cada exemplo tenha uns 150 tokens (ticket mais rótulo). Os números abaixo são ilustrativos.

Desenho	Exemplos enviados	Tokens de exemplo por chamada
31 fixos	31	cerca de 4.650
4 escolhidos	4	cerca de 600

Em 10 mil tickets por dia, a diferença é da ordem de 40 milhões de tokens. O conjunto pode crescer para 200 casos de Pix, boleto e cartão sem o prompt crescer: o seletor continua mandando 4.

O ticket “boleto venceu e o acesso bloqueou” no antes competia com 30 vizinhos, inclusive 8 de acesso puro. No paper “Lost in the Middle” (Liu et al., 2023), modelos prestam menos atenção ao que fica no meio de um contexto longo. Os 31 exemplos espalham o sinal. Com k=4 e um critério de diversidade, o seletor devolve dois de cobrança e um de acesso, e o modelo vê o contraste que importa: bloqueio por inadimplência é cobrança, não acesso.

O span registra few_shot.ids=["ex-041","ex-018","ex-007","ex-033"]. Se a triagem errar, você sabe quais exemplos estavam na mesa.

Checagem +20 XP de primeiraA triagem manda 31 exemplos em toda chamada. O time quer chegar a 80 para cobrir Pix, boleto e cartão. Sem seletor, o que acontece com o prompt?

Nada demais: exemplos no fim são baratos e o modelo usa todos

O prompt cresce a cada exemplo novo, o custo sobe e a atenção ao exemplo certo dilui

O eval vai melhorar na mesma proporção, então o crescimento se paga

Por que funciona

Separar os exemplos do código separa dois ciclos de mudança: o do código (engenharia, deploy) e o do conhecimento de domínio (operações, curadoria). Cada um anda no seu ritmo, com revisão própria. Ops acrescenta ex-041 com motivo e autor; engenharia só muda o seletor quando a lógica de escolha muda.

A seleção por similaridade resolve o acúmulo: o conjunto pode crescer para centenas de exemplos sem que o prompt cresça. E os metadados (motivo, autor, data) transformam a curadoria em algo possível: dá para achar exemplos contraditórios, remover os velhos e entender por que cada um existe.

O id no trace fecha o diagnóstico. Um exemplo ruim deixa de ser “o classificador errou” e vira “ex-018 está puxando boleto para acesso”. Você tira o exemplo, não o modelo.

Passo a passo seguro

0. Meça. Rode o eval com os exemplos atuais. Separe o dataset de eval dos exemplos: eles nunca podem se sobrepor. Se 12 casos são idênticos, tire-os de um dos dois lados e rode a linha de base de novo. A acurácia que cair é a real.
1. Exporte os exemplos do código para um arquivo ou tabela, acrescentando motivo e autor quando souber. Id estável desde o primeiro dia.
2. Faça uma curadoria inicial: remova duplicados, resolva contradições, equilibre as categorias. Três exemplos de Pix e vinte de cartão enviesam o seletor.
3. Implemente a seleção por similaridade, com k pequeno (3 a 5) e algum critério de diversidade, para não devolver quatro clones da mesma classe.
4. Defina o fluxo de edição: quem pode propor, quem revisa, e o eval rodando antes de valer. Um jsonl no repositório com pull request já é um fluxo.
5. Registre no trace os ids dos exemplos usados.
6. Meça de novo e compare com a versão de exemplos fixos, no eval sem sobreposição.

Cache de prompt e posição

As instruções fixas (função, categorias, formato de saída) ficam no prefixo, onde o cache do provedor acerta. Os exemplos escolhidos mudam a cada ticket: eles entram depois do prefixo, antes da entrada. Se você misturar um exemplo no meio das regras, o cache quebra e as regras também mudam de lugar a cada chamada.

Checagem +20 XP de primeiraO eval da triagem tem 60 casos, e 12 são idênticos a exemplos do prompt. O time quer migrar os 40 exemplos para um dataset. O que fazer antes de comparar?

Migrar primeiro e comparar com os 94% atuais, para ter uma linha contínua

Tirar a sobreposição, rodar a linha de base de novo e só então migrar e comparar

Copiar os 12 para o dataset e para o eval, para o seletor ter âncoras

Riscos

• Vazamento para o eval. Um exemplo igual a um caso de eval infla a acurácia. Cheque sobreposição automaticamente a cada mudança.
• Seleção ruim. Similaridade de embedding pode trazer exemplos parecidos na forma e diferentes no sentido (“não consigo acessar” vs. “acesso bloqueado por boleto”). Teste o seletor sozinho: dado um ticket, quais ids ele devolve, e a classe está certa?
• Edição sem controle. Um conjunto editável sem revisão e sem eval vira um caminho direto para produção. Uma linha errada em jsonl classifica milhares de tickets.
• Cache de prompt. Exemplos que mudam a cada pedido saem do prefixo cacheado. Coloque-os depois das instruções fixas.
• k grande demais. k=15 “para garantir” recria o acúmulo. Se o eval não sobe de k=4 para k=8, fique com 4.

Desafio

O time quer mover 40 exemplos fixos para um dataset. O eval atual tem 60 casos, e 12 deles são idênticos a exemplos do prompt. O que fazer antes da migração?

Ver solução

Separar os conjuntos. Os 12 casos idênticos precisam sair do eval (ou dos exemplos), senão o eval mede memorização. Depois disso, rode a linha de base de novo: a acurácia provavelmente vai cair um pouco, e esse é o número real. Só então faça a migração e compare.

Guarde os 12 como candidatos a exemplo, se forem bons, ou como casos de eval, se forem os que você quer medir. Não os dois.

Teste seu entendimento

Checagem +20 XP de primeiraOps quer acrescentar um exemplo de Pix falhou na triagem de ontem. Engenharia só faz deploy na quinta. Com o dataset versionado, quem deve editar, e quando a mudança vale?

Ops propõe o exemplo com motivo e autor; a mudança só vale depois da revisão e do eval

Ops edita o jsonl em produção na hora, porque o ponto é não esperar engenharia

Engenharia continua sendo quem edita, para não perder o controle do prompt

Checagem +20 XP de primeiraO seletor devolveu quatro exemplos de ‘acesso’ para o ticket ‘boleto venceu e o acesso bloqueou’. A classificação saiu ‘acesso’. Qual é a leitura mais útil?

O modelo é fraco nesse tipo de frase; troque o classificador

Falta aumentar k para 12, para algum exemplo de cobrança entrar

O seletor não teve diversidade e o conjunto talvez não tenha o contraste cobrança vs. acesso; corrija os dois

Checagem +20 XP de primeiraAs regras da triagem ficam no system prompt e são cacheadas. Os 4 exemplos escolhidos estão sendo concatenados no início, antes das regras, para ‘o modelo ver os casos primeiro’. O que quebra?

Nada. Exemplos no início melhoram few-shot

O cache de prompt, porque o prefixo deixa de ser estável

O seletor, porque ele assume que os exemplos vêm no fim

Checagem +20 XP de primeiraDepois da migração, alguém sugere k=31 para ‘não perder informação’, já que o dataset tem 31 itens. Qual é a resposta certa?

Aceitar, porque o dataset versionado já resolveu o smell

Recusar. k fica pequeno e fixo; o dataset é que cresce

Aceitar só no eval, para medir o teto, e usar k=4 em produção