Yapay Zeka Destekli Film Öneri Sistemi

Hibrit Makine Öğrenmesi (TF-IDF + KNN + K-Means) tabanlı bireysel ve grup film öneri uygulaması.
NEÜ Bilgisayar Mühendisliği
Şerife Nazlı ÜNAY · Esma Nur KÖKÖREN · Gamze POLAT

---

Ekran Gorüntuleri

Anasayfa	Benzer Filmler	Grup Modu	Profil

---

İçindekiler

• Proje Hakkında
• Sistem Mimarisi
• Özellikler
• Kurulum
• Çalıştırma Sırası
• API Referansı
• Proje Yapısı
• Kullanılan Teknolojiler

---

Proje Hakkında

Bu uygulama, MovieLens 100K veri seti üzerinde eğitilmiş hibrit bir öneri motoru kullanarak:

• Kullanıcıya kişiselleştirilmiş film önerileri sunar
• Aynı anda birden fazla kullanıcı için grup önerisi üretir (En Az Mağduriyet stratejisi)
• Yeni kayıtlı kullanıcılar için soğuk başlangıç (cold start) protokolü uygular
• İçerik tabanlı arama ile benzer filmler listeler

---

Sistem Mimarisi

┌─────────────────────┐        HTTP/JSON        ┌──────────────────────────┐
│   Flutter Mobil App │ ◄─────────────────────► │   FastAPI Backend         │
│   (iOS & Android)   │                         │   uvicorn + routes.py     │
└─────────────────────┘                         └────────────┬─────────────┘
                                                             │
                                  ┌──────────────────────────┼──────────────────────────┐
                                  │                          │                          │
                         ┌────────▼────────┐      ┌─────────▼────────┐      ┌──────────▼──────────┐
                         │  HybridEngine   │      │  MSSQL Veritabanı │      │  TMDB API            │
                         │  (pkl modeli)   │      │  (SQLAlchemy ORM) │      │  (Poster + Özet)     │
                         │                 │      │                   │      │                      │
                         │ • K-Means       │      │ • users           │      │ Paralel async istek  │
                         │ • TF-IDF + KNN  │      │ • movies          │      │ (httpx + asyncio)    │
                         │ • Least Misery  │      │ • ratings         │      └──────────────────────┘
                         └─────────────────┘      │ • friendships     │
                                                  │ • movie_statuses  │
                                                  └───────────────────┘

---

Kurulum

Gereksinimler

• Python 3.10+
• ODBC Driver 17 for SQL Server
• SQL Server Express (yerel kurulum)
• Flutter 3.x (mobil taraf için)

1. Depoyu klonla

git clone https://github.com/kullanici/film-oneri-sistemi.git
cd film-oneri-sistemi

2. Python bağımlılıklarını kur

pip install -r requirements.txt

3. Ortam değişkenlerini ayarla

backend/ klasöründe .env dosyası oluştur:

TMDB_API_KEY=buraya_tmdb_anahtarını_yaz

TMDB API anahtarı almak için: https://www.themoviedb.org/settings/api

Kendi SQL Server ayarlarına göre düzenle:

DB_DRIVER=
DB_SERVER=
DB_NAME=
DB_TRUSTED_CONNECTION=

5. Veri klasörünü hazırla

film-oneri-sistemi/
└── data/
    ├── movies.csv
    ├── movies_with_overviews.csv
    ├── ratings.csv
    └── processed_data.csv

---

Çalıştırma Sırası

# 1. backend/ klasörüne geç
cd backend

# 2. Tabloları oluştur ve CSV verilerini veritabanına aktar
python seed_db.py

# 3. ML modelini eğit ve pkl dosyasını oluştur
python train.py

# 4. API sunucusunu başlat
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Sunucu çalışınca API dokümantasyonuna şuradan eriş:
👉 http://localhost:8000/docs

Flutter uygulamasını başlatmak için

lib/services/api_service.dart içindeki IP adresini güncelle:

// Android Emülatör  → 10.0.2.2
// iOS Emülatör      → 127.0.0.1
// Gerçek cihaz      → bilgisayarının yerel IP'si (ör. 192.168.0.28)
static const String baseUrl = 'http://192.168.0.28:8000/api';

Mobil Çalıştırma

cd mobile
flutter pub get
flutter run

Proje Yapısı

film-oneri-sistemi/
│
├── backend/
│   ├── main.py               # FastAPI uygulama girişi
│   ├── routes.py             # Tüm API endpoint'leri
│   ├── database.py           # SQLAlchemy modelleri ve bağlantı
│   ├── seed_db.py            # CSV → veritabanı aktarımı
│   ├── migrate_data.py       # Alternatif veri aktarım scripti
│   ├── train.py              # Model eğitimi ve pkl kaydetme
├── ai_core/
│   ├── hybrid_engine.py  # Ana hibrit öneri motoru
│   ├── similarity.py     # TF-IDF + KNN içerik benzerliği
│   ├── clustering.py     # K-Means kullanıcı kümeleme
│   ├── preprocessing.py  # Veri ön işleme
│   └── metrics.py        # Silhouette, RMSE, MAE, Precision@K
│
├── models/                   # Eğitilmiş pkl dosyaları (train.py üretir)
│   ├── hybrid_engine_data.pkl
│   └── user_clustering_model.pkl
│
├── data/                     # MovieLens 100K veri seti
│   ├── movies.csv
│   ├── movies_with_overviews.csv
│   ├── ratings.csv
│   └── processed_data.csv
│
├── mobile/                   # Flutter uygulaması
│   └── lib/
│       ├── models/
│       │   ├── movie.dart
│       │   └── user_profile.dart
│       └── services/
│           └── api_service.dart
│
├── requirements.txt
├── .env                      # ← Git'e ekleme! (.gitignore'a ekle)
└── README.md

---

Kullanılan Teknolojiler

Katman	Teknoloji
Mobil	Flutter 3.x (Dart)
Backend	FastAPI + Uvicorn
Veritabanı	Microsoft SQL Server Express
ORM	SQLAlchemy 2.x
ML	scikit-learn (KMeans, NearestNeighbors, TF-IDF)
Veri işleme	Pandas, NumPy
Model kaydetme	Joblib
HTTP istemci	httpx (async)
Film verileri	TMDB API
Veri seti	MovieLens 100K

---