O que aprendemos rodando o fine-tune de documentação de código legado

Em agosto publiquei o projeto Celx: um fine-tune de um modelo pequeno (LoRA/QLoRA sobre uma base de ~1-2B parâmetros) treinado para documentar código legado em PHP, JavaScript e SQL — com uma regra rígida de não inventar regra de negócio que o código não sustenta. O treino usou cerca de 300 mil exemplos, combinando CodeXGLUE Code-to-Text e Spider, e o repositório inteiro roda no Google Colab.

Passado um tempo desde a publicação, este post é o retorno prático: o que esse processo confirmou, o que expôs de fragilidade e o que muda daqui para frente.

O que a disciplina de "não inventar" realmente exige

O contrato de saída do modelo — objetivo, parâmetros, retorno, funcionamento, regras de negócio identificadas e pontos não determinados — parece simples no papel. Na prática, a seção mais difícil de calibrar é justamente "pontos não determinados". Um modelo treinado só para prever o próximo token tem um viés natural para completar lacunas com algo plausível, porque isso é literalmente o que ele foi otimizado para fazer no pré-treino. Ensinar via fine-tuning a *não* completar — e sinalizar a lacuna em vez de preencher — é uma correção de comportamento, não só um ajuste de formato.

Dado público não é dado de negócio

CodeXGLUE e Spider ensinam o modelo a mapear estrutura de código para linguagem natural, mas nenhum dos dois carrega o vocabulário nem os padrões de nomenclatura que aparecem em sistemas legados reais de empresas brasileiras — variáveis em português misturado com inglês, convenções de banco específicas, regras de negócio codificadas em nomes de função obscuros. Isso já estava previsto desde a publicação original: dado público resolve o mapeamento geral código-texto, mas curadoria com exemplos reais do domínio continua sendo o gargalo de qualidade real, não o volume total de exemplos.

PHP e JavaScript se comportam diferente sob o mesmo contrato

Um ponto que não estava óbvio antes de rodar o pipeline por completo: o mesmo template de saída funciona bem melhor para PHP orientado a procedimento (funções com parâmetros e retorno claros) do que para JavaScript assíncrono ou baseado em callbacks, onde "o que a função retorna" às vezes é uma promise que só resolve dependendo de estado externo. A seção de "funcionamento" precisa de mais contexto de fluxo assíncrono do que o formato original previa — é um ajuste de template, não de dado.

Rodar no Colab democratiza, mas tem limite

Ter o pipeline inteiro reproduzível no Google Colab (o notebook 04_pipeline_completo.ipynb cobre dados, SFT, treino, avaliação e exportação do adapter) foi a decisão certa para permitir que qualquer pessoa reproduza o experimento sem infraestrutura própria. O limite aparece quando alguém quer treinar com dataset de curadoria própria muito maior — aí a GPU gratuita do Colab vira gargalo, e a recomendação prática é migrar para uma instância dedicada só nesse ponto, não desde o início.

O que muda no roadmap

Os próximos passos já estavam esboçados na publicação original — ampliar curadoria em português, refinar o modo bilíngue, medir qualidade com rubrica humana em vez de só métrica automática, encaixar o modelo no fluxo do dia a dia via CLI ou plugin de editor. Depois de rodar o processo, a prioridade ficou mais clara: rubrica humana vem antes de qualquer expansão de dado, porque sem ela não dá para saber se mais dado está de fato melhorando a fidelidade ao código ou só mudando o estilo da resposta.

O projeto continua aberto e o repositório é o lugar certo para acompanhar essas mudanças de perto: github.com/wolfxweb/Celx. Se você já rodou o pipeline com seu próprio código legado, quero muito ouvir o que apareceu de diferente do que descrevi aqui.