Versioning RAG Systems and Indexes

Versioning a RAG system means tracking the corpus, embeddings (and embedding model), prompts and serving code as one reproducible unit so a change can be audited and rolled back. Without it, a “successful” deploy can still serve stale chunks or a mismatched embedding space. Huwiler et al.’s VersionRAG paper (arXiv 2510.08109, 2025) shows naive RAG scoring 58% on their VersionQA set versus 90% for a version-aware approach — evidence that version conflation is a real failure mode, not a theoretical one. This page is the ship unit, not the research graph. It sits under RAG in production.

What should you version in a RAG system?

Four surfaces that change behaviour must move together. Dharmendra’s agentic-versioning write-up and Vention’s enterprise guide both treat code alone as insufficient — prompts, RAG config and model identities control behaviour outside the repo:

• Corpus / documents — content hash, document_id, and version or as-of timestamp on every chunk (Chatnexus version metadata; Particula registry).
• Embeddings + embedding model id — model_version on every vector; different models are incompatible spaces (DBI Services, captured 28 July 2026).
• Prompts — system and retrieval-assembly templates with SemVer or commit id (Maxim, 2025).
• Serving code and retrieval config — chunking params, top-k, filters (Dharmendra; Vention).

Where that unit ships is deployment.

How do you version the corpus and the index?

Put a version identifier on every indexed chunk and update by delta, not by full rebuild. Chatnexus names two strategies: snapshot versioning (periodic full index labelled by date or build — easy rollback, more storage) and delta versioning (re-embed only changed documents via a change log — efficient, needs robust change capture). Particula’s operational pattern: metadata registry (document_id, content_hash, ingestion timestamp) → hash-detect change → delete old vectors by document_id → insert new. Vector stores Weaviate, Pinecone, Qdrant and Milvus all support continuous insert in the guides reviewed here. Particula attributes incremental updates as “minutes instead of hours” in systems they audited — their claim; verify on your corpus. Full rebuilds remain required when the embedding model or chunking strategy changes (Particula FAQ). VersionRAG’s conflation failure (naive RAG 58% vs VersionRAG 90% on VersionQA) is why metadata filters and as-of retrieval matter; the graph method itself is out of scope here. Retrieval caches must key on index version — see caching.

How do you version embeddings when the model changes?

Never mix embeddings from two models in one query path — different models produce incompatible vector spaces (DBI Services). The upgrade path DBI spells out: (1) write new embeddings with a new model_version alongside the old; (2) build a separate index or partial index for the new model; (3) shadow — query both, serve old, compare quality; (4) cut over is_current / switch namespace; (5) stop writing the old model. Particula’s prod-v1 / prod-v2 namespace pattern is the same idea. Re-embed the corpus once under the new model; content deltas continue afterward. Gate the cutover on offline eval in CI/CD. Do not invent nDCG deltas for your upgrade.

How do you version prompts in a RAG pipeline?

Treat the RAG system prompt and retrieval-assembly templates as versioned artefacts — SemVer or git commit — not strings hardcoded in a deploy. Maxim’s 2025 practices: major / minor / patch for structural versus tweak changes; a change log (what / why / who); feature-flag or A/B swap without redeploying the whole service; rollback to last known-good. Chatnexus injects document-version tags into the prompt when answering as-of a date. Tie prompt version into the same ship unit as corpus and model so a bad prompt change is attributable in traces. Comparing prompt variants on live traffic is A/B testing.

How do you make a RAG change reproducible and reversible?

A change is reproducible when you can name the exact corpus version, embedding model_version, prompt version and code commit that produced an answer — and reversible when you can flip traffic back to the previous bundle. Tag every release with those four ids; keep the previous index namespace / is_current=true bundle warm; gate the cutover on offline eval; retain short-term prior document versions. Particula’s guidance is a 7–14 day keep window before purging old document versions — attribute as theirs. VersionRAG’s failure mode without this discipline is version conflation with no clean rollback. Detect live regressions with monitoring and reconstruct a bad answer with observability; ship through deployment and CI/CD.