1342 lines
40 KiB
Markdown
1342 lines
40 KiB
Markdown
# ZP Agent
|
||
|
||
Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom
|
||
záverečných prác `zpwiki`.
|
||
|
||
Projekt načítava Markdown dokumenty, spracuje YAML metadata, rozdelí
|
||
obsah na tokenové chunky a vytvorí SQLite index kombinujúci FTS5
|
||
fulltextové vyhľadávanie a embeddingy. Nad hybridným vyhľadávaním je
|
||
vytvorená RAG vrstva, ktorá pripravuje kontext, zdroje a pravidlá pre
|
||
odpoveď jazykového modelu. API je integrované so školským OpenWebUI ako
|
||
OpenAPI Tool Server.
|
||
|
||
Stabilná baseline retrieval vetva používa klasický hybridný RAG:
|
||
FTS5/BM25 + embeddingy + RRF. Nad týmto baseline sa vo vetve GraphRAG
|
||
dopĺňa knowledge graph uložený v Neo4j. Aktuálne je implementovaná
|
||
grafová infraštruktúra, deterministický builder, vizualizácia grafu a
|
||
samostatné grafové vyhľadávanie. Grafová vrstva má zdrojovo overený benchmark a zmrazenú opravenú
|
||
verziu v7 s novým TESTom 80 kombinácií a regresiou 320 historických otázok, kontrolou všetkých vrátených
|
||
typovaných faktov a samostatným overením generovania odpovedí cez OpenWebUI API. Ďalším krokom je natívne zapojenie grafového
|
||
nástroja a hlavného agenta do OpenWebUI.
|
||
|
||
## Implementované
|
||
|
||
- načítanie Markdown súborov a YAML front matter,
|
||
- normalizácia názvov, autorov, tagov, kategórií a `published`,
|
||
- tokenové chunkovanie pomocou `tiktoken`,
|
||
- konfigurovateľná maximálna veľkosť chunku, overlap a minimálna
|
||
veľkosť chunku,
|
||
- zachovanie názvu dokumentu a hierarchie nadpisov v chunku,
|
||
- SQLite databáza a FTS5 fulltextový index,
|
||
- BM25 vyhľadávanie s podporou diakritiky a prefixových výrazov,
|
||
- vyhľadávacie stratégie `all_terms`, `prefix_terms` a `any_term`,
|
||
- embeddingy pre každý chunk pomocou modelu
|
||
`intfloat/multilingual-e5-small`,
|
||
- uloženie embeddingov priamo v SQLite,
|
||
- vektorové vyhľadávanie pomocou cosine similarity,
|
||
- hybridné vyhľadávanie FTS5 + embeddings pomocou RRF,
|
||
- nižšia váha pre slabú `any_term` FTS stratégiu,
|
||
- lexikálne zvýhodnenie presných alebo veľmi silných zhôd,
|
||
- obmedzenie počtu výsledkov z jedného dokumentu pomocou
|
||
`max_per_document`,
|
||
- filtrovanie publikovaných dokumentov,
|
||
- generovanie `source_url` pre dohľadateľnosť výsledkov,
|
||
- RAG vrstva s pripraveným kontextom, zdrojmi a pravidlami pre
|
||
grounded odpoveď,
|
||
- autorizovaný `/answer` s kontrolou faktických väzieb, citácií a úplnosti,
|
||
najviac jednou opravou a zostavením finálneho textu z overených údajov;
|
||
[OpenWebUI Pipe](tools/answers/openwebui_pipe.py), postup je nižšie v časti OpenWebUI,
|
||
- rozšírenie RAG kontextu o začiatok rovnakej sekcie
|
||
(`section-lead expansion`) bez globálneho zvýšenia
|
||
`max_per_document`,
|
||
- pravidlá proti používaniu neoverených informácií a zamieňaniu
|
||
rôznych typov údajov,
|
||
- no-answer správanie pri chýbajúcej alebo nedostatočne podloženej
|
||
informácii,
|
||
- FastAPI endpointy `/health`, `/rag`, `/search`, `/sync` a
|
||
`/webhook/gitea`,
|
||
- striktná validácia API vstupov,
|
||
- autorizácia vyhľadávania pomocou `X-API-Key` alebo Bearer tokenu,
|
||
- autorizácia `/sync` pomocou samostatného API kľúča,
|
||
- CORS konfigurácia pre OpenWebUI,
|
||
- bezpečnostné HTTP hlavičky,
|
||
- integrácia s OpenWebUI cez OpenAPI Tool Server,
|
||
- Gitea webhook s HMAC-SHA256 podpisom, limitom veľkosti payloadu a
|
||
kontrolou udalosti a repozitára,
|
||
- zámok proti súbežnému reindexovaniu,
|
||
- atomická výmena databázy po úspešnom reindexovaní,
|
||
- persistentná Hugging Face cache v Docker volume,
|
||
- warm-up embeddingového modelu,
|
||
- Neo4j databáza spúšťaná ako samostatná Docker služba,
|
||
- deterministická tvorba knowledge graphu z `documents.json` a
|
||
`chunks.json`,
|
||
- grafové entity `Person`, `Document`, `DocumentAuthor`, `Thesis`,
|
||
`Work`, `Keyword`, `Topic` a `Category`,
|
||
- grafové vzťahy pre dokumenty, práce, témy, kategórie a autorstvo,
|
||
- uniqueness constraints a opakovateľný rebuild GraphRAG grafu,
|
||
- Neo4j Browser na vizualizáciu a kontrolu vytvoreného grafu,
|
||
- samostatné grafové vyhľadávanie nad Neo4j s rozpoznaním entít, vzťahov, prác, tém a rokov,
|
||
- retrieval evaluácia pre FTS, embeddings a hybridný retrieval,
|
||
- answer-level RAG evaluácia cez OpenWebUI model a RAG tool,
|
||
- oddelené answer-level overrides bez úpravy frozen retrieval
|
||
benchmarku,
|
||
- príprava rozšírených datasetov pre extended RAG, GraphRAG,
|
||
robustness a performance experimenty.
|
||
|
||
## Architektúra
|
||
|
||
```text
|
||
zpwiki
|
||
↓
|
||
Markdown + YAML
|
||
↓
|
||
scan_zpwiki.py
|
||
↓
|
||
normalizované dokumenty
|
||
↓
|
||
build_chunks.py
|
||
↓
|
||
tokenové chunky
|
||
↓
|
||
build_sqlite_index.py
|
||
↓
|
||
SQLite
|
||
├── dokumenty
|
||
├── metadata
|
||
├── chunky
|
||
├── FTS5
|
||
└── embeddingy
|
||
↓
|
||
search_core.py / search_utils.py
|
||
↓
|
||
hybridné vyhľadávanie
|
||
├── FTS5 / BM25
|
||
├── embeddingové vyhľadávanie
|
||
└── RRF fusion + lexical anchor
|
||
↓
|
||
rag_utils.py
|
||
├── výber zdrojov
|
||
├── section-lead expansion
|
||
├── RAG kontext
|
||
└── grounding pravidlá
|
||
↓
|
||
FastAPI /rag
|
||
↓
|
||
OpenWebUI / ZP Agent
|
||
↓
|
||
jazykový model
|
||
↓
|
||
odpoveď + source_url
|
||
```
|
||
|
||
GraphRAG vývojová vetva:
|
||
|
||
```text
|
||
documents.json + chunks.json
|
||
↓
|
||
graphrag.py
|
||
↓
|
||
build_graphrag.py
|
||
↓
|
||
Neo4j
|
||
├── Person
|
||
├── Document
|
||
├── Thesis
|
||
├── Work
|
||
├── Keyword
|
||
├── Topic
|
||
├── Category
|
||
└── DocumentAuthor
|
||
↓
|
||
grafové vzťahy + vizualizácia
|
||
↓
|
||
graph_search.py
|
||
↓
|
||
grafové entity + cesty + zdrojové dokumenty
|
||
↓
|
||
spojenie s klasickým RAG
|
||
```
|
||
|
||
V aktuálnom stave je implementované vytvorenie a uloženie knowledge
|
||
graphu aj samostatné grafové vyhľadávanie. Jeho zapojenie do `/rag` a
|
||
OpenWebUI sa ešte dopĺňa.
|
||
|
||
Synchronizačná vetva:
|
||
|
||
```text
|
||
Gitea push
|
||
↓
|
||
POST /webhook/gitea
|
||
↓
|
||
HMAC + repository + event validácia
|
||
↓
|
||
durable synchronizačná fronta
|
||
↓
|
||
overenie vetvy + git fetch + merge --ff-only
|
||
↓
|
||
nové JSON, SQLite a grafový payload v stagingu
|
||
↓
|
||
koordinované prepnutie SQLite a Neo4j + spoločná verzia dát
|
||
```
|
||
|
||
Evaluačná vetva:
|
||
|
||
```text
|
||
tools/rag/evaluation/json_files/*.json
|
||
↓
|
||
retrieval evaluator / RAG answer evaluator
|
||
↓
|
||
runner
|
||
↓
|
||
metriky
|
||
↓
|
||
tools/rag/evaluation/results/
|
||
```
|
||
|
||
`tools/rag/evaluation/results/` nie je v nižšie uvedenom stromčeku,
|
||
pretože obsahuje generované výstupy experimentov.
|
||
|
||
## Štruktúra projektu
|
||
|
||
Nižšie je funkčná štruktúra projektu. Testovacie súbory, generované
|
||
výsledky, cache, `__pycache__`, Git interné súbory a podobné pomocné
|
||
artefakty sú zámerne vynechané.
|
||
|
||
```text
|
||
zp-agent/
|
||
├── app/
|
||
│ ├── main.py
|
||
│ ├── routes.py
|
||
│ └── security.py
|
||
│
|
||
├── tools/
|
||
│ ├── answers/
|
||
│ │ ├── answer_delivery.py
|
||
│ │ └── openwebui_pipe.py
|
||
│ ├── answer_evaluation/
|
||
│ │ ├── checked_generation.py
|
||
│ │ ├── context_policy.py
|
||
│ │ └── evaluate_graph_answers.py
|
||
│ ├── retrieval/
|
||
│ │ ├── publication.py
|
||
│ │ ├── retrieval_contract.py
|
||
│ │ └── text_budget.py
|
||
│ ├── runtime/
|
||
│ │ ├── runtime_assets.py
|
||
│ │ ├── runtime_health.py
|
||
│ │ ├── tool_health.py
|
||
│ │ └── bootstrap_indexes.py
|
||
│ ├── sync/
|
||
│ │ ├── index_state.py
|
||
│ │ ├── sync_indexes.py
|
||
│ │ ├── sync_jobs.py
|
||
│ │ └── wiki_git.py
|
||
│ ├── rag/
|
||
│ │ ├── common.py
|
||
│ │ ├── scan_zpwiki.py
|
||
│ │ ├── build_chunks.py
|
||
│ │ ├── build_sqlite_index.py
|
||
│ │ ├── embedding_utils.py
|
||
│ │ ├── rebuild_index.py
|
||
│ │ ├── search_core.py
|
||
│ │ ├── search_utils.py
|
||
│ │ ├── search_db.py
|
||
│ │ ├── rag_utils.py
|
||
│ │ ├── rag_document_expansion.py
|
||
│ │ ├── rag_query_evidence.py
|
||
│ │ ├── rag_supplemental_expansion.py
|
||
│ │ ├── run_e5_regression.sh
|
||
│ │ ├── run_e5_1_regression.sh
|
||
│ │ ├── evaluation/
|
||
│ │ │ ├── evaluate_retrieval.py
|
||
│ │ │ ├── evaluate_rag_answers.py
|
||
│ │ │ ├── retrieval_runner.py
|
||
│ │ │ ├── rag_runner.py
|
||
│ │ │ ├── metrics.py
|
||
│ │ │ ├── rag_metrics.py
|
||
│ │ │ └── json_files/
|
||
│ │ └── tests/
|
||
│ │
|
||
│ └── graphrag/
|
||
│ ├── graph_db.py
|
||
│ ├── graphrag.py
|
||
│ ├── build_graphrag.py
|
||
│ ├── graph_search.py
|
||
│ ├── neo4j_smoke.py
|
||
│ ├── evaluation/
|
||
│ │ └── graphrag_questions.json
|
||
│ └── tests/
|
||
│
|
||
├── test/
|
||
│ ├── test_api.py
|
||
│ ├── test_configuration.py
|
||
│ └── test_security.py
|
||
│
|
||
├── scripts/
|
||
│ ├── start_project.sh
|
||
│ └── verify_project.py
|
||
│
|
||
├── data/
|
||
│ ├── documents.json
|
||
│ ├── chunks.json
|
||
│ └── zp_index.sqlite
|
||
│
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
├── requirements.txt
|
||
├── requirements-dev.txt
|
||
└── README.md
|
||
```
|
||
|
||
`answers/` doručuje overené odpovede a obsahuje inštalovateľný OpenWebUI Pipe.
|
||
`answer_evaluation/` obsahuje kontrolu odpovedí, renderer a evaluačné klienty.
|
||
`retrieval/` zdieľa dátový kontrakt, publikačnú politiku a delenie podľa rozpočtu.
|
||
`runtime/` pripravuje model/tokenizér a kontroluje štart a dostupnosť služieb.
|
||
`sync/` spravuje Git, frontu a spoločné publikovanie SQLite/Neo4j indexov.
|
||
V koreňovom `tools/` zostáva iba `__init__.py`.
|
||
|
||
Na Gite je z dokumentácie iba tento hlavný README. Vedľajšie návody,
|
||
pracovné záznamy a textové správy ostávajú lokálne a sú ignorované.
|
||
JSON/CSV výsledky a pôvodné experimentálne manifesty zostávajú zachované.
|
||
Historické zmrazené merania sa reprodukujú v ich pôvodnom Git checkoute;
|
||
presun modulov nemení ich uložené odtlačky ani výsledky.
|
||
|
||
### `app/`
|
||
|
||
`app/main.py`
|
||
|
||
- vytvára FastAPI aplikáciu,
|
||
- nastavuje lifespan aplikácie,
|
||
- validuje bezpečnostnú konfiguráciu pri štarte,
|
||
- vykonáva warm-up embeddingovej vrstvy,
|
||
- nastavuje CORS a bezpečnostné hlavičky,
|
||
- pripája API routery,
|
||
- ponecháva OpenAPI schému dostupnú pre OpenWebUI.
|
||
|
||
Interaktívne Swagger/Redoc rozhranie môže byť v produkčnej konfigurácii
|
||
vypnuté. Pre integráciu OpenWebUI je dôležitý endpoint:
|
||
|
||
```text
|
||
/openapi.json
|
||
```
|
||
|
||
`app/routes.py`
|
||
|
||
- definuje `/health`,
|
||
- definuje verejne publikovaný RAG nástroj `/rag`,
|
||
- obsahuje interné/zabezpečené `/search` a `/sync`,
|
||
- obsluhuje `/webhook/gitea`,
|
||
- vykonáva validáciu requestov a sanitizáciu chýb,
|
||
- používa reindexovací zámok,
|
||
- kontroluje webhook payload pred spracovaním.
|
||
|
||
`app/security.py`
|
||
|
||
- spracúva `SEARCH_API_KEY`,
|
||
- spracúva `SYNC_API_KEY`,
|
||
- spracúva `WEBHOOK_SECRET`,
|
||
- vyžaduje dostatočne dlhé a navzájom odlišné tajomstvá,
|
||
- používa bezpečné porovnávanie autentifikačných hodnôt,
|
||
- validuje očakávaný Gitea repozitár a súvisiacu konfiguráciu.
|
||
|
||
### `tools/rag/`
|
||
|
||
`common.py`
|
||
|
||
Spoločné utility a konfiguračné funkcie používané indexovacou a
|
||
vyhľadávacou vrstvou.
|
||
|
||
`scan_zpwiki.py`
|
||
|
||
- prechádza repozitár `zpwiki`,
|
||
- načítava Markdown a YAML front matter,
|
||
- normalizuje dokumentové metadata,
|
||
- pripravuje dokumenty na ďalšie spracovanie.
|
||
|
||
`build_chunks.py`
|
||
|
||
- rozdeľuje dokumenty na tokenové chunky,
|
||
- používa `tiktoken`,
|
||
- zachováva nadpisy, kódové bloky a tabuľky,
|
||
- podporuje tokenový overlap,
|
||
- eviduje token count a hash obsahu chunku.
|
||
|
||
`build_sqlite_index.py`
|
||
|
||
- vytvára SQLite databázu,
|
||
- ukladá dokumenty, chunky a metadata,
|
||
- vytvára FTS5 index,
|
||
- ukladá embeddingy do SQLite,
|
||
- pripravuje databázu pre hybridný retrieval.
|
||
|
||
`embedding_utils.py`
|
||
|
||
- načítava embeddingový model,
|
||
- vytvára embeddingy pre dokumenty a query,
|
||
- normalizuje vektory,
|
||
- poskytuje utility pre vektorové vyhľadávanie.
|
||
|
||
### `tools/graphrag/`
|
||
|
||
`graph_db.py`
|
||
|
||
- načítava konfiguráciu Neo4j,
|
||
- vytvára Neo4j driver,
|
||
- poskytuje kontrolu spojenia s grafovou databázou.
|
||
|
||
`graphrag.py`
|
||
|
||
- pripravuje dátový model knowledge graphu,
|
||
- normalizuje grafové identifikátory,
|
||
- extrahuje osoby, práce, roky, témy, kategórie a súvisiace metadata,
|
||
- pripravuje uzly a vzťahy pre zápis do Neo4j.
|
||
|
||
`build_graphrag.py`
|
||
|
||
- načíta `documents.json` a `chunks.json`,
|
||
- vytvorí GraphRAG payload,
|
||
- vytvorí Neo4j uniqueness constraints,
|
||
- zapíše uzly a vzťahy,
|
||
- podporuje opakovateľný rebuild spravovanej časti grafu,
|
||
- vypíše základné počty uzlov, vzťahov a kvalitu extrakcie názvov prác.
|
||
|
||
`graph_search.py`
|
||
|
||
- rozpoznáva relevantné osoby a obmedzenia v otázke,
|
||
- vyhľadáva práce, témy, roky a spoločné vzťahy v Neo4j,
|
||
- vracia grafové cesty, fakty a zdrojové dokumenty,
|
||
- slúži ako základ budúceho GraphRAG nástroja pre OpenWebUI.
|
||
|
||
`neo4j_smoke.py`
|
||
|
||
Jednoduchý smoke test pripojenia k Neo4j používaný pri kontrole Docker
|
||
prostredia.
|
||
|
||
`search_core.py`
|
||
|
||
Nízkoúrovňové jadro vyhľadávania:
|
||
|
||
- normalizácia query,
|
||
- FTS5 vyhľadávanie,
|
||
- embeddingové vyhľadávanie,
|
||
- scoring,
|
||
- RRF fusion,
|
||
- lexical anchor,
|
||
- metadata,
|
||
- diverzifikácia výsledkov.
|
||
|
||
`search_utils.py`
|
||
|
||
Vyššia orchestration vrstva nad `search_core.py` a kompatibilné
|
||
vyhľadávacie utility používané ostatnými časťami projektu.
|
||
|
||
`search_db.py`
|
||
|
||
CLI rozhranie na ručné vyhľadávanie nad lokálnym SQLite indexom.
|
||
|
||
`rag_utils.py`
|
||
|
||
- zostavuje RAG kontext,
|
||
- pripravuje zdrojové metadata,
|
||
- pridáva `source_url`,
|
||
- aplikuje grounding pravidlá,
|
||
- podporuje no-answer správanie,
|
||
- rozširuje primárny chunk o začiatok rovnakej sekcie,
|
||
- zachováva väzbu medzi primárnym chunkom a section-lead chunkom.
|
||
|
||
`rebuild_index.py`
|
||
|
||
Orchestruje kompletný rebuild:
|
||
|
||
```text
|
||
scan
|
||
→ chunking
|
||
→ SQLite/FTS
|
||
→ embeddings
|
||
→ validácia
|
||
→ atomická výmena DB
|
||
```
|
||
|
||
### `tools/rag/evaluation/`
|
||
|
||
`evaluate_retrieval.py`
|
||
|
||
CLI vstup pre retrieval benchmark. Umožňuje spúšťať DEV, TEST alebo
|
||
celý dataset a používa strict dataset validáciu.
|
||
|
||
`retrieval_runner.py`
|
||
|
||
Spúšťa jednotlivé retrieval stratégie nad evaluačnými otázkami.
|
||
|
||
`metrics.py`
|
||
|
||
Počíta retrieval metriky, napríklad:
|
||
|
||
```text
|
||
Hit@1
|
||
Hit@3
|
||
Hit@5
|
||
MRR
|
||
Recall@5
|
||
```
|
||
|
||
`evaluate_rag_answers.py`
|
||
|
||
CLI vstup pre answer-level RAG evaluáciu. Hodnotí celý tok:
|
||
|
||
```text
|
||
otázka
|
||
→ OpenWebUI model
|
||
→ ZP Agent tool
|
||
→ /rag
|
||
→ finálna odpoveď
|
||
```
|
||
|
||
Podporuje answer-level overrides, aby nebolo potrebné meniť frozen
|
||
retrieval benchmark pri otázkach, ktoré sú pre generatívnu evaluáciu
|
||
nejednoznačné.
|
||
|
||
`rag_runner.py`
|
||
|
||
Spúšťa jednotlivé answer-level prípady a komunikuje s OpenWebUI/API.
|
||
|
||
`rag_metrics.py`
|
||
|
||
Počíta answer-level metriky, napríklad:
|
||
|
||
- prítomnosť očakávaných faktov,
|
||
- správnosť `source_url`,
|
||
- `should_answer`,
|
||
- použitie toolu,
|
||
- strict pass,
|
||
- latency a tokenové údaje.
|
||
|
||
### `tools/rag/evaluation/json_files/`
|
||
|
||
`questions.json`
|
||
|
||
Hlavný frozen benchmark pre klasický retrieval a RAG. Po zmrazení
|
||
benchmarku sa nemá meniť len preto, aby sa zlepšil výsledok answer-level
|
||
evaluácie.
|
||
|
||
`rag_answer_overrides.json`
|
||
|
||
Obsahuje iba answer-level úpravy formulácie alebo očakávaní pri
|
||
nejednoznačných otázkach. Retrieval benchmark tým ostáva nezmenený.
|
||
|
||
`questions_before_ambiguity_cleanup.json`
|
||
|
||
Historická záloha datasetu pred úpravami nejednoznačností.
|
||
|
||
`questions_before_validation.json`
|
||
|
||
Historická záloha datasetu pred validačnými úpravami.
|
||
|
||
`questions_extended.json`
|
||
|
||
Rozšírený benchmark s presne 2000 otázkami. Je pripravený pre neskoršie
|
||
rozsiahlejšie experimenty nad klasickým retrievalom a RAG.
|
||
|
||
Obsahuje kombináciu:
|
||
|
||
- faktických otázok,
|
||
- parafráz,
|
||
- otázok bez diakritiky,
|
||
- preklepov,
|
||
- krátkych query,
|
||
- no-answer prípadov,
|
||
- negatívnej verifikácie,
|
||
- multi-document otázok,
|
||
- porovnávania,
|
||
- citation-oriented prípadov.
|
||
|
||
Tento dataset je zatiaľ pripravený, ale nemá sa používať na priebežné
|
||
ladenie frozen benchmarku.
|
||
|
||
GraphRAG benchmark je po oddelení nástrojov uložený samostatne v:
|
||
|
||
```text
|
||
tools/graphrag/evaluation/graphrag_questions.json
|
||
```
|
||
|
||
Obsahuje 500 otázok zameraných na grafové a viacvzťahové dopyty.
|
||
|
||
`robustness_questions.json`
|
||
|
||
Samostatný dataset s 200 otázkami pre testovanie robustnosti.
|
||
|
||
Pokrýva napríklad:
|
||
|
||
- chýbajúcu diakritiku,
|
||
- preklepy,
|
||
- nekonzistentnú kapitalizáciu a interpunkciu,
|
||
- nerelevantný šum,
|
||
- prompt injection,
|
||
- konfliktné tvrdenia používateľa,
|
||
- tlak na halucinovanie,
|
||
- no-answer grounding,
|
||
- ambiguity/disambiguation,
|
||
- integritu citácií,
|
||
- kombinovaný vstupný šum.
|
||
|
||
Každá položka obsahuje aj `robustness` metadata s typom útoku,
|
||
perturbáciou, očakávaným správaním a závažnosťou.
|
||
|
||
`performance_queries.json`
|
||
|
||
Samostatný workload s 200 query pre budúce performance a stress
|
||
experimenty.
|
||
|
||
Profily zahŕňajú:
|
||
|
||
- baseline single-document query,
|
||
- krátke query,
|
||
- noisy query,
|
||
- multi-document query,
|
||
- no-answer query,
|
||
- query s väčším retrieval limitom,
|
||
- context-heavy query,
|
||
- opakované hot query.
|
||
|
||
Súbor samotný performance nemeria. Je to vstup pre budúci samostatný
|
||
performance runner, ktorý bude volať `/rag` a merať napríklad:
|
||
|
||
```text
|
||
mean latency
|
||
median
|
||
P50
|
||
P95
|
||
P99
|
||
requests/second
|
||
error rate
|
||
timeout rate
|
||
cold vs warm latency
|
||
```
|
||
|
||
Stress režim bude nad rovnakým workloadom zvyšovať paralelizmus a
|
||
sledovať správanie systému pri rastúcej záťaži.
|
||
|
||
## Konfigurácia
|
||
|
||
V koreňovom priečinku vytvor `.env`:
|
||
|
||
```dotenv
|
||
WEBHOOK_SECRET=<náhodná hodnota s minimálne 32 znakmi>
|
||
SYNC_API_KEY=<iná náhodná hodnota s minimálne 32 znakmi>
|
||
SEARCH_API_KEY=<ďalšia náhodná hodnota s minimálne 32 znakmi>
|
||
EXPECTED_GITEA_REPOSITORY=jp170na/zpwiki
|
||
EXPECTED_GITEA_BRANCH=master
|
||
WEBHOOK_PULL_GIT=true
|
||
ZPWIKI_SSH_KEY=/absolutna/cesta/k/ssh_klucu
|
||
ZPWIKI_KNOWN_HOSTS=/absolutna/cesta/k/known_hosts
|
||
|
||
# Voliteľné
|
||
EMBEDDING_MODEL=intfloat/multilingual-e5-small
|
||
EMBEDDING_BATCH_SIZE=32
|
||
OPENWEBUI_API_KEY=<kľúč pre generujúci školský model>
|
||
ANSWER_MODEL=model120-fast
|
||
ANSWER_LLM_URL=https://ui.tukekemt.xyz/api/chat/completions
|
||
|
||
# GraphRAG / Neo4j
|
||
NEO4J_URI=bolt://localhost:7687
|
||
NEO4J_USER=neo4j
|
||
NEO4J_PASSWORD=<silné lokálne heslo>
|
||
NEO4J_DATABASE=neo4j
|
||
```
|
||
|
||
Tajomstvá je možné vygenerovať príkazom:
|
||
|
||
```bash
|
||
openssl rand -hex 32
|
||
```
|
||
|
||
Súbor `.env` sa nesmie commitovať.
|
||
|
||
Chunkovanie je možné konfigurovať pomocou premenných prostredia:
|
||
|
||
```dotenv
|
||
CHUNK_MAX_TOKENS=450
|
||
CHUNK_OVERLAP_TOKENS=70
|
||
CHUNK_MIN_TOKENS=80
|
||
CHUNK_TOKEN_ENCODING=cl100k_base
|
||
```
|
||
|
||
## Spustenie cez Docker
|
||
|
||
Potrebný je dostupný Docker Engine, natívny Linux Compose v2 a Buildx.
|
||
Vo WSL používaj kontext, ku ktorému sa Linux klient vie pripojiť; Windows
|
||
kontext s `npipe` tu nie je náhradou Linux socketu. Overenie:
|
||
|
||
```bash
|
||
docker --context default info
|
||
docker compose version
|
||
docker buildx version
|
||
```
|
||
|
||
Po vytvorení `.env`, klonu `../zpwiki` a SSH konfigurácie spusti:
|
||
|
||
```bash
|
||
./scripts/start_project.sh
|
||
```
|
||
|
||
Skript štandardne používa kontext `default`, nemení globálny Docker kontext
|
||
a spravuje iba projekt `zp-agent`. Iný cieľ nastav cez `ZP_DOCKER_CONTEXT`.
|
||
Zostaví image, počká na zdravý Neo4j, overí existujúce indexy a podľa
|
||
potreby ich koordinovane vytvorí. Až potom spustí API a počká na readiness.
|
||
Pri opakovanom spustení ponechá konzistentné a aktuálne indexy.
|
||
|
||
Model aj tokenizér sú súčasťou image v `/opt/zp-assets`. Bežný štart
|
||
nevyžaduje internet ani existujúcu používateľskú Hugging Face/tiktoken cache.
|
||
Prvý build potrebuje balíky a modelové súbory; build overuje aj načítanie
|
||
pripravených assets so zakázanou sieťou. Prázdny HF cache volume neskrýva
|
||
model pribalený v image. Git pripojenie je samostatná sieťová operácia;
|
||
príznaky offline zakazujú sťahovanie modelu, nie synchronizáciu wiki.
|
||
|
||
Voliteľne môžeš pred buildom pripraviť ignorované lokálne podklady a využiť
|
||
už stiahnutý model z hostiteľa:
|
||
|
||
```bash
|
||
.venv/bin/python -m tools.runtime.runtime_assets prepare
|
||
```
|
||
|
||
`runtime_assets/` obsahuje veľké modelové súbory a do Gitu nepatrí; verzovaný
|
||
je iba prázdny adresár pre čistý build. Bez pripravených lokálnych podkladov
|
||
si ich Docker build vytvorí sám. Súbory majú manifest so SHA-256 a model je
|
||
pripnutý na konkrétny commit. Iný model/revízia vyžaduje nový build s
|
||
`EMBEDDING_MODEL`/`EMBEDDING_REVISION` a zodpovedajúce pripravené assets.
|
||
API pri nesúlade neprejde potichu na sťahovanie iného modelu.
|
||
|
||
Kontrola služby:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/health
|
||
```
|
||
|
||
OpenAPI schéma:
|
||
|
||
```text
|
||
http://127.0.0.1:8000/openapi.json
|
||
```
|
||
|
||
Logy:
|
||
|
||
```bash
|
||
docker compose logs -f zp-agent-api
|
||
```
|
||
|
||
Zastavenie:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
Hugging Face cache volume zostáva persistentné; predvolený embeddingový
|
||
model a tokenizér však štartujú priamo z overených súborov v image.
|
||
|
||
Neo4j je spustené ako samostatná služba v rovnakom Docker Compose
|
||
prostredí. Stav služieb je možné skontrolovať:
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
Neo4j Browser je lokálne dostupný na:
|
||
|
||
```text
|
||
http://127.0.0.1:7474/browser/
|
||
```
|
||
|
||
Kontrola spojenia z API kontajnera:
|
||
|
||
```bash
|
||
docker compose exec zp-agent-api \
|
||
python -m tools.graphrag.neo4j_smoke
|
||
```
|
||
|
||
## Reindexovanie
|
||
|
||
Spoločná synchronizácia pripraví dokumenty, chunky, SQLite/FTS5, embeddingy
|
||
a Neo4j graf z jedného snapshotu wiki. Nová generácia sa aktivuje až po
|
||
úspešnej príprave oboch indexov:
|
||
|
||
```bash
|
||
docker compose run --rm zp-agent-api python -m tools.rag.rebuild_index
|
||
```
|
||
|
||
Vzniknú súbory:
|
||
|
||
```text
|
||
data/documents.json
|
||
data/chunks.json
|
||
data/zp_index.sqlite
|
||
data/index_version.json
|
||
```
|
||
|
||
Databáza obsahuje dokumenty, chunky, FTS5 index, metadata a embeddingy.
|
||
|
||
Manuálny `/sync`, push webhook a uvedený CLI príkaz používajú rovnakú pipeline.
|
||
SQLite, Neo4j a odpovede nástrojov evidujú spoločnú verziu dát a Git revíziu.
|
||
Pri krátkom prepnutí sa nové vyhľadávanie dočasne odmietne; chyba grafu
|
||
vyvolá rollback. Pri nedokončenom prepnutí po páde zostane vyhľadávanie
|
||
nedostupné do úspešného opakovania synchronizácie. Podrobnosti a zotavenie:
|
||
Implementácia je v [tools/sync/sync_indexes.py](tools/sync/sync_indexes.py).
|
||
|
||
## Publikovanie a dostupnosť nástrojov
|
||
|
||
Oba nástroje predvolene vylučujú iba explicitné `published=false`.
|
||
Chýbajúca hodnota sa považuje za publikovanú. Parameter
|
||
`published_only=false` výslovne zahrnie aj nepublikované dokumenty pri
|
||
autorizovanom volaní; CLI používa `--include-unpublished`.
|
||
|
||
`/health` uvádza samostatne `tools.rag`, `tools.neo4j` a `tools.graphrag`.
|
||
Globálne `ready` vyžaduje oba vyhľadávacie nástroje; pri výpadku Neo4j
|
||
môže klient ďalej používať RAG podľa `tools.rag.ready`.
|
||
Spoločná politika je v [tools/retrieval/publication.py](tools/retrieval/publication.py).
|
||
|
||
## Hybridné vyhľadávanie
|
||
|
||
RAG aj GraphRAG používajú spoločné polia `status`, `reason`, `sources`,
|
||
`index_version`, `complete`, `truncated` a `truncation_reasons`. Pôvodný
|
||
RAG kontext aj grafové fakty a cesty zostávajú dostupné. Úplnosť vyhľadania
|
||
sa odlišuje od pravdivosti odpovede; pri RAG môže byť nezaručená (`null`).
|
||
Typované polia a chyby definuje
|
||
[tools/retrieval/retrieval_contract.py](tools/retrieval/retrieval_contract.py).
|
||
|
||
Vyhľadávanie kombinuje:
|
||
|
||
```text
|
||
dotaz
|
||
├── FTS5 / BM25
|
||
└── embeddingové vyhľadávanie
|
||
↓
|
||
RRF fusion
|
||
↓
|
||
lexical anchor
|
||
↓
|
||
výsledky
|
||
```
|
||
|
||
FTS5 používa stratégie:
|
||
|
||
```text
|
||
all_terms
|
||
prefix_terms
|
||
any_term
|
||
```
|
||
|
||
Presné lexikálne výsledky majú prednosť pred slabšími sémantickými
|
||
zhodami. Pri slabšej `any_term` stratégii sa znižuje jej váha a väčší
|
||
význam môže dostať embeddingové vyhľadávanie.
|
||
|
||
Test z terminálu:
|
||
|
||
```bash
|
||
docker compose run --rm zp-agent-api \
|
||
python -m tools.rag.search_db "rag agent" --limit 5
|
||
```
|
||
|
||
Pred volaním API načítaj premenné z `.env`:
|
||
|
||
```bash
|
||
set -a
|
||
source .env
|
||
set +a
|
||
```
|
||
|
||
Vyhľadávanie cez zabezpečené API:
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/search \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $SEARCH_API_KEY" \
|
||
-d '{
|
||
"query": "strojový preklad",
|
||
"limit": 3,
|
||
"published_only": true,
|
||
"max_per_document": 1
|
||
}'
|
||
```
|
||
|
||
API používa hybridný engine:
|
||
|
||
```text
|
||
hybrid_fts5_embeddings
|
||
```
|
||
|
||
`max_per_document=1` zabezpečí, že sa pri požiadavke na viac výsledkov
|
||
preferujú rôzne dokumenty namiesto viacerých chunkov z rovnakého
|
||
dokumentu.
|
||
|
||
## RAG
|
||
|
||
Nad hybridným retrievalom je implementovaná RAG vrstva v
|
||
`tools/rag/rag_utils.py`.
|
||
|
||
Endpoint `/rag` vyhľadá relevantné dokumenty a pripraví:
|
||
|
||
- textový kontext pre jazykový model,
|
||
- metadata použitých zdrojov,
|
||
- názov a autora dokumentu,
|
||
- `source_url`,
|
||
- interné retrieval informácie,
|
||
- pravidlá pre grounded odpoveď.
|
||
|
||
RAG pravidlá požadujú, aby model odpovedal iba podľa poskytnutých
|
||
zdrojov. Zároveň rozlišujú údaje, ktoré sa môžu ľahko zameniť, napríklad
|
||
autora dokumentu, osobu, o ktorej dokument pojednáva, rok začiatku
|
||
štúdia a rok záverečnej práce.
|
||
|
||
Ak sa relevantná informácia nenachádza priamo v primárnom chunke,
|
||
RAG vrstva môže k rovnakému zdroju doplniť začiatok rovnakej sekcie.
|
||
Táto section-lead expanzia umožňuje zachovať retrieval
|
||
`max_per_document=1`, ale zároveň doplniť názov témy, rok alebo inú
|
||
informáciu umiestnenú na začiatku sekcie.
|
||
|
||
Pri nedostatočnej podpore má model odmietnuť informáciu domýšľať.
|
||
|
||
Príklad:
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/rag \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $SEARCH_API_KEY" \
|
||
-d '{
|
||
"query": "V akom roku robil Ján Holp diplomovú prácu?",
|
||
"limit": 5,
|
||
"published_only": true,
|
||
"max_per_document": 1
|
||
}'
|
||
```
|
||
|
||
## GraphRAG
|
||
|
||
GraphRAG vetva rozširuje existujúci klasický RAG o knowledge graph.
|
||
Graf sa vytvára deterministicky z už pripravených dokumentov a chunkov
|
||
a ukladá sa do Neo4j.
|
||
|
||
Aktuálne používané hlavné typy uzlov:
|
||
|
||
```text
|
||
Person
|
||
Document
|
||
DocumentAuthor
|
||
Thesis
|
||
Work
|
||
Keyword
|
||
Topic
|
||
Category
|
||
```
|
||
|
||
Hlavné vzťahy zahŕňajú napríklad:
|
||
|
||
```text
|
||
Person -[:HAS_DOCUMENT]-> Document
|
||
Person -[:AUTHORED]-> Thesis
|
||
Person -[:HAS_WORK]-> Work
|
||
Thesis/Work -[:EVIDENCED_BY]-> Document
|
||
Document -[:HAS_KEYWORD]-> Keyword
|
||
Document -[:IN_CATEGORY]-> Category
|
||
DocumentAuthor -[:AUTHORED_DOCUMENT]-> Document
|
||
Document -[:DESCRIBES]-> Topic
|
||
```
|
||
|
||
Knowledge graph sa vytvorí príkazom:
|
||
|
||
```bash
|
||
docker compose exec zp-agent-api \
|
||
python -m tools.graphrag.build_graphrag
|
||
```
|
||
|
||
Builder vytvára constraints, zapisuje uzly a vzťahy a pri štandardnom
|
||
spustení obnoví iba časť grafu spravovanú ZP Agentom. Zmazanie aj zápis
|
||
prebiehajú v jednej transakcii s kontrolou počtov, takže chyba zachová
|
||
pôvodný graf. Opakované spustenie nevytvára duplicitné uzly.
|
||
|
||
Graf je možné vizuálne kontrolovať v Neo4j Browseri. Samostatné
|
||
grafové vyhľadávanie je implementované v `tools/graphrag/graph_search.py`.
|
||
GraphRAG zatiaľ nezasahuje do stabilného klasického `/rag` toku; ďalšia
|
||
etapa spojí grafové výsledky s klasickým RAG a OpenWebUI nástrojom.
|
||
|
||
Aktuálna evaluácia GraphRAG **v7** má DEV **1 046/1 046** a nový TEST
|
||
**80/80** pre grafové vyhľadávanie aj finálne odpovede. Modelový DEV má
|
||
**46/46**; pri novom TESTe prešlo na prvý pokus **77/80 (96,25 %)**,
|
||
po jednej povolenej oprave **80/80 (100 %)**. Prirodzený text sa skladá
|
||
z overených štruktúrovaných tvrdení. Sú to nové kombinácie nad známym
|
||
korpusom a šablónami, nie neznáme osoby ani ľudsky anotovaný benchmark.
|
||
Samostatná historická regresia má **319/320 (99,69 %)**; nepodložená
|
||
odpoveď v zostávajúcom prípade bola odmietnutá pred doručením.
|
||
|
||
Pri zmrazení v7 prešli vtedajšie testy vrátane živých. V7 opravuje ignorovanie rokov
|
||
mimo 20xx, kontrolu rozporných tvrdení o úplnosti, počtov, povinných tvrdení
|
||
a citácií vrátane referenčného Markdownu a HTML. Začiatok štúdia vyžaduje
|
||
explicitný zdroj, neodvodzuje sa z adresára; opravilo sa 10 očakávaní.
|
||
Všetky v1–v6 merania ostávajú zachované.
|
||
[Uložené výsledky v7](tools/graphrag/evaluation/results/final_v7_2026-10-26/summary.json)
|
||
obsahujú metriky; historické manifesty a raw odpovede ostávajú pri meraniach.
|
||
|
||
Historická v4 mala grafový strict TEST 320/320, doplnkovú kontrolu kontextových
|
||
faktov 319/320 a LLM TEST 281/300 (93,67 %). Pôvodné otázky aj výsledky
|
||
v1–v4 zostávajú zachované. Aktuálne skóre nie je zárukou všeobecnej pravdivosti.
|
||
V7 benchmark nie je nezávisle anotovaný človekom. Nové ladenie na známych
|
||
otázkach sa označuje ako regresia, nie ako nový nezávislý TEST.
|
||
|
||
## OpenWebUI
|
||
|
||
Pripravená kontrolovaná cesta používa samostatný Pipe v
|
||
[tools/answers/openwebui_pipe.py](tools/answers/openwebui_pipe.py).
|
||
Administrátor v **Admin Panel → Functions → Create** vloží celý súbor,
|
||
uloží ho napríklad ako `zp_verified` a aktivuje. Vo **Valves** nastaví:
|
||
|
||
| Pole | Hodnota |
|
||
|---|---|
|
||
| `BACKEND_URL` | Adresa API dostupná zo servera OpenWebUI, bez `/answer` |
|
||
| `BACKEND_API_KEY` | Hodnota `SEARCH_API_KEY` backendu |
|
||
| `DEFAULT_ENGINE` | `rag` |
|
||
| `TIMEOUT_SECONDS` | `300` |
|
||
|
||
Backend používa `OPENWEBUI_API_KEY` pre generujúci model.
|
||
`ANSWER_LLM_URL` je predvolene `https://ui.tukekemt.xyz/api/chat/completions`
|
||
a `ANSWER_MODEL` je `model120-fast`. Základný model nesmie odkazovať na
|
||
tento Pipe, aby nevznikla slučka. Kľúče patria do `.env` alebo Valves.
|
||
Po aktivácii sú vo výbere dva modely: overený RAG a overený GraphRAG.
|
||
Pipe odovzdáva poslednú otázku; kontextové odkazy na predchádzajúce správy
|
||
zatiaľ samostatne nerozvíja.
|
||
|
||
Tok: **Pipe → autorizovaný `/answer` → retrieval → generovanie → kontroly
|
||
→ renderer → priamy text v UI**. Vyžaduje `accepted_for_delivery=true`;
|
||
odmietnutý text ani opravné pokusy sa nezobrazia. Iný model finálny text
|
||
neprepisuje. Inštalácia na školskom serveri čaká na administrátora a
|
||
sieťové sprístupnenie API. `localhost` vo funkcii znamená server OpenWebUI,
|
||
nie vývojový počítač. V spoločnej Compose sieti môže byť URL
|
||
`http://zp-agent-api:8000`.
|
||
|
||
Pôvodný OpenAPI Tool Server poskytuje podklady cez `/rag`.
|
||
|
||
OpenWebUI používa OpenAPI schému ZP Agent API a Bearer autentifikáciu
|
||
pre vyhľadávací/RAG nástroj.
|
||
|
||
Tok požiadavky:
|
||
|
||
```text
|
||
používateľ
|
||
↓
|
||
OpenWebUI
|
||
↓
|
||
jazykový model
|
||
↓
|
||
ZP Agent /rag
|
||
↓
|
||
hybrid retrieval
|
||
↓
|
||
RAG kontext + zdroje
|
||
↓
|
||
jazykový model
|
||
↓
|
||
odpoveď
|
||
```
|
||
|
||
Výsledná odpoveď má byť grounded v ZP Wiki a má používať relevantný
|
||
`source_url`. Táto pôvodná cesta s voľným následným generovaním sama
|
||
nezaručuje kontroly doručenia pripraveného Pipe.
|
||
|
||
## Retrieval evaluácia
|
||
|
||
Frozen retrieval benchmark sa spúšťa napríklad:
|
||
|
||
```bash
|
||
python -m tools.rag.evaluation.evaluate_retrieval \
|
||
--split dev \
|
||
--strict-dataset
|
||
```
|
||
|
||
Podporované režimy:
|
||
|
||
```text
|
||
dev
|
||
test
|
||
all
|
||
```
|
||
|
||
Vyhodnocujú sa samostatne:
|
||
|
||
```text
|
||
FTS
|
||
vector
|
||
hybrid
|
||
```
|
||
|
||
a metriky:
|
||
|
||
```text
|
||
Hit@1
|
||
Hit@3
|
||
Hit@5
|
||
MRR
|
||
Recall@5
|
||
```
|
||
|
||
TEST split sa nemá používať na priebežné ladenie retrieval konfigurácie.
|
||
|
||
## RAG answer evaluácia
|
||
|
||
Answer-level evaluácia používa:
|
||
|
||
```bash
|
||
python -m tools.rag.evaluation.evaluate_rag_answers --split dev
|
||
```
|
||
|
||
Evaluuje kompletný model/tool/RAG tok a od retrieval benchmarku je
|
||
oddelená.
|
||
|
||
Ak je pôvodná otázka vhodná pre retrieval, ale nejednoznačná pre
|
||
generatívnu odpoveď, jej answer-level formulácia sa upraví iba cez:
|
||
|
||
```text
|
||
tools/rag/evaluation/json_files/rag_answer_overrides.json
|
||
```
|
||
|
||
Pôvodný frozen `questions.json` tým ostáva nezmenený.
|
||
|
||
## Tokenové limity, segmenty a embeddingová cache
|
||
|
||
Chunkovanie dodrží `CHUNK_MAX_TOKENS` aj pri dlhom slove, riadku kódu,
|
||
tabuľke alebo nadpise. Posledné delenie zachová Unicode znaky a obsah;
|
||
celá cesta nadpisov zostáva v metadátach.
|
||
|
||
Finálny embeddingový vstup obsahuje názov, autora, tagy, kategórie, obsah
|
||
aj prefix `passage: `. Jeho veľkosť sa meria skutočným tokenizérom modelu
|
||
vrátane špeciálnych tokenov. Nadlimitný vstup sa bez straty obsahu rozdelí
|
||
na segmenty. Pôvodný chunk, FTS a graf ostávajú zachované. Vektorové
|
||
vyhľadávanie vyberá najlepšiu zhodu segmentu a každý chunk vráti iba raz.
|
||
Encoder nadlimitný nesegmentovaný vstup odmietne namiesto tichého orezania.
|
||
|
||
`data/embedding_cache.sqlite` uchováva vektory podľa presného vstupu a
|
||
odtlačku váh, tokenizéra a konfigurácie modelu. Pri zmene relevantných
|
||
metadát alebo modelu sa vektor prepočíta. Kontrolný súčet zachytí poškodený
|
||
záznam cache. Prvé vytvorenie novej cache prepočíta všetko; ďalšia obnova
|
||
nezmenených vstupov použije cache. Výsledok synchronizácie obsahuje
|
||
`embedding_segments`, `embedding_computed` a `embedding_reused`; počet
|
||
`embedding_chunks` stále označuje počet pokrytých pôvodných chunkov.
|
||
Cache je obnoviteľná optimalizácia; jej odstránenie pri zastavenej
|
||
synchronizácii vyvolá nový výpočet, nezmení aktívne indexy.
|
||
|
||
`POST /rag` predvolene vracia dôkazy iba raz v `context` a stručné citačné
|
||
metadáta v `sources`. Diagnostické expanzie a ich texty sa vrátia len pri
|
||
explicitnom `include_diagnostics: true`, oddelene v `diagnostics`.
|
||
RAG evaluačný klient diagnostiku pred odoslaním modelu vždy odstráni.
|
||
|
||
`RAG_LLM_MAX_TOKENS` (predvolene 12000) obmedzuje celý JSON podkladu
|
||
vrátane kontextu, pokynov, zdrojov a verzie dát. Nie je to rozpočet celej
|
||
konverzácie ani výstupu modelu. `RAG_LLM_TOKEN_ENCODING` má predvolene
|
||
`cl100k_base`; ide o explicitný odhad, nie presný tokenizér všetkých
|
||
vzdialených modelov. Výstup `context_budget` uvádza použitý tokenizér,
|
||
limit a skutočný počet podľa tohto odhadu. Pri orezaní nástroj nastaví
|
||
`complete=false`, `truncated=true` a dôvod `llm_context_budget`.
|
||
|
||
## Manuálna synchronizácia a stav úloh
|
||
|
||
`POST /sync` uloží požiadavku do persistentnej fronty a ihneď vráti HTTP 202.
|
||
Indexovanie prebieha na pozadí; prijatie požiadavky ešte neznamená dokončenie.
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/sync \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: $SYNC_API_KEY" \
|
||
-d '{"pull_git": true}'
|
||
```
|
||
|
||
Odpoveď obsahuje `job_id` a `status_url`, napríklad `/sync/jobs/<job_id>`.
|
||
Stav načítaj rovnakým `SYNC_API_KEY`:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/sync/jobs/<job_id> -H "X-API-Key: $SYNC_API_KEY"
|
||
curl http://127.0.0.1:8000/sync/status -H "X-API-Key: $SYNC_API_KEY"
|
||
```
|
||
|
||
Úloha má stav `queued`, `running`, `succeeded` alebo `failed`. Pole `phase`
|
||
rozlišuje čakanie na zámok, Git, budovanie a publikovanie indexov. Úspešná
|
||
úloha obsahuje v `result` počty, trvanie a spoločnú verziu SQLite a Neo4j.
|
||
Prehľad obsahuje aktívne úlohy, posledný úspech a posledné zlyhanie.
|
||
|
||
Fronta `data/sync_jobs.sqlite` prežije reštart. Procesový zámok povoľuje
|
||
iba jedného pracovníka; rozpracovaná úloha sa po páde zopakuje. Push prijatý
|
||
po začiatku obnovy vytvorí následnú úlohu. Ďalšie čakajúce požiadavky sa
|
||
zlúčia, pričom požiadavka na stiahnutie z Gitu sa zachová. Konflikt s CLI
|
||
obnovou spôsobí čakanie, nie stratu požiadavky. Bežná chyba sa skúsi najviac
|
||
trikrát; následne zostane viditeľný stav `failed` a možno poslať nový `/sync`.
|
||
CLI `python -m tools.rag.rebuild_index --pull` zostáva synchronný.
|
||
|
||
## Gitea webhook a prístup ku Gitu
|
||
|
||
Endpoint `POST /webhook/gitea` overuje HMAC-SHA256 nad pôvodným telom,
|
||
veľkosť payloadu, udalosť `push`, repozitár a konkrétnu vetvu z `ref`:
|
||
|
||
```dotenv
|
||
EXPECTED_GITEA_REPOSITORY=jp170na/zpwiki
|
||
EXPECTED_GITEA_BRANCH=master
|
||
WEBHOOK_PULL_GIT=true
|
||
```
|
||
|
||
Push inej vetvy a zmazanie vetvy sa ignorujú bez obnovy. `X-Gitea-Delivery`
|
||
zabraňuje opakovanému zaradeniu rovnakého doručenia. Platný push vráti HTTP
|
||
202 s odkazom na stav úlohy; nečaká na dokončenie indexovania.
|
||
|
||
Git aktualizácia overí zhodu `origin` s očakávaným repozitárom, aktívnu
|
||
vetvu a neprítomnosť lokálnych zmien vrátane nesledovaných súborov. Potom vykoná:
|
||
|
||
```bash
|
||
git fetch --no-tags --no-recurse-submodules origin refs/heads/master:refs/remotes/origin/master
|
||
git merge --ff-only refs/remotes/origin/master
|
||
```
|
||
|
||
Cieľom je aktuálna verzia nakonfigurovanej vetvy; oneskorený webhook
|
||
neprepína wiki naspäť na starší commit. Odlišná história sa automaticky
|
||
neprepisuje. Pri chybe Gitu zostávajú predchádzajúce indexy zachované.
|
||
|
||
Pre tento wiki server treba SSH. V `.env` nastav absolútne hostiteľské cesty
|
||
`ZPWIKI_SSH_KEY` a `ZPWIKI_KNOWN_HOSTS`. Compose pripája iba tieto dva súbory
|
||
na čítanie do `/run/secrets/`; kľúč sa nekopíruje do image ani repozitára.
|
||
Použi kľúč s prístupom k wiki, ideálne deploy kľúč iba na čítanie, a vopred
|
||
over záznam servera v `known_hosts`. SSH používa `BatchMode` a povinné
|
||
striktné overenie servera; pri chybe si interaktívne nepýta heslo.
|
||
|
||
Na Gitea nastav push webhook na verejne dosiahnuteľnú adresu
|
||
`https://<adresa-api>/webhook/gitea` s rovnakým `WEBHOOK_SECRET`. Lokálna
|
||
adresa `127.0.0.1` nie je zo vzdialeného Gitea servera dosiahnuteľná.
|
||
|
||
## Bezpečnosť
|
||
|
||
Vyhľadávanie podporuje API key:
|
||
|
||
```text
|
||
X-API-Key: <SEARCH_API_KEY>
|
||
```
|
||
|
||
aj Bearer autentifikáciu:
|
||
|
||
```text
|
||
Authorization: Bearer <SEARCH_API_KEY>
|
||
```
|
||
|
||
Endpoint `/sync` používa samostatný `SYNC_API_KEY` a webhook samostatný
|
||
`WEBHOOK_SECRET`.
|
||
|
||
Tajomstvá sa ukladajú do `.env`, ktorý nesmie byť súčasťou Git
|
||
repozitára.
|
||
|
||
Bezpečnostná vrstva zároveň kontroluje minimálnu dĺžku tajomstiev,
|
||
odlišnosť jednotlivých secretov a používa bezpečné porovnávanie
|
||
hodnôt.
|
||
|
||
## Testy
|
||
|
||
Inštalácia testovacích závislostí:
|
||
|
||
```bash
|
||
pip install -r requirements-dev.txt
|
||
```
|
||
|
||
Bežné automatizované testy:
|
||
|
||
```bash
|
||
pytest -q
|
||
```
|
||
|
||
Kompletná lokálna kontrola s bežiacim projektom a `.env`:
|
||
|
||
```bash
|
||
.venv/bin/python scripts/verify_project.py --git-network
|
||
```
|
||
|
||
Skript skompiluje všetky Python súbory v aplikácii, nástrojoch, testoch
|
||
a skriptoch, overí interné importy a syntax shell skriptov, Git,
|
||
Compose, API, spoločnú verziu indexov, integritu SQLite a kompletnú
|
||
regresiu vrátane lokálneho Neo4j. Prepínač `--git-network` navyše iba
|
||
načíta hlavičku nastavenej wiki vetvy cez existujúce SSH pripojenie.
|
||
Počas pytestu sú externé spojenia zablokované a kľúč generujúceho modelu
|
||
odstránený. Výsledky a log ostávajú lokálne v `data/`.
|
||
|
||
Kontrola syntaxe najdôležitejších upravovaných modulov:
|
||
|
||
```bash
|
||
python -m py_compile \
|
||
tools/rag/rag_utils.py \
|
||
tools/rag/evaluation/evaluate_rag_answers.py \
|
||
tools/rag/evaluation/rag_runner.py \
|
||
tools/rag/evaluation/rag_metrics.py
|
||
```
|
||
|
||
Pred checkpointom je vhodné použiť aj:
|
||
|
||
```bash
|
||
git diff --check
|
||
git status
|
||
```
|
||
|
||
Pevný počet `pytest` výsledkov nie je v README uvádzaný, pretože sa
|
||
s vývojom mení. Aktuálny stav sa má vždy potvrdiť novým spustením testov
|
||
na konkrétnom commite.
|
||
|
||
## Experimentálne datasety
|
||
|
||
Pre ďalšie experimenty sú pripravené:
|
||
|
||
```text
|
||
questions_extended.json
|
||
graphrag_questions.json
|
||
robustness_questions.json
|
||
performance_queries.json
|
||
```
|
||
|
||
`graphrag_questions.json` je aktuálne určený pre vývoj GraphRAG vetvy.
|
||
Ostatné datasety zostávajú oddelené od priebežného ladenia frozen
|
||
klasického baseline.
|
||
|
||
## Najbližší postup
|
||
|
||
Klasický RAG a GraphRAG sú oddelené do samostatných komponentov v
|
||
`tools/rag/` a `tools/graphrag/`. Stabilný klasický RAG zostáva
|
||
referenčným bodom.
|
||
|
||
### 1. GraphRAG dátový model
|
||
|
||
Model je implementovaný. Rozlišuje autora dokumentu, študenta, záverečnú
|
||
prácu, projekt, tému a kľúčové slovo. Študijný program sa nedopĺňa bez
|
||
spoľahlivého zdroja.
|
||
|
||
### 2. GraphRAG evaluácia
|
||
|
||
V7 má zmrazený graf, DEV **1 046/1 046** a nový TEST **80/80**.
|
||
[Finálne metriky](tools/graphrag/evaluation/results/final_v7_2026-10-26/summary.json)
|
||
oddeľuje nový TEST od historickej regresie a vyhľadávanie od modelu
|
||
s kontrolami a rendererom; pôvodné v1–v6 sa nemenia.
|
||
Pred formálnym porovnaním s klasickým RAG potrebujeme spoločnú metodiku
|
||
a ideálne otázky anotované nezávislým človekom. Nový nezávislý TEST vyžaduje
|
||
nové otázky; opakované meranie odhalených otázok je regresia.
|
||
|
||
### 3. OpenWebUI nástroje
|
||
|
||
Pripraviť samostatne inštalovateľný RAG nástroj a GraphRAG nástroj.
|
||
Každý komponent bude mať vlastný adresár, rozhranie a testy.
|
||
|
||
### 4. Hlavný agent
|
||
|
||
Pridať hlavný prompt/agenta, ktorý podľa otázky vyberie vhodný nástroj a
|
||
bude vedieť kombinovať ich výsledky.
|
||
|
||
### 5. Git MCP server
|
||
|
||
Pridať samostatný MCP server pre prácu s Git repozitárom a spúšťať ho v
|
||
Dockeri. Následne ho sprístupniť hlavnému agentovi ako ďalší nástroj.
|
||
|
||
### 6. Spojenie GraphRAG s klasickým RAG
|
||
|
||
Po stabilizovaní grafového vyhľadávania spojiť výsledky grafu s
|
||
existujúcim FTS5 + embedding vyhľadávaním a porovnať klasický RAG s
|
||
GraphRAG variantom.
|
||
|
||
### 7. Finálne experimenty
|
||
|
||
Až po stabilizovaní celého systému vykonať širšie porovnanie embedding
|
||
modelov, robustnosti, výkonu a ostatných finálnych experimentov.
|