jp170na/dp-zp-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Ján Pták 2026-06-04 17:26:38 +02:00
parent b6f4857ba6
commit 44eb3cd679
1 changed files with 133 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
README.md
View File

@ -2,7 +2,7 @@
Agent pre manažment záverečných prác nad repozitárom `zpwiki`.
Projekt zatiaľ rieši základnú časť systému pre vyhľadávanie v Markdown súboroch zo školského repozitára záverečných prác. Cieľom je vytvoriť samostatnú službu, ktorá vie indexovať obsah `zpwiki`, vyhľadávať v ňom a neskôr sa napojí na OpenWebUI, RAG, znalostný graf a webhook synchronizáciu.
Projekt rieši základnú službu pre indexovanie a vyhľadávanie v Markdown súboroch zo školského repozitára záverečných prác. Cieľom je vytvoriť samostatné API, ktoré vie načítať obsah `zpwiki`, spracovať metadata, rozdeliť dokumenty na chunky, vyhľadávať v nich a neskôr sa napojiť na OpenWebUI, RAG, znalostný graf a Gitea webhook.
## Aktuálny stav
@ -17,8 +17,16 @@ Zatiaľ je implementované:
7. rozlíšenie režimu vyhľadávania:
1. `person` pre mená osôb, napríklad `jan ptak`,
2. `topic` pre tematické dopyty, napríklad `rag agent` alebo `knowledge graph`,
8. FastAPI backend s endpointmi `/health` a `/search`,
9. automatická Swagger dokumentácia API.
8. FastAPI backend s endpointmi:
1. `/health`,
2. `/search`,
3. `/sync`,
9. automatická Swagger dokumentácia API,
10. Dockerfile pre zostavenie API kontajnera,
11. `docker-compose.yml` pre spustenie služby,
12. mount repozitára `zpwiki` do kontajnera,
13. environment premenná `ZPWIKI_ROOT`,
14. reindexovanie dát cez endpoint `/sync`.
## Štruktúra projektu
@ -31,10 +39,14 @@ dp-zp-agent/
│ ├── scan_zpwiki.py
│ ├── build_chunks.py
│ ├── build_sqlite_index.py
│ ├── rebuild_index.py
│ ├── search_chunks.py
│ └── search_db.py
├── data/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .dockerignore
├── .gitignore
└── README.md
```
@ -79,6 +91,18 @@ Nakoniec sa vytvorí SQLite index:
python scripts/build_sqlite_index.py
```
Alebo sa dá celý index obnoviť jedným príkazom:
```bash
python scripts/rebuild_index.py
```
S voliteľným `git pull` pred reindexovaním:
```bash
python scripts/rebuild_index.py --pull
```
## Testovanie vyhľadávania v termináli
Vyhľadávanie podľa osoby:
@ -99,7 +123,7 @@ Vyhľadávanie podľa znalostného grafu:
python scripts/search_db.py "knowledge graph"
```
## Spustenie API
## Spustenie API lokálne
FastAPI server sa spustí príkazom:
@ -121,6 +145,24 @@ curl -X POST http://127.0.0.1:8000/search \
-d '{"query":"jan ptak","limit":5}'
```
Reindexovanie cez API:
```bash
curl -X POST http://127.0.0.1:8000/sync \
-H "Content-Type: application/json" \
-d '{"pull_git":false}'
```
Reindexovanie aj s `git pull`:
```bash
curl -X POST http://127.0.0.1:8000/sync \
-H "Content-Type: application/json" \
-d '{"pull_git":true}'
```
Poznámka: pri Docker verzii môže `pull_git:true` vyžadovať vyriešenie SSH prístupu ku Gitu. Zatiaľ je bezpečné používať hlavne `pull_git:false`.
## Swagger UI
FastAPI automaticky generuje Swagger dokumentáciu API.
@ -131,26 +173,68 @@ Po spustení servera je dostupná na adrese:
http://127.0.0.1:8000/docs
```
V Swagger UI je možné testovať endpointy `/health` a `/search` priamo z prehliadača.
V Swagger UI je možné testovať endpointy `/health`, `/search` a `/sync` priamo z prehliadača.
## Čo ešte treba dorobiť
## Spustenie cez Docker
### 1. Dockerizácia aplikácie
Treba vytvoriť:
1. `Dockerfile`,
2. `docker-compose.yml`,
3. jednoduchý návod na spustenie cez Docker,
4. volume alebo mount pre dáta a SQLite databázu.
Cieľ je, aby sa služba dala spustiť jedným príkazom:
Služba sa dá spustiť cez Docker Compose:
```bash
docker compose up --build
```
### 2. Upratanie kódu do modulov
Po spustení je API dostupné na:
```text
http://127.0.0.1:8000
```
Swagger UI:
```text
http://127.0.0.1:8000/docs
```
Health check:
```bash
curl http://127.0.0.1:8000/health
```
Vyhľadávanie:
```bash
curl -X POST http://127.0.0.1:8000/search \
-H "Content-Type: application/json" \
-d '{"query":"knowledge graph","limit":5}'
```
Reindexovanie:
```bash
curl -X POST http://127.0.0.1:8000/sync \
-H "Content-Type: application/json" \
-d '{"pull_git":false}'
```
V `docker-compose.yml` je repozitár `zpwiki` pripojený ako volume:
```yaml
volumes:
- ./data:/app/data
- ../zpwiki:/zpwiki
```
A cesta k nemu je nastavená cez environment premennú:
```yaml
environment:
- ZPWIKI_ROOT=/zpwiki
```
## Čo ešte treba dorobiť
### 1. Upratanie kódu do modulov
Aktuálne je veľká časť logiky priamo v `app/main.py`. Neskôr treba kód rozdeliť napríklad takto:
@ -166,19 +250,20 @@ app/
Cieľ je, aby API, vyhľadávanie, databáza a synchronizácia neboli v jednom veľkom súbore.
### 3. Synchronizácia so `zpwiki`
### 2. Vylepšenie synchronizácie so `zpwiki`
Treba pridať mechanizmus, ktorý bude vedieť aktualizovať dáta zo školského repozitára.
Aktuálne endpoint `/sync` vie obnoviť celý index. Neskôr treba pridať efektívnejšiu synchronizáciu.
Plánované časti:
Treba dorobiť:
1. skript pre `git pull`,
2. zistenie aktuálneho commitu,
3. detekcia zmenených Markdown súborov,
4. reindexovanie zmenených dokumentov,
5. uloženie stavu synchronizácie do databázy.
1. zistenie aktuálneho commitu,
2. uloženie posledného spracovaného commitu,
3. detekciu zmenených Markdown súborov,
4. reindexovanie iba zmenených dokumentov,
5. uloženie stavu synchronizácie do databázy,
6. logovanie výsledkov synchronizácie.
### 4. Webhook endpoint pre Git
### 3. Webhook endpoint pre Gitea
Treba vytvoriť endpoint napríklad:
@ -190,11 +275,12 @@ Tento endpoint má:
1. prijať webhook z Gitea,
2. overiť secret alebo podpis webhooku,
3. spustiť synchronizáciu repozitára,
4. spustiť reindexovanie zmenených súborov,
5. zapísať výsledok do logu alebo tabuľky synchronizácie.
3. spracovať push event,
4. spustiť synchronizáciu repozitára,
5. spustiť reindexovanie,
6. vrátiť výsledok synchronizácie.
### 5. OpenWebUI integrácia
### 4. OpenWebUI integrácia
Treba napojiť API na OpenWebUI.
@ -207,7 +293,7 @@ Možné riešenia:
Cieľ je, aby používateľ mohol v OpenWebUI položiť otázku a agent použil vyhľadávanie nad `zpwiki`.
### 6. Embeddingy a vektorové vyhľadávanie
### 5. Embeddingy a vektorové vyhľadávanie
Aktuálne vyhľadávanie je fulltextové a skórovacie. Ďalší krok je pridať embeddingy.
@ -219,14 +305,14 @@ Treba dorobiť:
4. vektorové vyhľadávanie,
5. porovnanie fulltextového a vektorového vyhľadávania.
Možné databázy:
Možné databázy alebo nástroje:
1. PostgreSQL plus pgvector,
2. Qdrant,
3. ChromaDB,
4. FAISS ako jednoduchý lokálny prototyp.
### 7. RAG odpovede s citáciami
### 6. RAG odpovede s citáciami
Treba doplniť generovanie odpovede pomocou jazykového modelu.
@ -240,7 +326,7 @@ Postup:
Cieľ je, aby agent nehalucinoval a vedel ukázať, z ktorých dokumentov odpovedal.
### 8. Znalostný graf
### 7. Znalostný graf
Treba vytvoriť štruktúrovaný graf nad dátami zo `zpwiki`.
@ -262,7 +348,7 @@ Základné vzťahy:
5. práca je podobná inej práci,
6. práca patrí do roka alebo obdobia.
### 9. GraphRAG
### 8. GraphRAG
Treba prepojiť RAG a znalostný graf.
@ -274,7 +360,7 @@ GraphRAG časť má umožniť:
4. analýzu tém podľa tagov, rokov a kategórií,
5. kombináciu textového, vektorového a grafového vyhľadávania.
### 10. Vyhodnotenie systému
### 9. Vyhodnotenie systému
Treba pripraviť testovaciu sadu otázok a porovnať viacero prístupov.
@ -303,7 +389,7 @@ Sledované vlastnosti:
5. čas odpovede,
6. čas reindexovania po zmene v Gite.
### 11. Dokumentácia do diplomovej práce
### 10. Dokumentácia do diplomovej práce
Treba priebežne písať:
@ -314,19 +400,20 @@ Treba priebežne písať:
5. ako funguje `zpwiki`,
6. návrh architektúry systému,
7. návrh databázy a indexu,
8. návrh webhook synchronizácie,
9. návrh integrácie s OpenWebUI,
10. popis experimentov a vyhodnotenia.
8. návrh synchronizácie,
9. návrh webhook integrácie,
10. návrh integrácie s OpenWebUI,
11. popis experimentov a vyhodnotenia.
## Najbližší praktický krok
Najbližšie treba spraviť Docker nasadenie aktuálneho FastAPI prototypu.
Najbližšie treba spraviť Gitea webhook endpoint.
Poradie najbližších krokov:
1. doplniť `README.md`,
1. commitnúť aktuálne zmeny,
2. pushnúť projekt na KEMT Git,
3. vytvoriť `Dockerfile`,
4. vytvoriť `docker-compose.yml`,
5. spustiť API cez Docker,
6. pripraviť základ pre webhook synchronizáciu.
3. vytvoriť endpoint `POST /webhook/gitea`,
4. pridať overenie secretu alebo podpisu webhooku,
5. napojiť webhook na `/sync`,
6. otestovať webhook lokálne alebo cez verejne dostupný tunel.