Přidat website/README.md
This commit is contained in:
parent
a504e98010
commit
e58f97a3ec
204
website/README.md
Normal file
204
website/README.md
Normal file
@ -0,0 +1,204 @@
|
|||||||
|
# Hate Speech Detector
|
||||||
|
|
||||||
|
## 1. Opis čo robí aplikácia
|
||||||
|
|
||||||
|
Aplikácia **Hate Speech Detector** slúži na analýzu zadaného textu s cieľom určiť, či ide o nenávistný alebo neutrálny obsah. Využíva trénovaný model umelej inteligencie na klasifikáciu textov. Používateľ môže cez webové rozhranie zadať ľubovoľný text a aplikácia okamžite vráti klasifikáciu spolu s možnosťou zobrazenia histórie.
|
||||||
|
|
||||||
|
Všetky predikcie sa ukladajú do databázy PostgreSQL a zároveň sa synchronizujú do súboru `history.json`, ktorý frontend využíva ako zdroj na zobrazenie histórie. Okrem predikcie aplikácia poskytuje aj REST API na správu histórie a jej vymazanie. Webové rozhranie aj API sú zabezpečené cez HTTPS.
|
||||||
|
|
||||||
|
Model bol trénovaný na slovenskom datasete s využitím metódy LoRA (PEFT), čo umožnilo efektívne doladenie modelu s minimálnym počtom trénovateľných parametrov.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Slovný opis použitého verejného klaudu a objektov
|
||||||
|
|
||||||
|
- **Cloud**: Google Cloud Platform (GCP)
|
||||||
|
- **Služby GCP**:
|
||||||
|
- **Google Cloud Run**: hostovanie kontajnera s Flask backendom a React frontendom
|
||||||
|
- **Artifact Registry**: uložisko pre Docker image
|
||||||
|
- **Cloud SQL (PostgreSQL)**: relačná databáza na uchovanie predikcií
|
||||||
|
|
||||||
|
- **Docker objekty**:
|
||||||
|
- Multistage `Dockerfile`:
|
||||||
|
- `node:18` na build React aplikácie
|
||||||
|
- `python:3.10-slim` pre backend (Flask + transformers)
|
||||||
|
- Frontend sa kopíruje do `/app/static/`
|
||||||
|
|
||||||
|
- **Trvalý zväzok**:
|
||||||
|
- Cloud SQL PostgreSQL a `history.json`
|
||||||
|
|
||||||
|
### Štruktúra tabuľky `history`:
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS history (
|
||||||
|
id SERIAL PRIMARY KEY,
|
||||||
|
text TEXT NOT NULL,
|
||||||
|
prediction TEXT NOT NULL,
|
||||||
|
timestamp TIMESTAMP NOT NULL
|
||||||
|
);
|
||||||
|
```
|
||||||
|
Popis polí:
|
||||||
|
|
||||||
|
- `id`: automatický primárny kľúč (číselný identifikátor)
|
||||||
|
- `text`: vstupný text, ktorý užívateľ zadal
|
||||||
|
- `prediction`: výstup modelu (napr. "Neutrálny text")
|
||||||
|
- `timestamp`: dátum a čas, kedy bol text spracovaný
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Štruktúra projektu
|
||||||
|
|
||||||
|
Projekt má nasledovnú štruktúru:
|
||||||
|
|
||||||
|
```
|
||||||
|
skuska/
|
||||||
|
├── Dockerfile # multistage Dockerfile (frontend + backend)
|
||||||
|
├── prepare-app-cloud.sh # skript na nasadenie aplikácie do GCP
|
||||||
|
├── remove-app-cloud.sh # skript na odstránenie služby
|
||||||
|
├── history.json # synchronizovaný záznam histórie (čítaný frontend)
|
||||||
|
├── frontend/ # React frontend projekt (vite)
|
||||||
|
│ └── ... # komponenty, assets, App.jsx atď.
|
||||||
|
├── backend/ # Flask backend
|
||||||
|
│ ├── app.py # hlavný backend súbor (Flask API)
|
||||||
|
│ └── requirements.txt # python balíčky (model sa sťahuje dynamicky z Hugging Face)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Opis odovzdaných súborov a konfigurácie:
|
||||||
|
|
||||||
|
### `backend/app.py`: hlavný backend aplikácie vo Flasku.
|
||||||
|
Obsahuje:
|
||||||
|
|
||||||
|
- endpoint `/api/predict` na AI predikciu
|
||||||
|
|
||||||
|
- `/api/history`, `/api/history/db` a `/api/history/reset` - slúžia na prácu s históriou. /api/history číta zo súboru history.json, ktorý je automaticky synchronizovaný s databázou. /api/history/db číta priamo z PostgreSQL databázy a zobrazí zoznam záznamov zoradených podľa času. /api/history/reset vymaže všetky záznamy z tabuľky history v databáze a zároveň prepíše history.json na prázdny zoznam.
|
||||||
|
|
||||||
|
- prepojenie na PostgreSQL (cez psycopg2 a DATABASE_URL)
|
||||||
|
|
||||||
|
- uloženie a synchronizáciu histórie
|
||||||
|
|
||||||
|
- automatické stiahnutie modelu z Hugging Face pri štarte aplikácie
|
||||||
|
|
||||||
|
### `frontend/`: React projekt vytvorený cez Vite.
|
||||||
|
- Obsahuje komponenty pre UI, API volania, zobrazovanie výsledkov a histórie.
|
||||||
|
|
||||||
|
### `backend/`: obsahuje `app.py`, `requirements.txt`
|
||||||
|
|
||||||
|
### Dockerfile: kombinácia frontend + backend do jedineho obrazu
|
||||||
|
|
||||||
|
Výrez Dockerfile:
|
||||||
|
|
||||||
|
```dockerfile
|
||||||
|
FROM node:18 AS frontend
|
||||||
|
WORKDIR /frontend
|
||||||
|
COPY frontend/ .
|
||||||
|
RUN npm install && npm run build
|
||||||
|
|
||||||
|
FROM python:3.10-slim
|
||||||
|
WORKDIR /app
|
||||||
|
COPY backend/ .
|
||||||
|
RUN apt-get update && apt-get install -y gcc libpq-dev && pip install -r requirements.txt
|
||||||
|
COPY --from=frontend /frontend/dist /app/static
|
||||||
|
CMD ["python", "app.py"]
|
||||||
|
```
|
||||||
|
### `prepare-app-cloud.sh`:
|
||||||
|
Bash skript, ktorý:
|
||||||
|
- definuje všetky dôležité premenne (názov projektu, región, názov obrazu a databázy)
|
||||||
|
- zostaví Docker image pomocou gcloud builds submit
|
||||||
|
- nasadí image do Google Cloud Run cez gcloud run deploy
|
||||||
|
- nastaví environmentálnu premennú DATABASE_URL
|
||||||
|
- prepojí službu so zvolenou databázou cez --add-cloudsql-instances
|
||||||
|
- vyžaduje spustený gcloud CLI a prihláseného používateľa
|
||||||
|
|
||||||
|
### `remove-app-cloud.sh`:
|
||||||
|
Bash skript, ktorý:
|
||||||
|
- pomocou gcloud run services delete zmaže existujúcu službu z Google Cloud Run
|
||||||
|
- využíva parameter --quiet na potlačenie výzvy na potvrdenie
|
||||||
|
- vyžaduje rovnaké prostredie ako skript `prepare-app-cloud.sh`
|
||||||
|
|
||||||
|
### `history.json`:
|
||||||
|
- vygenerovaný automaticky zo stavu databázy (synchronizuje sa pri každom uložení nového záznamu pomocou funkcie `sync_history_file()`)
|
||||||
|
|
||||||
|
### Pripojenie k databáze:
|
||||||
|
|
||||||
|
Premenná:
|
||||||
|
|
||||||
|
```
|
||||||
|
DATABASE_URL=postgresql://user:password@/mydb?host=/cloudsql/hatespeechsite:europe-central2:hate-db
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
## 5. Návod na použitie aplikácie v prehliadači:
|
||||||
|
|
||||||
|
1. Otvorte v prehliadači URL:
|
||||||
|
```
|
||||||
|
https://hate-detektor-19732600168.europe-central2.run.app/
|
||||||
|
```
|
||||||
|
2. Zadajte text do formulára
|
||||||
|
3. Kliknite na "Skontrolovať"
|
||||||
|
4. Zobrazí sa výsledok klasifikácie
|
||||||
|
5. Pod formulárom sa nachádza sekcia histórie
|
||||||
|
|
||||||
|
Pozamka: môžete resetovat' historiu priamo cez terminál príkazom:
|
||||||
|
```
|
||||||
|
curl -X POST https://hate-detektor-19732600168.europe-central2.run.app/api/history/reset | jq
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
## 6. Podmienky pre spustenie skriptov:
|
||||||
|
|
||||||
|
### `prepare-app-cloud.sh`:
|
||||||
|
|
||||||
|
vyžaduje:
|
||||||
|
|
||||||
|
- GCP projekt s povolenými službami: Artifact Registry, Cloud Build, Cloud Run, Cloud SQL
|
||||||
|
- `gcloud` CLI s aktívnym prihlásením a nastaveným projektom
|
||||||
|
|
||||||
|
vykonáva:
|
||||||
|
|
||||||
|
- build Docker image
|
||||||
|
- push do Artifact Registry
|
||||||
|
- deploy do Cloud Run + pripojenie k Cloud SQL + nastavenie DATABASE_URL
|
||||||
|
- používa premenné prostredia pre názvy služby a databázy
|
||||||
|
- skript je opakovateľný a nevyžaduje manuálnu interakciu
|
||||||
|
|
||||||
|
### `remove-app-cloud.sh`:
|
||||||
|
|
||||||
|
- odstráni službu z Cloud Run
|
||||||
|
- spustenie je okamžité bez potreby interakcie
|
||||||
|
- tichý režim (bez potvrdenia) pomocou parametra --quiet
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Externé zdroje:
|
||||||
|
|
||||||
|
Trénovaný model:
|
||||||
|
|
||||||
|
- Použitý model: `slovak-t5-base`, finetunovaný osobne
|
||||||
|
- Model bol trénovaný na slovenskom datasete pozostávajúcom z anotovaných viet so zameraním na identifikáciu nenávistného prejavu
|
||||||
|
- Tréning prebehol s využitím metódy PEFT (Parameter-Efficient Fine-Tuning) konkrétne cez technológiu LoRA (Low-Rank Adaptation), čo umožnilo efektívne doladiť model s minimálnym počtom trénovateľných parametrov
|
||||||
|
- Model dosiahol presnosť 74 % pri testovaní na slovenskom dátovom korpuse
|
||||||
|
|
||||||
|
Model: `tetianamohorian/hate_speech_model` z HuggingFace (transformers model BERT)
|
||||||
|
|
||||||
|
Knižnice a frameworky:
|
||||||
|
|
||||||
|
- `transformers`, `torch` pre modelovanie
|
||||||
|
- `Flask`, `psycopg2`, `pytz` pre backend
|
||||||
|
- `React`, `Vite`, `fetch` pre frontend
|
||||||
|
|
||||||
|
---
|
||||||
|
## 8. Zhrnutie a vykonané kroky:
|
||||||
|
|
||||||
|
- ✅ Vytvorený frontend v Reacte s použitím Vite
|
||||||
|
- ✅ Vytvorený backend vo Flasku s REST API
|
||||||
|
- ✅ Nasadený AI model trénovaný na slovenskom datasete (slovak-t5-base, LoRA, 74 % presnosť)
|
||||||
|
- ✅ Prepojenie aplikácie s databázou Cloud SQL (PostgreSQL)
|
||||||
|
- ✅ Vytvorená databázová tabuľka history s políčkami: id, text, prediction, timestamp
|
||||||
|
- ✅ Implementovaná synchronizácia databázy s `history.json`
|
||||||
|
- ✅ Nasadenie aplikácie pomocou Dockeru a Google Cloud Run
|
||||||
|
- ✅ Vytvorené shellové skripty na deploy (prepare-app-cloud.sh) a odstránenie (remove-app-cloud.sh)
|
||||||
|
- ✅ Zabezpečený verejný prístup cez HTTPS
|
||||||
|
- ✅ Otestované API: `/api/predict`, `/api/history`, `/api/history/reset`, `/api/history/db`
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user