Como Criar Bases de Documentação Inteligentes para Seu AI Coding Assistant
Construindo Bases de Documentação Inteligentes para Seu Assistente de Código com IA
Alimentar uma IA com documentação técnica bruta costuma ser um erro comum. Em vez de aprender com o conteúdo relevante, o modelo se perde em meio a páginas de navegação, políticas legais e listas de referências. Na NameOcean, desenvolvemos uma abordagem prática para preparar essa documentação de forma mais eficiente.
Nem Toda Página Tem Valor para a IA
Muitos sites de documentação contêm páginas que existem apenas por estrutura ou exigências legais. Índices, políticas de privacidade, changelogs e listas de APIs ajudam humanos a navegar, mas atrapalham quando o objetivo é ensinar algo ao modelo.
Quando você insere tudo sem filtro em um banco vetorial, a IA precisa processar material que não agrega conhecimento. O resultado são buscas mais lentas, embeddings inchados e respostas que citam páginas irrelevantes.
Uma Estratégia de Classificação em Dois Passos
A solução mais eficiente combina filtros automáticos com classificação seletiva por LLM. É como triar documentos antes de armazená-los.
Primeiro Passo: Filtro Rápido por Regras
Comece identificando padrões em URLs e estrutura básica. Muitas páginas problemáticas podem ser descartadas automaticamente:
- Páginas legais: busque padrões como
/legal/,/privacy,/terms - Hubs de navegação: páginas com menos de 200 palavras cheias de links
- Changelogs e referências: geralmente seguem padrões previsíveis de URL
Esse passo roda localmente, é gratuito e resolve entre 40% e 60% dos casos.
Segundo Passo: Classificação com LLM Local
Para as páginas restantes, envie apenas o essencial para um modelo local: URL, título, os primeiros 200 palavras e a hierarquia de headings. Peça para classificar segundo a estrutura Diátaxis:
- Conceptual: explicações e contexto
- Tutorial: guias passo a passo
- How-to: tarefas específicas
- Examples: amostras de código
- Structural: navegação, referências e conteúdo legal
O LLM só processa o que as regras não conseguiram filtrar.
Gerando Embeddings com Inteligência
Depois de remover o ruído, o próximo passo é gerar embeddings. Páginas longas geralmente ultrapassam limites de tokens, então é melhor dividir pelo markdown — separando por headings — e calcular a média dos vetores resultantes.
Use um modelo local de sentence transformer. Evita custos de API e, para documentação técnica, o desempenho costuma ser suficiente.
Criando um Grafo de Conhecimento Híbrido
O verdadeiro ganho aparece quando você combina dois tipos de conexão:
- Links explícitos: hyperlinks escritos pelos autores da documentação
- Arestas semânticas: conexões baseadas em similaridade de embeddings (acima de 0.75 de similaridade)
Armazene tudo como arestas direcionadas. Limite o número de vizinhos por página (20 é um bom número) e exclua páginas de navegação e legais do grafo semântico.
O Resultado Final: Um Banco SQLite Portátil
Todo o processo gera um único arquivo SQLite contendo:
- Conteúdo limpo em markdown
- Classificações das páginas
- Embeddings
- Arestas do grafo
- Metadados e URLs
Esse formato é portátil, permite consultas em SQL e facilita filtros como "mostrar apenas tutoriais sobre autenticação". Agentes de IA conseguem navegar pelo grafo e encontrar conexões relevantes sem depender de APIs externas.
Fluxo Prático
O pipeline completo inclui:
- Fazer o crawl do site respeitando robots.txt
- Converter HTML em markdown limpo
- Classificar páginas com regras e LLM
- Gerar embeddings locais dividindo por headings
- Construir o grafo híbrido
- Salvar tudo em SQLite
Com isso, seu assistente de código trabalha com uma base estruturada e relevante, em vez de um monte de páginas soltas.