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
|
||||
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**.
|
||||
Spracúva profily študentov, zadania a priebežné poznámky zo ZP Wiki.
|
||||
Poskytuje dohľadateľné odpovede o prácach, projektoch, rokoch a vzťahoch
|
||||
prostredníctvom klasického RAG a grafového vyhľadávania v Neo4j.
|
||||
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.
|
||||
|
||||
## Implementované funkcie
|
||||
## Ako funguje
|
||||
|
||||
- Import Markdownov a YAML metadát, štruktúrne tokenové chunkovanie.
|
||||
- SQLite FTS5/BM25, viacjazyčné embeddingy E5 a hybridné radenie RRF.
|
||||
- Segmentácia finálnych embeddingových vstupov a cache nezmenených vektorov.
|
||||
- Deterministický znalostný graf a parametrizované vyhľadávanie v Neo4j.
|
||||
- Kontrola faktov, väzieb, citácií, počtov a úplnosti pred doručením odpovede.
|
||||
- Rozlíšenie zadania, plánov, priebežného stavu a výsledkov práce.
|
||||
- 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.
|
||||
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čí.
|
||||
|
||||
## 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
|
||||
zpwiki (Git) -> Markdown/YAML -> spoločný snapshot
|
||||
|-- SQLite: FTS5 + embeddingy
|
||||
`-- Neo4j: entity + vzťahy
|
||||
## Vyhľadávanie
|
||||
|
||||
Claude + Skills -> HTTPS/OAuth -> MCP -> FastAPI /answer
|
||||
|
|
||||
+------------+------------+
|
||||
| |
|
||||
RAG / SQLite GraphRAG / Neo4j
|
||||
| |
|
||||
+------------+------------+
|
||||
|
|
||||
model -> kontroly -> renderer
|
||||
|
|
||||
odpoveď + zdrojové odkazy
|
||||
```
|
||||
**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` a `/graphrag` vracajú podklady. `/answer` vykonáva kontrolovanú
|
||||
prípravu odpovede; pri nedostatočných dôkazoch informáciu nedopĺňa odhadom.
|
||||
**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.
|
||||
|
||||
## Štruktúra
|
||||
## Použité technológie
|
||||
|
||||
| Priečinok | Obsah |
|
||||
| --- | --- |
|
||||
| `app/` | FastAPI, vstupné modely a autorizácia. |
|
||||
| `tools/rag/` | Import, chunky, SQLite a hybridné vyhľadávanie. |
|
||||
| `tools/graphrag/` | Dátový model, Neo4j, grafové dotazy a evaluácia. |
|
||||
| `tools/answers/`, `tools/answer_evaluation/` | Generovanie, dôkazy, kontroly a metriky. |
|
||||
| `tools/retrieval/`, `tools/sync/`, `tools/runtime/` | Kontrakty, synchronizácia a prevádzka. |
|
||||
| `packages/claude/` | Skills, MCP, OAuth, klient a inštalovateľné ZIPy. |
|
||||
| `deployment/`, `scripts/` | Docker, závislosti, štart a overovacie skripty. |
|
||||
| `test/`, `tools/*/tests/` | Jednotkové a integračné regresie. |
|
||||
- **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í.
|
||||
|
||||
## Spustenie
|
||||
## Súčasný stav
|
||||
|
||||
Vyžaduje Docker s Compose v2 a Buildx, lokálny klon wiki v `../zpwiki`
|
||||
a súbor `.env` s konfiguráciou kľúčov, Neo4j, Git prístupu a modelového API.
|
||||
Prvý build potrebuje sieť na získanie závislostí a modelových súborov.
|
||||
Pre webový Claude treba navyše dostupnú HTTPS adresu MCP a OAuth nastavenia.
|
||||
|
||||
```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.
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user