121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# Hate Speech Bot – Dokumentácia
|
||
|
||
## 🧠 Opis aplikácie
|
||
|
||
Hate Speech Bot je kompletný systém na automatickú detekciu nenávistnej reči v prostredí **Telegramu**. Aplikácia slúži ako monitorovací a analytický nástroj, ktorý umožňuje:
|
||
|
||
- Automaticky **zachytiť a analyzovať správy** používateľov v skupinových chatoch.
|
||
- V prípade detekcie nenávistného prejavu zaznamená informáciu o **používateľovi a správe do databázy**.
|
||
- Vizualizuje porušovateľov cez **webové rozhranie** v reálnom čase.
|
||
|
||
### Komponenty systému:
|
||
1. **Telegram Bot**: Interceptuje správy v skupine a pomocou trénovaného LLM modelu klasifikuje, či ide o nenávistnú reč.
|
||
2. **MySQL databáza**: Ukladá údaje o používateľoch, správach a čase incidentu.
|
||
3. **Webová aplikácia (Flask)**: Zobrazuje tabuľku s porušeniami, automaticky aktualizovanú každých 5 sekúnd.
|
||
|
||
---
|
||
|
||
## 🧱 Zoznam použitých Docker kontajnerov
|
||
|
||
| Kontajner | Popis |
|
||
|--------------------------------------|-------|
|
||
| tetianamohorian/hate-speech-bot | Obsahuje Telegram bota, klasifikačný model (napr. fine-tuned BERT), a Flask frontend. |
|
||
| mysql:8 | Relačný databázový systém pre ukladanie záznamov o porušovateľoch. |
|
||
|
||
---
|
||
|
||
## ☸️ Zoznam Kubernetes objektov
|
||
|
||
| Objekt | Popis |
|
||
|----------------------------|-------|
|
||
| Namespace: botspace | Izolovaný priestor pre všetky objekty súvisiace s aplikáciou. |
|
||
| Deployment: bot-deployment | Nasadzuje kontajner s botom. |
|
||
| Deployment: flask-web | Nasadzuje Flask webserver. |
|
||
| StatefulSet: mysql | Zabezpečuje perzistentný a konzistentný chod MySQL databázy. |
|
||
| PersistentVolume | Uchováva fyzické dáta databázy mimo podu. |
|
||
| PersistentVolumeClaim | Žiadosť o diskový priestor pre databázu. |
|
||
| Service: mysql | Vnútorná služba pre prístup k databáze. |
|
||
| Service: flask-service | Port-forward pre sprístupnenie webu. |
|
||
| ConfigMap: init-sql | Obsahuje SQL skripty na prvotnú inicializáciu schémy. |
|
||
| Secret: bot-secret | Bezpečné uloženie citlivých údajov ako je Telegram token. |
|
||
|
||
---
|
||
|
||
## 🌐 Virtuálne siete a úložiská
|
||
|
||
- Všetky pody komunikujú cez internú sieť v botspace, čím sa znižuje riziko únikov údajov.
|
||
- PersistentVolume pripojený k MySQL zaručuje zachovanie dát aj po reštarte podu.
|
||
|
||
---
|
||
|
||
## ⚙️ Konfigurácia kontajnerov
|
||
|
||
- **Flask Web**: Beží na porte 5000, ktorý je dostupný cez flask-service. Obnovuje sa každých 5 sekúnd pomocou JavaScriptu (AJAX fetch).
|
||
- **Telegram Bot**: Spustený v samostatnom threade, číta správy, klasifikuje ich pomocou PyTorch modelu (alebo HuggingFace Transformers), a zapisuje výsledok do databázy.
|
||
- **MySQL**: Inicializovaná pomocou initContainer, ktorý spustí skript uložený v ConfigMap.
|
||
|
||
---
|
||
|
||
## 🚀 Návod na použitie
|
||
|
||
### 1. Príprava aplikácie:
|
||
|
||
bash
|
||
./prepare-app.sh
|
||
|
||
|
||
- Zostaví Docker image s aplikáciou.
|
||
- Pushne ho do Docker Hub repozitára.
|
||
|
||
---
|
||
|
||
### 2. Spustenie aplikácie:
|
||
|
||
bash
|
||
./start-app.sh
|
||
|
||
|
||
- Vytvorí Kubernetes objekty.
|
||
- Spustí port-forwarding pre Flask web na localhost:8888.
|
||
|
||
---
|
||
|
||
### 3. Pozastavenie (port-forward):
|
||
|
||
bash
|
||
pkill -f "kubectl port-forward"
|
||
|
||
|
||
- Zastaví dočasný prístup cez port-forward.
|
||
|
||
---
|
||
|
||
### 4. Odstránenie aplikácie:
|
||
|
||
bash
|
||
./stop-app.sh
|
||
|
||
|
||
- Zmaže celý botspace, vrátane databázy a všetkých služieb.
|
||
|
||
---
|
||
|
||
## 🌍 Prístup k webovej aplikácii
|
||
|
||
Po úspešnom spustení aplikácie otvorte webový prehliadač:
|
||
|
||
http://localhost:8888
|
||
|
||
|
||
- Zobrazí sa tabuľka s informáciami o porušovateľoch.
|
||
- Dáta sa aktualizujú automaticky každých 5 sekúnd bez potreby obnoviť stránku.
|
||
|
||
---
|
||
|
||
## 📦 Použité technológie
|
||
|
||
- **Python, Flask, PyTorch / Transformers** – analýza a klasifikácia textov
|
||
- **Docker, Docker Hub** – kontajnerizácia
|
||
- **Kubernetes** – orchestrácia, škálovanie a sieťová izolácia
|
||
- **MySQL** – relačné databázové úložisko
|
||
- **JavaScript (AJAX)** – aktualizácia frontendu v reálnom čase тоже самое сделай |