Índice não é fonte da verdade

Vetor é representação derivada

Embedding mapeia conteúdo para vetor. Similaridade seleciona candidatos segundo geometria aprendida; não prova autorização, atualidade ou correção. Banco vetorial é um índice derivado. A fonte canônica continua sendo o documento ou registro versionado.

Cada chunk precisa de document_id, versão, posição, hash, tenant, ACL, validade, modelo de embedding e status. Sem isso, não há deleção confiável nem citação auditável.

SELECT chunk_id, text, source_locator
FROM chunks
WHERE tenant_id = :tenant
  AND acl_groups && :groups
  AND valid_from <= now()
  AND (valid_to IS NULL OR valid_to > now())
ORDER BY embedding <=> :query
LIMIT 20;

A sintaxe é ilustrativa. O princípio é filtrar no mesmo plano da busca. Buscar globalmente e esconder depois já expôs dados ao pipeline.

Atualização e migração

Trocar modelo de embedding muda o espaço vetorial. Nunca misture vetores incompatíveis. Crie índice novo, faça backfill, valide, duplique escrita temporariamente e altere alias de forma atômica. Mantenha rollback.

fonte v7 → parser v3 → chunker v2 → embedding e4 → índice 2026-08

Essa cadeia é provenance. Exclusão ou revogação deve percorrê-la. Defina SLA de propagação e teste tombstones.

Citações

Citação deve apontar para passagem que sustenta a afirmação, com versão e localizador. Link para página inicial não basta. Verifique entailment entre claim e trecho; números e exceções exigem atenção. Se fontes divergem, mostre divergência ou abstenha.

Quando usar e evitar

Use vetores para similaridade semântica em corpus não trivial. Prefira SQL para filtros/valores estruturados e busca lexical para códigos. Híbrido costuma ser melhor para documentação técnica. Evite criar infraestrutura vetorial se cem documentos cabem numa busca simples mensurável.

Falhas, segurança e operação

Ataques incluem poisoning, embedding inversion, inferência de associação, documento persuasivo e filtro omitido. Controles: origem permitida, ACL pré-retrieval, criptografia, isolamento, testes canário, auditoria e minimização. Não inclua dados proibidos só porque embeddings “não são legíveis”.

Monitore lag de atualização, documentos órfãos, distribuição de similaridade, recall por fonte, resultado vazio, ACL sem correspondência e índice/modelo. Backup do índice não substitui backup das fontes e pipeline reprodutível.

Exercício e aceite

Crie dois tenants, dois grupos e versões conflitantes do mesmo manual. Prove que nenhuma consulta cruza ACL, a versão revogada desaparece dentro do SLA e cada frase gerada aponta a chunk válido. Reindexe com outro embedding e faça rollback.

Fontes

• PostgreSQL Row Security
• pgvector
• OWASP LLM08:2025
• BEIR benchmark

Laboratório e caderno de evidências

Este caderno transforma o conceito do livro em uma decisão de engenharia auditável. O cenário é Migrar embedding sem misturar espaços vetoriais. A regra é começar pelo sistema atual — índice lexical e versão vetorial atual — e só acrescentar complexidade quando uma avaliação previamente definida demonstrar ganho líquido.

1. Escreva o contrato da decisão

Registre em uma página: quem usa, qual decisão recebe apoio, quais entradas existem naquele instante, qual saída é permitida, qual efeito é proibido e quem responde pelo resultado. Separe sugestão, decisão e execução. Uma resposta textual pode sugerir; a API de domínio continua autorizando e registrando qualquer mudança.

Use critérios no formato dado/quando/então. Inclua caminho nominal, ausência de dados, conflito, outro tenant, dependência indisponível e tentativa adversarial. “Funciona bem” não é critério. Declare o limite de tempo, custo, dados e risco, além da condição de parada.

2. Construa o pacote mínimo de evidência

Crie um conjunto pequeno, porém representativo, antes de alterar o sistema. Cada caso tem identificador estável, origem, resposta ou comportamento esperado, risco, tags e razão da inclusão. O conjunto de desenvolvimento ajuda a iterar; um holdout separado impede otimizar contra a própria prova. Dados reais exigem minimização, controle de acesso e retenção. Quando usar casos sintéticos, identifique-os e confirme que não substituem a distribuição real.

A comparação deve manter constantes as partes que não estão sendo avaliadas. Se trocar modelo e prompt ao mesmo tempo, você não saberá a causa. Registre versões, configurações, ambiente, seeds quando aplicável e data. Preserve os piores erros como artefatos, não apenas a média.

