README.md

---
title: Sentinel API
emoji: "🛡️"
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# Sentinel API

# Hibrit İçerik Moderasyon Sistemi

Türkçe ve İngilizce kullanıcı içeriklerini düşük gecikmeyle analiz edip zararlı içeriği otomatik sınıflandıran, kara liste + yapay zeka modellerini birlikte kullanan katmanlı bir moderasyon sistemidir.

## 1. Proje Amacı
Bu proje, gerçek zamanlı içerik moderasyonunda hem hızlı hem de yüksek doğruluklu karar üretmek için kural tabanlı filtreleri ve makine öğrenmesi modellerini tek bir hibrit akışta birleştirir.

## 2. Kullanılan Teknolojiler
- `Python 3.x`
- `FastAPI` (API servis katmanı)
- `Uvicorn` (ASGI sunucu)
- `Streamlit` (moderasyon paneli)
- `PyTorch` (inference altyapısı)
- `Transformers` (BERTurk tokenizer/model yükleme)
- `Detoxify` (toxicity, insult, threat, identity attack skorları)
- `Supabase` (canlı kara liste veritabanı)
- `Pandas` / `Openpyxl` (toplu veri analizi)
- `Scikit-learn` / `Matplotlib` (değerlendirme ve raporlama)

## 3. Proje Dizin Yapısı
```text
moderasyon/
├─ main.py
├─ app.py
├─ utils.py
├─ performance_test.py
├─ stress_test.py
├─ vram_check.py
├─ requirements.txt
├─ models_cache/
│  ├─ bertturk-offensive-42k/
│  └─ bertturk-hate-speech/   # v4 raporunda aktif akıştan çıkarıldı
└─ app/
   ├─ api/
   │  └─ endpoints.py
   ├─ core/
   │  └─ config.py
   ├─ db/
   │  └─ supabase_client.py
   ├─ ml/
   │  └─ model_loader.py
   ├─ services/
   │  ├─ cache_manager.py
   │  └─ moderation_service.py
   └─ utils/
      └─ text_utils.py
```

## 4. Sistem Nasıl Çalışır?
Sistem, gelen metni önce temizler, sonra spam/gibberish ve kara liste kontrollerini yapar, en son gerekli ise ML modellerini çalıştırıp tek bir karar motorunda sonucu üretir.

### 4.1 Genel Akış
```mermaid
flowchart TD
    A[POST /analyze] --> B[clean_text_nfkc]
    B --> C{is_spam?}
    C -- Evet --> D[SPAM/GIBBERISH - Early Exit]
    C -- Hayir --> E[Supabase Cache Kontrolu]
    E --> F{Dil}
    F -- TR --> G[BERTurk Offensive + Detoxify Multilingual]
    F -- EN --> H[Gibberish Detector + Detoxify Original]
    G --> I[calculate_verdict]
    H --> I
    I --> J[decision + risk + action + latency_ms]
```

### 4.2 TR Pipeline
- Metin normalize edilir (`NFKC`, obfuscation temizliği, leet dönüşümü).
- `is_spam()` hızlı kuralları çalışır; pozitifse model çağrılmaz.
- Supabase kara listesi RAM cache içinden taranır.
- `BERTurk Offensive 42K` ile `off_score` hesaplanır.
- `Detoxify Multilingual` ile toxicity/insult/threat/identity attack skorları alınır.
- `calculate_verdict()` son kararı üretir.

### 4.3 EN Pipeline
- Metin normalize edilir.
- `is_spam()` kontrolü yapılır.
- Supabase EN cache taranır.
- Gibberish detector `noise > 0.98` ise erken çıkış verir.
- `Detoxify Original` 6 etiketli skor üretir.
- `calculate_verdict()` ile nihai sınıflandırma yapılır.

## 5. Modeller, Veri Setleri ve Eğitim Süreci

### 5.1 Kullanılan Veri Setleri
- `Toygar/turkish-offensive-language-detection` (aktif TR modeli)
  - Toplam: `53,005`
  - Train: `42,398`, Validation: `1,756`, Test: `8,851`
  - Etiketler: `0=temiz`, `1=offensive`
