Stručný opis projektu
This commit is contained in:
parent
fa33a73e6a
commit
49c8159e2a
106
README.md
106
README.md
@ -3,86 +3,48 @@
|
|||||||
Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom
|
Backend pre indexovanie, hybridné vyhľadávanie a RAG nad repozitárom
|
||||||
záverečných prác `zpwiki`.
|
záverečných prác `zpwiki`.
|
||||||
|
|
||||||
## Účel
|
|
||||||
|
|
||||||
Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**.
|
Projekt vzniká v rámci práce **Agent pre manažment záverečných prác**.
|
||||||
Spracúva profily študentov, zadania a priebežné poznámky zo ZP Wiki.
|
Spracúva profily študentov, zadania a poznámky zo ZP Wiki a poskytuje
|
||||||
Poskytuje dohľadateľné odpovede o prácach, projektoch, rokoch a vzťahoch
|
odpovede o prácach, projektoch, rokoch a súvisiacich vzťahoch so zdrojovými odkazmi.
|
||||||
prostredníctvom klasického RAG a grafového vyhľadávania v Neo4j.
|
|
||||||
|
|
||||||
## Implementované funkcie
|
## Ako funguje
|
||||||
|
|
||||||
- Import Markdownov a YAML metadát, štruktúrne tokenové chunkovanie.
|
1. Načíta Markdown dokumenty a YAML metadáta z lokálnej kópie Git repozitára.
|
||||||
- SQLite FTS5/BM25, viacjazyčné embeddingy E5 a hybridné radenie RRF.
|
2. Rozdelí obsah na tokenové úseky a vytvorí textový, vektorový a grafový index.
|
||||||
- Segmentácia finálnych embeddingových vstupov a cache nezmenených vektorov.
|
3. Podľa zvoleného nástroja vyhľadá relevantné texty alebo grafové fakty.
|
||||||
- Deterministický znalostný graf a parametrizované vyhľadávanie v Neo4j.
|
4. Jazykový model vyberie dôkazy alebo navrhne štruktúrované tvrdenia.
|
||||||
- Kontrola faktov, väzieb, citácií, počtov a úplnosti pred doručením odpovede.
|
5. Backend skontroluje hodnoty, väzby, citácie a pokrytie požadovaných údajov.
|
||||||
- Rozlíšenie zadania, plánov, priebežného stavu a výsledkov práce.
|
6. Z overených podkladov zostaví odpoveď; chýbajúce informácie výslovne označí.
|
||||||
- Spoločná synchronizácia SQLite a Neo4j z Gitu, webhook a persistentná fronta.
|
|
||||||
- FastAPI, Docker Compose, kontroly dostupnosti a modelové assets pre offline štart.
|
|
||||||
- Claude Skills a MCP konektor s OAuth/PKCE pre RAG, GraphRAG a stav služieb.
|
|
||||||
- Retrieval evaluácia, zdrojové audity a automatické regresné testy.
|
|
||||||
|
|
||||||
## Architektúra
|
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.
|
||||||
|
|
||||||
```text
|
## Vyhľadávanie
|
||||||
zpwiki (Git) -> Markdown/YAML -> spoločný snapshot
|
|
||||||
|-- SQLite: FTS5 + embeddingy
|
|
||||||
`-- Neo4j: entity + vzťahy
|
|
||||||
|
|
||||||
Claude + Skills -> HTTPS/OAuth -> MCP -> FastAPI /answer
|
**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.
|
||||||
| |
|
|
||||||
RAG / SQLite GraphRAG / Neo4j
|
|
||||||
| |
|
|
||||||
+------------+------------+
|
|
||||||
|
|
|
||||||
model -> kontroly -> renderer
|
|
||||||
|
|
|
||||||
odpoveď + zdrojové odkazy
|
|
||||||
```
|
|
||||||
|
|
||||||
`/rag` a `/graphrag` vracajú podklady. `/answer` vykonáva kontrolovanú
|
**GraphRAG** využíva znalostný graf osôb, dokumentov, prác, projektov,
|
||||||
prípravu odpovede; pri nedostatočných dôkazoch informáciu nedopĺňa odhadom.
|
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.
|
||||||
|
|
||||||
## Štruktúra
|
## Použité technológie
|
||||||
|
|
||||||
| Priečinok | Obsah |
|
- **Python, FastAPI a Pydantic** – API, validácia vstupov a typované odpovede.
|
||||||
| --- | --- |
|
- **SQLite a FTS5** – dokumenty, metadáta, fulltextový index a uložené vektory.
|
||||||
| `app/` | FastAPI, vstupné modely a autorizácia. |
|
- **Sentence Transformers a multilingual-e5-small** – viacjazyčné embeddingy.
|
||||||
| `tools/rag/` | Import, chunky, SQLite a hybridné vyhľadávanie. |
|
- **Tiktoken** – meranie veľkosti a delenie textových úsekov.
|
||||||
| `tools/graphrag/` | Dátový model, Neo4j, grafové dotazy a evaluácia. |
|
- **Neo4j a Cypher** – uloženie a vyhľadávanie grafových vzťahov.
|
||||||
| `tools/answers/`, `tools/answer_evaluation/` | Generovanie, dôkazy, kontroly a metriky. |
|
- **MCP a Claude Skills** – sprístupnenie RAG a GraphRAG používateľovi v Claude.
|
||||||
| `tools/retrieval/`, `tools/sync/`, `tools/runtime/` | Kontrakty, synchronizácia a prevádzka. |
|
- **OAuth s PKCE** – autentizácia webového MCP konektora.
|
||||||
| `packages/claude/` | Skills, MCP, OAuth, klient a inštalovateľné ZIPy. |
|
- **Docker Compose** – spoločné nasadenie API, Neo4j a MCP servera.
|
||||||
| `deployment/`, `scripts/` | Docker, závislosti, štart a overovacie skripty. |
|
- **Git a Gitea webhooky** – získavanie zmien a spúšťanie synchronizácie.
|
||||||
| `test/`, `tools/*/tests/` | Jednotkové a integračné regresie. |
|
- **Pytest a evaluačné skripty** – regresie, kontrola vyhľadávania a odpovedí.
|
||||||
|
|
||||||
## Spustenie
|
## Súčasný stav
|
||||||
|
|
||||||
Vyžaduje Docker s Compose v2 a Buildx, lokálny klon wiki v `../zpwiki`
|
RAG, GraphRAG, kontrolovaná cesta odpovedí a pripojenie cez Claude sú funkčné.
|
||||||
a súbor `.env` s konfiguráciou kľúčov, Neo4j, Git prístupu a modelového API.
|
Systém obsahuje embeddingovú cache, kontroly dostupnosti a persistentnú
|
||||||
Prvý build potrebuje sieť na získanie závislostí a modelových súborov.
|
synchronizačnú frontu. Historické evaluácie sú uložené pri jednotlivých vetvách.
|
||||||
Pre webový Claude treba navyše dostupnú HTTPS adresu MCP a OAuth nastavenia.
|
Samostatný hlavný agent, CRZP a spracovanie plných textov prác sú ďalšie etapy.
|
||||||
|
|
||||||
```bash
|
|
||||||
./scripts/start_project.sh
|
|
||||||
./scripts/compose.sh --profile claude up -d --build
|
|
||||||
curl http://127.0.0.1:8000/health
|
|
||||||
```
|
|
||||||
|
|
||||||
Konfiguráciu služieb určuje [Docker Compose](deployment/docker-compose.yml).
|
|
||||||
Klientské pokyny sú v [RAG Skill](packages/claude/rag/SKILL.md) a
|
|
||||||
[GraphRAG Skill](packages/claude/graphrag/SKILL.md).
|
|
||||||
Balíky sa zostavia cez `python scripts/build_claude_packages.py`.
|
|
||||||
Lokálne overenie poskytuje `scripts/verify_project.py` po príprave jeho závislostí.
|
|
||||||
|
|
||||||
## Stav a ďalší vývoj
|
|
||||||
|
|
||||||
Obe vetvy a kontrolovaná cesta odpovedí sú funkčné a overené aj cez Claude.
|
|
||||||
Prototyp používa dočasný HTTPS tunel; trvalé nasadenie zostáva ďalšou etapou.
|
|
||||||
Plánované sú tolerantné rozpoznávanie mien, hlavný agent, Git nástroje,
|
|
||||||
CRZP, plné texty prác a spoločné porovnanie RAG/GraphRAG a modelov.
|
|
||||||
Historické merania sú v evaluačných priečinkoch; nepredstavujú univerzálnu
|
|
||||||
záruku presnosti aktuálneho agenta. Tajomstvá, databázy a modelové váhy nepatria na Git.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user