Arquitetura LLM & RAG

📐 Visão Geral da Arquitetura

Esta arquitetura cobre end-to-end um sistema RAG enterprise para ambientes regulados (saúde, financeiro, jurídico), multitenant, com SLA contratual e custo governado. Foi desenhada para sobreviver a incidentes reais, não apenas demos.

1.Pipeline RAG - Camada de Retrieval

1.1 Hybrid Retrieval

Nenhum sistema de produção depende só de dense retrieval. A arquitetura utiliza três camadas complementares:

• Dense retrieval via embeddings (ex: text-embedding-3-large)
• Sparse retrieval via BM25/TF-IDF para termos exatos e nomes próprios
• Reranking via cross-encoder (ex: Cohere Rerank, BGE-Reranker) após fusão dos resultados

Fusion strategy: Reciprocal Rank Fusion (RRF) com pesos ajustáveis por tipo de query.

1.2 Adaptive Top-K

O número de documentos recuperados não é fixo. O sistema ajusta K dinamicamente com base em:

• Score médio dos top candidatos (se baixo, expande K)
• Orçamento de tokens disponível para o contexto
• Complexidade estimada da query (ver Feature Store, seção 7)

1.3 Context Compression

Antes de montar o prompt, os chunks recuperados passam por compressão:

• Extractive compression: remove sentenças irrelevantes dentro do chunk
• Hierarchical summarization: para documentos longos, usa sumarização em cascata
• Deduplication: remove chunks semanticamente redundantes (cosine similarity > 0.92)

1.4 Evaluation CI

O pipeline de retrieval tem avaliação automatizada em CI:

PR → Retrieval Eval Suite → RAGAS metrics (faithfulness, answer relevancy, context recall)
     ↓ se recall cair > 5% → bloqueia merge

Métricas monitoradas: Recall@K, MRR, NDCG, Context Precision.

2.Segurança - Três Camadas de PII + Guardrails

2.1 PII em Repouso

• Campos PII nos vetores são armazenados criptografados (AES-256)
• Metadados de documentos passam por NER antes da indexação
• PII detectado é substituído por tokens ([NOME_1], [CPF_1]) antes do embedding

2.2 PII em Trânsito

• TLS 1.3 obrigatório em todos os endpoints
• Headers de resposta nunca expõem dados brutos do chunk
• Logs são sanitizados antes de serem escritos (regex + NER em streaming)

2.3 PII Sintético para Testes

• Datasets de desenvolvimento usam geração sintética (ex: Faker com perfis LGPD-compatíveis)
• Nunca usar dados reais em staging ou CI
• Pipeline de geração sintética auditável e versionado

2.4 Guardrails - Camada 1 (Input)

Prompt Injection Direta:

