İçeriğe geç

Atölye Kurulumu: Python 3.12, uv, PyTorch, FAISS, Polars ve Jupyter Lab

Recommender systems çalışmak için modern bir Python ortamını sıfırdan kuruyoruz: uv (Rust-based, conda'dan 80x hızlı), Python 3.12, PyTorch 2.5+, FAISS CPU+GPU, Polars, implicit, lightfm, surprise, Jupyter Lab. Mac, Windows (WSL2), Linux ve Google Colab seçenekleri.

Şükrü Yusuf KAYA
25 dakikalık okuma
Başlangıç
Atölye Kurulumu: Python 3.12, uv, PyTorch, FAISS, Polars ve Jupyter Lab
🛠️ Bu dersin hedefi
Bu dersin sonunda elinde çalışan bir atölye olacak: ders notebook'larını açıp
Shift+Enter
'a basabileceğin, importlar hata vermeyen, GPU varsa görünen, FAISS çalışan bir ortam. Üç platform için ayrı talimat veriyorum: macOS, Windows (WSL2), Linux. Hiç bilgisayar yoksa: Google Colab fallback'i de var.

TL;DR — Hedef Yığın#

Şu araçları kuracağız:
AraçSürümNiçin?
Python3.12.xModern. 3.13 hâlâ bazı paketlerle uyumsuz.
uvlatest (Astral)Paket yöneticisi — pip'ten 10-100x hızlı, Rust-yazılmış.
PyTorch2.5+CUDA 12.4 destekli, Mac MPS destekli.
NumPy2.xModern.
Polars1.xPandas alternatif — 5-30x hızlı büyük verilerde.
scipy.sparselatestSparse matrix işlemleri için.
FAISS1.8+ (cpu veya gpu)ANN search — vector retrieval'in standart aracı.
implicit0.7+ALS, BPR, LMF — production-grade.
lightfm1.17+Hybrid (CF + content) modeller için.
surprise1.1+Klasik CF (eski ama didaktik).
scikit-learn1.5+Yardımcı ML araçları.
xgboost / lightgbmlatestRanking için.
Jupyter Lab4+Notebook ortamı.
matplotlib + seaborn + plotlylatestGörselleştirme.

Neden uv? (conda yerine)#

Eskiden Python'da bir ML ortamı kurmak demek:
conda create
,
pip install -r requirements.txt
, 15 dakika beklemek, çakışma çözmek demekti. uv bu hikayeyi değiştirdi.
uv
, Astral şirketi tarafından Rust'ta yazılmış bir modern Python paket yöneticisidir:
  • 10-100x daha hızlı — gerçek bir benchmark: PyTorch + transformers + datasets + faiss + sklearn → conda 4 dk 28 sn, uv 8 sn. (Test: M2 Mac, gigabit fiber.)
  • Resolver çok daha akıllı — paket çakışmasını saniyelerde çözer.
  • Lock file standardı (
    uv.lock
    ) — reproducible environment.
  • Tek binary — Python kendisi olmadan da çalışır (kendi indirir).
  • pip uyumlu
    uv pip install x
    yazabilirsin, pip'tekiyle aynı.
Önbilgi:
uv
Kasım 2024'te 1.0'a ulaştı, Mart 2025'te endüstri standardı haline gelmeye başladı. Türkiye'de henüz az kullanılıyor — bu kursla öğrenmen sana avantaj.

Platforma Göre Adımlar#

Senin platformuna git, sırayla uygula. Hepsi ~5-15 dakika sürer.

macOS — M1/M2/M3/M4 (Apple Silicon)#

1. Homebrew yoksa kur

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. uv'yi kur

brew install uv # veya kendi installer'ı: curl -LsSf https://astral.sh/uv/install.sh | sh

3. Proje klasörü oluştur ve Python 3.12 ile init et

mkdir -p ~/recommender-master-class && cd ~/recommender-master-class uv init --python 3.12

4. Paketleri yükle

uv add numpy scipy pandas polars matplotlib seaborn plotly tqdm uv add scikit-learn xgboost lightgbm uv add torch torchvision torchaudio # MPS otomatik destekli uv add faiss-cpu # Mac'te GPU yok, CPU yeterli uv add implicit lightfm scikit-surprise uv add jupyterlab ipywidgets uv add datasets transformers # ileride lazım olacak

5. Doğrulama

uv run python -c "import torch; print(torch.backends.mps.is_available())" # True dönmeli

6. Jupyter'i başlat

uv run jupyter lab
Mac'te FAISS GPU yok, ama PyTorch MPS (Metal Performance Shaders) embedding modelleri için yeterli. M1 16GB makinede MovieLens-25M rahatça çalışır.

Hepsinin Çalıştığını Doğrula#

Atölye kurulumu sonrası şu doğrulama script'ini çalıştır. Yeşil tikleri görmek seni bir sonraki derse hazırlar.
python
# verify_atolye.py — Atölye sağlık kontrolü
import sys
import importlib
 
REQUIRED = {
"numpy": "2.0",
"scipy": "1.13",
"pandas": "2.0",
"polars": "1.0",
"sklearn": "1.5",
"torch": "2.5",
"faiss": "1.8",
"implicit": "0.7",
"lightfm": "1.17",
"surprise": "1.1",
"matplotlib": "3.8",
"xgboost": "2.0",
"lightgbm": "4.0",
}
 
def check_version(pkg, min_ver):
try:
mod = importlib.import_module(pkg)
ver = mod.__version__
return True, ver
except ImportError:
return False, None
 
print("=" * 60)
print("🔍 Recommender Systems Master Class — Atölye Sağlık Kontrolü")
print("=" * 60)
print(f"Python: {sys.version.split()[0]}")
print("-" * 60)
 
failed = []
for pkg, min_ver in REQUIRED.items():
ok, ver = check_version(pkg, min_ver)
status = "✅" if ok else "❌"
print(f"{status} {pkg:15s} → {ver if ok else 'YÜKLÜ DEĞİL'}")
if not ok:
failed.append(pkg)
 
print("-" * 60)
 
# PyTorch GPU/MPS kontrolü
try:
import torch
if torch.cuda.is_available():
print(f"🎮 CUDA: {torch.cuda.get_device_name(0)} (count: {torch.cuda.device_count()})")
elif torch.backends.mps.is_available():
print("🎮 MPS: Apple Silicon GPU mevcut")
else:
print("⚠️ GPU yok — CPU-only modunda çalışacak (yavaş ama OK)")
except Exception as e:
print(f"⚠️ PyTorch GPU kontrolü başarısız: {e}")
 
# FAISS GPU kontrolü
try:
import faiss
gpu_count = faiss.get_num_gpus()
if gpu_count > 0:
print(f"🎮 FAISS GPU: {gpu_count} GPU görüldü")
else:
print("ℹ️ FAISS CPU-only (Mac veya CPU-only kurulum normal)")
except Exception as e:
print(f"⚠️ FAISS kontrolü başarısız: {e}")
 
print("=" * 60)
if failed:
print(f"❌ Eksik paketler: {', '.join(failed)}")
print(" Yeniden yükle: uv add " + " ".join(failed))
sys.exit(1)
else:
print("🎉 Tüm paketler hazır — bir sonraki derse geçebilirsin!")
 
Atölye doğrulama script'i — `uv run python verify_atolye.py` ile çalıştır.
🚨 Sık karşılaşılan kurulum sorunları
  1. FAISS GPU Windows native'de çalışmaz — WSL2 zorunlu. 2) PyTorch CUDA versiyonu uyumsuz çıkıyorsa:
    uv add 'torch --index-url https://download.pytorch.org/whl/cu124'
    . 3) implicit kurulumu Apple Silicon'da hata veriyorsa:
    brew install libomp
    sonra tekrar dene. 4) scikit-surprise build hatası veriyorsa:
    uv add 'scikit-surprise --no-build-isolation'
    . Yine takıldıysan forum/discord'da sor.

