Construindo um dataset de treinamento para Drupal: um guia prático

A maioria dos artigos sobre construção de datasets de instruções para fine-tuning de LLMs ou para RAG assume que você já tem material-fonte limpo e estruturado. Projetos reais raramente têm isso — e é exatamente nessa lacuna que a engenharia interessante acontece. Este artigo percorre o pipeline que construímos para transformar conteúdo técnico disperso do Drupal em um dataset de instruções estruturado e verificado, e compartilha os números de uma execução real de produção.

Por quê: o problema real que isso resolve

O Drupal 7 está fora de suporte oficial há um tempo, mas ainda roda em uma grande parcela de sites em produção. Migrar esses sites para a linha moderna Drupal 9/10/11 é um trabalho técnico lento e caro: a superfície da API mudou substancialmente, e boa parte do que um engenheiro de migração precisa está espalhada em documentação de referência que não é escrita como um guia, e em anos de perguntas e respostas da comunidade de qualidade desigual, às vezes referentes à versão errada. O objetivo deste dataset não é engenharia de dataset pelo próprio bem: é construir a base de conhecimento que permite a um sistema de IA realmente ajudar a ler código legado de Drupal 7, explicar o que ele faz, e propor o equivalente moderno — o gargalo específico e caro na maioria das migrações de Drupal.

Por que o Drupal especificamente é um alvo difícil e que vale a pena

Duas propriedades do Drupal tornam esse exercício exigente e útil ao mesmo tempo:

1. Fragmentação de versões. O Drupal 7 e a linha moderna Drupal 9/10/11 são parecidas o suficiente no nome para serem confundidas, e diferentes o suficiente na superfície de API para que conteúdo escrito para uma precise de tratamento cuidadoso e consciente da versão antes de ser aplicado à outra. Acertar isso é uma condição necessária para que o dataset sirva para trabalho de migração.
2. Documentação de referência não é Q&A. A documentação oficial da API descreve classes, métodos e hooks — ela não vem pronta como "um desenvolvedor pergunta X, aqui está a resposta". O conteúdo de perguntas e respostas da comunidade se aproxima mais de como os desenvolvedores realmente formulam seus problemas. Transformar as duas em pares de instrução consistentes é a transformação central que esse pipeline realiza.

O pipeline

Em linhas gerais, o pipeline tem três fases por tipo de fonte:

1. Extração — páginas/threads brutas são coletadas, marcadas por versão do Drupal, e o ruído óbvio é removido (navegação, listas de links entre versões, contadores de referência das páginas de documentação da API). Essa limpeza, por si só, melhorou de forma significativa a qualidade das etapas seguintes assim que medimos o quanto ela importava.
2. Geração — um modelo local, pequeno e rápido, transforma cada fonte já limpa em um trio candidato (instruction, context, response).
3. Verificação — um segundo modelo, mais forte, checa o candidato contra a fonte e o contrato de geração, detectando qualquer coisa que invente conteúdo, não corresponda à versão de Drupal declarada, ou viole o esquema de saída. Se falhar, o próximo modelo da cadeia regenera do zero. Só o que sobrevive à verificação é escrito no dataset.

Essa estrutura de gerar-e-verificar (uma cascata, com seu próprio artigo) foi o que permitiu que um modelo pequeno e barato carregasse a maior parte do trabalho sem sacrificar a confiança em um dataset onde o que importa, para a tarefa final, é a correção — não só a fluência.

Transformando os logs de rejeição em um roteiro

Um pipeline ingênuo trata "o modelo devolveu um JSON válido" como sucesso. Fomos além: cada rejeição foi registrada e categorizada, transformando a etapa de verificação em uma ferramenta de diagnóstico, não apenas em um filtro. Ao longo da vida do projeto, isso gerou 1.251 rejeições categorizadas de primeira rodada, e tê-las detalhadas por causa foi o que tornou possível uma melhoria sistemática:

Motivo da rejeição — Percentual

• Resposta vaga ou incompleta: 29,9%
• Conteúdo inventado que não está na fonte: 23,3%
• JSON malformado / formato de saída incorreto: 19,3%
• Fora do tema ou símbolo errado: 13,6%
• Versão de Drupal incorreta: 7,0%
• Falta um campo de explicação obrigatório: 3,9%
• Resposta vazia: 2,7%

Cada categoria recebeu uma correção específica em vez de um ajuste genérico de prompt "para se esforçar mais", e cada correção reduziu sua categoria de forma mensurável.

Fidelidade de versão: a correção com o impacto de volume mais claro

Uma das lições mais contraintuitivas veio de questionar uma salvaguarda existente em vez de adicionar uma nova. Uma versão inicial do pipeline usava um filtro prévio rígido que descartava qualquer pergunta sobre Drupal que não declarasse explicitamente sua versão, sob a teoria de que uma marcação de versão ambígua contaminaria o dataset. Ao observar de perto, a maioria dos desenvolvedores simplesmente não escreve "Drupal 7" quando isso é óbvio pelo contexto — o filtro estava descartando bom conteúdo aos montes enquanto mal tocava o problema real: conteúdo que contradiz ativamente a versão declarada.

Substituir "descartar qualquer coisa ambígua" por "descartar apenas contradições genuínas, verificadas contra o conteúdo técnico real" gerou duas melhorias separadas, que vale a pena distinguir, no pipeline de perguntas e respostas da comunidade:

• O volume total de saída aceita aproximadamente triplicou execução após execução, porque muito menos candidatos bons estavam sendo descartados antes mesmo de chegar à geração.
• A taxa de aceitação de primeira rodada do próprio modelo de geração subiu de 0% para 26,4% na janela de medição equivalente, porque os candidatos que agora chegavam eram, em média, menos ambíguos e mais fáceis de acertar.

São duas métricas diferentes contando duas partes diferentes da mesma história — uma é sobre quanto bom material-fonte chega ao pipeline, a outra é sobre quão bem o modelo se sai com o que chega até ele — e vale a pena mantê-las separadas em vez de tratar um número como se fosse o outro.

Resultados de uma execução real

Depois das melhorias descritas acima, uma execução de 7 horas sem supervisão produziu:

• 176 pares verificados do pipeline de documentação de referência, com uma taxa de aceitação de primeira rodada de 46,0% para o modelo de geração pequeno — igualando a melhor taxa já registrada historicamente para este pipeline.
• 53 pares verificados do pipeline de perguntas e respostas da comunidade, com a taxa de primeira rodada de 26,4% mencionada acima.

Os dois pipelines continuam melhorando, e um pipeline bem instrumentado transforma "o modelo errou" de um beco sem saída na próxima coisa concreta a corrigir — com o objetivo final, sempre, de um dataset preciso e completo o suficiente para de fato acelerar o trabalho real de migração do Drupal 7 para o Drupal 9/10/11, não um número de benchmark por si só.

Conclusões

• Categorize as rejeições antes de tentar corrigi-las — um detalhamento preciso transforma "às vezes falha" em uma lista priorizada e gerenciável.
• Questione suas salvaguardas existentes, não só suas ideias novas. Nossa maior vitória de rendimento veio de afrouxar um filtro excessivamente cauteloso, não de apertar um.
• Mantenha "quanto material chega ao seu modelo" e "quão bem seu modelo se sai com o que chega" como números separados e relatados separadamente. Misturá-los faz uma melhoria real soar como uma melhoria diferente e maior do que ela é.