Diagrama de arquitetura RAG: como as peças de uma aplicação de geração aumentada por recuperação se encaixam

A maioria dos diagramas de arquitetura RAG tem três caixas: um usuário, um banco de dados vetorial e um LLM. Essa imagem explica a ideia em uma reunião. Ela não ajuda ninguém a operar o sistema, porque faltam as decisões que definem a qualidade e a segurança das respostas: como os documentos são divididos em chunks, qual modelo de embeddings é usado, quem pode ver cada chunk, como os resultados são ordenados e como alguém sabe que as respostas estão boas.

Este guia desenha o quadro completo de uma aplicação de geração aumentada por recuperação como dois caminhos em volta de modelos e armazenamentos compartilhados e depois mostra o que rotular e os erros mais comuns.

Dois caminhos, não um

O termo vem de Lewis et al. (2020), que combinaram um modelo de linguagem com um índice vetorial denso da Wikipédia, consultado por um recuperador no momento da geração. A maioria das aplicações RAG em produção mantém a ideia sem treinar as partes juntas: recuperar passagens relevantes, colocá-las no prompt e pedir ao modelo que responda com base nelas.

Isso dá a toda aplicação RAG dois caminhos:

• A ingestão roda continuamente em segundo plano. Ela transforma documentos em chunks, vetores e metadados.
• A consulta roda uma vez por pergunta. Ela transforma uma pergunta em uma resposta com fontes.

Os dois se encontram nas partes compartilhadas: o modelo de embeddings, que precisa estar na mesma versão nos dois caminhos, o índice vetorial e o armazenamento de metadados. Um diagrama que mostra só o caminho de consulta esconde metade do sistema e a maioria dos bugs.

O caminho de ingestão

1. Fontes e detecção de mudanças. Conectores, webhooks ou um crawler percebem documentos novos, alterados e excluídos e colocam jobs em uma fila. Exclusões e mudanças de permissão também são jobs.
2. Parsing. Extraia o texto preservando a estrutura: títulos, listas, tabelas e metadados como título, URL, dono, última atualização e lista de controle de acesso.
3. Chunking. Divida primeiro pela estrutura do documento e depois por tamanho. O tamanho dos chunks e a sobreposição são parâmetros que você ajusta com as suas próprias perguntas, não números universais. Guarde em cada chunk o caminho de títulos, para que um parágrafo faça sentido sozinho.
4. Embeddings. Chame um único modelo de embeddings e fixe a versão dele. Guarde o nome e a versão do modelo com cada vetor. Vetores de modelos diferentes não são comparáveis, então trocar de modelo significa recalcular os embeddings do corpus inteiro.
5. Indexação. Faça upsert de cada chunk com o vetor, o ID do documento, o número do chunk, a versão e as tags de acesso. Se você planeja busca híbrida, mantenha um índice de palavras-chave ao lado do índice vetorial.
6. Atualização e exclusão. Torne os upserts idempotentes, apague os chunks de documentos removidos e acompanhe o frescor: quanto tempo uma mudança na fonte leva para chegar ao índice.

O caminho de consulta

1. Identifique o usuário. Resolva os grupos do usuário antes de a recuperação começar.
2. Reescreva a pergunta (opcional). Uma pergunta de acompanhamento como "e para os terceirizados?" precisa virar, com a ajuda da conversa, uma consulta independente.
3. Recupere. A busca vetorial encontra passagens com significado parecido; a busca por palavras-chave encontra termos exatos, como códigos de erro e nomes de produtos. A busca híbrida roda as duas e combina as listas, muitas vezes com reciprocal rank fusion, que dá a cada documento a pontuação 1/(k + posição) somada nas listas. O artigo original do RRF fixou k em 60.
4. Filtre por permissão dentro da consulta. Passe os grupos do usuário como filtro sobre as tags de acesso, para que os chunks que ele não pode ver nunca cheguem ao prompt. Verifique como o seu armazenamento aplica filtros. A documentação do pgvector avisa que, com índices aproximados, o filtro roda depois da varredura do índice: com o ef_search padrão do HNSW, 40, um filtro que corresponde a 10% das linhas devolve em média cerca de 4 linhas. Varreduras iterativas, índices parciais ou particionamento resolvem isso.
5. Reordene. Recupere com folga, por exemplo 50 candidatos, e deixe um modelo de reranqueamento pontuá-los em relação à pergunta. Fique com os melhores, por exemplo 8.
6. Monte o prompt. Instruções, os chunks escolhidos com IDs e títulos e a pergunta, dentro de um orçamento de tokens. Peça citações por ID de chunk.
7. Gere e cite. Chame o LLM, transmita a resposta por streaming e transforme os IDs de chunk em links que o usuário possa conferir.

Em volta dos dois caminhos

• Trate o texto recuperado como entrada não confiável. Um documento pode conter instruções voltadas ao modelo. A OWASP lista isso como injeção de prompt indireta. Mantenha as ferramentas e os dados que o modelo alcança tão restritos quanto o acesso do próprio usuário.
• Rastreie cada requisição. Registre a consulta reescrita, os IDs dos chunks recuperados e reordenados com as pontuações, a versão do prompt, as versões dos modelos e a latência de cada etapa.
• Avalie com um conjunto fixo de perguntas. Rode esse conjunto a cada mudança em chunking, modelos, recuperação ou prompt. O artigo do RAGAS aponta três dimensões úteis: fidelidade ao contexto recuperado, relevância da resposta e relevância do contexto. Confira também se a fonte esperada aparece entre os primeiros resultados.
• Use cache com cuidado. Fazer cache dos embeddings das consultas costuma ser seguro. Fazer cache das respostas só é seguro por conjunto de permissões.

