From 44eb3cd6790a491eb8abf8a0aa6f2979c334e9e8 Mon Sep 17 00:00:00 2001 From: jp170na Date: Thu, 4 Jun 2026 17:26:38 +0200 Subject: [PATCH] Update README --- README.md | 179 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 133 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index fee7215..af4e2b4 100644 --- a/README.md +++ b/README.md @@ -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.