# Playbook: RAG em Produção — O Checklist de 15 Itens Antes de Ir pro Ar Colar documentos num vector store não é RAG em produção — é um protótipo esperando para falhar em público. Este playbook cobre os 15 itens concretos e testáveis que separam um pipeline RAG confiável de um que alucina, vaza PII e estoura orçamento sem que ninguém perceba. A verdade incômoda: ~80% das alucinações são falha de recuperação, não do modelo. - URL: https://fernando.moretes.com/studies/playbook-rag-em-producao-checklist - Markdown: https://fernando.moretes.com/studies/playbook-rag-em-producao-checklist/study.md?lang=pt - Type: Playbook - Domain: IA / RAG - Date: 2025-09-15 - Tags: RAG, GenAI, AWS Bedrock, vector search, production, evaluation, guardrails, OpenSearch - Reading time: 9 min --- Todo mundo consegue fazer um demo de RAG funcionar em 30 minutos. O problema é que 90% desses demos nunca deveriam ir a produção no estado em que estão — chunking arbitrário, sem avaliação, sem controle de custo, sem guardrails. Este playbook é o checklist que eu aplico antes de assinar qualquer deploy de RAG em ambiente real. ## TL;DR — O que você vai conseguir decidir depois deste playbook - Identificar os 5 grupos de risco em qualquer pipeline RAG: ingestão, recuperação, geração, avaliação e guardrails/custo - Aplicar os 15 itens do checklist de forma concreta e testável antes de cada deploy - Decidir entre busca só-semântica e busca híbrida+reranking com base em recall, precisão, custo e latência reais - Parar de trocar de modelo quando o problema real é a qualidade da recuperação - Medir custo por consulta desde o dia zero — não depois que a fatura chegar ## O modelo mental que desbloqueia tudo: RAG é um pipeline de dados, não uma feature de IA A maioria dos times trata RAG como se fosse uma chamada de API com um passo extra. Não é. RAG é um pipeline de dados com pelo menos seis estágios sequenciais — e cada estágio tem seus próprios modos de falha silenciosa. Quando o sistema responde errado, a culpa instintiva vai para o LLM. Na prática, o LLM é frequentemente a parte mais confiável do sistema. Pense assim: o LLM só pode responder com base no que você passou no contexto. Se os chunks recuperados estão errados, incompletos, duplicados ou fora de ordem, o modelo vai fazer o melhor que pode com lixo — e isso parece alucinação, mas é garbage-in, garbage-out clássico. A estimativa que circula na comunidade, e que bate com o que eu vejo em campo, é que cerca de 80% dos casos de resposta incorreta em RAG têm origem na fase de recuperação: chunk errado, threshold de similaridade mal calibrado, ausência de filtro por tenant, ou simplesmente embedding que não captura o domínio. O modelo mental correto é: **você está construindo um sistema de busca com um gerador de linguagem natural na ponta**. Isso muda completamente as prioridades. Antes de ajustar temperatura, antes de trocar de modelo, antes de fazer prompt engineering sofisticado — conserte a busca. Meça recall. Meça precisão. Só depois suba na pilha. No contexto AWS, isso significa tratar o Amazon OpenSearch Serverless (ou outro vector store) como um componente de dados de primeira classe, com o mesmo rigor que você aplicaria a um banco relacional em produção: versionamento de índice, estratégia de reindexação, monitoramento de deriva de distribuição, e testes de regressão quando você troca o modelo de embedding. ## Referência Rápida — Stack e Escopo - **Domínio:** IA Generativa / RAG em produção - **Stack de referência AWS:** Amazon Bedrock Knowledge Bases, OpenSearch Serverless (vector engine), Bedrock Evaluation, Bedrock Guardrails - **Modelos de embedding relevantes:** Amazon Titan Embeddings V2, Cohere Embed v3 (via Bedrock) - **Modelos de geração relevantes:** Claude 3.x (Sonnet/Haiku), Amazon Nova Pro/Lite (via Bedrock) - **Padrão de busca recomendado:** Híbrida (semântica + BM25) + reranking cross-encoder - **Métricas de avaliação-chave:** Faithfulness, Answer Relevance, Context Recall, Context Precision - **Escopo deste playbook:** Agnóstico de domínio; exemplos ancorados em AWS; aplicável a qualquer stack RAG ## Os cinco grupos de risco — por que o checklist está estruturado assim Organizo os 15 itens em cinco grupos porque cada grupo tem um perfil de falha diferente e um dono diferente dentro do time. **Grupo 1 — Ingestão** é onde a maioria dos problemas nasce e onde menos gente olha depois do deploy inicial. Chunking ruim contamina o índice inteiro. Metadados ausentes eliminam a possibilidade de filtros eficientes. Duplicatas inflam o índice e distorcem scores de similaridade. E sem versionamento de índice, você não consegue fazer rollback quando um novo modelo de embedding quebra a qualidade. **Grupo 2 — Recuperação** é o coração do sistema. A decisão entre busca puramente semântica e busca híbrida (semântica + BM25 + reranking) tem impacto direto e mensurável em recall e precisão. Top-k mal calibrado ou ausência de filtro por tenant são vetores de vazamento de informação em sistemas multi-tenant — um risco de segurança real, não teórico. **Grupo 3 — Geração** é onde o LLM entra — e onde as pessoas passam tempo demais. Os itens aqui são mais simples do que parecem: citar a fonte no output (rastreabilidade), ter uma resposta válida de 'não sei' quando o contexto não suporta a resposta (evitar confabulação), e usar structured output quando o downstream precisa parsear a resposta. **Grupo 4 — Avaliação** é o grupo mais negligenciado em projetos que conheço. Sem um dataset de avaliação com ground truth, você está voando cego. Sem testes de regressão, cada troca de modelo de embedding ou LLM é um salto de fé. O Bedrock Evaluation oferece métricas de faithfulness e relevância que podem ser integradas a um pipeline de CI/CD. **Grupo 5 — Guardrails e Custo** fecha o ciclo. PII no contexto recuperado é um problema de compliance, não de UX. Prompt injection via documentos maliciosos é um vetor de ataque real. E custo por consulta não medido é o caminho mais rápido para uma surpresa desagradável no fim do mês — especialmente com reranking e múltiplas chamadas de embedding somando tokens. ## O Checklist de 15 Itens — Concreto e Testável 1. **INGESTÃO #1 — Chunking pela estrutura do documento, não por tamanho fixo** — Teste: pegue 10 documentos representativos e inspecione os chunks manualmente. Um chunk válido deve conter uma unidade semântica completa (seção, parágrafo, item de lista). Chunks que cortam no meio de uma frase ou separam pergunta da resposta são falha. Use heading-aware ou sentence-boundary chunking. Bedrock Knowledge Bases suporta chunking hierárquico e semântico nativamente. 2. **INGESTÃO #2 — Metadados estruturados em todo chunk** — Teste: consulte o vector store e verifique que cada chunk tem pelo menos: source_id, document_title, section, tenant_id (se multi-tenant), created_at, version. Sem esses campos, filtros de recuperação e rastreabilidade de fonte são impossíveis. No OpenSearch Serverless, defina o mapeamento explicitamente antes de indexar. 3. **INGESTÃO #3 — Deduplicação antes de indexar** — Teste: calcule hash SHA-256 do conteúdo de cada chunk antes de inserir. Verifique que o pipeline rejeita ou atualiza duplicatas em vez de inserir novamente. Duplicatas inflam o índice, distorcem scores de similaridade e fazem o mesmo trecho aparecer múltiplas vezes no contexto, desperdiçando tokens. 4. **INGESTÃO #4 — Reindexação versionada com rollback** — Teste: troque o modelo de embedding por uma versão nova e verifique que você consegue manter o índice antigo ativo enquanto o novo é construído (blue/green de índice). No OpenSearch Serverless, use aliases de índice. Sem isso, qualquer upgrade de embedding é uma operação de risco com downtime ou degradação silenciosa. 5. **RECUPERAÇÃO #5 — Busca híbrida ativada (semântica + BM25)** — Teste: construa um conjunto de 20 queries de teste com ground truth de chunks esperados. Meça recall@5 com busca só-semântica e com busca híbrida. Se recall@5 híbrido não for ≥ recall semântico em pelo menos 70% dos casos, revise os pesos. Busca híbrida é especialmente crítica para queries com termos exatos (IDs, nomes próprios, códigos). 6. **RECUPERAÇÃO #6 — Reranking cross-encoder antes de passar ao LLM** — Teste: compare MRR (Mean Reciprocal Rank) do top-k antes e depois do reranking no seu dataset de teste. O reranker deve mover o chunk mais relevante para posições mais altas consistentemente. Sem reranking, você passa os k chunks mais próximos em embedding space — que não é o mesmo que os k mais relevantes para a query. 7. **RECUPERAÇÃO #7 — Top-k calibrado por domínio, não por default** — Teste: meça a distribuição do número de chunks realmente úteis por query no seu dataset. Se 80% das queries precisam de no máximo 3 chunks, passar top-k=10 ao LLM desperdiça tokens e dilui o contexto. Se há queries que precisam de 8 chunks, top-k=3 vai truncar. Calibre por percentil, não por intuição. 8. **RECUPERAÇÃO #8 — Filtro por metadados/tenant obrigatório em multi-tenant** — Teste: com dois tenants A e B no mesmo índice, faça uma query autenticada como tenant A e verifique que nenhum chunk de tenant B aparece nos resultados. Isso não é opcional — é isolamento de dados. No OpenSearch Serverless, use pre-filters na query kNN. No Bedrock Knowledge Bases, use metadata filtering. ## Busca Só-Semântica vs. Híbrida + Reranking | Critério | Dimensão | Só-Semântica (kNN puro) | Híbrida (kNN + BM25) | Híbrida + Reranking Cross-Encoder | | --- | --- | --- | --- | --- | | Recall em queries de linguagem natural | Alto | Alto | Alto | — | | Recall em queries com termos exatos (IDs, códigos) | Baixo — embeddings generalizam demais | Alto — BM25 captura termos exatos | Alto | — | | Precisão no top-k final | Média — muitos falsos positivos por similaridade de embedding | Média-Alta | Alta — reranker reordena por relevância real | — | | Latência adicionada | Baseline (~10-50ms no OpenSearch Serverless) | +5-15ms (fusão de scores) | +50-200ms (chamada ao reranker) | — | | Custo adicional por consulta | Nenhum além do embedding da query | Mínimo | Moderado — depende do modelo de reranking | — | | Complexidade de implementação | Baixa | Média — requer configuração de índice BM25 + fusão | Alta — requer serviço de reranking separado ou modelo Bedrock | — | | Quando usar | Protótipos, domínios com linguagem muito homogênea | Maioria dos casos de produção | Alta precisão exigida, domínio técnico, documentos longos | — | ## Pipeline RAG de Produção — Ingestão → Índice → Recuperação → Reranking → Geração → Guardrail → Avaliação Fluxo completo de um pipeline RAG em produção na AWS. O caminho superior é o pipeline de ingestão (offline/batch). O caminho inferior é o pipeline de consulta (online/real-time). Avaliação é um loop contínuo que alimenta melhorias em ambos os caminhos. ### 📥 Ingestão (Offline) - Fontes S3 / SharePoint / DB (storage) - Parser Estrutura + Metadados (compute) - Dedup SHA-256 Hash (compute) - Chunker Semântico / Hierárquico (compute) - Embedding Model Titan V2 / Cohere (ai) ### 🗄️ Índice (Versionado) - OpenSearch Serverless Vector + BM25 Index (data) - Index Alias Blue/Green (data) ### 🔍 Recuperação (Online) - Usuário Query (user) - Embedding Query (ai) - Busca Híbrida kNN + BM25 + Filtro Tenant (compute) - Reranker Cross-Encoder (ai) ### 🤖 Geração + Guardrails - Prompt Builder Contexto + Instrução (compute) - Bedrock Guardrails PII + Injection Filter (security) - LLM Claude / Nova (ai) - Output Resposta + Citations (frontend) ### 📊 Avaliação Contínua - Dataset Ground Truth (data) - Bedrock Evaluation Faithfulness / Relevance (ai) - CloudWatch Custo + Latência + Alertas (messaging) ### Fluxos - src -> parser: extrai - parser -> dedup: chunks brutos - dedup -> chunker: sem duplicatas - chunker -> embed_ingest: chunks + metadados - embed_ingest -> oss: vetores - oss -> alias: versão ativa - user -> embed_query: query - embed_query -> hybrid: vetor + texto - alias -> hybrid: índice ativo - hybrid -> rerank: top-k candidatos - rerank -> prompt: chunks reordenados - prompt -> guardrail: prompt completo - guardrail -> llm: prompt filtrado - llm -> output: resposta + citations - output -> bedrock_eval: log de respostas - eval_ds -> bedrock_eval: ground truth - bedrock_eval -> cw: métricas - cw -> chunker: feedback loop ## O que fazer quando as métricas de avaliação regridem Quando você roda o dataset de avaliação e vê uma regressão, o instinto é ir direto para o LLM ou para o prompt. Na maioria das vezes, esse é o lugar errado para começar. Sigo um protocolo de diagnóstico em camadas: **Primeiro, isole o estágio.** Meça context recall separadamente de faithfulness. Se context recall caiu mas faithfulness está estável, o problema é na recuperação — chunking, embedding, threshold de similaridade, ou filtros. Se faithfulness caiu mas context recall está ok, aí sim o problema pode ser no prompt ou no modelo. **Segundo, verifique se houve mudança de distribuição nos documentos.** Documentos novos com estrutura diferente, terminologia nova, ou idioma diferente podem degradar a qualidade do embedding sem nenhuma mudança de código. Monitore a distribuição dos scores de similaridade ao longo do tempo — uma queda no score médio dos top-1 chunks é um sinal precoce. **Terceiro, antes de trocar de modelo, ajuste os parâmetros de recuperação.** Mudar o threshold de similaridade mínima, ajustar os pesos de fusão híbrida, ou calibrar o top-k frequentemente resolve regressões sem o custo e risco de uma troca de modelo. Trocar de modelo de embedding implica reindexar tudo — é uma operação cara e que exige os testes de regressão do item #13. **Quarto, mantenha um log de decisões de avaliação.** Cada vez que você aceita uma regressão em uma métrica em troca de melhora em outra, documente. Isso evita que a equipe reverta decisões já tomadas e cria um histórico de trade-offs que é valioso quando o sistema cresce. > **Anti-padrões que eu vejo em todo projeto RAG:** **1. Chunking por tamanho fixo de caracteres ou tokens.** O padrão mais comum e o mais destrutivo. Um chunk de 512 tokens que corta no meio de uma tabela ou separa a pergunta da resposta em um FAQ vai produzir recuperações inúteis independente de qual embedding você use. Sempre inspecione chunks manualmente antes de indexar. **2. Deploy sem dataset de avaliação.** 'Testamos manualmente com algumas queries e pareceu ok' não é avaliação. Sem ground truth, você não tem como saber se uma mudança melhorou ou piorou o sistema. Construir o dataset é trabalho, mas é o único jeito de ter confiança em mudanças. **3. Custo por consulta não medido.** Reranking + embedding + LLM com contexto grande somam rápido. Vi projetos com custo de $0.15-0.30 por consulta que ninguém havia medido. Com 10.000 consultas/dia, isso é $1.500-3.000/dia. Configure métricas de custo estimado desde o primeiro deploy. **4. Trocar de modelo como primeiro recurso quando a qualidade é ruim.** Claude 3.5 Sonnet não vai consertar chunks ruins. GPT-4o não vai consertar ausência de filtro por tenant. O modelo é o último lugar para otimizar — conserte a busca primeiro. **5. Ignorar prompt injection via documentos.** Se usuários podem fazer upload de documentos que vão ser indexados, um documento malicioso com instruções embutidas pode manipular o comportamento do LLM. Use Bedrock Guardrails e sanitize o conteúdo dos documentos antes de indexar. > **Regra de Bolso:** **Se a resposta está errada, culpe a busca antes de culpar o modelo.** ~80% dos problemas de qualidade em RAG têm origem na recuperação. Antes de trocar de LLM, meça context recall. Se o chunk certo não está no top-k, nenhum modelo vai gerar a resposta certa. > **Minha perspectiva sênior — o que eu faço na prática:** Quando começo um projeto RAG, a primeira coisa que faço não é escolher o LLM — é entender a estrutura dos documentos. Documentos com estrutura previsível (PDFs com headings, JSONs, markdowns) permitem chunking determinístico e de alta qualidade. Documentos escaneados, PDFs de formulários, ou conteúdo misto são onde a maioria dos projetos afunda antes mesmo de chegar ao modelo. Minha ordem de prioridade invariável: (1) ingestão e chunking corretos, (2) metadados completos, (3) busca híbrida com filtros, (4) dataset de avaliação com pelo menos 50 pares, (5) reranking, (6) guardrails, (7) aí sim otimização de prompt e escolha de modelo. Nunca inverto essa ordem. Na AWS, uso Bedrock Knowledge Bases para o caminho feliz — hierarquical chunking + OpenSearch Serverless + citations nativas economizam semanas de trabalho. Mas para sistemas com requisitos de multi-tenancy rigorosos ou domínios muito especializados, construo o pipeline manualmente com mais controle sobre o índice e os filtros. O item que mais frequentemente está ausente quando recebo um projeto para revisar é o #12 — dataset de avaliação. Sem ele, toda decisão de arquitetura é baseada em intuição. Com ele, você tem uma conversa baseada em dados. É o investimento de menor custo e maior retorno em qualquer projeto RAG. ## Veredito RAG confiável em produção não é um problema de modelo — é um problema de engenharia de dados com um LLM na ponta. Os 15 itens deste checklist não são boas práticas opcionais: são a linha que separa um sistema que você consegue operar e melhorar com confiança de um que você torce para funcionar. Conserte a busca antes de trocar o modelo. Meça antes de otimizar. E nunca faça deploy sem um dataset de avaliação — você está apenas adiando a descoberta do problema para o pior momento possível. ## Referências - [Amazon Bedrock Knowledge Bases — Overview](https://aws.amazon.com/bedrock/knowledge-bases/) - [Amazon Bedrock — Retrieval Augmented Generation (User Guide)](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) - [Amazon OpenSearch Serverless — Vector Engine for Semantic Search](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-vector-search.html) - [Amazon Bedrock — Evaluate RAG Systems](https://docs.aws.amazon.com/bedrock/latest/userguide/evaluation.html) ## Fontes do caso - [AWS — Amazon Bedrock Knowledge Bases](https://aws.amazon.com/bedrock/knowledge-bases/) - [AWS — Retrieval Augmented Generation](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) - [Amazon OpenSearch Serverless — Vector engine](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-vector-search.html) - [AWS — Evaluate RAG (Bedrock)](https://docs.aws.amazon.com/bedrock/latest/userguide/evaluation.html)