420 lines
9.2 KiB
Markdown
420 lines
9.2 KiB
Markdown
# dp-zp-agent
|
|
|
|
Agent pre manažment záverečných prác nad repozitárom `zpwiki`.
|
|
|
|
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
|
|
|
|
Zatiaľ je implementované:
|
|
|
|
1. načítanie Markdown súborov z repozitára `zpwiki`,
|
|
2. extrakcia metadát z YAML front matter,
|
|
3. spracovanie položiek `taxonomy`, hlavne kategórie, tagy a autor,
|
|
4. rozdelenie dokumentov na menšie textové chunky,
|
|
5. vytvorenie SQLite indexu,
|
|
6. jednoduché fulltextové vyhľadávanie nad chunkmi,
|
|
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:
|
|
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
|
|
|
|
```text
|
|
dp-zp-agent/
|
|
├── app/
|
|
│ ├── __init__.py
|
|
│ └── main.py
|
|
├── scripts/
|
|
│ ├── 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
|
|
```
|
|
|
|
## Príprava prostredia
|
|
|
|
Projekt očakáva, že vedľa neho existuje naklonovaný repozitár `zpwiki`.
|
|
|
|
Odporúčaná štruktúra:
|
|
|
|
```text
|
|
~/DP/
|
|
├── zpwiki
|
|
└── zp-agent
|
|
```
|
|
|
|
Vytvorenie a aktivácia Python prostredia:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Vygenerovanie dát a indexu
|
|
|
|
Najprv sa načítajú dokumenty a metadata:
|
|
|
|
```bash
|
|
python scripts/scan_zpwiki.py
|
|
```
|
|
|
|
Potom sa dokumenty rozdelia na chunky:
|
|
|
|
```bash
|
|
python scripts/build_chunks.py
|
|
```
|
|
|
|
Nakoniec sa vytvorí SQLite index:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
python scripts/search_db.py "jan ptak"
|
|
```
|
|
|
|
Vyhľadávanie podľa témy:
|
|
|
|
```bash
|
|
python scripts/search_db.py "rag agent"
|
|
```
|
|
|
|
Vyhľadávanie podľa znalostného grafu:
|
|
|
|
```bash
|
|
python scripts/search_db.py "knowledge graph"
|
|
```
|
|
|
|
## Spustenie API lokálne
|
|
|
|
FastAPI server sa spustí príkazom:
|
|
|
|
```bash
|
|
uvicorn app.main:app --reload
|
|
```
|
|
|
|
Health check:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/health
|
|
```
|
|
|
|
Vyhľadávanie cez API:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/search \
|
|
-H "Content-Type: application/json" \
|
|
-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.
|
|
|
|
Po spustení servera je dostupná na adrese:
|
|
|
|
```text
|
|
http://127.0.0.1:8000/docs
|
|
```
|
|
|
|
V Swagger UI je možné testovať endpointy `/health`, `/search` a `/sync` priamo z prehliadača.
|
|
|
|
## Spustenie cez Docker
|
|
|
|
Služba sa dá spustiť cez Docker Compose:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
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:
|
|
|
|
```text
|
|
app/
|
|
├── main.py
|
|
├── search.py
|
|
├── database.py
|
|
├── schemas.py
|
|
├── sync.py
|
|
└── webhook.py
|
|
```
|
|
|
|
Cieľ je, aby API, vyhľadávanie, databáza a synchronizácia neboli v jednom veľkom súbore.
|
|
|
|
### 2. Vylepšenie synchronizácie so `zpwiki`
|
|
|
|
Aktuálne endpoint `/sync` vie obnoviť celý index. Neskôr treba pridať efektívnejšiu synchronizáciu.
|
|
|
|
Treba dorobiť:
|
|
|
|
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.
|
|
|
|
### 3. Webhook endpoint pre Gitea
|
|
|
|
Treba vytvoriť endpoint napríklad:
|
|
|
|
```text
|
|
POST /webhook/gitea
|
|
```
|
|
|
|
Tento endpoint má:
|
|
|
|
1. prijať webhook z Gitea,
|
|
2. overiť secret alebo podpis webhooku,
|
|
3. spracovať push event,
|
|
4. spustiť synchronizáciu repozitára,
|
|
5. spustiť reindexovanie,
|
|
6. vrátiť výsledok synchronizácie.
|
|
|
|
### 4. OpenWebUI integrácia
|
|
|
|
Treba napojiť API na OpenWebUI.
|
|
|
|
Možné riešenia:
|
|
|
|
1. OpenAPI tool server,
|
|
2. OpenWebUI tool,
|
|
3. OpenWebUI pipeline,
|
|
4. vlastný agent, ktorý bude volať endpoint `/search`.
|
|
|
|
Cieľ je, aby používateľ mohol v OpenWebUI položiť otázku a agent použil vyhľadávanie nad `zpwiki`.
|
|
|
|
### 5. Embeddingy a vektorové vyhľadávanie
|
|
|
|
Aktuálne vyhľadávanie je fulltextové a skórovacie. Ďalší krok je pridať embeddingy.
|
|
|
|
Treba dorobiť:
|
|
|
|
1. výber embedding modelu,
|
|
2. generovanie embeddingov pre chunky,
|
|
3. uloženie embeddingov,
|
|
4. vektorové vyhľadávanie,
|
|
5. porovnanie fulltextového a vektorového vyhľadávania.
|
|
|
|
Možné databázy alebo nástroje:
|
|
|
|
1. PostgreSQL plus pgvector,
|
|
2. Qdrant,
|
|
3. ChromaDB,
|
|
4. FAISS ako jednoduchý lokálny prototyp.
|
|
|
|
### 6. RAG odpovede s citáciami
|
|
|
|
Treba doplniť generovanie odpovede pomocou jazykového modelu.
|
|
|
|
Postup:
|
|
|
|
1. používateľ položí otázku,
|
|
2. systém nájde relevantné chunky,
|
|
3. chunkom priradí zdrojové URL,
|
|
4. jazykový model vytvorí odpoveď iba z nájdeného kontextu,
|
|
5. odpoveď obsahuje odkazy na zdrojové stránky.
|
|
|
|
Cieľ je, aby agent nehalucinoval a vedel ukázať, z ktorých dokumentov odpovedal.
|
|
|
|
### 7. Znalostný graf
|
|
|
|
Treba vytvoriť štruktúrovaný graf nad dátami zo `zpwiki`.
|
|
|
|
Základné entity:
|
|
|
|
1. `Student`,
|
|
2. `Thesis`,
|
|
3. `Tag`,
|
|
4. `Category`,
|
|
5. `Author`,
|
|
6. `Year`.
|
|
|
|
Základné vzťahy:
|
|
|
|
1. študent má prácu,
|
|
2. práca má tag,
|
|
3. práca patrí do kategórie,
|
|
4. autor vedie alebo spravuje prácu,
|
|
5. práca je podobná inej práci,
|
|
6. práca patrí do roka alebo obdobia.
|
|
|
|
### 8. GraphRAG
|
|
|
|
Treba prepojiť RAG a znalostný graf.
|
|
|
|
GraphRAG časť má umožniť:
|
|
|
|
1. vyhľadávanie podľa vzťahov,
|
|
2. vysvetlenie, prečo sa našli konkrétne práce,
|
|
3. odporúčanie podobných tém,
|
|
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.
|
|
|
|
### 9. Vyhodnotenie systému
|
|
|
|
Treba pripraviť testovaciu sadu otázok a porovnať viacero prístupov.
|
|
|
|
Porovnať treba minimálne:
|
|
|
|
1. jednoduché fulltextové vyhľadávanie,
|
|
2. vektorové vyhľadávanie,
|
|
3. RAG,
|
|
4. GraphRAG.
|
|
|
|
Príklady testovacích otázok:
|
|
|
|
1. `Nájdi práce o RAG.`
|
|
2. `Nájdi práce podobné téme Agent pre manažment záverečných prác.`
|
|
3. `Ktoré práce používajú znalostný graf?`
|
|
4. `Kto riešil chatbot alebo agenta?`
|
|
5. `Aké témy patria do kategórie dp2027?`
|
|
6. `Zhrň práce súvisiace s NLP.`
|
|
|
|
Sledované vlastnosti:
|
|
|
|
1. relevantnosť výsledkov,
|
|
2. správnosť odpovede,
|
|
3. správnosť citácií,
|
|
4. počet halucinácií,
|
|
5. čas odpovede,
|
|
6. čas reindexovania po zmene v Gite.
|
|
|
|
### 10. Dokumentácia do diplomovej práce
|
|
|
|
Treba priebežne písať:
|
|
|
|
1. čo je RAG,
|
|
2. čo je generatívny model,
|
|
3. čo je znalostný graf,
|
|
4. čo je GraphRAG,
|
|
5. ako funguje `zpwiki`,
|
|
6. návrh architektúry systému,
|
|
7. návrh databázy a indexu,
|
|
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ť Gitea webhook endpoint.
|
|
|
|
Poradie najbližších krokov:
|
|
|
|
1. commitnúť aktuálne zmeny,
|
|
2. pushnúť projekt na KEMT Git,
|
|
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.
|