A Cloudflare Vectorize embedding migration changes how your application represents and retrieves information. Even when the new model accepts the same documents, its vectors and ranking behaviour can differ. Replacing the model name in a query path is not a complete migration plan.
Build a separate, versioned index for the new embedding configuration, backfill it from authoritative sources and keep updates and deletions reconciled while both paths exist. Compare retrieval on a representative question set, then switch the query and index configuration together. Keep a tested rollback path until the new results are accepted.
Imagine a documentation assistant moving to an embedding approach intended to handle a wider language mix. The existing index is serving customers. The team wants to improve relevant retrieval without making current manuals disappear, restoring deleted material or returning passages that the caller cannot access.
This article describes a proposed application migration procedure. It is not a claim that Vectorize automatically translates vectors between models or that a different embedding model will necessarily improve your results.
Cloudflare Vectorize embedding migration begins with a contract
Cloudflare’s index creation guidance documents dimensions and distance metric as index configuration, and states that those settings cannot be changed after creation. Confirm the selected model’s output and the intended index configuration before preparing the replacement.
Matching dimensions alone is not a compatibility test. The application should treat the embedding model, preprocessing, chunking and index as a versioned retrieval configuration. Queries need the corresponding representation used for the stored document vectors.
| Contract element | Record before migration | Why it matters |
|---|---|---|
| Source revision | Authoritative document identity and revision | Reproduces the material indexed |
| Processing | Extraction and chunking configuration | Explains changed passage boundaries |
| Embedding | Model and relevant configuration | Identifies the vector representation |
| Index | Name, dimensions and metric | Prevents mismatched query routing |
| Retrieval policy | Filters and result handling | Preserves access and application meaning |
The contract should be readable without inspecting the live deployment. A future engineer needs to establish which representation produced a result and which application release selected it.
Decide what the migration is meant to improve
Write down the problem with the current results. It might be poor retrieval for a particular language, weak handling of terminology or a model-support requirement. “Use a newer model” is not an acceptance criterion.
Build a question set that exposes the actual weakness and retains important existing cases. Include exact product references, unanswerable questions, restricted documents and examples from each relevant language. Have source owners identify useful evidence before comparing answers.
Evaluate retrieved passages independently of generated prose. A language model can make weak retrieval appear coherent. If the replacement finds worse evidence but produces smoother answers, the migration has not necessarily improved the application.
Record acceptable trade-offs. A gain in broad descriptive search may come with poorer exact-reference results. The owner should decide whether that trade-off is acceptable or whether the application needs a different retrieval strategy.
Build a parallel index from authoritative material
Create the replacement index under a distinct, traceable identity. Do not overwrite the only working representation before the new one has passed evaluation. Backfill from the source system or a documented source snapshot rather than treating the old vectors as the original documents.
Maintain stable mappings from source records to the chunks inserted into each index. A change in chunking can produce a different set of identifiers, so the deletion and replacement procedure must know which derived records belong to a source revision.
Keep the source snapshot and processing progress visible. An operator should be able to identify documents that were never processed, failed extraction or were rejected by the embedding path. A total vector count does not reveal whether the missing records are the important ones.
Cloudflare’s query guidance is the reference for using the resulting index. Test against the selected current API rather than assuming that a successful insertion immediately proves every query path is ready.
Reconcile changes while both representations exist
A backfill can take time while source documents continue changing. Decide how the replacement catches up. Options include a versioned change log or another deliberate synchronization process appropriate to the source system.
Track deletions explicitly. A document removed during backfill must not be reintroduced when an older snapshot item finishes processing later. Compare the source’s current revision and deletion state before accepting derived material.
| During-migration event | Required decision |
|---|---|
| Document added | Index it under the replacement contract |
| Document revised | Supersede the earlier representation deliberately |
| Document removed | Remove or exclude all relevant derived records |
| Permission changed | Apply current access rules to retrieval |
| Processing fails | Record the missing source and recovery action |
Do not claim the replacement is caught up solely because the backfill job exited successfully. Reconcile expected source identities and revisions against processing outcomes. Account for exceptions individually or through an explicit accepted policy.
Our RAG data freshness guide covers the ongoing update problem. The migration adds a second representation that must follow those same source rules until cutover and retirement are complete.
Compare retrieval under the same permissions
Run the old and replacement query paths against the same permitted question set. Keep the query embedding configuration paired with the correct index. A comparison using mismatched representations is measuring an integration defect rather than model quality.
Verify filters and source opening as well as ranking. Cloudflare’s metadata-filtering reference documents that mechanism; your application must preserve the access conditions required by the workload.
| Evaluation category | Evidence to compare |
|---|---|
| Relevant evidence | Whether a reviewer finds the needed source passage |
| Exact references | Whether adjacent product or error identifiers are confused |
| Unanswerable questions | Whether the system can return no usable evidence |
| Restricted material | Whether unauthorized passages and citations stay absent |
| Updated and deleted sources | Whether results match the accepted source state |
| Operational behaviour | End-to-end timing and explainable failures |
Keep the individual failed cases. An aggregate score can hide a commercially important regression, such as returning an obsolete instruction for a frequently used product. The owner should review those cases before accepting a switch.
Cut over a complete retrieval configuration
Switch the query embedding path, index selection and associated retrieval configuration together. Keep a single documented selector for the accepted version where practical. A partial deployment can send new query vectors to the old index or apply incompatible assumptions about stored metadata.
Start with a controlled rollout appropriate to the application’s risk. Compare observed results with the acceptance set and keep enough version information in traces to identify which path served a question.
Rollback should restore the complete previous configuration. Test it before relying on it. If the old index stopped receiving source changes during the trial, rolling back may restore stale or deleted material; document how that condition is prevented or reconciled.
Retire the older representation only after the agreed observation period and source review. Removing it is a separate operational step with its own retention and recovery implications. A successful switch does not automatically authorize deleting all previous evidence.
Estimate the migration rather than only the backfill
The project cost includes source reconciliation, processing, evaluation, controlled deployment and rollback. A quote covering only vector generation excludes the work that makes the migration trustworthy.
Request a GBP estimate using corpus size, source-change rate, supported languages, permission complexity and the quality of existing identifiers. Include temporary parallel storage and duplicated processing where the design requires them.
Verify current vendor rates for the actual embedding and storage configuration before quoting usage charges. Record assumptions about failed processing and reindexing. A model with a lower unit rate can still require more engineering if its results need a different processing pipeline.
We can scope a bounded migration assessment through our AI integration pilot . Request an embedding migration proposal with the current model, index contract, source-update process and failed search examples. Those details make the proposed improvement testable before the working system is replaced.
Frequently Asked Questions
Can we replace the embedding model without rebuilding the index? Do not assume compatibility. Treat the model and document representation as a versioned contract, and verify the replacement through a separately built index and retrieval evaluation. Matching vector dimensions does not establish equivalent meaning.
Can Vectorize index dimensions change in place? The current index-creation documentation says dimensions and distance metric cannot be changed after creation. Confirm the replacement model’s output and create an appropriate new index rather than planning an in-place configuration change.
Why keep the old index during migration? It provides a working comparison and potential rollback path while the replacement is evaluated. That path remains useful only if source updates, deletions and permissions are kept current or deliberately reconciled.
What happens to documents deleted during backfill? Track their deletion against the authoritative source state. An older snapshot item must not reintroduce removed material after deletion. Reconcile derived records and source revisions before accepting the replacement.
Should we compare generated answers or retrieved passages? Evaluate passages first, then the generated answers that use them. This distinguishes retrieval regressions from changes in summarization and prevents fluent prose from hiding missing or obsolete evidence.
What should rollback restore? Restore the complete previous retrieval configuration, including query embeddings, index selection and relevant metadata/filter assumptions. Verify that the restored path does not expose stale, deleted or newly restricted material.
What determines migration cost? Source quality, update frequency, processing changes, permission rules and evaluation requirements drive the work. Include parallel operation, deployment and rollback in a scoped GBP estimate rather than quoting vector generation alone.