An embedding model transforms an input—such as text, an image, or audio—into a fixed-length vector. During training, the model learns a geometry useful for particular similarity tasks. Results depend on the exact model, revision, preprocessing, input type, language, truncation, and task instructions, so every stored embedding needs versioned provenance.
Tokens are the model's input units. Dimensions are the number of numbers in the output vector. A 200-token passage can produce a 1,024-dimensional vector; those quantities describe different stages.
Models may distinguish document and query inputs through prefixes or parameters. If the model expects search_document: and search_query: instructions, omitting them can reduce retrieval quality even though dimensions still match.
At minimum:
For derived rows, also store source checksum, chunker version, embedded timestamp, and model ID. The vector column's dimension enforces shape, but shape alone cannot prove that query and document embeddings share the same semantic space.
It means the model's learned representation places two inputs near one another under a chosen metric. That can reflect topic, intent, style, syntax, image content, or training artifacts. It does not prove equivalence, truth, causation, safety, or authorization. Measure whether neighborhoods serve your task with labeled examples.
Unit tests can use a deterministic fake embedder:
This tests plumbing, dimensions, idempotency, and SQL parameters—not semantic quality. Integration and retrieval evaluations must use the intended embedding model and representative data.
Embed the same input twice with identical settings; compare vectors or provider guarantees. Embed it after changing whitespace, case policy, task prefix, or model revision. Record what changes. Query the vector length in application code and compare it with the PostgreSQL column definition before any insert.
Design an EmbeddingProvider interface for [Python/TypeScript]. It must expose model identity, revision, dimensions, supported input types, maximum input policy, document/query modes, batch embedding, and typed errors. Include a deterministic fake for unit tests. Do not include real API keys or assume retries are always safe.
Verification contract: Tests must reject a wrong-length vector, distinguish query and document modes, and prove that cache keys include model revision and preprocessing version.