pixel-cinema-svd-movielens32m

🎬 Pixel Cinema — SVD Film Öneri Modeli (MovieLens 32M)

30,7 milyon değerlendirme, 200 bin kullanıcı ve 9.278 film üzerinde, Truncated SVD (Matrix Factorization) ile eğitilmiş gerçek-zamanlı film öneri motoru. Filmler 50 boyutlu gizli (latent) vektörlere sıkıştırılır; öneriler kosinüs benzerliği ile milisaniyeler içinde üretilir.

Bu depo model ağırlıklarını, eğitim/değerlendirme kodunu ve başarım metriklerini içerir. Tam proje (React arayüzü, FastAPI backend, PostgreSQL, Tinder tarzı keşif sayfası, film oynatıcı) ayrıdır:

👉 github.com/ba2hannn/pixel-cinema

---

📊 Başarı Skorları

Aşağıdaki metrikler evaluation/metrics.md dosyasında detaylandırılmıştır. Değerlendirme, held-out %90/%10 split (test verisi modele gösterilmez) ve 10.000 rastgele kullanıcı örnekleme üstüne yapılmıştır.

Not — RMSE neden yüksek? Bu model orijinal rating matrisini merkezlemeden (mean-subtraction) doğrudan SVD'ye verir. Bu nedenle mutlak rating tahmini güçlü değildir; model top-N öneri (sıralama) için tasarlanmıştır. Precision/ Recall/NDCG metrikleri asıl hedefe yöneliktir. Rating tahmini için bias modellemeli bir MF yaklaşımı gerekir.

---

🏗️ Mimari

graph TD
    A[MovieLens 32M Ham Veri] -->|Ön-işleme & Filtreleme| B[Kullanıcı-Film Puan Matrisi]
    B -->|SVD Matris Ayrıştırması| C[50 Boyutlu Gizli Vektörler]
    C -->|Offline Batch Eğitim| D[movie_embeddings.npy]
    D -->|Gerçek-zamanlı Sorgu| E[cosine_similarity]
    E -->|Top-N En Benzer| F[Film Önerileri]

Seyreltiklik problemi: 9.278 × 200.947 = ~1,86 milyar hücrenin yalnızca %1,65'i dolu (sparsity %98,35). Ham matris ~7-14 GB RAM gerektirir; SVD bunu 3,6 MB'lık 50 boyutlu bir diziye sıkıştırır.

---

🎯 Örnek Öneriler (Production Modeli)

Modelin tanınmış filmler için ürettiği en benzer 10 film (kalitatif kanıt — tüm liste evaluation/metrics.md içinde):

---

🚀 Kullanım

from recommender import recommender

# Inception (movieId=79132) için 10 öneri
ids = recommender.get_recommendations(movie_id=79132, top_n=10)
print(ids)  # [.., .., ..]  → movieId listesi

Bağımlılıklar: numpy, scikit-learn, joblib.

---

📁 Depo Yapısı

├── README.md                    # Bu dosya (model kartı)
├── LICENSE                      # MIT (kod ve ağırlıklar)
├── model/
│   ├── movie_embeddings.npy     # 9.278 × 50 SVD item embeddings (3,6 MB)
│   ├── movie_id_to_index.pkl    # movieId → satır indeksi
│   └── index_to_movie_id.pkl    # satır indeksi → movieId
├── recommender.py               # Tek-dosya inference (cosine similarity)
├── training/
│   └── egitici.py               # Modeli sıfırdan eğiten kod (repro)
└── evaluation/
    ├── evaluate.py              # Tüm metrikleri hesaplayan script
    ├── metrics.json             # Önceden hesaplanmış metrikler (makine-okur)
    └── metrics.md               # Önceden hesaplanmış metrikler (insan-okur, TR)

---

🔬 Değerlendirme Nasıl Tekrarlanır?

evaluate.py, modeli aynı hiperparametrelerle (n_components=50, random_state=42) yeniden eğitir, kaydedilen ağırlıklarla birebir tutarlı olduğunu doğrular ve held-out test üstünde metrikleri üretir.

# MovieLens verisini grouplens.org'dan indirin (repoda YOK):
#   ratings_final_for_model.csv  (userId,movieId,rating)
#   movies_final_for_db.csv      (movieId,title,genres,...)

python evaluation/evaluate.py \
    --ratings /path/to/ratings_final_for_model.csv \
    --movies  /path/to/movies_final_for_db.csv

Tam koşu için ~8-16 GB RAM ve ~2 dakika gerekir.

---

📦 Eğitim Detayları

• Algoritma: sklearn.decomposition.TruncatedSVD (randomized solver)
• Parametreler: n_components=50, random_state=42
• Matris orientasyonu: ITEM × USER (satırlar = film)
• Veri: MovieLens ml-32m → 200+ rating eşiğiyle filtrelenmiş 30.770.501 değerlendirme
• sklearn sürümü: 1.3.0

---

🗃️ Veri Seti & Lisans

Model MovieLens ml-32m veri seti üstüne eğilmiştir.

• Veri bu depoda DAĞITILMAMAKTADIR (GroupLens lisans kısıtlamaları). Kendi verinizi https://grouplens.org/datasets/movielens/ adresinden indirin.
• Atıf zorunludur:

  Harper, F. M. and Konstan, J. A. (2015). The MovieLens Datasets: History and Context. ACM Transactions on Interactive Intelligent Systems (TiiS), 5(4). https://doi.org/10.1145/2827872

Bu deponun kodu ve türetilmiş ağırlıkları MIT lisansı altındadır (LICENSE). Veri lisansı ayrıdır ve yukarıdaki şartlara tabidir.

---

⚠️ Limitasyonlar

1. Rating tahmini zayıf: Matris merkezlenmediği için mutlak puan tahmini (RMSE) güçlü değildir; model top-N öneri için optimize edilmiştir.
2. Cold-start: Yeni kullanıcı/film için embedding yoktur.
3. Long-tail: 200'den az rating alan filmler veri hazırlığında elenmiştir (9.278 film), bu yüzden niş filmler zayıf temsil edilir.
4. Tarihsel/dilsel bias: Veri TMDB/MovieLens kaynaklıdır; tarih ve dil dağılımı yanıltıcı olabilir.

---

🔗 İlgili

• Tam proje (UI + backend + DB): github.com/ba2hannn/pixel-cinema
• Veri seti: GroupLens MovieLens