CaptainYifei/fake-news-detector

📚 Project Overview

AI 虚假新闻检测器 – a Streamlit‑based web app that lets users verify the factuality of news articles. It chains together large‑language‑model (LLM) prompting, semantic‑embedding retrieval, and multi‑step claim verification. The system works in Chinese, English, Japanese and Korean and can run with any OpenAI‑compatible model service (local Ollama, LM Studio, OpenAI, or a custom API).

🔑 Core Capabilities

Feature	What it does
Multi‑language support	Auto‑detects input language and can output results in Chinese, English, Japanese or Korean.
Three‑node fact‑checking pipeline	1️⃣ Extract core claim(s) from the article using an LLM. 2️⃣ Rewrite queries, retrieve web evidence (DuckDuckGo by default, optional SearXNG), rank with BGE‑M3 embeddings, filter by similarity and entity match. 3️⃣ Decompose claims into atomic statements, answer with the evidence, and aggregate a final verdict.
Model‑agnostic backend	Works with Ollama (default Qwen2.5‑3B + BGE‑M3), LM Studio, OpenAI GPT models, or any service that follows the OpenAI API schema.
Evidence gating	Configurable top‑K, similarity threshold, and entity‑gate to ensure only high‑quality sources reach the verification step.
User & data management	Multi‑user login, persistent history stored in a local DB, and PDF export of verification reports.
API	A lightweight REST endpoint (`/check`) mirrors the web UI functionality for programmatic use.

🛠️ Quick Start (Linux/macOS)

# 1. Clone
git clone https://github.com/CaptainYifei/fake-news-detector.git
cd fake-news-detector

# 2. Install Python deps (requires Python 3.12+)
pip install -r requirements.txt

# 3. Install and run Ollama (recommended)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:3b   # LLM
ollama pull bge-m3:latest # embedding model

# 4. (Optional) configure a different search backend in model_config.json

# 5. Launch the UI
streamlit run app.py

Open http://localhost:8501 in a browser.

📡 Using the API

python api.py   # starts the server on port 8080

curl -X POST http://localhost:8080/check \
  -H "Content-Type: application/json" \
  -d '{
        "text": "新闻正文…",
        "api_base": "http://localhost:11434/v1",
        "model": "qwen2.5:3b",
        "embedding_model": "bge-m3:latest",
        "search_engine": "duckduckgo"
      }'

The response contains the extracted claims, retrieved evidence, and a final verdict (TRUE, FALSE, or UNVERIFIABLE).

📂 Repository Layout

fake-news-detector/
├─ app.py                # Streamlit front‑end
├─ api.py                # REST service
├─ fact_checker.py       # Orchestrates the three nodes
├─ fact_checking/        # Node implementations
├─ model_manager.py      # Loads config & creates LLM/embedding clients
├─ model_config.json     # Provider, model, and search defaults
├─ auth.py, db_utils.py  # User auth & SQLite helpers
├─ pdf_export.py         # Generates PDF reports
├─ requirements.txt
└─ docs/ …               # Usage guide, API docs, screenshots

📦 Configuration Highlights (`model_config.json`)

Providers – define base URLs and model IDs for Ollama, LM Studio, etc.
Defaults – choose which LLM/embedding model to use, search engine, output language, and evidence‑filtering thresholds (evidence_top_k, evidence_min_similarity, evidence_entity_gate).
Switching to a different provider only requires editing the JSON; the code reads it at startup.

🐞 Known Issues & Troubleshooting

Model hangs or returns empty – verify the Ollama service is running (ollama list) and that model_config.json points to the correct base_url.
No search results – check network connectivity; the ddgs wrapper will fall back across several DuckDuckGo back‑ends. If all fail, enable the optional SearXNG backend.
Unverifiable verdicts – may be caused by the similarity threshold being too high or the entity gate filtering out all candidates; adjust evidence_min_similarity or set evidence_entity_gate to false.
Multilingual output problems – ensure the selected LLM supports the target language; larger OpenAI models tend to handle all four languages more reliably.

📄 License

MIT – see LICENSE.

TL;DR – This repo delivers a ready‑to‑run, locally‑hosted AI fact‑checking system that combines LLM prompting, semantic search, and multi‑step verification, with a web UI, API, and multilingual support. It is a genuine, functional AI software project.