Como Criar Bases de Documentação Inteligentes para Seu AI Coding Assistant
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.
Tem uma ideia? Encontre o domínio perfeito para ela
O nosso gerador de nomes de domínio com IA sugere nomes disponíveis em centenas de extensões. SSL, DNS e privacidade Whois gratuitos incluídos.
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.
Tem uma ideia? Encontre o domínio perfeito para ela
O nosso gerador de nomes de domínio com IA sugere nomes disponíveis em centenas de extensões. SSL, DNS e privacidade Whois gratuitos incluídos.