Önerilen Proje Yapısı#

Kursu yaparken kendi klasör yapın şöyle olmalı:
recommender-master-class/ ├── pyproject.toml # uv tarafından oluşturuldu ├── uv.lock # lock file (commit et) ├── .python-version # 3.12 ├── data/ # dataset'ler buraya iner │ ├── movielens-100k/ │ ├── movielens-1m/ │ └── ... ├── notebooks/ # ders notebook'ları │ ├── 00-setup-verification.ipynb │ ├── 01-landscape-eda.ipynb │ └── ... ├── src/ # reusable Python modülleri │ ├── data/ # dataset loaders │ ├── models/ # model implementations │ ├── eval/ # evaluation utilities │ └── utils/ ├── checkpoints/ # eğitilmiş modeller (gitignore'a ekle) └── README.md
.gitignore
örnek:
data/ checkpoints/ *.pyc __pycache__/ .ipynb_checkpoints/ .venv/

Sıradakİ Ders#

Bir sonraki derste (0.5) hangi datasetlerle çalışacağımızı detaylı tanıtacağım — MovieLens (100K → 1M → 25M), Amazon Reviews, RetailRocket, H&M, MIND News, Spotify MPD, Last.fm. Hangi dataset hangi problem için en uygun, lisansları neler, ne kadar büyük, nasıl indireceğiz — hepsi orada. Hadi bakalım. 📊

Sık Sorulan Sorular

Evet, kullanabilirsin — eğitsel olarak fark yok. Ama uv 10-100x daha hızlı, modern, ve son 2 yılda endüstri standardı haline geldi. Conda ile kalmanın tek avantajı: çok yaşlı dependency'ler (örn. eski TensorFlow). Bu kurs için sıfır gerekçen var.

Yorumlar & Soru-Cevap

(0)
Yorum yazmak için giriş yap.
Yorumlar yükleniyor...

İlgili İçerikler