7.7 KiB
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áciepython:3.10-slim
pre backend (Flask + transformers)- Frontend sa kopíruje do
/app/static/
- Multistage
-
Trvalý zväzok:
- Cloud SQL PostgreSQL a
history.json
- Cloud SQL PostgreSQL a
Štruktúra tabuľky history
:
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ľ zadalprediction
: 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:
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:
- Otvorte v prehliadači URL:
https://hate-detektor-19732600168.europe-central2.run.app/
- Zadajte text do formulára
- Kliknite na "Skontrolovať"
- Zobrazí sa výsledok klasifikácie
- 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 modelovanieFlask
,psycopg2
,pytz
pre backendReact
,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