Vector Index Migration and Cutover Runbook (Handoff)

Vector Index Migration and Cutover Runbook (Handoff)

1. 01

   Freeze the source index and record a point-in-time snapshot with row counts per collection

   Capture embedding model name, vector dimensions, distance metric, and index parameters alongside the snapshot so the target build can be reproduced exactly rather than approximated.

2. 02

   Re-embed a 500 to 1,000 document sample on the target stack and diff similarity scores against the source

   A cosine or dot-product drift above roughly 0.02 on the same query set signals a model or normalization mismatch that will surface as wrong answers in the client's assistant.

3. 03

   Map every metadata field the client's filters depend on, then confirm the target supports the same filter operators

   Hybrid dense-sparse retrieval and payload filtering behave differently across engines, so a filter that works on one platform can silently return unfiltered results on another.

4. 04

   Run dual-write for a minimum of five business days before any read traffic moves

   Dual-write exposes ingestion lag, schema coercion errors, and rate-limit ceilings while the legacy system still serves production queries for the client.

5. 05

   Shift read traffic in 10 percent increments, watching p95 latency and recall on a fixed 50-query evaluation set

   Hold each increment for at least 24 hours; rollback is a routing change, not a rebuild, as long as dual-write stays live.

6. 06

   Retire the legacy index only after two consecutive clean weeks and a signed client acceptance note

   Keep the final snapshot in cold storage for 90 days in case the client disputes retrieval behavior during the first billing cycle on the new stack.

7. 07

   Hand the client a one-page operations sheet covering backup cadence, scaling triggers, and who owns reindexing

   Name the specific person on the agency side and the client side; unnamed ownership is the most common cause of a stalled post-cutover fix.