143 lines
5.6 KiB
Markdown
143 lines
5.6 KiB
Markdown
# README.md
|
||
|
||
Tento súbor slúži ako dokumentácia.
|
||
|
||
## Prehľad projektu
|
||
|
||
AI Fact Checker - full-stack webová aplikácia, ktorá overuje tvrdenia používateľov pomocou modelov NLI (Natural Language Inference). Systém prehľadáva web prostredníctvom služby SerpAPI, analyzuje úryvky z vyhľadávania z dôveryhodných zdrojov v porovnaní s tvrdeniami a vracia verdikty (Pravda/Nepravda/Nejednoznačné) spolu s nájdenými dôkazmi.
|
||
|
||
## Technologický Stack
|
||
|
||
**Backend (Python/Flask):**
|
||
- Flask REST API s CORS kompatibilitou
|
||
- Strojové učenie: HuggingFace Transformers (RoBERTa, mDeBERTa-v3)
|
||
- Preklad: deep_translator (Google Translate)
|
||
- Databáza: SQLite s cache vrstvou
|
||
- Vyhľadávanie: SerpAPI pre extrakciu výsledkov z Google
|
||
|
||
**Frontend (React/Vite):**
|
||
- React 19 s Vite 7
|
||
- React Router pre navigáciu medzi stránkami
|
||
- Axios pre HTTP požiadavky
|
||
- Vlastné CSS pre vizuálne témy a dizajn
|
||
|
||
## Architektúra
|
||
|
||
```
|
||
factchecker/
|
||
├── backend/
|
||
│ ├── app.py # Flask API, NLI logika, prepínanie modelov
|
||
│ ├── database.py # SQLite cache, overené fakty, štatistiky
|
||
│ ├── .env # SERPAPI_API_KEY (povinné)
|
||
│ └── venv/ # Virtuálne prostredie Pythonu
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── App.jsx # Nastavenie routera
|
||
│ │ ├── main.jsx # Vstupný bod pre React
|
||
│ │ ├── components/
|
||
│ │ │ └── Layout.jsx
|
||
│ │ └── pages/
|
||
│ │ ├── Home.jsx # Hlavné UI pre fact-checking
|
||
│ │ └── About.jsx
|
||
│ └── package.json
|
||
└── factchecker.db # SQLite databáza (vytvára sa automaticky)
|
||
```
|
||
|
||
## Základné príkazy
|
||
|
||
### Backend
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate # alebo na Windows: venv\Scripts\activate
|
||
python app.py # Spustí Flask server na porte 5000
|
||
python view_db.py # Zobrazí obsah databázy v termináli
|
||
```
|
||
|
||
### Frontend
|
||
```bash
|
||
cd frontend
|
||
npm install # Nainštaluje závislosti
|
||
npm run dev # Spustí Vite vývojový server
|
||
|
||
```
|
||
|
||
## API Endpointy
|
||
|
||
- `POST /api/check` - Overí tvrdenie (body: claim, language, dateFrom, dateTo, selectedSource, model)
|
||
- `GET /api/history` - Získa históriu overovaní (query limit: limit počtu)
|
||
- `GET /api/stats` - Získa štatistiky z databázy
|
||
- `POST /api/admin/add-fact` - Pridá manuálne overený fakt (pre admina)
|
||
|
||
## Modely
|
||
|
||
Dva NLI modely dostupné s rôznymi kompromismi:
|
||
1. **RoBERTa** (`ynie/roberta-large-snli_mnli_fever_anli_R1_R2_R3-nli`) - Je rýchly, ale vyžaduje preklad vstupu do angličtiny.
|
||
2. **mDeBERTa** (`MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7`) - Je najlepší a najpresnejší pre slovenčinu a natívne podporuje viaceré jazyky.
|
||
|
||
## Schéma Databázy
|
||
|
||
- `fact_checks` - Cashované (uložené) výsledky vrátane hashu tvrdenia, verdiktu, NLI hlasov, dôkazov a zdrojov.
|
||
- `verified_facts` - Manuálne a napevno overené fakty (pridávané adminom).
|
||
|
||
## Dôležité poznámky
|
||
|
||
- Súbor `.env` musí obsahovať kľúč pre SerpAPI - **nezahŕňajte/necommitujte ho do Gitu!**
|
||
- Modely sa načítavajú až na požiadanie. Prepnutie modelu v UI môže spustiť reset bežiaceho modelu a vymazanie RAM.
|
||
- Slovenské tvrdenia sú pre model RoBERTa pred spustením NLI vždy automaticky prekladané. Model mDeBERTa zvláda slovenčinu natívne, bez potreby prekladu do angličtiny.
|
||
- Výsledky vyhľadávania prechádzajú filtrom domén (whitelist vs. blacklist), primárne so zameraním na slovenské aj celosvetové spravodajské portály a inštitúcie.
|
||
- Výsledky sa vždy ukladajú do cache, aby sa predišlo opakovaným a drahým volaniam vyhľadávacieho API pre rovnaké dotazy.
|
||
|
||
## Návod na inštaláciu a spustenie
|
||
|
||
Ak si projekt práve vyklonoval z repozitára a chceš ho rozbehať lokálne, postupuj podľa týchto krokov:
|
||
|
||
### 1. Klonovanie repozitára a prerekvizity
|
||
Najprv si naklonuj projekt a presuň sa do hlavnej zložky:
|
||
```bash
|
||
git clone git@git.kemt.fei.tuke.sk:vd768er/fact_checker.git
|
||
cd factchecker
|
||
```
|
||
*Poznámka: Pre beh projektu potrebuješ mať nainštalovaný **Python** (pre backend) a **Node.js + npm** (pre frontend).*
|
||
|
||
### 2. Príprava a spustenie backendu (Umelá inteligencia a API)
|
||
Otvor si prvý terminál a prekopíruj tieto príkazy:
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# Vytvorenie a aktivácia virtuálneho prostredia (pre Windows)
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
# Pre Mac/Linux zvoľ: source venv/bin/activate
|
||
|
||
# Inštalácia všetkých Python potrebných knižníc
|
||
pip install flask flask-cors transformers torch requests python-dotenv deep-translator
|
||
```
|
||
|
||
Ďalej musíš **vytvoriť `.env` súbor** v priečinku `backend/`.
|
||
Vytvor ho ručne a nastav si v ňom kľúč pre vyhľadávanie cez Serp API (ak ho nemáš, vytvor si zdarma účet na [serpapi.com](https://serpapi.com/)):
|
||
```env
|
||
SERPAPI_API_KEY=tvoj_tajny_api_kluc
|
||
```
|
||
|
||
Nakoniec backend spusti pomocou:
|
||
```bash
|
||
python app.py
|
||
```
|
||
*(Server by mal teraz nabehnúť na adrese `http://127.0.0.1:5000`. Tento terminál nechaj bežať a nevypínaj.)*
|
||
|
||
### 3. Príprava a spustenie frontendu (Rozhranie aplikácie)
|
||
Otvor si druhý, úplne **nový preklikávací terminál / okno na pozadí**, uisti sa že si v koreňovom priečinku `factchecker` a presuň sa do frontendu:
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# Inštalácia Node.js závislostí z package.json
|
||
npm install
|
||
|
||
# Spustenie Vite vývojového servera
|
||
npm run dev
|
||
```
|
||
|
||
Ak všetko prebehne úspešne, terminál ti vyhodí odkaz (zvyčajne to býva `http://localhost:5173/` alebo `http://localhost:5174/`). Otvor si ho v prehliadači a hotovo – môžeš začať s Fact-Checkingom!
|