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

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:

~/DP/
├── zpwiki/
└── zp-agent/

Konfigurácia

V koreňovom priečinku vytvor .env:

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:

openssl rand -hex 32

Súbor .env sa nesmie commitovať.

Spustenie cez Docker

docker compose build --no-cache
docker compose up -d

Kontrola služby:

curl http://127.0.0.1:8000/health

Swagger UI:

http://127.0.0.1:8000/docs

Zastavenie:

docker compose down

Reindexovanie

Celý proces načíta dokumenty, vytvorí chunky a obnoví SQLite FTS5 index:

docker compose run --rm zp-agent-api python scripts/rebuild_index.py

Vzniknú súbory:

data/documents.json
data/chunks.json
data/zp_index.sqlite

Vyhľadávanie

Test z terminálu:

docker compose run --rm zp-agent-api   python scripts/search_db.py "rag agent" --limit 5

Vyhľadávanie cez API:

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:

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í:

pip install -r requirements-dev.txt

Bežné automatizované testy:

pytest -q test

Testy vrátane kontroly reálne vygenerovaných dát a databázy:

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.

3.6 KiB Raw Blame History