O diagrama

Como ler:

• À esquerda, a ingestão. Mudanças nas fontes viram jobs em uma fila. O worker de ingestão faz o parsing e o chunking de cada documento, chama o modelo de embeddings, faz upsert de chunks e vetores com tags de acesso no índice vetorial e grava os metadados dos documentos no Postgres.
• No centro, modelos e armazenamentos compartilhados. O mesmo modelo de embeddings, com versão fixada, atende os dois caminhos. O LLM também fica aqui e só é chamado pelo caminho de consulta.
• À direita, a consulta. A API de RAG busca os grupos do usuário, calcula o embedding da pergunta, roda a busca híbrida com o filtro de permissões, manda 50 candidatos para o reranker e chama o LLM com os 8 melhores chunks.
• No canto inferior esquerdo. Um exemplo de orçamento de latência por etapa, para que uma resposta lenta possa ser rastreada até a etapa que estourou o orçamento.

O que rotular

• As versões dos modelos em cada nó de modelo, inclusive o modelo de embeddings.
• Os parâmetros de chunking, no worker de ingestão ou em uma nota.
• Onde as permissões são aplicadas, na conexão de recuperação, não em uma nota de rodapé.
• Quantos resultados passam entre as etapas: 50 recuperados, 8 no prompt.
• As metas de frescor e latência: em quanto tempo uma mudança na fonte fica pesquisável e o orçamento de cada etapa da consulta.

Erros comuns

• Uma caixa chamada "IA". Recuperação, reranqueamento e geração falham de jeitos diferentes e precisam de caixas separadas.
• Sem caminho de ingestão. Respostas desatualizadas ou ausentes costumam começar ali.
• Sem permissões. Se o índice tem documentos para públicos diferentes, um diagrama sem tags de acesso descreve um vazamento de dados.
• Sem avaliação. Sem um conjunto de perguntas, toda mudança no prompt ou no tamanho dos chunks é um palpite.
• Versões de embeddings misturadas. Recalcular com um modelo novo os embeddings de metade do corpus quebra a busca sem fazer barulho.

Quando RAG não é a resposta

• A resposta está em dados estruturados. Consulte o banco de dados ou uma API em vez de calcular embeddings de linhas de tabela.
• A tarefa precisa de um documento inteiro. Resumir um contrato funciona melhor com o contrato completo no prompt, se couber.
• O corpus é minúsculo. Algumas páginas podem ir direto para o prompt.
• Você precisa de outro comportamento, não de mais conhecimento. Isso é um problema de prompt ou de fine-tuning.

Para ingestão orientada a eventos com filas, veja o guia do diagrama de arquitetura orientada a eventos.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Adicione dois nós Moldura do pack Básico: "Ingestion path" à esquerda e "Query path" à direita.
3. Na moldura de ingestão, adicione um Repositório de objetos do pack Dados para os documentos de origem, uma Fila do pack Dados para os jobs de ingestão e um Contêiner do pack Modelo C4 para o worker de ingestão.
4. No centro, adicione um Modelo do pack ML para o modelo de embeddings, um Índice vetorial do pack ML, um Postgres do pack Dados para metadados e permissões e um segundo Modelo para o LLM.
5. Na moldura de consulta, adicione uma Pessoa do pack Modelo C4 para o usuário, um Contêiner para a API de RAG e um Modelo do pack ML para o reranker.
6. Rotule cada conexão com o que passa por ela, incluindo "top 50" e "top 8", e coloque o orçamento de latência em um bloco Markdown do pack Básico.

O exemplo usa 13 nós de diagrama e fica dentro do plano Free. Se você trabalha com um agente de IA, ele pode desenhar uma primeira versão para você via MCP a partir de uma descrição dos dois caminhos; veja como criar diagramas de arquitetura com agentes de IA. Para o método geral, veja como desenhar um diagrama de arquitetura de software.

Perguntas frequentes

Preciso de um banco de dados vetorial dedicado para RAG? Não. Uma extensão vetorial em um banco que você já opera, como o pgvector no PostgreSQL, ou um mecanismo de busca com suporte a vetores dá conta de muitas aplicações. Escolha pelo tamanho do corpus, pelas necessidades de filtragem e pelo que o seu time opera bem.

Qual tamanho de chunk devo usar? Não existe um número universal. Divida por títulos e parágrafos e depois compare alguns tamanhos e sobreposições com o seu próprio conjunto de perguntas.

Onde devem ficar as verificações de permissão? Na ingestão, copiando a lista de acesso de cada documento para os chunks dele, e na recuperação, filtrando por ela. Nunca confie no prompt para esconder conteúdo.

Como avalio uma aplicação RAG? Mantenha um conjunto fixo de perguntas reais com as fontes esperadas. Meça se a recuperação encontra essas fontes e se as respostas são fiéis ao contexto recuperado e relevantes para a pergunta.

O LLM deve chamar ferramentas em vez de usar RAG? Para dados ao vivo ou estruturados, sim: uma ferramenta que consulta o sistema de registro é melhor que um índice de cópias. Muitas aplicações usam as duas coisas.

Comece grátis — um assento, sem cartão de crédito.