Skip to content

model-change.md

Latest commit

 

History

History
50 lines (41 loc) · 2.2 KB

model-change.md

File metadata and controls

50 lines (41 loc) · 2.2 KB
Raw

Model-change maintenance

Normal migration and seed are fail-closed. If the manifest profile ID, fingerprint, or dimension differs from the one active database row, scripts/migrate.py refuses to proceed and points to the maintenance command. It never silently applies a changed same-ID model over existing vectors.

Model changes are downtime operations:

  1. Update and commit rag-engine.yaml, including the artifact revision and SHA-256.

  2. Disable the scheduler, wait for Workflow syncs to finish, and stop MCP traffic.

  3. From that same revision, build and deploy the updated single rag-embeddings service. Auto-deploy is off for that service, so trigger it by hand.

  4. Run:

    python scripts/change_embedding_profile.py \
  --confirm-maintenance --max-pages 1000

    If the vector dimension changes, also pass the exact requested dimension. It must already match content.embedding.dimension in rag-engine.yaml from step 1 — the script requires the two to agree, and the shipped manifest is 768:

    python scripts/change_embedding_profile.py \
  --confirm-maintenance --confirm-dimension 1024

  5. Run python scripts/doctor.py, then restore MCP traffic and scheduling.

Run the command from the same revision used to build the embedding image. It verifies that the one service advertises only the expected immutable alias and can produce the expected vector dimension. A new contract resets vectors once; a rerun that finds the target profile already active preserves completed vectors and continues pending work. If --max-pages is reached, the command prints progress, exits with status 2, and can be rerun until complete. Dead letters are preserved and reported as operator failures, never silently reset on a rerun. The vector column and HNSW index are rebuilt only for a confirmed dimension change. Completion requires zero pending, dead-letter, or mismatched chunks. There is no zero-downtime or rollback claim; restore from backup or repeat the maintenance procedure with the prior model if needed.

Semantic SQL joins each complete chunk to the one active profile and requires matching profile ID and fingerprint. Stale or partial vectors cannot be returned.