Embeddings + pgvector
O laboratório começa com vetores manuais para que você possa verificar a matemática e o filtro sem depender de um modelo. Depois você desenhará a coleção real com metadados e um plano de comparação entre busca exata e aproximada.
Antes de executar, tente ordenar os dois documentos e explique por que o primeiro lugar global não pode ser usado pela empresa A. Essa tentativa retoma autorização e contexto: proximidade só é útil dentro do conjunto que a aplicação pode consultar.
JavaScriptPostgreSQLRAGAo terminar esta aula
- Embeddings exigem contrato de representação.
- Metadados complementam proximidade.
- Índices são escolhas operacionais que precisam de avaliação.
Antes de continuar: Leitura: Embeddings + pgvector
Preparar coleção e hipóteses
FundamentosCrie três políticas fictícias por empresa e registre id, texto, versão e vigência. Escreva perguntas com documento relevante conhecido e uma pergunta sem resposta. Diferencie relevância temática de evidência suficiente. Para cada pergunta, marque a condição ou trecho que sustenta o julgamento. Só depois escolha embedding e dimensionalidade para a etapa externa. Se não houver serviço ou modelo disponível, mantenha o conjunto manual como demonstração e declare a geração real pendente. A avaliação deve evitar confundir vetores desenhados para o exercício com representações aprendidas.
Implementar matemática e filtros
FundamentosExecute a função de cosseno e calcule um caso manualmente para comparar. Teste vetores iguais, ortogonais, nulos e dimensões diferentes. Aplique escopo antes de selecionar candidatos. Acrescente documento antigo semanticamente próximo e exclua-o pela política de vigência. Não use o score para decidir autoridade. Em uma implementação real, o filtro deve usar contexto autenticado e ser preservado na consulta ao banco. O exercício local demonstra a regra, mas não verifica plano SQL, permissões de tabela ou segurança do serviço vetorial.
Projetar pgvector e comparar opções
PostgreSQLDesenhe tabela de trechos com chave, documento, tenant, versão e vetor de dimensão definida. Consulte a documentação do pgvector para operadores e índices escolhidos antes de escrever SQL executável. Planeje uma busca exata como referência e uma configuração aproximada como candidata. Compare latência e documentos relevantes recuperados no mesmo corpus. Depois escreva uma ADR comparando PostgreSQL com um serviço especializado, incluindo manutenção, filtros e atualização. Não escolha apenas por uma demonstração de velocidade sem considerar a consulta autorizada e o custo operacional.
Avaliar resultados e falhas
FundamentosMonte uma tabela de pergunta, relevantes esperados, retornados e motivo dos erros. Teste paráfrase, termo exato e ausência de resposta. Se uma política de outra empresa aparece, a falha é de escopo; se a política correta não aparece, investigue representação, índice ou seleção. Se aparece política antiga, revise metadados e vigência. Compare uma configuração de cada vez para localizar a mudança. Feche com versões de corpus, embedding e índice, declarando quais medidas são locais, quais são externas e quais ainda faltam para decidir.
Executar a etapa PostgreSQL
PostgreSQLEm um ambiente de prática com pgvector instalado, crie tabela de trechos com chave, escopo, versão e coluna vector na dimensão escolhida. Consulte a documentação da extensão para CREATE EXTENSION e operadores da versão instalada. Para distância de cosseno, a documentação usa <=>; ordenar distância crescente encontra candidatos próximos. Aplique WHERE ao escopo autorizado e à vigência e limite a quantidade selecionada. Comece com busca exata e vetores manuais identificados como demonstração; depois ingira embeddings reais de um único modelo compatível. Registre versão do PostgreSQL, pgvector e modelo. Compare EXPLAIN e resultados antes de adicionar índice aproximado. Não declare benchmark de pgvector com a função JavaScript de cosseno: execução do banco é uma etapa própria com evidência e requisitos de instalação.
Caso adicional para diagnóstico e decisão
FundamentosAcrescente uma política com versão nova e embeddings produzidos por outro modelo com a mesma dimensão. O banco aceita o formato, mas isso não prova que os vetores vivem no mesmo espaço. Antes de consultar, escreva como separar coleções ou versões de representação e planejar reindexação. Teste também um filtro muito seletivo em busca aproximada e compare os candidatos com busca exata sobre o mesmo escopo. A rubrica adicional exige representação homogênea e cobertura conhecida. Compare reconstruir o índice inteiro com migração gradual em duas coleções: a primeira simplifica consistência em bases pequenas; a segunda permite transição controlada, mas exige roteamento e remoção da representação antiga. Registre custos e medidas ainda ausentes. Esse caso evita tratar dimensionalidade, índice e licença de um modelo como detalhes intercambiáveis de configuração.
Execução, inspeção e diagnóstico
FundamentosExecute os vetores manuais e acrescente um candidato não autorizado com score perfeito. Confirme que ele não participa da lista final. Depois teste vetor nulo e dimensão diferente para verificar que entradas inválidas não geram uma classificação numérica enganosa.
function cos(a,b) {
if(a.length!==b.length) throw new Error("Dimensão incompatível");
const norma = v=>Math.sqrt(v.reduce((s,x)=>s+x*x,0));
const divisor=norma(a)*norma(b);
if(!divisor) return null;
return a.reduce((s,x,i)=>s+x*b[i],0)/divisor;
}
const consulta=[1,0];
const documentos=[{id:"a",tenant:"A",v:[1,0.2]},
{id:"b",tenant:"B",v:[1,0]}];
console.log(documentos.filter(x=>x.tenant==="A")
.map(x=>({id:x.id,score:cos(consulta,x.v)})));Falha de escopo não se resolve aumentando top-k. Falha de dimensão exige corrigir contrato de embedding. Ausência no índice aproximado pede comparação com busca exata. O diagnóstico distingue dados, representação e mecanismo de consulta.
Exercício aplicado
Entregue busca local autorizada e desenho de coleção vetorial com avaliação de índice.
- Tente ordenar candidatos e rotule relevância.
- Execute matemática e casos inválidos.
- Desenhe metadados, filtros e armazenamento.
- Compare opções e registre evidência por etapa.
Abrir resolução comentada
A solução mantém tenantId vindo de contexto confiável e compara somente candidatos elegíveis. A coleção real possui versão e referência ao documento original. Para avaliar índice, use busca exata como referência sobre o mesmo conjunto autorizado.
A escolha de banco inclui manutenção, filtros e integração além da busca. O relatório separa demonstração matemática local, geração real de embeddings e benchmark de armazenamento. Não afirme que um banco foi testado apenas porque o cálculo de cosseno executou.
A referência mostra filtro e cálculo. A entrega completa acrescenta coleção versionada, casos rotulados e decisão de armazenamento ligada ao projeto.
A resolução cobre todos os checks locais com asserts: dimensão, valores finitos, vetor nulo, filtro por tenant e vigência antes da seleção e casos rotulados. O desenho de armazenamento registra representação, metadata e referência exata. Os vetores manuais não medem qualidade de embeddings; a ADR depende de latência, recuperação e operação reais do banco. A etapa PostgreSQL e o benchmark de índice continuam explicitamente separados da execução matemática local.
import assert from "node:assert/strict";
function cosine(a,b){
if(a.length!==b.length||!a.length)throw new Error("DIMENSAO_INVALIDA");
if(![...a,...b].every(Number.isFinite))throw new Error("VETOR_INVALIDO");
const norma=v=>Math.sqrt(v.reduce((s,x)=>s+x*x,0));const divisor=norma(a)*norma(b);
return divisor?a.reduce((s,x,i)=>s+x*b[i],0)/divisor:null;
}
const corpus=[{id:"d1",tenant:"A",versao:2,vigente:true,vetor:[1,0],texto:"Ativação"},
{id:"d2",tenant:"B",versao:2,vigente:true,vetor:[1,0],texto:"Outra empresa"},
{id:"d3",tenant:"A",versao:1,vigente:false,vetor:[1,0],texto:"Política antiga"},
{id:"d4",tenant:"A",versao:2,vigente:true,vetor:[0,1],texto:"Contato"}];
function buscar(query,ctx,k){return corpus.filter(d=>d.tenant===ctx.tenant&&d.vigente)
.map(d=>({...d,score:cosine(query,d.vetor)})).filter(d=>d.score!==null)
.sort((a,b)=>b.score-a.score).slice(0,k);}
assert.equal(cosine([1,0],[1,0]),1);assert.equal(cosine([1,0],[0,1]),0);
assert.equal(cosine([0,0],[1,0]),null);
assert.throws(()=>cosine([1],[1,0]),/DIMENSAO_INVALIDA/);
assert.throws(()=>cosine([NaN,0],[1,0]),/VETOR_INVALIDO/);
const encontrados=buscar([1,0],{tenant:"A"},2);
assert.deepEqual(encontrados.map(x=>x.id),["d1","d4"]);
const casos=[{id:"q1",query:[1,0],relevantes:["d1"]},{id:"q2",query:[0,1],relevantes:["d4"]}];
const avaliacao=casos.map(c=>({id:c.id,retornado:buscar(c.query,{tenant:"A"},1)[0].id,
relevantes:c.relevantes}));assert.ok(avaliacao.every(x=>x.relevantes.includes(x.retornado)));
const armazenamento={dimensao:2,modelo:"vetores manuais, não embeddings aprendidos",
metadata:["id","tenant","versao","vigente","origem"],
referencia:"busca exata no corpus autorizado",indiceCandidato:"avaliar HNSW ou IVFFlat no banco",
decisao:"pgvector quando integração relacional é requisito; comparar serviço especializado no ambiente real",
medidasPendentes:["latência e recall com índice","consumo e manutenção","geração real de embeddings"]};
console.log({status:"aprovado",encontrados,avaliacao,armazenamento,
bancoExecutado:false,scoreEhProbabilidade:false});Como conferir seu resultado
- Escopo é aplicado antes da seleção.
- Dimensão e vetor nulo são tratados.
- Scores não são apresentados como verdade factual.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Calcular norma/produto escalar.
- Aplicar filtro confiável de tenant.
q=(0,1), A=(0,2) proibido, B=(2,0) permitido, C=nulo. Teste filtro/dimensão.
Conferir raciocínio e critérios de domínio
A teria 1, B tem 0, C possui cosseno indefinido.
A nunca entra no contexto; B elegível não implica resposta suficiente.
Dimensão incompatível é erro; comparar exata/aproximada no mesmo corpus autorizado.
Evidências para autoavaliação ou revisão por pares
- Cosseno e degeneração: A teria 1, B tem 0, C possui cosseno indefinido.
- Filtro de acesso: A nunca entra no contexto; B elegível não implica resposta suficiente.
- Representação e índice: Dimensão incompatível é erro; comparar exata/aproximada no mesmo corpus autorizado.
Um erro frequente
Vetor nulo é semelhante a tudo.
Vetor de norma zero não possui cosseno definido.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Mesma dimensão torna dois modelos compatíveis?
Não.
Os espaços podem ter geometrias diferentes; trocar modelo exige avaliação e reindexação.
2. Score é probabilidade de verdade?
3. Índice aproximado garante todos os melhores candidatos?
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Vector embeddings
OpenAI • consulta: 2026-10-06
OpenAIRAGEmbeddings, similaridade, dimensionalidade e busca semântica.
Limites: Dimensões e limites dependem do modelo; não misturar vetores de modelos diferentes no mesmo espaço.
- pgvector README
pgvector contributors • consulta: 2026-10-06
PostgreSQLPostgreSQL com vetores, distâncias cosine/L2, índices HNSW/IVFFlat, filtragem e busca híbrida.
Limites: README atual mostra versão 0.8.7; performance, recall e ordem de filtros exigem benchmark no dataset.
- Qdrant Points
Qdrant • consulta: 2026-10-06
FundamentosPontos com vetores, IDs, payloads e operações de armazenamento.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- OpenAI Retrieval
OpenAI • consulta: 2026-10-06
OpenAIIngestion, chunking/overlap, metadata/filtros, ranking e reescrita de consultas em vector stores.
Limites: Implementação gerenciada OpenAI; defaults não são melhores escolhas universais para pgvector.
- Pinecone Semantic search
Pinecone • consulta: 2026-10-06
FundamentosBusca semântica, top-k e resultados em índices vetoriais.
Limites: Serviço e pricing próprios; comparar com alternativas usando dataset e custos medidos.
- Weaviate Hybrid search
Weaviate • consulta: 2026-10-06
RAGCombinação de busca keyword/BM25 e vetorial; filtros e parâmetros de ranking.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- Milvus Index Vector Fields
Milvus • consulta: 2026-10-06
FundamentosÍndices vetoriais e opções de busca em Milvus.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.