Embeddings & Vector Search

The flow

1. 1.Chunk
2. 2.Embed
3. 3.Index
4. 4.Query vector
5. 5.Rank

Similarity is a retrieval signal

An embedding maps content to a numeric vector. A distance or similarity measure ranks candidates; it does not prove relevance, truth or access rights. Exact product codes may work better with lexical search than with embeddings alone.

Cosine compares direction; dot product also depends on magnitude unless vectors are normalized. Use the metric recommended for the embedding model and index. Reject mismatched dimensions and zero vectors where the metric is undefined.

Version the representation

Do not mix document vectors from one model with query vectors from another simply because their dimensions match. A model change usually requires re-embedding and a new index, followed by retrieval evaluation.

Store source ID, chunk boundary, embedding version and access metadata. Apply permissions in retrieval; filtering only after generation can already expose private evidence.

Measure retrieval separately

Approximate indexes trade recall for speed and memory. Measure recall@k against labeled queries before adding reranking or increasing k. Inspect failed exact-match, multilingual and rare-term queries separately.

Try it

import assert from 'node:assert/strict';
function cosine(a, b) {
  if (!a.length || a.length !== b.length || ![...a, ...b].every(Number.isFinite)) {
    throw new Error('Invalid vectors');
  }
  const norm = v => Math.hypot(...v);
  if (!norm(a) || !norm(b)) throw new Error('Zero vector');
  return a.reduce((sum, n, i) => sum + n * b[i], 0) / (norm(a) * norm(b));
}
// Hand-authored vectors demonstrate ranking; they are not real embeddings.
const query = [1, 0];
const documents = [{ id: 'java', vector: [0.9, 0.1] }, { id: 'cooking', vector: [0, 1] }];
const ranked = documents.map(d => ({ id: d.id, score: cosine(query, d.vector) }))
  .sort((a, b) => b.score - a.score);
assert.equal(ranked[0].id, 'java');
assert.throws(() => cosine([1], [1, 2]));
assert.throws(() => cosine([0, 0], [1, 0]));
console.log(ranked);

Run with Node.js 22: node examples/generative-ai/embeddings-vector-search.mjs. This is a deterministic teaching example, not a live model call.

Interview questions

Official references

• Spring AI — embeddings

Continue learning

• RAG Fundamentals →
• Context Engineering →