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

Procesový .reindex.lock pripustí iba jednu synchronizáciu nad data volume.
Voliteľný git pull --ff-only zachováva pôvodné nastavenie synchronizácie.
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ť.
Overí sa, že sa zdrojové súbory ani Git revízia počas prípravy nezmenili.
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ť.
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.
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:

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.

5.0 KiB Raw Permalink Blame History