---
createdAt: 2025-09-10
updatedAt: 2025-09-10
title: Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)
description: Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)
keywords:
  - RAG
  - Documentação
  - Assistente
  - Fragmentação
  - Embeddings
  - Busca
slugs:
  - blog
  - rag-powered-documentation-assistant
---

# 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](https://intlayer.org/doc/why) 👉 [Boilerplate do código](https://github.com/aymericzip/smart_doc_RAG)

## 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

![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)

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:**

```js
[
  -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:

```txt
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 :

```txt
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](https://intlayer.org/doc/why) 👉 [Confira o modelo de código no GitHub](https://github.com/aymericzip/smart_doc_RAG)

## 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](https://intlayer.org/doc/why) 👉 [Confira o modelo de código no GitHub](https://github.com/aymericzip/smart_doc_RAG)

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