Capstone: RAG production-grade — de ponta a ponta

Este capstone não é um tutorial — é uma trilha de construção de um RAG system que aguenta produção: 100k+ docs, 200ms p95, eval automatizado, observability de primeira, feature flag pra mudanças arriscadas. O objetivo não é copiar código pronto, é entender cada decisão em cada estágio e ser capaz de justificar tradeoffs.

É um projeto cross-trilha. Você vai tocar em oito áreas diferentes do currículo. Se bateu dúvida em alguma, volte na trilha-origem antes de seguir.

Toda RAG production-grade passa por essas 7 fases. Cada fase tem decisões próprias. Pular fase = dívida técnica garantida.

Se o chunking estiver errado, nada depois salva o sistema. Embeddings ótimos + retrieval perfeito sobre chunks ruins = respostas ruins.

Checklist de ingestão:

• Parser preserva estrutura (headings, listas, tabelas) — não vira texto cru
• Metadata obrigatória por chunk: doc_id, chunk_id, source_url, page, section, created_at, lang
• Dedup por hash de conteúdo (evita embeddar e recuperar duplicado)
• Clean de boilerplate (headers/footers/nav) — senão contamina top-k
• Versionamento: a cada reingestão, novo ingest_version. Permite A/B em índices

Postgres + pgvector é o default pragmático: transação ACID, joins com filtros, HNSW index nativo. Só saia pra Pinecone/Weaviate se passar de ~50M chunks ou latência extrema.

-- Schema RAG profissional
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

CREATE TABLE chunks (
  id            BIGSERIAL PRIMARY KEY,
  doc_id        TEXT NOT NULL,
  chunk_id      TEXT NOT NULL,
  content       TEXT NOT NULL,
  content_tsv   TSVECTOR GENERATED ALWAYS AS (to_tsvector('portuguese', content)) STORED,
  embedding     VECTOR(1536) NOT NULL,  -- text-embedding-3-small
  source_url    TEXT,
  section       TEXT,
  lang          TEXT DEFAULT 'pt',
  tenant_id     TEXT NOT NULL,           -- multi-tenant: isolamento em nível de row
  ingest_version INT  NOT NULL,
  created_at    TIMESTAMPTZ DEFAULT now(),
  UNIQUE (doc_id, chunk_id, ingest_version)
);

-- HNSW pra vector search aproximado (p99 ~10ms em 10M chunks)
CREATE INDEX idx_chunks_embedding ON chunks
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

-- GIN pra full-text search (BM25-like via ts_rank_cd)
CREATE INDEX idx_chunks_tsv ON chunks USING GIN (content_tsv);

-- Isolamento por tenant (pré-filter, não post-filter — OBRIGATÓRIO em multi-tenant)
CREATE INDEX idx_chunks_tenant ON chunks (tenant_id);

Vector sozinho erra em termos exatos ("iPhone 15" vira "iPhone 14"). BM25 sozinho erra em paráfrase. Solução: rodar os dois e fundir com Reciprocal Rank Fusion.

Na Postgres, rode BM25 (ts_rank_cd) e vector (cosine distance) em paralelo, depois combine em código. Em escala menor, dá pra fazer tudo em uma query com CTEs.

Retrieval retorna top-50 candidatos. Reranker cross-encoder (leve mas caro por par) reordena em top-5 de alta precisão. Typical lift: +15-30% NDCG@5.

Aqui entra o Claude. Duas otimizações que mudam o jogo em produção: prompt caching e streaming.

from anthropic import Anthropic

client = Anthropic()

def answer_with_rag(query: str, chunks: list[dict]) -> str:
    # Blocos estáticos vão pro cache (TTL 5min na Anthropic, 90% hit em prod).
    system_static = [
        {
            "type": "text",
            "text": SYSTEM_PROMPT_LARGE,              # ementa + estilo + rules
            "cache_control": {"type": "ephemeral"},   # cacheável
        },
    ]

    # Bloco dinâmico (contexto retrieval) não é cacheado — muda toda query.
    context = "\n\n---\n\n".join(
        f"[{c['source_url']}] {c['content']}" for c in chunks
    )

    with client.messages.stream(
        model="claude-sonnet-4-7",
        max_tokens=1024,
        system=system_static,
        messages=[
            {
                "role": "user",
                "content": f"Contexto:\n{context}\n\nPergunta: {query}\n\n"
                           "Responda APENAS com base no contexto. Cite [source_url] em cada afirmação.",
            },
        ],
    ) as stream:
        for chunk_text in stream.text_stream:
            yield chunk_text      # streaming pro frontend

    # cache_read_input_tokens em stream.final_message.usage confirma hit

