Aktualizovat telegram_bot/README.md
This commit is contained in:
parent
2bce122ddf
commit
173e819191
@ -1,123 +1,122 @@
|
||||
# Hate Speech Bot – Documentation
|
||||
|
||||
# Hate Speech Bot – Dokumentácia
|
||||
## 🧠 Application Overview
|
||||
|
||||
## 🧠 Opis aplikácie
|
||||
The Hate Speech Bot is a complete system for the automated detection of hate speech within **Telegram**. It functions as a monitoring and analysis tool that enables:
|
||||
|
||||
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:
|
||||
- Automatic **interception and analysis of user messages** in group chats
|
||||
- When hate speech is detected, it records information about the **user and the message into a database**
|
||||
- Displays violators through a **real-time web interface**
|
||||
|
||||
- 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.
|
||||
### System Components:
|
||||
1. **Telegram Bot**: Intercepts messages and uses a fine-tuned LLM model to classify whether the message contains hate speech.
|
||||
2. **MySQL Database**: Stores user information, messages, and incident timestamps.
|
||||
3. **Web Application (Flask)**: Displays a real-time table of violations, updated every 5 seconds.
|
||||
|
||||
---
|
||||
|
||||
## 🧱 Zoznam použitých Docker kontajnerov
|
||||
## 🧱 List of Used Docker Containers
|
||||
|
||||
| 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. |
|
||||
| Container | Description |
|
||||
|-------------------------------------|-------------|
|
||||
| `tetianamohorian/hate-speech-bot` | Contains the Telegram bot, classification model (e.g. fine-tuned BERT), and Flask frontend |
|
||||
| `mysql:8` | Relational database for storing violator records |
|
||||
|
||||
---
|
||||
|
||||
## ☸️ Zoznam Kubernetes objektov
|
||||
## ☸️ List of Kubernetes Objects
|
||||
|
||||
| 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. |
|
||||
| Object | Description |
|
||||
|---------------------------|-------------|
|
||||
| `Namespace: botspace` | Isolated space for all app-related objects |
|
||||
| `Deployment: bot-deployment` | Deploys the container with the bot |
|
||||
| `Deployment: flask-web` | Deploys the Flask web server |
|
||||
| `StatefulSet: mysql` | Ensures persistent and consistent MySQL operation |
|
||||
| `PersistentVolume` | Stores database data outside the pod |
|
||||
| `PersistentVolumeClaim` | Requests disk space for the database |
|
||||
| `Service: mysql` | Internal service for accessing the database |
|
||||
| `Service: flask-service` | Port-forward service for accessing the web |
|
||||
| `ConfigMap: init-sql` | Contains initial SQL schema scripts |
|
||||
| `Secret: bot-secret` | Secure storage of sensitive data like the Telegram token |
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Virtuálne siete a úložiská
|
||||
## 🌐 Virtual Networks and Storage
|
||||
|
||||
- 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.
|
||||
- All pods communicate over an internal network in `botspace`, minimizing data leakage risks
|
||||
- `PersistentVolume` attached to MySQL ensures data preservation even after pod restarts
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Konfigurácia kontajnerov
|
||||
## ⚙️ Container Configuration
|
||||
|
||||
- **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`.
|
||||
- **Flask Web**: Runs on port `5000`, accessible via `flask-service`. Automatically updates via JavaScript (AJAX `fetch`) every 5 seconds
|
||||
- **Telegram Bot**: Runs in a separate thread, classifies messages using a PyTorch model or HuggingFace Transformers, and logs results into the database
|
||||
- **MySQL**: Initialized with an `initContainer` that runs a script from the `ConfigMap`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Návod na použitie
|
||||
## 🚀 Usage Guide
|
||||
|
||||
### 1. Príprava aplikácie:
|
||||
### 1. Prepare the Application:
|
||||
|
||||
```bash
|
||||
./prepare-app.sh
|
||||
```
|
||||
|
||||
- Zostaví Docker image s aplikáciou.
|
||||
- Pushne ho do Docker Hub repozitára.
|
||||
- Builds the Docker image
|
||||
- Pushes it to Docker Hub
|
||||
|
||||
---
|
||||
|
||||
### 2. Spustenie aplikácie:
|
||||
### 2. Start the Application:
|
||||
|
||||
```bash
|
||||
./start-app.sh
|
||||
```
|
||||
|
||||
- Vytvorí Kubernetes objekty.
|
||||
- Spustí port-forwarding pre Flask web na `localhost:8888`.
|
||||
- Creates Kubernetes objects
|
||||
- Starts port-forwarding for Flask web on `localhost:8888`
|
||||
|
||||
---
|
||||
|
||||
### 3. Pozastavenie (port-forward):
|
||||
### 3. Stop Port-Forwarding:
|
||||
|
||||
```bash
|
||||
pkill -f "kubectl port-forward"
|
||||
```
|
||||
|
||||
- Zastaví dočasný prístup cez port-forward.
|
||||
- Terminates temporary access via port-forward
|
||||
|
||||
---
|
||||
|
||||
### 4. Odstránenie aplikácie:
|
||||
### 4. Remove the Application:
|
||||
|
||||
```bash
|
||||
./stop-app.sh
|
||||
```
|
||||
|
||||
- Zmaže celý `botspace`, vrátane databázy a všetkých služieb.
|
||||
- Deletes the entire `botspace`, including database and services
|
||||
|
||||
---
|
||||
|
||||
## 🌍 Prístup k webovej aplikácii
|
||||
## 🌍 Accessing the Web Interface
|
||||
|
||||
Po úspešnom spustení aplikácie otvorte webový prehliadač:
|
||||
After launching the app, open a browser:
|
||||
|
||||
```
|
||||
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.
|
||||
- A table of violators will be displayed
|
||||
- Data updates automatically every 5 seconds
|
||||
|
||||
---
|
||||
|
||||
## 📦 Použité technológie
|
||||
## 📦 Technologies Used
|
||||
|
||||
- **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
|
||||
- **Python, Flask, PyTorch / Transformers** – text analysis and classification
|
||||
- **Docker, Docker Hub** – containerization
|
||||
- **Kubernetes** – orchestration, scaling, and network isolation
|
||||
- **MySQL** – relational data storage
|
||||
- **JavaScript (AJAX)** – real-time frontend updates
|
||||
Loading…
Reference in New Issue
Block a user