← Back to learning path
Case · Published

Case study: blue-green RAG index release and rollback

Build and sample-check a new index, then switch safely with a version pointer.

Source: knowledge/p24-b/collection_6e8fbe1e8b1ea569a539e8a5/cases/rag-index-blue-green-release.mdRAG knowledge engineering
Chapter progress 0%Learning path progress 0% · 0/10 chapters completedContinue learning path →

Problem and boundaries

The knowledge base is updated every day. Overwriting an index in place can expose partial results, so a new version must be built in an isolated directory, checked, and promoted only after it is healthy; failures must return to the previous version.

Design

Each index directory contains manifest.json, chunks.jsonl, and health-check results. current.json stores only the active version pointer. Promotion is one atomic file replacement.

Minimal implementation

import json
from pathlib import Path

def promote(root: Path, version: str) -> None:
    manifest = json.loads((root / version / 'manifest.json').read_text())
    if manifest.get('status') != 'healthy':
        raise ValueError('index is not healthy')
    tmp = root / 'current.json.tmp'
    tmp.write_text(json.dumps({'version': version}))
    tmp.replace(root / 'current.json')

Reproduction steps

  1. Write the input snapshot and build parameters into a new version directory.
  2. Check document count, chunk count, sampled retrieval, and permission filters.
  3. Mark the version healthy, then atomically replace current.json.
  4. Watch error rate and zero-result searches; on an anomaly, point current.json back to the old version.

Verification checklist

Verify that an interrupted build leaves current.json unchanged, a damaged manifest cannot be promoted, the old version remains readable after rollback, and cache keys include the index version.

Common questions

Why not use a database transaction? A production system can use a database pointer; this case uses a file pointer to make the atomic-switch idea explicit.

Does rollback delete the new index? No. Keep it until the rollback window ends and backups are complete.

Official references

OpenAI Production best practices; OpenAI Embeddings.

Last checked: 2026-11-16. Follow the linked sources for current interfaces and security boundaries; this case makes no performance or cost claim.

Prerequisite tutorials

KnowledgeRAG production pipeline: updates, cache, and rollback

Further reading

KnowledgeRAG for Enterprise Knowledge: Architecture and PracticeKnowledgeAI Agents: From Core Concepts to ProductionKnowledgeDesigning Reliable AI Automation Workflows
Product Hub Demo · V0.3