67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# ZP Agent
|
||
|
||
Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom
|
||
záverečných prác `zpwiki`.
|
||
|
||
Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**.
|
||
Spracúva profily študentov, zadania a poznámky zo ZP Wiki a poskytuje
|
||
odpovede o prácach, projektoch, rokoch a súvisiacich vzťahoch so zdrojovými odkazmi.
|
||
|
||
## Ako funguje
|
||
|
||
1. Načíta Markdown dokumenty a YAML metadáta z lokálnej kópie Git repozitára.
|
||
2. Rozdelí obsah na tokenové úseky a vytvorí textový, vektorový a grafový index.
|
||
3. Podľa zvoleného nástroja vyhľadá relevantné texty alebo grafové fakty.
|
||
4. Jazykový model vyberie dôkazy alebo navrhne štruktúrované tvrdenia.
|
||
5. Backend skontroluje hodnoty, väzby, citácie a pokrytie požadovaných údajov.
|
||
6. Z overených podkladov zostaví odpoveď; chýbajúce informácie výslovne označí.
|
||
|
||
Aktualizáciu možno spustiť manuálne alebo webhookom z Gitea. Oba indexy
|
||
sa obnovujú z rovnakého snapshotu a používajú spoločnú verziu dát.
|
||
|
||
## Vyhľadávanie
|
||
|
||
**RAG** kombinuje fulltextové vyhľadávanie BM25 so sémantickým vyhľadávaním
|
||
pomocou embeddingov. Výsledky spája metódou RRF. Je vhodný na otázky
|
||
na obsah, zadanie, metódy, priebeh a výsledky práce.
|
||
|
||
**GraphRAG** využíva znalostný graf osôb, dokumentov, prác, projektov,
|
||
tém, tagov a kategórií. Umožňuje vyhľadávať vzťahy, spoločné vlastnosti
|
||
a kombinácie podmienok, napríklad tag spolu s typom a rokom práce.
|
||
|
||
Obsahový graf dopĺňa pojmy a vzťahy extrahované jazykovým modelom z profilov
|
||
študentov. Každý poznatok zostáva spojený s pôvodným výňatkom, osobou, prácou
|
||
a explicitne uvedeným dátumom. Podporuje otázky na pokrok, čas výsledkov,
|
||
podobné témy a študentov venujúcich sa určitej činnosti. Zadanie ani plán
|
||
sa nevydávajú za dokončený výsledok; chýbajúce údaje sa neodhadujú.
|
||
Pri výsledkoch sa rozlišuje dátum záznamu od skutočného dňa vykonania práce.
|
||
Repozitárové odkazy sa overujú cez verejné API; neoveriteľné odkazy sa nezobrazujú.
|
||
|
||
Extrakciu spúšťa `python -m tools.knowledge.build` s nakonfigurovaným LLM API.
|
||
Vyžaduje pripravené spoločné indexy a Neo4j. Nezmenené vstupy využívajú cache;
|
||
po prvom vytvorení sa obsahový index obnovuje aj pri synchronizácii.
|
||
Claude Skills sú klientom rovnakého backendu, jeho logika nezávisí od rozhrania.
|
||
Voliteľný Compose profil `claude-tunnel` pripája Cloudflare priamo k službe MCP
|
||
v Docker sieti. Dočasná verejná URL vyžaduje zodpovedajúce OAuth nastavenie
|
||
`ZP_MCP_PUBLIC_URL`; po vytvorení nového tunela sa môže zmeniť.
|
||
|
||
## Použité technológie
|
||
|
||
- **Python, FastAPI a Pydantic** – API, validácia vstupov a typované odpovede.
|
||
- **SQLite a FTS5** – dokumenty, metadáta, fulltextový index a uložené vektory.
|
||
- **Sentence Transformers a multilingual-e5-small** – viacjazyčné embeddingy.
|
||
- **Tiktoken** – meranie veľkosti a delenie textových úsekov.
|
||
- **Neo4j a Cypher** – uloženie a vyhľadávanie grafových vzťahov.
|
||
- **MCP a Claude Skills** – sprístupnenie RAG a GraphRAG používateľovi v Claude.
|
||
- **OAuth s PKCE** – autentizácia webového MCP konektora.
|
||
- **Docker Compose** – spoločné nasadenie API, Neo4j a MCP servera.
|
||
- **Git a Gitea webhooky** – získavanie zmien a spúšťanie synchronizácie.
|
||
- **Pytest a evaluačné skripty** – regresie, kontrola vyhľadávania a odpovedí.
|
||
|
||
## Súčasný stav
|
||
|
||
RAG, GraphRAG, kontrolovaná cesta odpovedí a pripojenie cez Claude sú funkčné.
|
||
Systém obsahuje embeddingovú cache, kontroly dostupnosti a persistentnú
|
||
synchronizačnú frontu. Historické evaluácie sú uložené pri jednotlivých vetvách.
|
||
Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.
|