Hugging Face's logo

Spaces:
moztrk
/
sentinel-api
Sleeping

App Files Community
sentinel-api / README.md
Mustafa Öztürk
Fix HF metadata emoji
5bdeec3
preview code
|
raw
history blame contribute delete
9.41 kB
metadata 
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ı 

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ış 

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 

pip install -r requirements.txt

9.3 API'yi Başlatma 

uvicorn main:app --reload

9.4 Streamlit Paneli Başlatma 

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 

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:

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.