3. Desenhe a fronteira operacional

entrada validada → componente candidato → validação externa
                 → autorização/policy → resultado observável
                 → feedback curado → avaliação de regressão

Marque onde conteúdo não confiável entra, onde identidade e permissões são resolvidas, onde segredos ficam e qual componente pode produzir efeito. O modelo não é fonte de verdade nem mecanismo de autorização. Use schema, consulta ao sistema de registro, allowlists, limites e confirmação proporcional ao risco.

Para cada dependência defina timeout, retry, idempotência, fallback e circuit breaker. Retry não é padrão para efeitos: um timeout pode ocorrer depois do sucesso. Modo degradado precisa preservar segurança e deixar claro ao usuário o que perdeu.

4. Faça uma pré-mortem

As falhas prioritárias deste livro são: ACL tardia; chunk órfão; embedding incompatível; deleção incompleta. Para cada uma, escreva gatilho, impacto, detecção, contenção, recuperação e teste do controle. Inclua falha acidental e abuso deliberado. Se a única defesa é “o modelo provavelmente recusará”, o controle ainda não existe.

Execute tabletop: uma pessoa opera, outra injeta a falha e uma terceira observa. O operador deve diagnosticar usando dashboards, traces e runbook, sem depender do autor. Registre lacunas e transforme recorrência em teste, política, alerta ou mudança arquitetural.

5. Meça o sistema completo

O painel mínimo acompanha cross-tenant zero; lag de deleção; recall; chunks sem fonte. Faça cortes por versão, tipo de tarefa, risco e população relevante. Latência fim a fim inclui fila, retrieval e ferramentas. Custo é dividido por tarefa concluída, não por chamada. Qualidade em produção usa sinais curados; clique ou concordância do usuário não prova correção.

Defina SLO e orçamento de erro quando houver operação contínua. Alertas precisam de owner e ação. Telemetria passa por redaction antes de sair do processo; prompt, documento, memória ou trace completo podem conter informação pessoal, segredo ou conteúdo malicioso.

6. Libere em degraus

A sequência segura é offline, shadow, equipe interna, canário, aumento gradual e produção. Cada degrau possui gate e rollback. Feature flag separa deploy de liberação. A reversão deste cenário é: reverter alias e reconstruir a partir das fontes canônicas. Treine a reversão antes do incidente e verifique que dados derivados, filas e caches também retornam a estado compatível.

Mudança de modelo, prompt, índice, ferramenta, policy ou dataset é mudança de sistema. Rode regressão proporcional. Um fornecedor atualizar silenciosamente comportamento não remove sua obrigação de testar.

Matriz de aceite

Dimensão	Evidência exigida	Falha que bloqueia
valor	ganho sobre baseline em casos representativos	demo isolada sem comparação
correção	golden set, holdout e análise dos piores casos	métrica média sem cauda
segurança	testes negativos de identidade, dados e efeitos	policy apenas no prompt
privacidade	minimização, finalidade, retenção e exclusão	dado sensível em trace
operação	SLO, alerta, runbook e rollback exercitado	dependência sem timeout
governança	owner, versão, usos permitidos e revisão	sistema órfão

Exercício de competência

Entregue um repositório ou pacote reproduzível contendo contrato, diagrama de fronteiras, casos de avaliação, script de execução, relatório comparativo, threat model, dashboard mínimo e runbook. Introduza deliberadamente duas falhas da pré-mortem e demonstre detecção e recuperação. Outra pessoa deve conseguir repetir o resultado sem explicação oral.

A aprovação exige: baseline preservado; critérios definidos antes do resultado; pelo menos um caso em que o sistema se abstém; efeito sensível protegido fora do modelo; custos medidos; rollback testado; limitações e usos proibidos escritos. Se o candidato não superar o baseline com segurança, documentar “não adotar” é um resultado tecnicamente correto.

Perguntas de recuperação ativa

1. Qual afirmação deste sistema depende de evidência externa?
2. O que o modelo pode propor, mas jamais autorizar?
3. Qual mudança invalidaria o holdout?
4. Como detectaríamos a pior falha antes do usuário?
5. Qual é o caminho de retirada em menos de uma hora?

Relações

Use este caderno junto ao livro de evals para desenho estatístico, ao de segurança para cenários adversariais, ao de observabilidade para sinais e ao de UX para supervisão. A profundidade nasce da conexão entre decisão, implementação, medição e recuperação — não da quantidade de ferramentas citadas.