iddaai-be/mds/V25_MODEL_UPDATE.md

# V25 Model Güncelleme Özeti

**Tarih:** 12 Mart 2026
**Konu:** Target Leakage düzeltmesi ve model yeniden eğitimi

---

## 1. Sorun Tespiti

### Target Leakage (Hedef Sızıntısı)

Eski V25 modeli `total_goals` ve `ht_total_goals` feature'larını içeriyordu. Bu feature'lar:
- Maç başlamadan bilinemez
- Sadece maç bittikten sonra elde edilir
- Model "hile yapmış" oluyor - sonuca bakarak tahmin yapıyor

**Örnek:**
```
Feature: total_goals = 3  (maçta atılan toplam gol)
Target:   over_2.5 = Yes  (2.5 üstü)

Eğer total_goals'ü biliyorsan, zaten sonucu biliyorsun!
total_goals > 2.5 ise over_2.5 = Yes
```

---

## 2. Yapılan Değişiklikler

### 2.1 CatBoost Opsiyonel Hale Getirildi

**Dosya:** `ai-engine/models/v25_ensemble.py`

```python
# CatBoost is optional
try:
    from catboost import CatBoostClassifier
    CATBOOST_AVAILABLE = True
except ImportError:
    CatBoostClassifier = None
    CATBOOST_AVAILABLE = False
```

**Neden?**
- CatBoost modülü yüklü değildi
- Import hatası veriyordu
- Model CatBoost olmadan da çalışabilmeli

### 2.2 Yeni Training Script Oluşturuldu

**Dosya:** `ai-engine/scripts/train_v25_clean.py`

**Özellikler:**
- 73 feature (target leakage YOK)
- Market-specific modeller
- XGBoost + LightGBM ensemble
- Early stopping ile overfitting önleme

**Feature Listesi:**
```
ELO Features (8)
Form Features (12)
H2H Features (6)
Team Stats Features (8)
Odds Features (24)
League Features (4)
Upset Engine (4)
Referee Engine (5)
Momentum Engine (3)
```

**Kaldırılan Feature'lar:**
- `total_goals` ❌ (Target Leakage)
- `ht_total_goals` ❌ (Target Leakage)

### 2.3 V25Predictor Sınıfı Yeniden Yazıldı

**Dosya:** `ai-engine/models/v25_ensemble.py`

**Yeni API:**
```python
# MS tahmini
home_prob, draw_prob, away_prob = predictor.predict_ms(features)

# OU25 tahmini
over_prob, under_prob = predictor.predict_ou25(features)

# BTTS tahmini
btts_yes, btts_no = predictor.predict_btts(features)

# Tam maç tahmini
prediction = predictor.predict_match(
    match_id='123',
    home_team='Team A',
    away_team='Team B',
    features=features,
    odds={'ms_h': 1.85, 'ms_d': 3.50, 'ms_a': 4.20}
)
```

### 2.4 Test Script Güncellendi

**Dosya:** `ai-engine/scripts/test_v25_predictor.py`

---

## 3. Eğitim Sonuçları

### Model Performansı

| Market | Accuracy | Log Loss | Açıklama |
|--------|----------|----------|----------|
| MS (1X2) | 52.2% | 0.9747 | Ev sahibi, Berabere, Deplasman |
| OU25 | 59.7% | 0.6568 | Over/Under 2.5 gol |
| BTTS | 55.9% | 0.6805 | Her iki takım gol atar mı? |

### Veri Seti

- **Toplam maç:** 19,819
- **Train:** 14,319
- **Validation:** 2,527
- **Test:** 2,973

### Test Örneği Sonucu

```
MS Prediction:
   Home Win (1): 52.5%
   Draw (X):     27.6%
   Away Win (2): 19.9%

OU25 Prediction:
   Over 2.5:  47.8%
   Under 2.5: 52.2%

BTTS Prediction:
   Yes: 52.8%
   No:  47.2%
```

---

## 4. Dosya Yapısı

```
ai-engine/
├── models/
│   └── v25/
│       ├── xgb_v25_ms.json      # XGBoost Match Result
│       ├── lgb_v25_ms.txt       # LightGBM Match Result
│       ├── xgb_v25_ou25.json    # XGBoost Over/Under 2.5
│       ├── lgb_v25_ou25.txt     # LightGBM Over/Under 2.5
│       ├── xgb_v25_btts.json    # XGBoost BTTS
│       ├── lgb_v25_btts.txt     # LightGBM BTTS
│       └── feature_cols.json    # Feature listesi
├── scripts/
│   ├── train_v25_clean.py       # Yeni training script
│   └── test_v25_predictor.py    # Test script
└── models/
    └── v25_ensemble.py          # Predictor sınıfı
```

---

## 5. Kavramlar

### CatBoost Nedir?

- Yandex tarafından geliştirilen gradient boosting kütüphanesi
- XGBoost ve LightGBM gibi makine öğrenmesi modeli
- Kategorik değişkenleri otomatik işler
- Overfitting'e karşı dayanıklı
- Opsiyonel - yoksa XGBoost ve LightGBM ile çalışır

### Target Leakage Nedir?

Model eğitiminde kullanılan bir feature'ın aslında hedef değişkenin sonucunu "bilmesi" durumudur.

**Gerçek Hayat Örneği:**
- Doktor hastaya "hasta mısın?" diye sorar
- Hasta "evet" derse, model bu bilgiyi kullanarak hastalık tahmin eder
- Ama gerçek tahminde bu bilgi olmayacak!

**Futbol Örneği:**
- `total_goals` feature'ı maç sonucunu zaten biliyor
- Model bu bilgiyle "öğreniyor" ama gerçek tahminde bu bilgi yok
- Sonuç: Model gerçek dünyada başarısız olur

---

## 6. Kullanım

### Modeli Yükleme

```python
from models.v25_ensemble import get_v25_predictor

predictor = get_v25_predictor()
```

### Tahmin Yapma

```python
features = {
    'home_overall_elo': 1650.0,
    'away_overall_elo': 1580.0,
    'odds_ms_h': 1.85,
    'odds_ms_d': 3.50,
    'odds_ms_a': 4.20,
    # ... diğer feature'lar
}

# MS tahmini
home, draw, away = predictor.predict_ms(features)

# Tam tahmin
prediction = predictor.predict_match(
    match_id='match_001',
    home_team='Galatasaray',
    away_team='Fenerbahce',
    features=features,
    odds={'ms_h': 1.85, 'ms_d': 3.50, 'ms_a': 4.20}
)
```

### Modeli Yeniden Eğitme

```bash
cd ai-engine
python scripts/train_v25_clean.py
```

---

## 7. Sonraki Adımlar

1. **Hyperparameter Tuning:** Optuna ile daha iyi parametreler
2. **Feature Engineering:** Yeni feature'lar ekleme
3. **Calibration:** Probability calibration ile daha doğru olasılıklar
4. **Cross-Validation:** Daha güvenilir model değerlendirme
5. **Feature Importance:** Hangi feature'lar önemli?

---

## 8. Notlar

- Eski modeller `models/v25/` klasöründe yedeklendi
- Yeni modeller aynı klasöre kaydedildi
- Feature listesi `feature_cols.json` dosyasında
- Training data: `ai-engine/data/training_data.csv` (19,819 maç)

---

**Düzenleyen:** AI Assistant
**Tarih:** 12 Mart 2026