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 index kombinujúci FTS5 fulltextové vyhľadávanie a embeddingy. 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,
• embeddingy pre každý chunk pomocou modelu intfloat/multilingual-e5-small,
• uloženie embeddingov priamo v SQLite,
• vektorové vyhľadávanie pomocou cosine similarity,
• hybridné vyhľadávanie FTS5 + embeddings pomocou RRF,
• nižšia váha pre slabú any_term FTS stratégiu,
• zachovanie presných all_terms a prefix_terms výsledkov bez vektorového šumu,
• filtrovanie publikovaných dokumentov,
• FastAPI endpointy /health, /search, /sync a /webhook/gitea,
• autorizácia /search a /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.

Štruktúra

zp-agent/
├── app/
│   └── main.py
├── scripts/
│   ├── common.py
│   ├── scan_zpwiki.py
│   ├── build_chunks.py
│   ├── build_sqlite_index.py
│   ├── embedding_utils.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>
SEARCH_API_KEY=<ďalšia náhodná hodnota s minimálne 32 znakmi>
EXPECTED_GITEA_REPOSITORY=KEMT/zpwiki
WEBHOOK_PULL_GIT=false

# Voliteľné
EMBEDDING_MODEL=intfloat/multilingual-e5-small
EMBEDDING_BATCH_SIZE=32

Tajomstvá je možné vygenerovať príkazom:

openssl rand -hex 32

Súbor .env sa nesmie commitovať.

Spustenie cez Docker

docker compose build
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, obnoví FTS5 index a vytvorí embedding pre každý chunk:

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

Databáza obsahuje dokumenty, chunky, FTS5 index, metadata a embeddingy.

Vyhľadávanie

Vyhľadávanie kombinuje:

dotaz
├── FTS5 / BM25
└── embeddingové vyhľadávanie
        ↓
   RRF fusion
        ↓
   výsledky

Test z terminálu:

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

Pred volaním API načítaj premenné z .env:

set -a
source .env
set +a

Vyhľadávanie cez zabezpečené API:

curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SEARCH_API_KEY" \
  -d '{
    "query": "rag agent",
    "limit": 5,
    "published_only": false,
    "max_per_document": 3
  }'

API vracia hybridný engine:

hybrid_fts5_embeddings

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

Aktuálna testovacia sada:

65 passed, 2 skipped

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

RUN_LIVE_TESTS=1 pytest -q test

Ďalší krok

Najbližšia etapa je integrácia s OpenWebUI a vytvorenie agentového rozhrania. Následne sa doplnia RAG odpovede so zdrojmi a citáciami.