Fraud Detection Service

Üretime hazır bir fraud (dolandırıcılık) tespiti mikroservisi: dengesiz işlem verisi üzerinde model eğitir, en iyi modeli versiyonlayarak kaydeder ve bir REST API üzerinden gerçek zamanlı skorlama sunar. Celery ile periyodik yeniden eğitim ve basit bir drift izleme katmanı içerir.

Bu proje "notebook'ta XGBoost eğittim" değil, bir ML modelini servise alma (training pipeline → model registry → serving API → retraining → monitoring) hikâyesinin tamamını gösterir.

Neden bu problem?

Fraud tespiti, dengesiz (skewed) sınıflandırmanın ders kitabı örneğidir: işlemlerin yalnızca ~%0.3'ü fraud'dur. Bu yüzden:

• Accuracy yanıltıcıdır. Her şeye "normal" diyen bir model %99.7 accuracy alır ama tek bir dolandırıcılığı yakalamaz. Bu projede precision / recall / F1 / PR-AUC kullanılır.
• Karar eşiği 0.5 değildir. Eşik, precision-recall eğrisinden veriye göre seçilir (src/evaluate.py:tune_threshold).
• Tablo verisinde ağaç toplulukları kazanır. Baseline (Logistic Regression), XGBoost ve opsiyonel bir sinir ağı karşılaştırılır; beklendiği gibi XGBoost production modeli olur.

Mimari

                    ┌──────────────────┐
   ham işlem  ─────▶│  Training         │   LogReg / XGBoost / NN karşılaştırması
   verisi          │  pipeline         │   + eşik ayarı (PR eğrisi)
                    │  (src/train.py)   │
                    └────────┬─────────┘
                             │ en iyi model + metadata
                             ▼
                    ┌──────────────────┐
                    │  Model Registry  │   models/<timestamp>/model.joblib
                    │  (src/registry)  │   + meta.json, 'current' işaretçisi
                    └────────┬─────────┘
                             │ aktif model
                             ▼
   POST /predict ───▶┌──────────────────┐───▶ fraud_probability + karar
                     │  FastAPI servis  │
   GET /model-info ─▶│  (src/api.py)    │───▶ her tahmin loglanır (drift için)
                     └──────────────────┘
                             ▲
              Celery beat ───┘  her gece 03:00 retrain + drift raporu
              (src/tasks.py)

Teknolojiler

Python · scikit-learn · XGBoost · FastAPI · Celery · Redis · Docker / docker-compose · pytest. (Opsiyonel: TensorFlow/Keras ile sinir ağı karşılaştırması.)

Hızlı başlangıç

Docker ile (önerilen)

docker compose up --build
# API: http://localhost:8000/docs

İlk açılışta model yoksa otomatik eğitilir.

Lokal

pip install -r requirements.txt
python -m src.train          # eğit + en iyi modeli kaydet
uvicorn src.api:app --reload # servisi başlat

Örnek istek

curl -X POST http://localhost:8000/predict \
  -H 'Content-Type: application/json' \
  -d '{"features": {"V1": -2.2, "V3": 1.8, "V10": 2.0, "Amount": 120.0}}'

{
  "fraud_probability": 0.91,
  "is_fraud": true,
  "threshold": 0.5514,
  "model_version": "20260609_202326"
}

Veri

Gerçek veri olarak Kaggle'daki Credit Card Fraud Detection (ULB) seti kullanılır (data/creditcard.csv olarak konur). Dosya yoksa proje, aynı yapıda (V1..V28 + Amount + Class) gerçekçi sentetik veri üretir; böylece repo indirme yapmadan da uçtan uca çalışır (src/data.py).

Sonuçlar (örnek çalışma)

Model	Precision	Recall	F1	PR-AUC
Logistic Regression (baseline)	0.84	0.76	0.80	0.83
XGBoost (production)	0.97	0.86	0.91	0.95

Tablo verisinde XGBoost'un baseline'ı belirgin şekilde geçmesi beklenen sonuçtur; sinir ağı eklendiğinde benzer/altında kalır — bu da "yapılandırılmış veride önce ağaç toplulukları" prensibini doğrular.

Proje yapısı

src/
  config.py      # yollar, sabitler, eşik
  data.py        # gerçek veri veya sentetik fallback
  evaluate.py    # dengesiz veri metrikleri + eşik ayarı
  train.py       # 3 model eğitimi, karşılaştırma, en iyiyi kaydet
  registry.py    # model versiyonlama
  api.py         # FastAPI: /predict /model-info /health
  monitoring.py  # tahmin loglama + drift kontrolü
  tasks.py       # Celery retraining + drift raporu
tests/           # API testleri

Test

pytest -q

Yol haritası (sonraki adımlar)

• Gerçek Kaggle verisiyle sonuçları sabitleme
• Prometheus + Grafana ile metrik panosu
• SHAP ile özellik açıklanabilirliği (hangi sinyal fraud'a işaret etti)
• Model registry'yi MLflow'a taşıma