Sem eval, você não sabe se mudança melhorou ou regrediu. E "perguntar 3 queries e achar que ficou bom" é vibes, não engenharia.

Golden set — 100 tuplas curadas:

{
  "id": "gs-042",
  "query": "Qual a diferença entre Sonnet 4 e Opus 4.7 em context length?",
  "expected_sources": ["docs.anthropic.com/models", "docs.anthropic.com/models/opus-4-7"],
  "expected_facts": [
    "Sonnet 4 tem 200k tokens de context padrão",
    "Opus 4.7 suporta 1M tokens em long-context mode"
  ],
  "forbidden": [
    "não pode inventar context de 2M tokens em Sonnet",
    "não pode dizer que Opus é sempre melhor"
  ],
  "difficulty": "medium",
  "tags": ["models", "factual"]
}

LLM-as-judge — rubrica estruturada, modelo juiz diferente do gerador:

Em produção, você precisa saber em tempo real: qual query está lenta, onde tá o cost leak, que tenant está regredindo qualidade.

Traces por request (Langfuse / LangSmith / OpenTelemetry custom):

# Cada fase vira um span observável
from langfuse.decorators import observe

@observe(name="rag.retrieve")
def retrieve(query, tenant_id):
    # log: query_tokens, tenant, top_k, latency
    return hybrid_search(query, tenant_id)

@observe(name="rag.rerank")
def rerank(query, candidates):
    return cohere_rerank(query, candidates, top_n=5)

@observe(name="rag.generate", as_type="generation")
def generate(query, chunks):
    # Langfuse captura tokens, cost, latency automaticamente
    return claude_with_cache(query, chunks)

@observe(name="rag.pipeline")
def answer(query, tenant_id):
    cands = retrieve(query, tenant_id)
    top5 = rerank(query, cands)
    return generate(query, top5)

Métricas RED a monitorar:

Feature flag + canary pra mudanças arriscadas (prompt, retrieval, rerank):

# LaunchDarkly / Unleash / Statsig — mesmo padrão
variant = feature_flag.variation(
    key="rag-prompt-v2",
    user=current_user,
    default="control",
)

if variant == "treatment":
    prompt = PROMPT_V2   # nova versão, 5% dos users
else:
    prompt = PROMPT_V1   # controle, 95%

# Monitoring compara: judge_score, latency_p95, cost per answer
# entre control vs treatment. Se treatment regredir → rollback 1 clique.

• Tenant isolation obrigatório em SQL: WHERE tenant_id = $1 pré-filter, nunca pós-filter. Vazamento entre tenants = incidente grave
• Sanitize chunks antes do prompt: remova marcações que possam ser interpretadas como instrução (<system>, markdown headings suspeitos)
• PII scrubbing no ingest: CPF, cartão, email → mask no embedding E no chunk text
• Output filter: scan resposta por padrões proibidos (CPF, tokens) antes de streamear
• Rate limit por tenant: queries/min + tokens/dia. Previne cost attack

• Ingest reproduzível com versionamento (ingest_version) — dá pra rodar A/B entre versões
• Dedup por hash implementado; teste com 100 docs duplicados
• Hybrid search (BM25 + vector) com RRF; NDCG@10 medido em golden set
• Rerank integrado ou explicitamente adiado com justificativa escrita
• Prompt caching ativado; hit rate monitorado > 80%
• Streaming no front; time-to-first-token < 500ms p95
• Golden set ≥ 50 exemplos, eval roda em CI a cada PR que toca prompt/retrieval
• LLM-as-judge com modelo diferente + human spot-check semanal
• Observability: traces por request + cost/tenant/day + alertas RED configurados
• Feature flag em prompt/retrieval/rerank; canary <= 10% com rollback automático
• Tenant isolation em SQL verificado via teste de integração
• Prompt injection: red-team manual com 20+ payloads documentados
• PII scrubbing ingest + output filter; logs de compliance
• Rate limit por tenant; alerta de cost spike
• Runbook escrito: "what to do if judge score drops below 3.5"

Este artigo é mapa, não implementação linha-a-linha. Para cada fase, a trilha citada no início tem os detalhes profundos. Sequência sugerida:

1. Semana 1: ingest + embed + pgvector. Índice 1k-5k docs, query com vector simples. Mede recall@10
2. Semana 2: adiciona BM25, RRF, golden set mínimo (20 exemplos). Compara NDCG hybrid vs vector-only
3. Semana 3: Claude generation + prompt caching + streaming. Langfuse para trace
4. Semana 4: rerank (Cohere) + LLM-as-judge + feature flag. Primeiro canary
5. Semana 5+: tenant isolation, security audit, SLO definition, alertas