🎬 Moviek

Film öneri sistemi - Bir film seçin, size benzer filmleri önereyim!

LightFM ve Streamlit ile geliştirilmiş, MovieLens 25M veri setini kullanan akıllı öneri sistemi.

🚀 Hızlı başlangıç

Öngereksinimler

• Docker (windows için önemli!)
• Python 3.10

1. Veri Seti Kurulumu

⚠️ Important: MovieLens 25M veriseti default olarak kuruluyor ./scripts/init-data.sh dosyasından düzenlenebilir.

Veriseti hızlı kurulum:

# Linux/Mac
./scripts/init-data.sh

# Windows
scripts\init-data.bat

Manual İndirme:

1. https://grouplens.org/datasets/movielens/25m/
2. indir ml-25m.zip (~265 MB)
3. data/ml-25m/ klasörüne ekle

Detaylı veri kurulumu için DATA-SETUP.md

2. Docker ile Çalıştırma (Önerilen)

# Uygulamayı başlatma
docker compose up --build

# http://localhost:8501 adresine git

3. Localde çalıştırma (Alternatif)

# Bağımlılıkları yükle
uv sync

# uygulamayı çalıştır
uv run streamlit run src/app.py

📁 Proje Yapısı

moviek/
├── data/                     # Veri Seti Klasörü (gitignored)
│   └── ml-25m/               # MovieLens 25M veriseti
│       ├── ratings.csv       # ⚠️ Gerekli
│       └── movies.csv        # ⚠️ Gerekli
├── src/
│   ├── app.py                # Streamlit UI
│   ├── recommender.py        # LightFM öneri motoru
├── scripts/
│   ├── init-data.sh          # Veriseti Kurulumu (Linux/Mac)
│   └── init-data.bat         # Veriseti Kurulumu (Windows)
├── Dockerfile                # Docker konfigürasyonları
├── compose.yaml              # Docker Compose konfigürasyonları
├── pyproject.toml            # Python bağımlılıkları
└── README.md                 # Bu dosya

🎯 Özellikler

🎬 Film Bazlı Öneri Sistemi

• İçerik Tabanlı Öneriler: Bir film seçin, benzer filmleri görün
• 3 Farklı Algoritma:
  • 🔀 Hibrit: AI embeddings + tür benzerliği (en iyi sonuç)
  • 🧠 AI Embeddings: LightFM'in öğrendiği gizli özellikler
  • 🎭 Tür Benzerliği: Film türlerine göre öneriler
• Akıllı Arama: Film adına göre hızlı arama
• Detaylı Sonuçlar: Benzerlik skorları ve görsel göstergeler

🚀 Teknik Özellikler

• LightFM + WARP Loss: Sıralama optimizasyonu için
• Hızlı Eğitim: Yapılandırılabilir veri limitleri
• İnteraktif UI: Streamlit ile kolay kullanım
• Docker Desteği: Geliştirme için hot-reload
• Akıllı Önbellek: Tekrar eğitim gerektirmez

🔧 Konfigürasyon

Memory ve Performans

src/app.py dosyasında güncelleme.

# Hızlı öğrenme limitini ayarla (default: 500,000)
rec.load_and_filter_data(limit=500_000)

# Training epochs değeri (default: 10)
rec.train_model(epochs=10)

Memory kullanımı:

• 500K ratings: ~200-300 MB RAM
• 1M ratings: ~400-600 MB RAM
• Tüm veriseti (25M): ~4-8 GB RAM

Model Parametreleri

src/recommender.py dosyasını düzenle:

# Number of latent factors (default: 30)
self.model = LightFM(loss="warp", no_components=30)

# Minimum reviews per movie (default: 50)
rec.load_and_filter_data(min_reviews=50)

📊 Veriseti Bilgileri

• Kaynak: MovieLens 25M
• Boyut: ~265 MB (compressed), ~1.5 GB (extracted)
• Ratings: 25 million ratings
• Filmler: 62,000 movies
• Kullanıcılar: 162,000 users
• Lisans: Araştırmalar ve öğrenciler için ücretsiz

Citation:

F. Maxwell Harper and Joseph A. Konstan. 2015.
The MovieLens Datasets: History and Context.
ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4: 19:1–19:19.

