What Are Embeddings?
Understand vector representations and semantic retrieval, including the limits of similarity scores and document search.
Before you start: Large language models · Basic JavaScript for the example. Reading time is an estimate; allow extra time for practice.
What you’ll learn
- Explain embeddings as learned numerical representations for comparison.
- Calculate and interpret cosine similarity on small illustrative vectors.
- Design a retrieval pipeline that preserves source versions and permissions.
- Evaluate retrieved passages separately from a generated answer.
On this page
Represent meaning for a particular task
A user searches for “recover my login,” while the relevant page is titled “Reset your password.” Keyword overlap may be small even though the intent is related. Embeddings can help retrieve this page by representing texts in a space where useful relationships are easier to compare. Whether they succeed must still be tested on your documents and questions.
An embedding is a numerical vector representing an item such as a passage, image or query. An embedding model learns representations that can make useful relationships easier to compare. For text retrieval, related questions and passages should often be close according to the chosen similarity measure, even when their wording differs.
Vector dimensions are not usually human-readable categories. You cannot generally label one coordinate “billing” and another “JavaScript”. The representation depends on the model and its training objective. Vectors produced by different models are not automatically comparable, even when their lengths match.
Build a small document-search pipeline
Split approved documents into coherent passages, keeping titles, version information and source URLs. Embed the passages and store their vectors with that metadata. Embed the query using a compatible model, retrieve candidates, and optionally rerank them. The result is a set of candidate sources, not yet a verified answer.
Chunk boundaries matter. A passage containing “this does not apply” without the preceding condition is misleading. Avoid splitting a function signature from its explanation or dropping a heading that establishes the library version. Keep document permissions with every chunk and enforce them during retrieval.
function cosine(a, b) {
if (!a.length || a.length !== b.length) throw new Error('Shape mismatch');
if (![...a, ...b].every(Number.isFinite)) throw new Error('Non-finite value');
const dot = a.reduce((sum, value, i) => sum + value * b[i], 0);
const norm = Math.hypot(...a) * Math.hypot(...b);
if (!norm) throw new Error('Zero vector');
return dot / norm;
}
console.log(cosine([1, 0], [0, 1])); // 0
console.log(cosine([1, 0], [2, 0])); // 1
console.log(cosine([1, 0], [-1, 0])); // -1Run in Node.js or a browser console; expected output is 0, 1, then -1. These small hand-written vectors demonstrate angle comparison, not learned semantic meaning. The function rejects empty, mismatched, zero and non-finite inputs; it assumes ordinary small finite arrays and is not numerically robust for extreme magnitudes or large vectors. Use a tested numerical implementation and the metric recommended for a real embedding model.
Similarity is not truth
A high similarity score means closeness under a representation and metric. It is not the probability that a document is correct or that it answers the question. “Enable deletion” and “do not enable deletion” can share many concepts while recommending opposite actions. Old documentation can be highly relevant and still describe the wrong version.
Evaluate retrieval separately from generation. For a collection of real questions, identify acceptable source passages and check whether they appear among the retrieved results. Include exact identifiers, rare error codes and questions outside the collection. Keyword or hybrid search can outperform purely semantic retrieval for some of those cases.
Keep the index aligned with the source
When documents change, update or remove their indexed passages. When an embedding model changes, plan to rebuild compatible vectors and evaluate the new retrieval behaviour. Store model identity and source revision so you can investigate why an answer used a stale passage.
Embeddings are not a privacy guarantee. Protect the source text, stored vectors and retrieval logs according to the information they represent. A retrieval-augmented generator should expose useful citations and decline unsupported questions rather than treating the nearest available result as sufficient evidence.
Understand what the similarity calculation means
Cosine similarity divides the dot product of two vectors by the product of their lengths. For ordinary nonzero finite vectors, its mathematical range is −1 to 1: identical directions score 1, perpendicular directions score 0 and opposite directions score −1. Scaling [1, 0] to [2, 0] changes its length but not its direction, which is why their cosine is 1.
A text embedding model learns the representation; cosine merely compares the resulting coordinates. There is no universal score such as 0.8 that proves a passage answers a question. Score distributions depend on the model, collection and query. Select any acceptance threshold using labeled retrieval examples, including questions that have no answer in the collection.
For a small documentation experiment, write five questions and the acceptable passage IDs before searching. Request the top three permitted candidates and count how many answerable questions have a supporting passage among them. Also inspect the unanswerable questions: retrieving a nearest neighbor is not a reason to manufacture an answer. This separates missing-source failures from mistakes made after a good source was retrieved.
Try it yourself
Create five queries for a tiny documentation collection: a synonym, an exact function name, a version-specific question, a negated instruction and an unanswerable question.
Show hint
Write the expected source before running search. Inspect the retrieved passages even if a generated answer sounds correct; otherwise generation can hide retrieval failures.
Check your understanding
5 questions to revisit the ideas. No score is saved, and you can retry. This is separate from Skill Quiz; it does not award XP or unlock guides.
Related programming documentation
Sources & further reading
Primary references for the concepts in this guide. Examples and exercises are illustrative; verify provider-specific behaviour against the version you use.