• Detecção via classificador fine-tuned (threshold > 0.85 → rejeita)
• Sanitização de delimitadores especiais (###, <|, system:)
• Validação de schema do input (JSON Schema + regex allowlist)

Prompt Injection Indireta (via documentos):

• Chunks recuperados passam por scanner antes de compor o prompt
• Instruções embedadas em documentos são neutralizadas ([INSTRUÇÃO REMOVIDA])
• Auditoria de qual chunk gerou qual output (ver seção 5)

2.5 Guardrails - Camada 2 (Output)

• Classificador de output: detecta jailbreak, conteúdo proibido, vazamento de PII
• Se score de risco > threshold → resposta bloqueada + evento de auditoria gerado
• Fallback: resposta genérica de recusa sem vazar motivo técnico

2.6 Cross-Tenant Isolation

• Namespace por tenant no vector DB (ex: Pinecone namespaces, Weaviate multi-tenancy)
• Todas as queries têm tenant_id como filtro obrigatório — sem exceção
• Teste de cross-tenant em CI: query de tenant A não pode retornar documentos de tenant B

2.7 WORM Audit Log

• Todos os eventos (queries, respostas, bloqueios, erros) gravados em log imutável
• Implementação: AWS S3 Object Lock (COMPLIANCE mode) ou Azure Immutable Blob Storage
• Retenção mínima: 5 anos (ajustável por regulação do setor)
• Schema do evento: {timestamp, tenant_id, user_id, query_hash, response_hash, guardrail_scores, chunks_used[]}

3.Resiliência - Circuit Breaker & Fallback Chain

3.1 Circuit Breaker (Closed / Open / Half-Open)

Estado CLOSED: requisições normais ao LLM primário
     ↓ se error_rate > 50% em janela de 60s
Estado OPEN: requisições bloqueadas, fallback ativado imediatamente
     ↓ após 30s de cooldown
Estado HALF-OPEN: 1 requisição de teste
     ↓ se sucesso → volta a CLOSED
     ↓ se falha → volta a OPEN

Métricas que disparam: error_rate, p99 latency, timeout_rate.

3.2 Fallback Chain

LLM Primário (ex: GPT-4o)
    → LLM Secundário (ex: Claude 3.5 Sonnet)
        → LLM Terciário menor/local (ex: Llama 3.1 70B via vLLM)
            → Resposta degradada: "Sistema temporariamente indisponível. Consulte [X]."

Fallback não é só retry, é troca de provider com contexto preservado.

3.3 Backpressure & Queue Depth Scaling

• Fila de requests com profundidade máxima configurável por tenant
• Se queue > threshold → HTTP 429 com Retry-After header
• Queue depth exposta como métrica → auto-scaling de workers

3.4 Degradação Controlada

• Modo degradado: RAG desativado, LLM responde só com knowledge base interna
• Modo mínimo: resposta cacheada mais recente para queries similares
• Cada modo de degradação gera evento de auditoria

4.Cost Governance - FinOps para LLM

4.1 Budget Enforcement Hard

• Cada tenant tem orçamento mensal em tokens (configurável)
• Contagem em tempo real via billing ledger (ver 4.4)
• Se tenant atinge 80% do budget → alerta
• Se atinge 100% → requests bloqueados com mensagem específica

4.2 Model Routing por Complexidade

Query simples (classificador confidence > 0.9) → modelo pequeno (GPT-4o-mini, Haiku)
Query média → modelo padrão (GPT-4o, Sonnet)
Query complexa / regulada → modelo premium (o1, Opus)

O classificador de complexidade usa features do Feature Store (ver seção 7).

4.3 Anomaly Detection de Custo

• Baseline de tokens/query por tenant calculado via rolling window (7 dias)
• Se query atual > 3x baseline → alerta + revisão manual opcional
• Padrões de abuso detectados: loops infinitos de agente, queries malformadas com contexto gigante

4.4 Billing Ledger por Tenant

Schema do ledger:

{
  "tenant_id": "acme-corp",
  "timestamp": "2025-01-15T14:32:00Z",
  "model": "gpt-4o",
  "prompt_tokens": 1842,
  "completion_tokens": 312,
  "cost_usd": 0.02154,
  "query_id": "q_abc123",
  "feature_flags": ["rag_enabled", "reranking_enabled"]
}

Ledger é imutável, append-only, exportável para faturamento.

5.Observabilidade — CI Gate & Distributed Tracing

5.1 Trace Completo por Query

Cada query gera um trace end-to-end:

query_received → embedding_generated → retrieval_executed → 
reranking_applied → prompt_assembled → llm_called → 
guardrail_output_checked → response_delivered

Cada span inclui: latência, tokens, modelo usado, tenant_id, chunks_ids utilizados.

5.2 Métricas de Observabilidade

5.3 CI Gate de Observabilidade

# .github/workflows/eval.yml
- name: RAG Evaluation Gate
  run: |
    python eval/run_suite.py --dataset golden_set_v3.jsonl
    # Falha o build se:
    # - Recall@5 < 0.82
    # - Faithfulness < 0.90
    # - p95 latency > 2000ms

Bloqueia merge se métricas de qualidade caírem abaixo do threshold.

6.Cold-Start — Readiness Gate & Predictive Scaling

6.1 Warm-up Automático

Ao iniciar um novo pod/instância, antes de receber tráfego real:

• Warm index: carrega índice vetorial em memória (evita cold read do disco)
• Warm embeddings: executa queries sintéticas para aquecer o modelo de embedding
• Warm connection pool: estabelece conexões com LLM provider, vector DB, cache

6.2 Readiness Gate

Pod inicia → executa health checks:
  ✓ Vector DB responde em < 100ms
  ✓ LLM provider responde em < 500ms  
  ✓ Embedding model carregado
  ✓ Cache hit em query de teste
→ Apenas então: Kubernetes marca pod como Ready

Sem readiness gate, p95 explode nas primeiras requisições pós-deploy.

6.3 Predictive Scaling

• Analisa padrões de uso histórico por tenant (dia da semana, horário)
• Escala proativamente antes do horário de pico esperado
• Integrado com HPA do Kubernetes + métricas customizadas (queue depth, p95 latency)

7.Feature Store & ML Híbrido — NOVO

7.1 Por que Feature Store?

O RAG puro não aprende. Para um sistema que melhora com o tempo, precisamos de features estruturadas alimentando classificadores e re-rankers.

7.2 Features por Query

Computadas em tempo real e armazenadas no Feature Store (ex: Feast, Tecton, ou Redis + Postgres):

7.3 Features por Tenant (Perfil Histórico)

Atualizadas em batch (ex: a cada hora):

7.4 Feedback Loop Supervisionado

Query → Resposta gerada → Usuário dá thumbs up/down
                          ↓
              Evento registrado no feedback store
                          ↓
              Feature: response_quality_label = 1/0
                          ↓
              Usado para fine-tune do reranker por tenant

Cadência de re-treino: semanal se > 500 novos labels; mensal caso contrário.

7.5 Reward Modeling

• Treinar um reward model por tenant usando feedback explícito + implícito (tempo de leitura, follow-up queries)
• Reward model alimenta o reranker: documentos que historicamente geraram respostas aprovadas recebem score maior
• Implementação inicial: LightGBM ranker sobre features do Feature Store

7.6 Active Learning Pipeline

• Queries com baixo confidence do classificador de complexidade são flagadas
• Human-in-the-loop para labeling (interface interna)
• Novos labels entram no pipeline de re-treino automaticamente

8.Drift Detection

8.1 Por que Drift Importa?

Em sistemas RAG, o drift mata silenciosamente. Embeddings que funcionavam 6 meses atrás podem performar mal hoje porque:

• A distribuição das queries mudou (usuários evoluem)
• O modelo de embedding foi atualizado
• O domínio do conteúdo se expandiu

8.2 Embedding Centroid Monitoring

# A cada hora, calcula centroide dos embeddings de queries
current_centroid = np.mean(embeddings_last_1h, axis=0)
baseline_centroid = load_baseline_centroid(tenant_id)

drift_score = cosine_distance(current_centroid, baseline_centroid)

if drift_score > DRIFT_THRESHOLD:  # ex: 0.15
    alert("Embedding drift detectado", tenant_id, drift_score)
    trigger_reindex_evaluation()

Baseline recalculado mensalmente ou após re-treino do embedding model.

8.3 Query Entropy Monitoring

• Monitora a distribuição de tipos de query ao longo do tempo
• Usa KL-divergence entre distribuição atual e baseline
• Se KL-div > threshold → alerta de mudança de comportamento do usuário
• Gatilho para revisar templates de prompt e estratégia de retrieval

8.4 Retrieval Recall Drift Alert

Diariamente: executa golden evaluation set por tenant
Compara Recall@5 com baseline do último mês
Se queda absoluta > 3pp → alerta nível WARNING
Se queda absoluta > 7pp → alerta nível CRITICAL + freeze de deploy

8.5 Top-K Hit Distribution Drift

• Monitora qual posição do ranking é mais utilizada pelo LLM no contexto
• Se o LLM começa a usar consistentemente só o doc #1 (ignorando os demais), pode indicar falha no reranker
• Alerta se distribuição de hits sair 2 desvios padrão da baseline

8.6 Pipeline de Reação ao Drift

Drift detectado
    → Nível 1 (Warning): alerta + aumenta frequência de eval
    → Nível 2 (Critical): pausa indexação de novos docs + análise manual
    → Nível 3 (Emergency): rollback de embedding model version

9.Data Residency por Região

9.1 Topologia Multi-Região

Para enterprise global, os dados não podem cruzar fronteiras sem controle explícito.

Região us-east-1:          Região eu-west-1:          Região ap-southeast-1:
  - Vector DB (US tenants)   - Vector DB (EU tenants)   - Vector DB (APAC tenants)
  - LLM routing → OpenAI US  - LLM routing → OpenAI EU  - LLM routing → local provider
  - Audit logs US            - Audit logs EU (GDPR)      - Audit logs APAC
  - Billing ledger US        - Billing ledger EU         - Billing ledger APAC

9.2 Tenant ↔ Região Mapping

{
  "tenant_id": "acme-corp-eu",
  "data_residency": "eu-west-1",
  "allowed_llm_providers": ["openai-eu", "azure-france-central"],
  "vector_db_namespace": "eu/acme-corp-eu",
  "audit_bucket": "s3://audit-eu-west-1/acme-corp-eu/",
  "pii_regulation": "GDPR"
}

9.3 LLM Provider Regional Routing

• OpenAI: endpoints regionais (api.openai.com vs Azure OpenAI em regiões específicas)
• Anthropic: verificar disponibilidade de endpoints regionais
• Fallback regional: se provider EU indisponível → provider EU alternativo (nunca rota para US sem consentimento explícito)

9.4 Compliance por Regulação

| Regulação | Restrição Principal | Implementação | |-----------|--------------------|--------------|  | GDPR (EU) | Dados não saem da UE sem adequacy decision | LLM provider com endpoint EU + Vector DB eu-west | | LGPD (BR) | Transferência internacional só com consentimento | Flag por tenant, rota somente para providers com DPA assinado | | HIPAA (US) | PHI só em infraestrutura com BAA | AWS GovCloud ou Azure Government para tenants saúde | | SOC 2 | Audit trail completo | WORM logs + acesso auditado |

10.Chaos Engineering & Reliability Testing

10.1 Por que Chaos Engineering?

Fallback chain no papel não é suficiente. Sem testar falhas reais em staging, você descobre que o circuit breaker não funciona durante um incidente de produção às 2h da manhã.

10.2 Fault Injection em Staging

Experimentos executados automaticamente a cada release:

10.3 GameDays

Sessões trimestrais com o time de engenharia:

Formato:

1. Escolher 1-2 cenários de falha realistas (baseados em incidentes históricos ou near-misses)
2. Executar falha em ambiente de staging com tráfego real simulado
3. Time responde como se fosse produção (runbook, alertas, decisões)
4. Post-mortem imediato: o que falhou no processo, não nas pessoas

Exemplos de cenários GameDay:

• Provider OpenAI retorna 500 para 30% das requests por 15 minutos
• Vazamento de cross-tenant detectado em auditoria (como respondemos?)
• Spike de custo 10x por tenant malicioso

10.4 Chaos Testing Automatizado (CI/CD)

# Executa em staging a cada deploy para main
chaos_tests:
  - name: primary_llm_outage
    duration: 60s
    inject: block_provider("openai")
    assert: fallback_rate > 0.95 AND p99_latency < sla_threshold
  
  - name: vector_db_slow
    duration: 120s
    inject: add_latency("vector_db", 1500ms)
    assert: cache_hit_rate increases AND p99 < 3000ms
  
  - name: budget_exhaustion
    duration: 30s
    inject: set_budget("test_tenant", 0)
    assert: new_requests_blocked AND existing_requests_complete

10.5 Runbooks de Incidente

Para cada tipo de falha coberta pelo chaos testing, existe um runbook:

• Formato: Sintoma → Diagnóstico rápido (3 comandos) → Ação imediata → Escalação
• Localização: Wiki interna linkada nos alertas do PagerDuty/OpsGenie
• Revisão: Após cada GameDay e cada incidente real

11.Orquestração Multiagente (LangGraph)

11.1 Topologia Formal

Supervisor Agent
├── Planner (decompõe a tarefa em sub-tarefas)
├── Retrieval Worker (executa RAG)
├── Analysis Worker (analisa documentos recuperados)
├── Synthesis Worker (consolida e gera resposta final)
└── Critic (valida resposta antes de entregar)

11.2 Auditoria de Tool Decisions

Cada decisão de tool use é logada:

{
  "agent": "retrieval_worker",
  "tool": "vector_search",
  "input": {"query": "...", "top_k": 5},
  "output_summary": "5 docs retrieved, avg_score: 0.82",
  "latency_ms": 134,
  "cost_tokens": 0,
  "loop_iteration": 2
}

11.3 Custo Acumulado por Loop

• Cada iteração do agente registra tokens consumidos
• Budget máximo por execução de agente (ex: 50k tokens)
• Se budget de execução esgotado → agente para e retorna melhor resposta parcial
• Evita loops infinitos caros

11.4 Timeout por Grafo

• Timeout global por execução (ex: 30s para queries síncronas, 5min para assíncronas)
• Cada nó tem timeout individual
• Timeout dispara fallback para resposta parcial, nunca erro silencioso

12.Multi-Tenant Isolation

13.ML Ops Contínuo por Tenant

13.1 Ciclo de Vida do Modelo por Tenant

Baseline Model (genérico)
    → Coleta de feedback (explícito + implícito)
    → Feature engineering no Feature Store
    → Re-treino do reranker (semanal/mensal)
    → Avaliação offline vs baseline (eval suite)
    → Shadow deployment (0% tráfego, apenas logging)
    → Canary deployment (5% do tráfego do tenant)
    → Full rollout se métricas melhoram
    → Rollback automático se recall cair > 3pp

13.2 Versionamento de Modelos por Tenant

• Cada tenant tem sua versão do reranker armazenada no Model Registry (ex: MLflow)
• Rollback para versão anterior em < 2 minutos
• A/B testing entre versões com split configurável

13.3 Monitoramento de Performance por Tenant

Dashboard por tenant com:

• Recall@5 trend (últimos 30 dias)
• Feedback score trend
• Custo por query trend
• Drift scores (embedding + query entropy)
• Número de queries por tipo (factual/analytical/etc.)

14.Tabela de Avaliação por Dimensão

15.Checklist de Readiness para Produção

Antes de ir para produção regulada:

• Cross-tenant test suite passando em CI
• Chaos tests básicos (LLM down, DB slow, budget exhausted) validados
• WORM audit configurado e testado (simular auditoria regulatória)
• Data residency verificada: query de tenant EU nunca roteia para US
• Budget limits configurados por tenant com alerta a 80%
• Readiness gate validado: pod só recebe tráfego após warm-up
• Runbooks escritos para top 5 cenários de incidente
• Eval suite com golden set por domínio (jurídico/saúde/financeiro)
• Drift monitoring ativo com baseline calculado
• Feedback loop coletando dados (mesmo sem re-treino ainda)

16.Estimativa de Custo — 1M Queries/Mês

Model routing reduz custo em ~40% vs usar modelo premium para tudo.

17.Próximos Passos Priorizados

Para times começando a implementar esta arquitetura, a ordem de prioridade recomendada:

1. Fundação (Semanas 1-4): RAG híbrido + isolamento multi-tenant + guardrails básicos
2. Operação (Semanas 5-8): Observabilidade + billing ledger + circuit breaker
3. Qualidade (Semanas 9-12): Eval CI gate + cold-start + drift detection básico
4. Maturidade (Meses 4-6): Feature store + feedback loop + chaos engineering básico
5. Excelência (Meses 7-12): ML ops contínuo por tenant + data residency + GameDays regulares