164 lines
3.6 KiB
Markdown
164 lines
3.6 KiB
Markdown
# ZP Agent
|
|
|
|
Backend pre indexovanie a vyhľadávanie v repozitári záverečných prác `zpwiki`.
|
|
|
|
Projekt načítava Markdown dokumenty, spracuje YAML metadata, rozdelí obsah na tokenové chunky a vytvorí SQLite FTS5 index. Vyhľadávanie je dostupné cez FastAPI a systém podporuje manuálnu aj webhookovú synchronizáciu.
|
|
|
|
## Implementované
|
|
|
|
- načítanie Markdown súborov a YAML front matter,
|
|
- normalizácia názvov, autorov, tagov, kategórií a `published`,
|
|
- tokenové chunkovanie pomocou `tiktoken`,
|
|
- zachovanie názvu dokumentu a hierarchie nadpisov v chunku,
|
|
- SQLite databáza a FTS5 fulltextový index,
|
|
- BM25 vyhľadávanie s podporou diakritiky a prefixových výrazov,
|
|
- filtrovanie publikovaných dokumentov,
|
|
- FastAPI endpointy `/health`, `/search`, `/sync` a `/webhook/gitea`,
|
|
- autorizácia `/sync` pomocou API kľúča,
|
|
- Gitea webhook s HMAC-SHA256 podpisom a kontrolou udalosti a repozitára,
|
|
- zámok proti súbežnému reindexovaniu,
|
|
- atomická výmena databázy po úspešnom reindexovaní,
|
|
- automatizované a integračné testy nad reálnymi dátami.
|
|
|
|
## Štruktúra
|
|
|
|
```text
|
|
zp-agent/
|
|
├── app/
|
|
│ └── main.py
|
|
├── scripts/
|
|
│ ├── common.py
|
|
│ ├── scan_zpwiki.py
|
|
│ ├── build_chunks.py
|
|
│ ├── build_sqlite_index.py
|
|
│ ├── rebuild_index.py
|
|
│ ├── search_db.py
|
|
│ └── search_utils.py
|
|
├── test/
|
|
├── data/
|
|
├── Dockerfile
|
|
├── docker-compose.yml
|
|
├── requirements.txt
|
|
├── requirements-dev.txt
|
|
└── README.md
|
|
```
|
|
|
|
Projekt očakáva repozitáre v tejto štruktúre:
|
|
|
|
```text
|
|
~/DP/
|
|
├── zpwiki/
|
|
└── zp-agent/
|
|
```
|
|
|
|
## Konfigurácia
|
|
|
|
V koreňovom priečinku vytvor `.env`:
|
|
|
|
```dotenv
|
|
WEBHOOK_SECRET=<náhodná hodnota s minimálne 32 znakmi>
|
|
SYNC_API_KEY=<iná náhodná hodnota s minimálne 32 znakmi>
|
|
EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki
|
|
WEBHOOK_PULL_GIT=false
|
|
```
|
|
|
|
Tajomstvá je možné vygenerovať príkazom:
|
|
|
|
```bash
|
|
openssl rand -hex 32
|
|
```
|
|
|
|
Súbor `.env` sa nesmie commitovať.
|
|
|
|
## Spustenie cez Docker
|
|
|
|
```bash
|
|
docker compose build --no-cache
|
|
docker compose up -d
|
|
```
|
|
|
|
Kontrola služby:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/health
|
|
```
|
|
|
|
Swagger UI:
|
|
|
|
```text
|
|
http://127.0.0.1:8000/docs
|
|
```
|
|
|
|
Zastavenie:
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
## Reindexovanie
|
|
|
|
Celý proces načíta dokumenty, vytvorí chunky a obnoví SQLite FTS5 index:
|
|
|
|
```bash
|
|
docker compose run --rm zp-agent-api python scripts/rebuild_index.py
|
|
```
|
|
|
|
Vzniknú súbory:
|
|
|
|
```text
|
|
data/documents.json
|
|
data/chunks.json
|
|
data/zp_index.sqlite
|
|
```
|
|
|
|
## Vyhľadávanie
|
|
|
|
Test z terminálu:
|
|
|
|
```bash
|
|
docker compose run --rm zp-agent-api python scripts/search_db.py "rag agent" --limit 5
|
|
```
|
|
|
|
Vyhľadávanie cez API:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/search -H "Content-Type: application/json" -d '{
|
|
"query": "rag agent",
|
|
"limit": 5,
|
|
"published_only": false,
|
|
"max_per_document": 3
|
|
}'
|
|
```
|
|
|
|
Manuálne reindexovanie cez zabezpečený endpoint:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/sync -H "Content-Type: application/json" -H "X-API-Key: $SYNC_API_KEY" -d '{"pull_git": false}'
|
|
```
|
|
|
|
## Testy
|
|
|
|
Inštalácia testovacích závislostí:
|
|
|
|
```bash
|
|
pip install -r requirements-dev.txt
|
|
```
|
|
|
|
Bežné automatizované testy:
|
|
|
|
```bash
|
|
pytest -q test
|
|
```
|
|
|
|
Testy vrátane kontroly reálne vygenerovaných dát a databázy:
|
|
|
|
```bash
|
|
RUN_LIVE_TESTS=1 pytest -q test
|
|
```
|
|
|
|
Aktuálna implementácia prešla všetkými 65 testami vrátane live testov.
|
|
|
|
## Ďalší krok
|
|
|
|
Najbližšia etapa je integrácia s OpenWebUI a vytvorenie agentového rozhrania. Následne sa doplnia embeddingy, hybridné vyhľadávanie a RAG odpovede s citáciami.
|