Skip to content
⚠️ Before You Start
Risk: High
Duration: 1-3 days hands-on, plus re-embedding time
Last Validated: Not yet validated (draft)
Kind: Runbook
Risk Note: High (query and document vectors from different models give silently wrong results to every user)

Upgrade the embedding model and re-embed the corpus

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-13). Author: Yogeshwaran · dry-run: Ranjith · sign-off: Kranthi. Work items: RAG-09-T05, RAG-09-T06, RAG-09-T07, RAG-09-T08.

1. Summary

The embedding model is being retired, a better or cheaper model is chosen, or vector dimensions or compression must change.

Risk: High (query and document vectors from different models give silently wrong results to every user). Typical duration: 1-3 days hands-on, plus re-embedding time.

2. When to use and when not to

Use it when: The embedding model is being retired, a better or cheaper model is chosen, or vector dimensions or compression must change.

Do not use it when: to be written by the author.

3. What you must know first

  • Query vectors and document vectors must come from the same model with the same dimensions
  • A vector field's dimensions must match the embedding skill output; a change means a new field or a new index
  • Defining the vectorizer on the index lets one alias switch move documents and queries together
  • The text-embedding-3 models support a range of dimensions; truncation is a separate compression setting
  • Re-embedding bills every chunk again; estimate tokens before you start
  • Quantisation needs a new vector profile and a new vector field

4. Prerequisites and access

  • New embedding model deployed with enough tokens-per-minute quota for the corpus
  • Token estimate and cost approval for re-embedding the whole corpus
  • Golden set with relevance labels (PB-RAG-08-02)
  • PB-RAG-09-01 rehearsed in the sandbox
  • Queries vectorised by the index vectorizer, or a plan to switch query-side code at the same moment

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Inventory every index, field and client that uses the current embedding model.
  2. Estimate corpus tokens and get cost approval.
  3. Benchmark the new model on the golden set in a sandbox index.
  4. Create a new index with the new vector field, dimensions, profile and vectorizer.
  5. Create a new skillset whose embedding skill uses the new deployment, and a new indexer.
  6. Re-embed the corpus while watching quota errors and skill throttling.
  7. Verify document counts, vector index size and golden-set quality on the new index.
  8. Switch the alias (PB-RAG-09-01 steps 9-10) so index, vectors and vectorizer change together.
  9. Watch quality and latency for 24-72 hours; roll back by repointing the alias.
  10. Remove the old index and the old model deployment after sign-off.

Draft snippet: Index fragment: new vector field with an Azure OpenAI vectorizer

{
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "chunk", "type": "Edm.String", "searchable": true },
    {
      "name": "contentVector3L",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": false,
      "dimensions": 3072,
      "vectorSearchProfile": "hnsw-te3l"
    }
  ],
  "vectorSearch": {
    "algorithms": [ { "name": "hnsw-default", "kind": "hnsw" } ],
    "vectorizers": [
      {
        "name": "te3l-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "${AZURE_OPENAI_ENDPOINT}",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    ],
    "profiles": [ { "name": "hnsw-te3l", "algorithm": "hnsw-default", "vectorizer": "te3l-vectorizer" } ]
  }
}

Snippets to add:

  • snippets/defs/after/index-kb-v2-vectors.json: New index fragment with vector field, profile and vectorizer (json)
  • snippets/ops/estimate_embedding_tokens.py: Corpus token estimate for re-embedding (python)
  • snippets/ops/queries/embedding-errors.kql: Embedding deployment errors during re-embedding (kql)

6. Monitoring and alerts

Signal Alert when Action
SkillExecutionCount where Failed = true for the new skillset More than 0 over 15 minutes Check indexer status errors and embedding quota.
IndexVectorUsage (platform metric) Above 80% of vector quota Stop the indexer and add capacity or compression.
AzureOpenAIRequests client errors on the embedding deployment Above 1% of requests for 15 minutes Check quota and throttling; slow the indexer.

7. Rollback

To be written by the author: how to undo each risky step.

8. Known issues and fixes

Symptom Likely cause Fix
Relevance collapses straight after the switch The application still embeds queries with the old model Roll back now; then use the index vectorizer for queries or release query-side code with the alias switch.
Indexer errors on the vector field Embedding output dimensions do not match the field definition Set the same dimensions in the embedding skill and the field.
Embedding skill throttled Deployment quota too low for bulk re-embedding Raise tokens-per-minute quota, lower batchSize and run off-peak.
Indexing fails part way with a vector quota error Larger vectors or two copies exceed the per-partition vector quota Add a partition, use quantisation or choose smaller dimensions.

9. AWS and open-source equivalents

Amazon Bedrock Knowledge Bases configures the embedding model when the knowledge base is created, so plan a new knowledge base and a configuration switch, and confirm in current docs. In OpenSearch, create a new index with the new knn_vector dimension, re-ingest and swap the alias. With pgvector, add a new vector column or table, build the HNSW index concurrently and switch a view.

10. Validation record

Pending. Planned dry-run scenario: A second engineer moves a sandbox index from one embedding model to another, including a deliberate mismatch test where the app embeds queries with the old model. Pass: the golden-set check catches the mismatch before the switch, the correct switch shows no failed queries, and rollback works.

11. Sources