Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)

O que você recebe

Eu construí um assistente de documentação com RAG e o empacotei em um boilerplate que você pode usar imediatamente.

• Vem com uma aplicação pronta para uso (Next.js + OpenAI API)
• Inclui um pipeline RAG funcional (fragmentação, embeddings, similaridade cosseno)
• Fornece uma interface completa de chatbot construída em React
• Todos os componentes da interface são totalmente editáveis com Tailwind CSS
• Registra todas as consultas dos usuários para ajudar a identificar documentação faltante, pontos problemáticos dos usuários e oportunidades de produto

👉 Demo ao vivo 👉 Boilerplate do código

Introdução

Se você já se perdeu na documentação, rolando infinitamente em busca de uma resposta, sabe o quão frustrante isso pode ser. Documentações são úteis, mas são estáticas e a busca nelas muitas vezes parece desajeitada.

É aí que entra o RAG (Geração Aumentada por Recuperação). Em vez de forçar os usuários a vasculhar o texto, podemos combinar recuperação (encontrar as partes certas da documentação) com geração (permitir que um LLM explique de forma natural).

Neste post, vou mostrar como construí um chatbot de documentação alimentado por RAG e como ele não apenas ajuda os usuários a encontrar respostas mais rapidamente, mas também oferece às equipes de produto uma nova forma de entender os pontos problemáticos dos usuários.

Por que usar RAG para documentação?

RAG tornou-se uma abordagem popular por um motivo: é uma das maneiras mais práticas de tornar os grandes modelos de linguagem realmente úteis.

Para documentação, os benefícios são claros:

• Respostas instantâneas: os usuários perguntam em linguagem natural e recebem respostas relevantes.
• Melhor contexto: o modelo vê apenas as seções mais relevantes da documentação, reduzindo alucinações.
• Busca que parece humana: mais como Algolia + FAQ + chatbot, tudo em um.
• Ciclo de feedback: ao armazenar consultas, você descobre com o que os usuários realmente têm dificuldades.

Esse último ponto é crucial. Um sistema RAG não apenas responde perguntas, ele mostra o que as pessoas estão perguntando. Isso significa:

• Você descobre informações faltantes na sua documentação.
• Você vê surgirem pedidos de funcionalidades.
• Você identifica padrões que podem até orientar a estratégia do produto.

Portanto, RAG não é apenas uma ferramenta de suporte. É também um motor de descoberta de produto.

Como funciona o pipeline RAG

Em um nível geral, aqui está a receita que usei:

1. Dividir a documentação em partes Grandes arquivos Markdown são divididos em partes. Dividir permite fornecer como contexto apenas as partes relevantes da documentação.
2. Gerar embeddings Cada parte é transformada em um vetor usando a API de embedding da OpenAI (text-embedding-3-large) ou um banco de dados vetorial (Chroma, Qdrant, Pinecone).
3. Indexação e armazenamento Os embeddings são armazenados em um arquivo JSON simples (para minha demonstração), mas em produção, provavelmente você usaria um banco de dados vetorial.
4. Recuperação (R em RAG) A consulta do usuário é transformada em embedding, a similaridade cosseno é calculada, e os chunks mais relevantes são recuperados.
5. Aumento + Geração (AG em RAG) Esses chunks são injetados no prompt para o ChatGPT, para que o modelo responda com o contexto real da documentação.
6. Registro de consultas para feedback Cada consulta do usuário é armazenada. Isso é ouro para entender pontos problemáticos, documentação faltante ou novas oportunidades.

Passo 1: Lendo a Documentação

O primeiro passo foi simples: eu precisava de uma forma de escanear uma pasta docs/ para todos os arquivos .md. Usando Node.js e glob, eu busquei o conteúdo de cada arquivo Markdown para a memória.

Isso mantém o pipeline flexível: em vez de Markdown, você poderia buscar documentos de um banco de dados, um CMS ou até mesmo uma API.

Passo 2: Dividindo a Documentação em Partes

Por que dividir em partes? Porque os modelos de linguagem têm limites de contexto. Alimentá-los com um livro inteiro de documentação não funciona.

