Systems labIntermediate90 min estimateOriginal publication

The Embedding Contract

A vector has meaning only inside the exact task, transformation, and comparison policy that produced it.

Authorship: InterviewsVector
Published / updated: 2026-09-20 / 2026-09-20
Review status: Artifact tests passing · primary sources recorded

Original InterviewsVector teaching. Executable illustrative contracts are covered by focused tests and primary sources are recorded. No named human review, benchmark result, or production certification is claimed.

The decision in one pass

Treat an embedding as a versioned interface, not a portable array of floats. Bind the retrieval task, model and weights revision, query-versus-document treatment, preprocessing, tokenizer, truncation, pooling, output dimension, normalization, distance metric, and source content identity. A query vector and an indexed document vector are comparable only when their contracts are compatible. Changing any behavior-bearing field creates a new embedding space and normally requires a separately built index, qualified retrieval evidence, a controlled read cutover, and a rollback route. Equal dimensions or a successful dot product prove structural compatibility only; they do not prove semantic quality.

Why this matters

Embedding failures often look plausible. A mixed index can return neighbors, a swapped metric can produce sorted scores, and a new model can emit the same dimension while changing the geometry completely. Without an explicit contract, these changes become silent corpus corruption rather than observable migrations.

You will be able to

Separate tokenization, pooling, normalization, and comparison into explicit representation boundaries.
Derive when cosine, inner product, and squared L2 produce comparable or different rankings.
Bind query and document embeddings to source and contract content identities.
Plan dual-write, backfill, validation, read cutover, and rollback for an embedding migration.
Distinguish structural validation from retrieval-quality evidence and production approval.

Prerequisite contract

Your Vector Loop for this lab

01
Model
Name the retrieval task and draw the text-to-vector path for queries and documents separately.
02
Derive
Derive dimensions, normalization invariants, metric semantics, and the evidence required for cross-version comparability.
03
Build
Create a content-addressed contract and bind every vector record to it and to its source revision.
04
Stress
Mix revisions, swap roles and metrics, alter prefixes, poison numbers, truncate inputs, and bypass constructors.
05
Operate
Run old and new indexes in parallel, monitor slice recall and drift, cut reads over explicitly, and retain rollback.
06
Defend
State what local validation proves, what offline retrieval evidence adds, and what remains a release decision.

An embedding space is task-conditioned

An encoder maps an input sequence into hidden states; pooling maps those states into a fixed-width representation; optional normalization changes the geometry used by the index. The learned objective and input convention determine what proximity tends to preserve. A representation trained for semantic textual similarity is not automatically the right interface for asymmetric question-to-passage retrieval, classification, clustering, or deduplication.

Contract field	Why it changes behavior	Failure when omitted
task and role	query and document inputs may use different encoders, prefixes, or instructions	same text is embedded with the wrong side of the retrieval objective
model and weights revision	training data and geometry can change without changing the API name	new queries search an old vector space
preprocessing and tokenizer	normalization, segmentation, and truncation change model input	source revisions map to untracked vectors
pooling and dimension	token states are reduced into a particular coordinate interface	shape-compatible but semantically different arrays are mixed
normalization and metric	score magnitude and ranking semantics depend on both	thresholds and rankings silently move

Derive the score you are actually ranking

cos(q,d) = (q·d)/(||q||₂||d||₂); IP(q,d)=q·d; L2²(q,d)=Σᵢ(qᵢ-dᵢ)²

For unit-normalized vectors, maximizing cosine and inner product gives the same order, while squared L2 is related by ||q-d||²=2-2q·d. Without fixed norms, inner product also rewards magnitude and these equivalences disappear.

Choose the metric used during evaluation and index construction; do not infer it from a column named score. If a provider supports reduced dimensions, truncation or projection is valid only when that model and dimension were designed and evaluated for it. Cropping arbitrary coordinates is not an interchangeable optimization merely because the resulting array is smaller.

Bind vectors to inputs and revisions

01Identify the sourceRecord a stable source ID, exact revision, access scope, and content digest before preprocessing.
02Identify the transformHash task, role, prefixes, preprocessing, tokenizer, truncation, pooling, normalization, model, and dimension.
03Identify the outputStore the vector with the contract digest and an immutable embedding identity; validate finite components and exact dimension.
04Qualify the spaceMeasure held-out retrieval outcomes by task slice and compare the exact candidate index against a declared baseline.

A content digest is an identity check, not provenance by itself. The producer must still attest that the declared encoder actually processed the declared input. The teaching artifact accepts caller-supplied input digests and vectors, then checks their local bindings and deterministic ranking; it cannot authenticate the upstream inference run.

Re-embedding is a data migration

Never overwrite an active vector index in place. Expand first: create a new contract and index namespace, dual-write newly eligible content, and backfill immutable source revisions idempotently. Compare document counts, revision coverage, missing vectors, query slice recall, score distributions, latency, and access filtering. Shadow reads or route a bounded cohort before changing the default. Contract only after rollback and the compatibility window expire.

Stage	Forward evidence	Rollback anchor
expand	new schema accepts the new contract without changing readers	old writer and old index remain valid
backfill	every eligible source revision has one content-bound vector	restart from checkpoints; never infer completion from job exit
shadow	same queries evaluated against both spaces by slice	serve only the old index
cut over	new read alias and thresholds are explicit	atomically restore old read alias and policy
contract	retention, deletion, and audit obligations are satisfied	separate authorization after the rollback window

