O que é um embedding

// dada a matriz [n_tokens x d] devolvida pelo modelo
const meanPool = (tokens, mask) => {
  const d = tokens[0].length;
  const acc = new Float32Array(d);
  let n = 0;
  tokens.forEach((t, i) => {
    if (!mask[i]) return;            // ignora padding
    for (let k = 0; k < d; k++) acc[k] += t[k];
    n++;
  });
  return Array.from(acc, (x) => x / (n || 1));
};

const l2 = (v) => {
  const norm = Math.hypot(...v) || 1;
  return v.map((x) => x / norm);       // ‖v̂‖ = 1
};

-- pgvector: a dimensão faz parte do tipo da coluna
CREATE TABLE chunks (
  id      bigserial PRIMARY KEY,
  doc_id  bigint NOT NULL,
  content text   NOT NULL,
  embedding vector(384)      -- fixa: mudar exige migração
);

-- half-precision corta a memória do índice pela metade
CREATE INDEX ON chunks
  USING hnsw ((embedding::halfvec(384)) halfvec_cosine_ops);

import numpy as np

def cosine(a, b):
    return float(a @ b / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-12))

# em lote: query [d] contra base [N, d] já normalizada
scores = base @ query            # [N]   um BLAS, não um loop
top    = np.argpartition(-scores, 10)[:10]
top    = top[np.argsort(-scores[top])]

-- pgvector: <=> é DISTÂNCIA de cosseno (1 - similaridade)
SELECT id, content,
       1 - (embedding <=> $1) AS similarity
FROM   chunks
ORDER BY embedding <=> $1       -- ASC: menor distância primeiro
LIMIT  10;

-- <#> = produto escalar negativo | <-> = L2
-- ORDER BY tem que usar o MESMO operador do índice,
-- senão o planner ignora o HNSW e faz seq scan.

import numpy as np

# base: [N, d] com TODAS as linhas normalizadas (L2)
def top_k(query, base, k=10):
    q = query / np.linalg.norm(query)
    scores = base @ q                        # O(N*d), mas em BLAS
    idx = np.argpartition(-scores, k)[:k]  # O(N), não O(N log N)
    return idx[np.argsort(-scores[idx])], scores

# medir recall do índice aproximado contra a verdade exata
def recall_at_k(approx_ids, exact_ids, k=10):
    return len(set(approx_ids[:k]) & set(exact_ids[:k])) / k

# CONSULTA   roda a cada pergunta (online)
def answer(question: str) -> str:
    qv   = embed(f"query: {question}")      # o outro prefixo
    hits = db.search(qv, k=20)                # pesca largo…
    hits = rerank(question, hits)[:5]        # …e refina com cross-encoder

    context = "\n\n---\n\n".join(
        f"[{h.doc_id}#{h.id}] {h.content}" for h in hits
    )
    return llm(
        system="Responda SÓ com base no contexto. Cite [doc#chunk]. "
               "Se o contexto não responder, diga que não sabe.",
        user=f"<contexto>\n{context}\n</contexto>\n\n{question}",
    )

# O reranker é um cross-encoder: lê pergunta E trecho JUNTOS.
# É lento demais para varrer a base (por isso o k=20 antes),
# e bem mais preciso que cosseno para ordenar o topo.

-- Híbrida: BM25 e vetorial em paralelo, fundidos por RRF.
-- score_rrf = Σ 1 / (k + posição), k=60 é o valor usual.
WITH lexical AS (
  SELECT id, row_number() OVER (
           ORDER BY ts_rank(tsv, websearch_to_tsquery($1)) DESC) AS pos
  FROM chunks WHERE tsv @@ websearch_to_tsquery($1) LIMIT 50
), semantic AS (
  SELECT id, row_number() OVER (ORDER BY embedding <=> $2) AS pos
  FROM chunks ORDER BY embedding <=> $2 LIMIT 50
)
SELECT c.id, c.content,
       coalesce(1.0 / (60 + l.pos), 0) +
       coalesce(1.0 / (60 + s.pos), 0) AS rrf
FROM chunks c
LEFT JOIN lexical  l ON l.id = c.id
LEFT JOIN semantic s ON s.id = c.id
WHERE l.id IS NOT NULL OR s.id IS NOT NULL
ORDER BY rrf DESC LIMIT 10;