- `fawern/turkish-hate-speech` (referans)
  - v4 notu: ayrı hate modeli aktif akıştan çıkarılmıştır.

### 5.2 Fine-Tuning Özeti (BERTurk Offensive 42K)
- `num_train_epochs=3`
- `batch_size=16`
- `learning_rate=2e-5`
- `weight_decay=0.01`
- `fp16=True`
- `load_best_model_at_end=True`

Eğitim gözlemi (özet): model ilk epoch'tan sonra hızla iyileşir, sonraki epoch'larda doğruluk artışı sınırlı kalsa da en iyi checkpoint otomatik seçilerek stabil performans korunur.

### 5.3 Neden Hibrit Mimari?
- Sadece blacklist: semantik saldırganlığı kaçırabilir.
- Sadece model: obfuscation ve açık küfürlerde gereksiz gecikme yaratabilir.
- Hibrit yaklaşım: erken çıkış + semantik model kombinasyonuyla hız/doğruluk dengesi sağlar.

## 6. Başarı Metrikleri (Rapor v4)

### 6.1 Model Kalitesi
- TR Accuracy: `%92`
- TR Macro F1: `%92`
- Offensive sınıfı F1: `%92`

### 6.2 Performans
- Tek istek gecikmesi:
  - TR: `~90ms - 240ms`
  - EN: `~54ms - 111ms`
- Hedef: `<300ms` (karşılanıyor)

### 6.3 Stress Test
- `50` istek, `5` eş zamanlı kullanıcı
- Ortalama gecikme: `319.69ms`
- Throughput: `15.01 req/sec`
- GPU: `RTX 3050 Ti Laptop GPU`
- VRAM: `687.36MB allocated / 750MB reserved`

### 6.4 Gerçek Veri Testi (500 Tweet)
- Toplam süre: `83 saniye` (`~166ms/satır`)
- Dağılım:
  - `TEMİZ`: `216` (`%43.2`)
  - `KÜFÜR/PROFANITY`: `169` (`%33.8`)
  - `SALDIRGAN/TOXIC`: `87` (`%17.4`)
  - `İNCELEME GEREKLİ`: `27` (`%5.4`)
  - `SPAM/GİBBERİSH`: `1` (`%0.2`)

## 7. API Endpointleri
- `POST /analyze`
  - Girdi: `{"text": "...", "platform_dil": "tr|en"}`
  - Çıktı: `decision`, `risk_level`, `details`, `latency_ms`
- `GET /refresh-cache`
  - Supabase kara listesini sistemi durdurmadan RAM'e yeniden yükler.
- `GET /vram-status`
  - GPU bellek kullanımını döndürür.

## 8. Önemli Fonksyonlar

### 8.1 `clean_text_nfkc()` ne yapar?
Dosya: `app/utils/text_utils.py`
- Mesajdaki karakterleri standartlaştırır.
- Gizlenmiş küfürleri görünür hale getirir.
- Örnek: `m.a.l` -> `mal`, `ger1zekalı` -> `gerizekalı`.

Kısaca: Kullanıcı metnini “makine için okunabilir ve karşılaştırılabilir” hale getirir.

### 8.2 `is_spam()` ne yapar?
Dosya: `app/utils/text_utils.py`
- Çok kısa, anlamsız, tekrar eden veya reklam kalıbı içeren metni işaretler.
- Eğer spam ise pahalı model çağrısını atlar.

Kısaca: Sistemin hem hızını artırır hem de gereksiz GPU kullanımını azaltır.

### 8.3 `load_blacklist_to_ram()` ne yapar?
Dosya: `app/services/cache_manager.py`
- Supabase'deki `blacklist` tablosunu sayfalı şekilde çeker.
- TR ve EN kelimeleri ayrı sözlüklerde RAM'e alır.
- `/refresh-cache` çağrısıyla canlı güncellenir.

Kısaca: Kara listeyi veritabanından her istekte tekrar okumadan çok hızlı kullanmayı sağlar.