Run the structural contract

The executable fixture reconstructs frozen records at the public boundary, rejects string subclasses and non-finite or subnormal numbers, verifies exact contract digests and roles, enforces vector dimension and L2 normalization, and ranks a toy corpus deterministically. The output says structural compatibility only because no real encoder or held-out retrieval benchmark runs here.

embedding_contract.py

1def main():
2    contract = example_contract()
3    query, documents = example_records(contract)
4    result = audit(contract, query, documents)
5    print("example=illustrative_only")
6    print("contract=VALID")
7    print(f"dimension={result.dimension}")
8    print("metric=" + result.metric)
9    print("top_item=" + result.ranked[0].embedding_id)
10    print("claim=" + result.claim)

Expected output

example=illustrative_only
contract=VALID
dimension=3
metric=cosine
top_item=doc-policy
claim=STRUCTURAL_COMPATIBILITY_ONLY

Verify: python3 -m unittest discover courses/ai-engineering/reference-impl/embedding_contract

Observe comparability and task outcomes separately

At runtime, count writes and reads by contract digest, reject mixed-version search requests, and alert on missing source revisions, wrong dimensions, norm drift, non-finite values, and stale backfills. Separately measure retrieval recall, precision, downstream answer support, language and tenant slices, latency, and cost. Structural health cannot substitute for task evidence, and average task evidence cannot waive access controls or deletion semantics.

Operate at three altitudes

Production lens

— Attach the contract digest to every vector write, index build, query, result trace, and offline evaluation.
— Reject mixed spaces at the boundary and monitor source-to-vector coverage before switching a read alias.
— Evaluate query and document roles, truncation, multilingual cohorts, permissions, and stale source revisions separately.

Staff lens

— Make embedding upgrades governed data migrations with an owner, compatibility window, acceptance evidence, and funded rollback capacity.
— Require task-specific evaluation before reusing one representation across search, clustering, recommendations, and policy decisions.
— Separate authenticated lineage from hashes: identity without trusted production records is not provenance.

Interview defense

You must replace the embedding model behind a live retrieval system without corrupting search. What is your migration plan?

I define a new immutable contract covering task and query/document roles, model and tokenizer revisions, preprocessing, truncation, pooling, dimension, normalization, and metric. I create a separate index, dual-write new content, idempotently backfill exact source revisions, and reject cross-contract comparisons. I compare old and new spaces on held-out query slices plus coverage, latency, access filters, deletions, and downstream support. I shadow and canary before an explicit read-alias cutover, preserve the old index and thresholds for rollback, and contract only after the compatibility window. Shape checks prove compatibility, not quality.

Expect the interviewer to press on

— When do cosine and dot product rank identically?
— What must a vector digest bind?
— Why is equal dimension insufficient?

Misconceptions to remove

“Vectors with the same dimension can share an index.”

Dimension is only a shape check. Learned coordinates, preprocessing, roles, normalization, and metric must also be compatible.

“Cosine and dot product are always interchangeable.”

They rank identically under fixed positive norms such as unit normalization; otherwise magnitude changes inner-product ranking.

“A content hash proves the model generated the vector.”

It binds supplied content. Trusted execution and provenance records must attest that the declared transform ran.

Check your model

1. Why should query and document prefixes be versioned?

They change the encoder input and can be part of an asymmetric retrieval objective, so changing them changes the representation contract.

2. Can a new embedding model overwrite vectors in the active index?

No. Build a separately identified index, prove coverage and retrieval behavior, then perform an explicit reversible read cutover.

3. What does unit norm let you infer?

For unit vectors, cosine equals inner product and squared L2 is 2 minus twice their dot product, so their rankings are linked.

Prove the mechanism

Specify an embedding contract for multilingual support search. Include distinct query/document inputs, truncation, source revision, access scope, metric, and rollback. Design one test that catches each field changing silently.

Add a production constraint

Plan a two-week migration between spaces of different dimensions. Define idempotent backfill checkpoints, mixed-version rejection, shadow evaluation slices, alias cutover, rollback triggers, and the later contraction authorization.

Artifact: Versioned embedding contract

courses/ai-engineering/reference-impl/embedding_contract/embedding_contract.py

Download reference implementation

Primary references and next links

References

1. Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks
Reimers and Gurevych. Primary sentence-embedding work using independently encoded representations and cosine comparison.
2. Dense Passage Retrieval for Open-Domain Question Answering
Karpukhin et al.. Primary dual-encoder retrieval work separating question and passage representations.
3. Text Embeddings by Weakly-Supervised Contrastive Pre-training
Wang et al.. Primary E5 embedding work; its task results do not establish this lesson's illustrative contract.
4. Faiss Index documentation
Faiss. Official index interface documentation recording dimension and metric as index-level properties.

Continue through the graph

Approximate Nearest Neighbors Under a Latency Budget →
Carry the representation contract into index evaluation.
Chunking Is a Recall Policy →
Define which source unit the document encoder receives.

Glossary: embedding · dual encoder · pooling · cosine similarity · inner product · normalization · backfill · content digest