Então, a ideia é quebrar o texto em partes gerenciáveis (por exemplo, 500 tokens cada) com sobreposição (por exemplo, 100 tokens). A sobreposição garante continuidade para que você não perca o significado nas fronteiras das partes.

Exemplo:

• Parte 1 → “…a velha biblioteca que muitos haviam esquecido. Suas prateleiras imponentes estavam cheias de livros…”
• Parte 2 → “…as prateleiras estavam cheias de livros de todos os gêneros imagináveis, cada um sussurrando histórias…”

A sobreposição garante que ambas as partes contenham contexto compartilhado, para que a recuperação permaneça coerente.

Esse equilíbrio (tamanho do chunk vs sobreposição) é fundamental para a eficiência do RAG:

• Muito pequeno → você obtém ruído.
• Muito grande → você estoura o tamanho do contexto.

Passo 3: Gerando Embeddings

Uma vez que os documentos são divididos em chunks, geramos embeddings — vetores de alta dimensão que representam cada chunk.

Usei o modelo text-embedding-3-large da OpenAI, mas você pode usar qualquer modelo moderno de embedding.

Exemplo de embedding:

[  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,  //...+1533 elementos];

Cada vetor é uma impressão digital matemática do texto, permitindo a busca por similaridade.

Passo 4: Indexando e Armazenando Embeddings

Para evitar regenerar embeddings várias vezes, eu os armazenei em embeddings.json.

Em produção, você provavelmente vai querer um banco de dados vetorial como:

• Chroma
• Qdrant
• Pinecone
• FAISS, Weaviate, Milvus, etc.

Bancos de dados vetoriais lidam com indexação, escalabilidade e busca rápida. Mas para meu protótipo, um JSON local funcionou bem.

Passo 5: Recuperação com Similaridade Cosseno

Quando um usuário faz uma pergunta:

1. Gere um embedding para a consulta.
2. Compare-o com todos os embeddings dos documentos usando similaridade cosseno.
3. Mantenha apenas os N chunks mais similares.

A similaridade cosseno mede o ângulo entre dois vetores. Uma correspondência perfeita tem pontuação 1.0.

Dessa forma, o sistema encontra as passagens do documento mais próximas da consulta.

Passo 6: Aumento + Geração

Agora vem a mágica. Pegamos os chunks principais e os injetamos no prompt do sistema para o ChatGPT.

Isso significa que o modelo responde como se esses trechos fizessem parte da conversa.

O resultado: respostas precisas e baseadas na documentação.

Passo 7: Registro das Consultas dos Usuários

Este é o superpoder oculto.

Cada pergunta feita é armazenada. Com o tempo, você constrói um conjunto de dados de:

• Perguntas mais frequentes (ótimo para FAQs)
• Perguntas sem resposta (documentação ausente ou pouco clara)
• Solicitações de funcionalidades disfarçadas de perguntas (“Integra com X?”)
• Casos de uso emergentes que você não havia planejado

Isso transforma seu assistente RAG em uma ferramenta contínua de pesquisa com usuários.

Quanto Custa?

Uma objeção comum ao RAG é o custo. Na prática, é surpreendentemente barato:

• Gerar embeddings para cerca de 200 documentos leva cerca de 5 minutos e custa 1–2 euros.
• O recurso de busca na documentação é 100% gratuito.
• Para consultas, usamos o gpt-4o-latest sem o modo “thinking”. No Intlayer, vemos cerca de 300 consultas de chat por mês, e a fatura da API OpenAI raramente ultrapassa 10 dólares.

Além disso, você pode incluir o custo de hospedagem.

Detalhes da Implementação

Stack:

• Monorepo: workspace pnpm
• Pacote de documentação: Node.js / TypeScript / API OpenAI
• Frontend: Next.js / React / Tailwind CSS
• Backend: rota API Node.js / API OpenAI

O pacote @smart-doc/docs é um pacote TypeScript que lida com o processamento da documentação. Quando um arquivo markdown é adicionado ou modificado, o pacote inclui um script build que reconstrói a lista de documentação em cada idioma, gera embeddings e os armazena em um arquivo embeddings.json.

Para o frontend, usamos uma aplicação Next.js que fornece:

• Renderização de Markdown para HTML
• Uma barra de pesquisa para encontrar documentação relevante
• Uma interface de chatbot para fazer perguntas sobre a documentação

Para realizar uma busca na documentação, a aplicação Next.js inclui uma rota de API que chama uma função do pacote @smart-doc/docs para recuperar fragmentos de documentação que correspondem à consulta. Usando esses fragmentos, podemos retornar uma lista de páginas de documentação relevantes para a busca do usuário.

Para a funcionalidade do chatbot, seguimos o mesmo processo de busca, mas além disso, injetamos os fragmentos de documentação recuperados no prompt enviado ao ChatGPT.

Aqui está um exemplo de um prompt enviado ao ChatGPT:

Prompt do sistema:

Você é um assistente prestativo que pode responder perguntas sobre a documentação do Intlayer.Fragmentos relacionados:-----docName: "getting-started"docChunk: "1/3"docUrl: "https://example.com/docs/pt/getting-started"---# Como começar...-----docName: "another-doc"docChunk: "1/5"docUrl: "https://example.com/docs/pt/another-doc"---# Outro documento...

Consulta do usuário :

Como começar?

Usamos SSE para transmitir a resposta da rota da API.

Como mencionado, usamos gpt-4-turbo sem o modo "thinking". As respostas são relevantes e a latência é baixa. Experimentamos com o gpt-5, mas a latência era muito alta (às vezes até 15 segundos para uma resposta). Mas revisaremos isso no futuro.

👉 Experimente a demonstração aqui 👉 Confira o modelo de código no GitHub

Indo Além

Este projeto é uma implementação mínima. Mas você pode estendê-lo de várias maneiras:

• Servidor MCP → a função de pesquisa de documentação para um servidor MCP para conectar a documentação a qualquer assistente de IA

• Bancos de Dados Vetoriais → escalar para milhões de pedaços de documentação
• LangChain / LlamaIndex → frameworks prontos para pipelines RAG
• Painéis de análise → visualizar consultas dos usuários e pontos problemáticos
• Recuperação multi-fonte → buscar não apenas documentos, mas entradas de banco de dados, posts de blog, tickets, etc.
• Melhoria no prompting → reclassificação, filtragem e busca híbrida (palavra-chave + semântica)

Limitações que Encontramos

• A segmentação e sobreposição são empíricas. O equilíbrio correto (tamanho do pedaço, porcentagem de sobreposição, número de pedaços recuperados) requer iteração e testes.
• Embeddings não são regenerados automaticamente quando os documentos mudam. Nosso sistema redefine os embeddings para um arquivo somente se o número de pedaços for diferente do que está armazenado.
• Neste protótipo, os embeddings são armazenados em JSON. Isso funciona para demonstrações, mas polui o Git. Em produção, um banco de dados ou um armazenamento vetorial dedicado é melhor.

Por Que Isso Importa Além da Documentação

A parte interessante não é apenas o chatbot. É o ciclo de feedback.

Com RAG, você não apenas responde:

• Você aprende o que confunde os usuários.
• Você descobre quais recursos eles esperam.
• Você adapta sua estratégia de produto com base em consultas reais.

Exemplo:

Imagine lançar um novo recurso e ver instantaneamente:

• 50% das perguntas são sobre o mesmo passo de configuração pouco claro
• Usuários pedem repetidamente por uma integração que você ainda não suporta
• Pessoas buscam termos que revelam um novo caso de uso

Isso é inteligência de produto diretamente dos seus usuários.

Conclusão

RAG é uma das formas mais simples e poderosas de tornar os LLMs práticos. Ao combinar recuperação + geração, você pode transformar documentos estáticos em um assistente inteligente e, ao mesmo tempo, obter um fluxo contínuo de insights sobre o produto.

Para mim, este projeto mostrou que RAG não é apenas um truque técnico. É uma forma de transformar a documentação em:

• um sistema de suporte interativo
• um canal de feedback
• uma ferramenta de estratégia de produto

👉 Experimente a demonstração aqui 👉 Confira o modelo de código no GitHub

E se você também estiver experimentando com RAG, adoraria saber como está usando.