🎯 Nasıl Çalışır?

Öneri Algoritmaları

1. AI Embeddings (LightFM):

   • Model, kullanıcı etkileşimlerinden film özelliklerini öğrenir
   • Her film için çok boyutlu bir vektör oluşturur
   • Cosine similarity ile benzer filmleri bulur

2. Tür Benzerliği:

   • Film türlerini karşılaştırır (Drama, Aksiyon, vb.)
   • Jaccard benzerliği kullanır: kesişim / birleşim
   • Aynı türdeki filmleri önerir

3. Hibrit Yaklaşım:

   • %60 AI embeddings + %40 tür benzerliği
   • En dengeli ve etkili sonuçları verir

🐛 Sorun Giderme

"Veri seti eksik veya hatalı!"

Sorun: Veri seti /app/data/ml-25m/ratings.csv konumunda bulunamadı

Çözüm:

# Verify dataset location
ls -la data/ml-25m/ratings.csv

# If missing, run initialization
./scripts/init-data.sh

# Or download manually
cd data
curl -L -O https://files.grouplens.org/datasets/movielens/ml-25m.zip
unzip ml-25m.zip

"Film listesi yüklenemedi"

Sorun: Film listesi boş geliyor

Çözüm:

# Modeli yeniden eğit
# UI'dan "Modeli Yenile" butonuna bas veya:
docker compose restart

Container başlamıyor

# Logları kontrol et
docker compose logs app

# Yapılandırmayı doğrula
docker compose config

# Sıfırdan yeniden oluştur
docker compose down -v
docker compose build --no-cache
docker compose up

Port zaten kullanımda

# 8501 portunu kullanan uygulamayı bul
lsof -i :8501          # Linux/Mac
netstat -ano | find "8501"  # Windows

# Çakışan container'ı durdur
docker stop moviek_app

# Veya compose.yaml'da portu değiştir
ports:
  - "8080:8501"  # 8080 portunu kullan

Yavaş performans

# Veri seti boyutunu küçült (src/app.py)
rec.load_and_filter_data(limit=100_000)  # Daha düşük limit

# Eğitim epoch sayısını azalt
rec.train_model(epochs=5)  # Daha az epoch

# Cache'i temizle ve yeniden eğit
docker compose restart

Öneri sonuçları boş

Sorun: Seçilen film için öneri bulunamıyor

Çözüm:

• Farklı bir öneri algoritması deneyin (Hibrit yerine Tür Benzerliği)
• Öneri sayısını artırın (sidebar'dan)
• Daha popüler bir film seçin

📚 Dokumantasyon

• DATA-SETUP.md - Detaylı kurulum dosyası
• docs/DOCKER_FIXES.md - Docker konfigürasyon hataları

🧪 Kurulumu Test Etme

# Test Docker configuration
./test-docker.sh      # Linux/Mac
test-docker.bat       # Windows

# Expected output:
# - All tests passed
# - Application accessible at http://localhost:8501

🛣️ Yol Haritası

• Film bazlı öneri sistemi
• Hibrit algoritma (AI + Tür)
• İnteraktif arama ve filtreleme
• Model değerlendirme metrikleri
• Film posterleri (TMDb API)
• Önerileri CSV'ye aktarma
• Çoklu veri seti desteği
• REST API endpoint
• Kullanıcı bazlı öneri (opsiyonel)
• Film detay sayfası
• Favorilere ekleme

🤝 Katkıda Bulunma

Katkılar memnuniyetle karşılanır! Lütfen:

1. Repository'yi fork edin
2. Feature branch oluşturun
3. Değişikliklerinizi yapın
4. Kapsamlı test edin (Docker dahil)
5. Pull request gönderin

🎓 Öğrenme Kaynakları

• LightFM Dokümantasyonu: https://making.lyst.com/lightfm/docs/home.html
• Streamlit Dokümantasyonu: https://docs.streamlit.io/
• MovieLens Veri Seti: https://grouplens.org/datasets/movielens/
• Collaborative Filtering: https://en.wikipedia.org/wiki/Collaborative_filtering

📄 Lisans

Bu proje eğitim amaçlı kullanılmıştır.

Made with ❤️ using LightFM and Streamlit by Emre Kayık