Embedding drift is a day-one decision

The one rule

Never query against a mixed-version index. The moment two embedding model versions share an index, your similarity scores stop meaning one thing. Retrieval quality degrades in ways you cannot cleanly explain.

Three config fields and one job

Tag every chunk with its model version

At write time, every chunk records which embedding model produced it. That single field keeps versions separable forever. It costs nothing to add on day one.

Maintain parallel indexes during transitions

When you upgrade models, you build the new index alongside the old one. Queries route to a single, consistent version. No silent mixing, no mystery regressions.

Retire old indexes on a schedule

A background job, not a fire drill

Built in iteration 1, not iteration 7

A scheduled job retires stale indexes once a transition completes. This is three config fields and one background job. Skip it and you will rebuild the entire pipeline later, under pressure, while debugging degradation you cannot name.

Why we build it first

We have watched teams do the painful retrofit twice, and it is always avoidable. Getting this right early turns model upgrades into a routine operation. Your retrieval quality stays explainable as you grow.

The retrofit you are avoiding

Picture the retrofit you are signing up for by waiting. It is iteration seven, you have live users, and retrieval quality is sliding for reasons no dashboard explains. You discover two model versions have quietly shared one index for months.

Now every fix is a production migration. You re-embed the whole corpus while traffic flows, comparing scores that were never comparable in the first place. The version field and the parallel-index habit would have cost a few hours in week one, and they turn that future emergency into a scheduled, boring background job.

Common questions