Procedura

Runbook: odtworzenie indeksu i grafu (RAG/GraphRAG)

Klasyczna robota operacyjna: snapshot, build, verify, cutover. Bez skrótów — bo skróty w wiedzy kończą się incydentem.

Czas czytania: ~10 min Aktualizacja: 2026-01-10
Wersje i bezpieczeństwo
  • SSOT snapshot jest obowiązkowy (doc@ver + ACL).
  • Blue/green lub canary — nigdy „in‑place rebuild”.
  • Golden set jest bramką; bez tego nie ma cutover.
  • Rollback przygotowany przed startem budowy.
Tryb bezpieczny: snapshot → build → verify → cutover (z rollback).
Tryb bezpieczny: snapshot → build → verify → cutover (z rollback).
To jest runbook. Zakładamy, że działasz w trybie produkcyjnym lub blisko produkcji. Priorytetem jest kontrola ryzyka: wersje, ślady, bramki i możliwość natychmiastowego rollback.

1. Kiedy uruchamiać runbook

  • Spadek retrieval success / evidence coverage po zmianie indeksu lub SSOT.
  • Wysoki odsetek krawędzi bez provenance po aktualizacji ekstrakcji relacji.
  • Zmiana embedding modelu / chunkingu / ontologii wymagająca pełnego rebuild.

2. Warunki wstępne

  • Snapshot SSOT (doc@ver, ACL) — jednoznaczny punkt odniesienia.
  • Okno zamrożenia publikacji (freeze) na czas budowy.
  • Blue/green lub canary: nowy indeks i graf uruchamiasz obok starego.
  • Golden set i minimalne progi akceptacji.

3. Kroki: snapshot → build → verify → cutover

3.1 Snapshot i identyfikatory

  • Wygeneruj ssot_snapshot_id oraz listę plików doc@ver.
  • Zapisz bieżące wersje: embedding, chunking, ontologia, polityki.

3.2 Budowa indeksu (vector)

  1. Chunking zgodny z aktualnym standardem (spójne cytowania).
  2. Embedding + zapis metadanych: doc_id, version, chunk_id, ACL.
  3. Walidacja: brak pustych chunków, brak PII w polach indeksu.

3.3 Budowa grafu

  1. Ekstrakcja encji: mapowanie do ID (entity registry).
  2. Ekstrakcja relacji: każda krawędź musi mieć provenance (doc@ver + fragment).
  3. Walidacja schematu: constraints ontologii, brak relacji „unknown”.

3.4 Verify: golden set + sanity checks

  • Uruchom golden set: retrieval, coverage, path validity.
  • Sprawdź próbkę manualną (10 przypadków): cytowania prowadzą do właściwych fragmentów.

3.5 Cutover: canary → pełne przełączenie

  • Włącz canary (np. 5–10% ruchu) na nowy indeks/graf.
  • Porównaj SLO w czasie rzeczywistym: różnica > próg = rollback.
  • Po stabilizacji przełącz 100% ruchu.

4. Rollback

Rollback jest częścią procedury, nie porażką. Minimalny standard:

  • Stary indeks/graf utrzymujesz przez co najmniej jeden cykl wydawniczy.
  • Wpisujesz decyzję do rejestru zmian wraz z trace_id próbki incydentu.

5. Artefakty po wykonaniu

  • index_build_id, graph_build_id, ssot_snapshot_id
  • Raport regresji (golden set) + metryki porównawcze.
  • Wpis do Rejestru zmian.

6. Checklista

  • Snapshot SSOT zapisany (doc@ver, ACL, freeze).
  • Index i graph zbudowane w trybie blue/green.
  • Golden set przeszedł progi minimalne.
  • Canary stabilny; w razie potrzeby rollback wykonany.
Co najczęściej psuje produkcję
  1. Reindeksacja bez wersji (brak porównania).
  2. Krawędzie grafu bez provenance.
  3. Zmiana chunkingu bez aktualizacji cytowań.
Powiązane
Cykl życia SSOT Kontrakt cytowań i provenance Ewaluacja RAG Ewaluacja GraphRAG Monitoring retrieval i GraphRAG