### 8.4 `run_moderation()` ne yapar?
Dosya: `app/services/moderation_service.py`
- Tüm moderasyon adımlarını sırayla çalıştıran ana fonksiyondur.
- Temizleme -> spam -> kara liste -> model -> karar akışını yönetir.
- Sonuçta API'nin döndüğü tüm karar bilgilerini üretir.

Kısaca: Bu fonksiyon sistemin beyni gibi çalışır.

### 8.5 `calculate_verdict()` ne yapar?
Dosya: `app/services/moderation_service.py`
- Kara liste eşleşmeleri ve model skorlarını tek bir karara dönüştürür.
- Risk seviyesini (`CRITICAL`, `MEDIUM`, `LOW`, `NONE`) belirler.
- Karşılık gelen aksiyonu (`CENSOR`, `MONITOR`, `ALLOW`) tetikler.

Kısaca: Model skorlarını insanlar için anlaşılır moderasyon kararına çevirir.

### 8.6 `/analyze` endpoint'i ne yapar?
Dosya: `app/api/endpoints.py`
- Dış sistemin çağırdığı ana API kapısıdır.
- Metni alır, `run_moderation()` ile analiz eder.
- JSON formatında karar + gecikme bilgisi döndürür.

Kısaca: Platform ile moderasyon motoru arasındaki köprüdür.

## 9. Kurulum ve Çalıştırma

### 9.1 Gereksinimler
- Python 3.10+
- CUDA destekli GPU (önerilir, zorunlu değil)
- Supabase proje bilgileri (`SUPABASE_URL`, `SUPABASE_KEY`)

### 9.2 Kurulum
```bash
pip install -r requirements.txt
```

### 9.3 API'yi Başlatma
```bash
uvicorn main:app --reload
```

### 9.4 Streamlit Paneli Başlatma
```bash
streamlit run app.py
```

## 10. Notlar ve İyileştirme Önerileri
- Bilinen kenar vaka: aşırı tekrar + küfür kombinasyonlarında bazı metinler spam'e düşebilir.
- Öneri 1: tekrar harf sadeleştirmesini spam kontrolünden önce kesinleştir.
- Öneri 2: `İNCELEME GEREKLİ` eşiğini veri dağılımına göre yeniden kalibre et.
- Öneri 3: platformdan gelen etiketli gerçek verilerle periyodik yeniden eğitim yap.

---
Hazırlanan bu README, `Teknik Araştırma & Geliştirme Raporu v4` içeriğini proje kod yapısıyla birlikte tek dokümanda birleştirir.

## 11. Docker ve Hugging Face Spaces Deployment

Bu proje FastAPI servisini `main.py` içindeki `app` nesnesi ile başlatır. Docker imajı içinde doğru başlangıç komutu bu nedenle `uvicorn main:app ...` şeklindedir.

### 11.1 Yerelde Docker ile test
```bash
docker build -t sentinel-api .
docker run --rm -p 7860:7860 \
  -e SUPABASE_URL="https://YOUR_PROJECT.supabase.co" \
  -e SUPABASE_KEY="YOUR_SUPABASE_KEY" \
  sentinel-api
```

Test isteği:
```bash
curl -X POST "http://127.0.0.1:7860/analyze" \
  -H "Content-Type: application/json" \
  -d '{"text":"örnek metin","platform_dil":"tr"}'
```

### 11.2 Hugging Face Spaces adımları
1. Hugging Face hesabında `New Space` oluştur.
2. `SDK` olarak `Docker` seç.
3. Bu repodaki dosyaları Space'e yükle (`Dockerfile`, `requirements.txt`, `app/`, `main.py`, `models_cache/` vb.).
4. Space ayarlarında `Settings -> Variables and secrets` bölümüne şu secret'ları ekle:
   - `SUPABASE_URL`
   - `SUPABASE_KEY`
5. Build tamamlandığında servis `7860` portunda ayağa kalkar.

Notlar:
- Bu Docker kurulumunda `torch` CPU wheel olarak yüklenir (HF Spaces free tier için uygun).
- `.dockerignore` dosyası, gereksiz yerel dosyaları imaja dahil etmeyerek build süresini ve imaj boyutunu azaltır.