Why Embedding Dimensions and Model Versions Matter in Production

A matching length is necessary but insufficient

You cannot compare a 384-dimensional vector with a 1,536-dimensional vector in the same distance operation. Padding with zeros is not a migration. Even equal-length vectors from different models may occupy unrelated spaces. Search queries and indexed documents need a compatible embedding contract.

Changing chunk preparation can also change retrieval behaviour without changing the model name. Removing quoted history or changing chunk boundaries affects what is embedded. A useful index manifest records the model, dimensions, preparation version and source revision together.

Validate before activating a replacement

The documented MailTrace approach builds an immutable replacement set and checks its scope and completeness before activation. A failed or partial build leaves the previous active index available. This avoids a state in which half a case silently uses an old representation and half uses a new one.

from math import isfinite

def validate_vector(vector, actual, expected):
    if actual != expected:
        raise ValueError("Embedding contract mismatch")
    if len(vector) != expected["dimensions"]:
        raise ValueError("Wrong vector length")
    if not all(isfinite(x) for x in vector) or not any(vector):
        raise ValueError("Invalid vector values")

contract = {"model": "synthetic-demo", "dimensions": 3,
            "preparation": "v1"}
validate_vector([1.0, 0.0, 0.0], contract, contract)

Treat a model change as a data migration

A reviewable migration creates a new generation, embeds eligible current sources, evaluates retrieval and switches readers only after validation. The old generation remains identifiable for rollback and for understanding earlier saved answers. Application-level source freshness still needs checking after the switch.

Operational readiness and retrieval quality are separate gates. A database accepting all vectors proves schema compatibility, not that the new model finds better evidence. Compare both generations on the same labelled questions and report latency, indexing cost and missed evidence. A version label is useful because it makes those comparisons reproducible.