Melhores Práticas do pgvector

Como Usar Esta Lista

• Conclua antes do lançamento da produção de RAG.
• Reexecute quando o modelo de embedding, a versão do pgvector ou o tamanho do corpus mudarem em 10x.
• Emparelhe com a lista de verificação de pesquisa híbrida se o FTS estiver habilitado.

A - Extensão e Tipos

• Fixe a versão do pgvector em IaC. CREATE EXTENSION vector VERSION '0.8.0' corresponde ao pacote do SO.
• Qualifique o esquema para extensions.vector. Evite surpresas com search_path em conexões agrupadas (pooled).
• Fixe a dimensão em DDL. vector(1536) mais CHECK (vector_dims(embedding) = 1536).
• Armazene o modelo de embedding e a versão em metadados. Campanhas de re-embedding precisam de filtros determinísticos.
• Combine o operador de distância com o opclass do índice. <=> com vector_cosine_ops para embeddings de texto normalizados.

B - Índices e Taxa de Acerto (Recall)

• Avalie a taxa de acerto (recall@k) no seu corpus. Não confie nos padrões ef_search ou ivfflat.probes.
• Construa HNSW após o carregamento em massa, não em tabelas vazias. IVFFlat, especialmente, precisa de dados representativos.
• Use CREATE INDEX CONCURRENTLY em produção. Agende builds que consomem muita RAM fora do horário de pico.
• REINDEX após re-embedding principal ou upgrade do pgvector. Notas de release indicam reconstruções obrigatórias.
• Mantenha queries de referência (gold queries) de força bruta. 50-200 perguntas rotuladas para testes de regressão.

C - Schema e Tenancy

• Separe tabelas de documentos e chunks. Citações e ingestão idempotente precisam de IDs de origem estáveis.
• Habilite RLS em tenant_id para SaaS. Defina a variável de sessão por requisição no pooler.
• Índice parcial WHERE embedding IS NOT NULL. Jobs de embedding pendentes não devem inflar o índice ANN.
• Adicione coluna gerada FTS para busca híbrida. A mesma linha de chunk alimenta a pesquisa por palavra-chave + semântica.
• Hashed o conteúdo de origem no nível do documento. Pule a re-chunkagem quando content_hash não mudar.

D - Operações

• Monitore o tamanho do índice e idx_scan. Zero scans significa opclass incorreto ou o planejador recorrendo a varredura sequencial.
• Ajuste hnsw.ef_search por ambiente. O staging pode usar maior taxa de acerto do que a produção em horário de pico.
• Monitore o autovacuum em tabelas de chunk com alta rotatividade (churn). Re-embedding atualiza tuplas mortas rapidamente.
• Dimensionar RAM antes do build HNSW. Aumente maintenance_work_mem na sessão apenas para a role de migração.
• Documente quando particionar (shard) ou descarregar (offload). Critérios ADR antes que a fantasia de um bilhão de vetores se torne um mandato.

FAQs

Relacionados

• Noções Básicas do pgvector - tipos e operadores
• Índices IVFFlat vs HNSW - trade-offs
• pgvector em Escala - memória e vacuum
• Schema de Armazenamento RAG - design de tabelas
• Melhores Práticas de Extensões - fixação de versão

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PostGIS 3.5+, pgbouncer 1.x e Patroni 3.x.