Query2Diagram: Answering Developer Queries with UML Diagrams

1. Declaração do Problema

A documentação de software, particularmente os diagramas UML, está frequentemente desatualizada ou inexistente, criando uma barreira significativa para a compreensão de bases de código complexas. Embora ferramentas automatizadas de engenharia reversa (ER) possam gerar diagramas UML a partir do código, elas tipicamente produzem despejos estruturais exaustivos contendo detalhes avassaladores que prejudicam a compreensão. Essas ferramentas carecem de contexto semântico e intenção do desenvolvedor, falhando em filtrar componentes relevantes.

Por outro lado, embora os Modelos de Linguagem de Grande Escala (LLMs) se destaquem na compreensão de código e linguagem natural, sua aplicação à geração de diagramas orientada a consultas (criação de diagramas que respondem a perguntas específicas sobre o código) permanece inexplorada. As abordagens existentes de LLMs ou geram diagramas completos a partir do código (ignorando a intenção do usuário) ou derivam diagramas de especificações textuais (não de código). Existe uma lacuna crítica na geração de visualizações UML focadas e contextuais diretamente a partir do código-fonte com base em consultas em linguagem natural.

2. Metodologia

Os autores propõem um pipeline inovador chamado Query2Diagram, que gera diagramas UML em resposta a consultas específicas de desenvolvedores. A metodologia consiste em três etapas principais:

A. Curadoria de Dados

• Seleção de Código: A equipe coletou os 150 repositórios de código aberto mais estrelados (licenças MIT/Apache) cobrindo 12 linguagens (C, C++, Java, Python, JS, TS, Rust, etc.). Eles filtraram arquivos entre 3K–15K caracteres para garantir complexidade gerenciável.
• Síntese de Consultas: Como não há benchmark público que vincule consultas de código a diagramas UML, eles usaram dois LLMs abertos (DeepSeek-R1 e QwQ) para gerar perguntas em linguagem natural focadas em arquitetura, uso de API e padrões de design.
• Construção de Diagramas (Verdade Terrena):
  • Diagramas iniciais foram gerados usando Claude 3.5 Sonnet para garantir alta validade JSON.
  • O formato de saída é um grafo JSON estruturado contendo listas de nós, arestas e pacotes.
  • Tipos de Nós: Classe, método, campo, função, variável e entidade abstrata.
  • Correção: Todos os grafos gerados foram revisados e corrigidos manualmente para reparar defeitos (por exemplo, nós alucinados, erros de sintaxe, conexões ausentes). Grafos irreparáveis foram descartados.
  • Resultado: Um conjunto de dados curado de triplas código-consulta-diagrama (264 para treinamento, 36 para validação).

B. Adaptação do Modelo (Ajuste Fino)

• Modelo Base: Qwen2.5-Coder-14B-Instruct foi selecionado por seu forte desempenho zero-shot em codificação e compatibilidade com treinamento em GPU única (NVIDIA Tesla V100).
• Técnica: QLoRA (Adaptação de Baixo Rank Quantizada) foi usada para ajustar o modelo.
  • Os pesos foram quantizados para 4 bits (NF4).
  • Adaptadores de precisão total foram treinados usando perda de entropia cruzada supervisionada.
  • Otimizações incluíram Unsloth, regularização L2, dropout e acumulação de gradiente.
• Objetivo de Treinamento: O modelo aprende a mapear um par (arquivo de código, consulta em linguagem natural) para uma representação JSON estruturada de um diagrama UML.

C. Inferência e Geração

• Restrição: Para garantir validade sintática, o modelo usa Outlines para impor um esquema JSON como uma gramática restrita durante a decodificação.
• Saída: O modelo gera três versões do diagrama (Mínima, Média, Completa) e um resumo de texto, permitindo que os usuários escolham o nível de abstração.

3. Contribuições Principais

1. Formulação da Tarefa: Introdução da nova tarefa de geração de UML orientada a consultas, onde os diagramas não são exaustivos, mas filtrados e abstraídos com base em necessidades específicas de informação do desenvolvedor.
2. Método de Geração Estruturada: Desenvolvimento de um pipeline prático usando LLMs ajustados para saída de representações intermediárias baseadas em JSON (nós, arestas, pacotes) em vez de marcação bruta (PlantUML/Mermaid), reduzindo significativamente erros de sintaxe.
3. Framework de Avaliação Abrangente: Criação de uma estratégia de dupla avaliação combinando:
   • Análise Automática de Defeitos: Varredura para 19 padrões de defeitos (estilísticos, estruturais, não renderizáveis).
   • Avaliação Humana de Relevância: Classificação de nós em quatro categorias: Suficiência (essencial), Completude (útil), Alucinação (inventada) e Verbosidade (irrelevante).
4. Evidência Empírica: Demonstração de que o ajuste fino em uma quantidade modesta de dados corrigidos manualmente produz melhorias dramáticas sobre LLMs base e treinamento apenas sintético.

4. Resultados

O estudo avaliou cinco modelos: GPT-4o, Claude 3.5 Sonnet, Qwen2.5-Coder-14B base, e duas versões ajustadas (treinadas em dados sintéticos vs. dados corrigidos manualmente).

• Redução de Defeitos: O modelo ajustado treinado em dados corrigidos manualmente (Qwen2.5-Coder-14B SFT: Fixed Claude Synth) alcançou as menores taxas de defeitos, superando GPT-4o e Claude 3.5 Sonnet. Ele eliminou completamente defeitos "inaceitáveis".
• Relevância Semântica (Pontuações F1):
  • Modelos Base: Mostraram um trade-off. GPT-4o/Claude tiveram alta precisão (poucas alucinações) mas baixa recall (perderam informações relevantes). Qwen base teve alta recall mas baixa precisão (muitas alucinações/verbosidade).
  • Modelo Ajustado: Fechou com sucesso essa lacuna. Alcançou as maiores pontuações F1 (Micro: 0,808, Macro: 0,823) ao reter a recall do Qwen base enquanto suprimia drasticamente alucinações e verbosidade.
• Métricas Difíceis: Mesmo ao avaliar apenas nós de "Suficiência" (elementos indispensáveis), o modelo ajustado manteve alta precisão e recall, provando que gera diagramas estruturalmente sólidos e semanticamente fiéis.

5. Significado e Trabalho Futuro

• Viabilidade de Documentação Sob Demanda: O artigo prova que LLMs podem gerar documentação escalável e contextual que se adapta a consultas de desenvolvedores, indo além de diagramas estáticos e desatualizados.
• Eficiência de Dados: Os resultados destacam que conjuntos de dados de alta qualidade e pequena escala (corrigidos manualmente) são mais eficazes para tarefas especializadas do que dados sintéticos massivos e não curados.
• Direções Futuras:
  • Estender da análise de arquivo único para mapeamento de dependências multi-arquivo/abrangente do projeto.
  • Desenvolver interfaces conversacionais para refinamento iterativo (por exemplo, "zoom no tratamento de erros").
  • Expandir para outros tipos de diagramas (Sequência, Atividade, Máquina de Estados).
  • Integrar com IDEs para documentação em tempo real e sem esforço.

Em conclusão, Query2Diagram estabelece um novo paradigma para ferramentas de engenharia de software, demonstrando que combinar LLMs com restrições de saída estruturada e ajuste fino direcionado pode efetivamente preencher a lacuna entre a complexidade do código e a compreensão do desenvolvedor.