RAG · VECTOR DATABASE · PGVECTOR · OPENROUTER EMBEDDINGS
text-embedding-3-small · 1536 dimensões · similaridade cosseno
Fluxo de Embedding para Banco Vetorial
Como texto vira vetor numérico, como vetores são armazenados em PostgreSQL com pgvector, e como a busca semântica funciona
FASE 1 — INDEXAÇÃO · addDocuments() · acontece uma vez, quando os documentos são carregados
DOCUMENTO
CHUNKING
MODELO DE EMBEDDING
VETOR NUMÉRICO
BANCO VETORIAL
GRAVADO
📄 Document
{ pageContent, metadata }
pageContent: "O embedding..."
metadata: { source, page }
só carrega o texto — sem vetor ainda
✂️ Chunking / Split
RecursiveCharacterTextSplitter
chunkSize: 1000 chars
chunkOverlap: 200 (contexto entre chunks)
1 doc → N trechos menores
🤖 createEmbeddings()
OpenAI via OpenRouter
model: text-embedding-3-small
recebe: string (pageContent do chunk)
retorna: número[] com 1536 valores
POST /v1/embeddings → {"embedding":[...]}
🔢 Vetor 1536-D
representação semântica do texto
[0.023, -0.417, 0.891, 0.104,
0.332, -0.076, 0.558, ...,
/* 1536 números no total */]
cada número = 1 dimensão do espaço semântico
🗄 PGVectorStore
.initialize(client, embeddings)
guarda o cliente (embeddings)
conecta ao PostgreSQL via pool
tableName: "rag_trechos"
armazena client para reuso na busca
💾 rag_trechos
INSERT INTO
id: uuid
content: "O embed..."
embedding: [0.023,...]
metadata: {source}
💡 O QUE É O ESPAÇO VETORIAL?
Cada texto é transformado em um ponto num espaço de 1536 dimensões. Textos com significado similar ficam próximos nesse espaço — independentemente das palavras exatas usadas.
Ex: "cão" e "cachorro" ficam próximos. "cão" e "banco de dados" ficam distantes. A distância é medida pelo ângulo entre os vetores — isso é a similaridade cosseno.
"cachorro" (similar)
"cão" (origem)
"banco de dados" (distante)
ângulo ≈ 5°
cos ≈ 0.99
ângulo ≈ 75°
cos ≈ 0.26
cos(θ) = 1 → idêntico
cos(θ) = 0 → sem relação
cos(θ) = -1 → opostos
FASE 2 — BUSCA SEMÂNTICA · similaritySearchWithScore() · acontece a cada consulta do usuário
PERGUNTA
MESMO MODELO
VETOR DA QUERY
COMPARAÇÃO pgvector
TOP-K RESULTS
RESPOSTA
💬 Pergunta do Usuário
string de texto livre
"Como funciona o
embedding vetorial?"
passa direto para embeddings
🤖 createEmbeddings()
MESMO cliente da indexação
⚠ obrigatório usar o mesmo modelo!
vetores de modelos diferentes
não são comparáveis entre si
text-embedding-3-small → 1536-D
🔢 Vetor da Query
mesmas 1536 dimensões
query_vec = [-0.112, 0.834,
0.203, -0.551, 0.717,...]
representa o "significado" da pergunta
no mesmo espaço dos docs indexados
🔍 pgvector
1 - (embedding <=> query_vec)
operador <=> = distância cosseno
compara query_vec com TODOS os
embeddings da tabela rag_trechos
ORDER BY dist LIMIT k
📊 Top-K Resultados
[Document, score][]
1. score: 0.94 — trecho mais próximo
2. score: 0.87 — segundo mais próximo
3. score: 0.81 — terceiro mais próximo
k=4 por padrão · filtrável por threshold
✅ Contexto + LLM
RAG completo
trechos relevantes →
injetados no prompt
LLM responde com
contexto real do doc
SQL GERADO PELO pgvector
SELECT content, metadata,
1 - (embedding <=> '[0.023,...]'::vector) AS score
FROM rag_trechos
ORDER BY embedding <=> '[0.023,...]'::vector
LIMIT 4;
<=> é o operador de distância cosseno do pgvector · IVFFlat index acelera a busca
SCHEMA DA TABELA rag_trechos
id UUID PRIMARY KEY
content TEXT
embedding VECTOR(1536) ← pgvector
metadata JSONB
created_at TIMESTAMPTZ DEFAULT now()
CREATE INDEX ON rag_trechos USING ivfflat (embedding vector_cosine_ops)
LEGENDA E CONCEITOS-CHAVE
Documento de entrada
Modelo de embedding (OpenRouter)
pgvector / PGVectorStore
Resultado / RAG completo
Embedding:
vetor de floats que representa o significado semântico de um texto
Similaridade cosseno:
cos(θ) entre dois vetores · 1 = idêntico · 0 = sem relação · -1 = oposto
RAG:
Retrieval-Augmented Generation — LLM responde com contexto recuperado do banco vetorial
Chunking:
divisão do doc em trechos menores (chunk) para granularidade fina na busca
⚠ indexação e busca DEVEM usar o mesmo modelo — vetores de modelos distintos não são comparáveis
EMBEDDING FLOW
·
text → vector(1536) → pgvector → similaritySearchWithScore → RAG
OpenRouter · text-embedding-3-small · PostgreSQL + pgvector