94 lines
5.0 KiB
Markdown
94 lines
5.0 KiB
Markdown
# Spoločná synchronizácia RAG a GraphRAG
|
|
|
|
`POST /sync`, overený push webhook aj `python -m tools.rag.rebuild_index`
|
|
používajú spoločnú pipeline v `tools/sync_indexes.py`. Obnova vyžaduje dostupné
|
|
Neo4j a jeho konfiguráciu v prostredí. Pôvodné evaluačné výsledky sa nemenia.
|
|
|
|
## Priebeh
|
|
|
|
1. Procesový `.reindex.lock` pripustí iba jednu synchronizáciu nad data volume.
|
|
2. Voliteľný `git pull --ff-only` zachováva pôvodné nastavenie synchronizácie.
|
|
3. V `data/.sync-stage-*` vznikne kópia pôvodných README súborov. Dokumenty,
|
|
chunky, SQLite/FTS5 a embeddingy sa pripravujú z tejto jednej kópie. Aktívne
|
|
súbory sa počas prípravy nemenia a existujúce vyhľadávanie môže pokračovať.
|
|
4. Overí sa, že sa zdrojové súbory ani Git revízia počas prípravy nezmenili.
|
|
5. Pred aktiváciou vzniknú zálohy pôvodných súborov a trvalý marker
|
|
`.sync-pending.json`. Exkluzívny publikačný zámok počká na rozbehnutých
|
|
čitateľov. Nové požiadavky počas aktivácie dostanú dočasnú nedostupnosť.
|
|
6. Jedna explicitná Neo4j transakcia odstráni starý spravovaný graf, zapíše
|
|
nový graf a skontroluje počty uzlov/vzťahov oproti pripravenému payloadu.
|
|
Verzia grafu sa zapisuje v tej istej transakcii.
|
|
7. Pod publikačným zámkom sa aktivujú pripravené lokálne súbory a potvrdí sa
|
|
grafová transakcia. Po úspechu sa odstráni marker a sprístupní nová verzia.
|
|
|
|
SQLite a Neo4j netvoria distribuovanú ACID transakciu. Konzistenciu pri tejto
|
|
implementácii zaisťujú spoločný zámok pre podporované vyhľadávacie vstupy,
|
|
verzie, zálohy a marker nedokončeného prepnutia. Používanie samotného nízkoúrovňového
|
|
`search_graph_with_session` mimo publikačnej ochrany je určené pre kontrolované
|
|
interné evaluácie/testy; produkčný volajúci používa chránené `search_graph`.
|
|
|
|
## Verzia a dohľadateľnosť
|
|
|
|
Každá generácia má identifikátor `version`, Git revíziu zdrojovej wiki,
|
|
UTC čas prípravy, hash pôvodných README súborov, hashe dokumentov/chunkov
|
|
a názov embeddingového modelu. Hash zdrojov zachytáva aj necommitnuté zmeny;
|
|
samotný Git HEAD preto nie je jediným identifikátorom obsahu.
|
|
|
|
Rovnaký objekt `index_version` je uložený v:
|
|
|
|
- `data/index_version.json`,
|
|
- SQLite tabuľke `index_state`,
|
|
- operatívnom uzle Neo4j `IndexState` s ID `zpwiki`.
|
|
|
|
Operatívny uzol nie je súčasťou znalostného grafu označeného `graph_scope=zpwiki`.
|
|
Verziu vracajú `/sync`, webhook, `/health`, RAG vyhľadávanie a verejná Python
|
|
funkcia grafového vyhľadávania. Synchronizácia vracia aj `graph_counts`.
|
|
|
|
## Chyby a zotavenie
|
|
|
|
- Chyba prípravy, embeddingov alebo nedostupné Neo4j pred aktiváciou:
|
|
pôvodné indexy ostávajú aktívne.
|
|
- Chyba pri zápise grafu: celá grafová transakcia sa zruší.
|
|
- Chyba pri aktivácii lokálneho súboru: obnovia sa pôvodné súbory a grafová
|
|
transakcia sa zruší. Pri neúspešnej obnove marker zostáva.
|
|
- Stratené potvrdenie COMMIT: najprv sa kontroluje skutočná verzia v Neo4j.
|
|
Ak bola nová verzia potvrdená, staré lokálne dáta sa naslepo neobnovujú.
|
|
- Pád procesu alebo neoveriteľný výsledok transakcie: marker a obnovovacie
|
|
súbory ostávajú na disku. Vyhľadávanie odmietne nejasný snapshot; RAG API
|
|
vracia 503 a `/health` má `ready=false`.
|
|
|
|
Po odstránení príčiny spusti znova autorizovaný `/sync` alebo:
|
|
|
|
```bash
|
|
docker compose exec zp-agent-api python -m tools.rag.rebuild_index
|
|
```
|
|
|
|
Úspešná synchronizácia vytvorí kompletnú novú generáciu oboch indexov a marker
|
|
odstráni. Marker sa nemá ručne mazať ako náhrada opravy. Staršie adresáre
|
|
prerušených behov môžu zostať ako podklady na obnovu; bežný úspešný staging
|
|
sa automaticky odstraňuje.
|
|
|
|
## Samostatná obnova Neo4j
|
|
|
|
`python -m tools.graphrag.build_graphrag` používa rovnaký transakčný zápis.
|
|
Zmena grafu sa potvrdí celá alebo sa zruší celá. Ak JSON vstupy zodpovedajú
|
|
aktívnej generácii, jej proveniencia sa zachová. Iné vstupy alebo režim
|
|
`--no-replace` nemôžu predstierať synchronizovanú verziu; verejný grafový
|
|
vstup potom pri aktívnom manifeste vyžaduje spoločnú synchronizáciu.
|
|
|
|
## Overenie
|
|
|
|
Regresie pokrývajú chybu uprostred grafového zápisu, chybu po čiastočnej
|
|
aktivácii súborov, stratenú odpoveď COMMIT, neznámy výsledok COMMIT, následné
|
|
zotavenie, zámok pre čitateľov, nesúlad verzií, zmenu zdroja počas prípravy,
|
|
odpovede `/sync` aj podpísaného webhooku a API 503 pri nejasnej generácii.
|
|
Skutočné Neo4j testy overujú rollback po odstránení pôvodných uzlov a zápise
|
|
časti náhrady v izolovanom scope. Pozitívny prípad overuje aj opakovateľnosť.
|
|
|
|
Záverečná sada po dokončení opravy: **464 passed, 4 skipped**. Reálny `/sync`
|
|
v Docker API obnovil 114 dokumentov, 887 chunkov a 447 grafových uzlov /
|
|
879 vzťahov za 87,72 s. Overené sú rovnaké verzie v manifeste, SQLite, Neo4j,
|
|
health, skutočnej RAG odpovedi aj grafovom vyhľadávaní. Obsah znalostného
|
|
grafu zodpovedá pôvodnej v4; nové meranie presnosti LLM sa nevykonávalo.
|
|
Podrobné overenie: [záznam](synchronizacia_indexov_overenie.json).
|