Ek A — Ortam Kurulumu

Ek durumu: çevrildi. Kaynak metin: İngilizce A eki. Buradaki sürümler kitabın ölçümlerinin gerçekten koşulduğu sürümler; böylece bir bölümün sayılarının geldiği ortamdan başlarsınız. Bu sizi o sayılara yaklaştırır, ama aynı basamakları garanti etmez: alt bağımlılıklar kilitli değil, her Python sürümü sınanmadı ve hızlandırıcılar arasında küçük farklar var. Her biri aşağıda ele alınıyor.

Bu kitaptaki her şey üç yerden birinde koşuyor:

Tarayıcınızda. Her etkileşimli araç kendi kendine yeterli — kurulacak bir şey yok, koşulacak bir şey yok.
Bir Python ortamında. Bu kitaptaki her ölçüm Python 3.14.5 üzerinde koşuldu. Sabitlenmiş ortam Python 3.12 ve sonrasını gerektiriyor — NumPy 2.5.2 ile SciPy 1.18.1’in ikisi de Requires-Python >=3.12 bildiriyor — ve sayıların geldiği sürüm 3.14.5; aradaki sürümlerin hepsi sınanmadı.
Yerel bir model sunucusunda. IV–VII. kısımlar bir model çağırıyor. O kısımlardaki her ölçüm, barındırılan bir API yerine bir dizüstünde ollama kullandı; böylece bunları yeniden üretmek ücretli hiçbir API çağrısı gerektirmiyor ve bir sağlayıcının o anki model sürümüne bağlı olmuyor. Yine de bedava değil: aşağıdaki bütçe tablosundaki disk, bellek ve wall-clock süresi (gerçekte geçen süre) gerekiyor.

A.1 Yerel kurulum

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-chapters.txt

Ya da daha hızlı olan ve — her üst düzey bağımlılık == ile sabitlendiği için — aynı doğrudan sürümleri çözen uv ile (dosya transitive bağımlılıkları, yani doğrudan paketlerin kendi ihtiyaç duyduğu alt bağımlılıkları kilitlemiyor):

uv venv && source .venv/bin/activate
uv pip install -r requirements-chapters.txt

Depoda bir de requirements.txt var ve o başka bir şey: kitabı derleyen birkaç paket. Onu kurmak size bölüm kodunu vermez.

Aşağıdakiler requirements-chapters.txt’in sabitlediği sürümler. Her sürüm, bir bölümün kendi “The stack these numbers came from” tablosunun raporladığı sürüm; iki bölüm anlaşmazlığa düştüğünde ikisi de gösteriliyor, çünkü o anlaşmazlık ortalaması alınacak bir şey değil kitap hakkında bir olgu.

Ölçüldüğü hâliyle sabitlenmiş sürümler
paket	sürüm	nerede kullanılıyor
`numpy`	2.5.2	sayısal olan neredeyse her şey
`pandas`	3.0.5	derlem biçimlendiren bölümler
`scikit-learn`	1.9.0	Bölüm 4, Bölüm 12
`scipy`	1.18.0 / 1.18.1	Bölüm 22’nin boyutlandırma aritmetiği; sonrakini alın
`imbalanced-learn`	0.14.2	Bölüm 12’nin yeniden örneklemesi
`transformers`	5.15.0 / 5.15.1	Bölüm 13, Bölüm 15, Bölüm 16
`torch`	2.13.0	o bölümlerde fine-tuning (ince ayar) uygulanan modeller — bkz. Bölüm A.2
`datasets`	5.0.1	kitabın yüklediği her derlem
`sentence-transformers`	5.7.0 / 6.0.0	Bölüm 3, Bölüm 19; 6.0 satırları sonraki bölümler
`sacrebleu`	2.6.0	Bölüm 15
`seqeval`	1.2.2	Bölüm 13’ün span puanlaması
`sklearn-crfsuite`	0.5.0	Bölüm 13’ün CRF’i
`snowballstemmer`	3.1.1	Bölüm 16
`rouge-score`	0.1.2	Bölüm 14 — güvenmeden önce o bölümü okuyun
`datasketch`	2.0.0	Bölüm 5’in yakın kopya saptaması
`umap-learn`	0.5.12	Bölüm 11
`ollama`	0.24.0	IV–VII. kısımların her ölçümünün çağırdığı yerel model sunucusu
`pytest`	9.1.1	kitabın kendi kontrollerini koşmak

Bu tabloda eskiden yer alan iki paket ölçüm bağımlılığı değil ve dışarı alındı: matplotlib ile jupyter kitaptaki hiçbir sayıyı üretmiyor, kitabı derliyor.

En sonuncusunu almak yerine bunları sabitleyin. Kitabın bulgularından birkaçı belirli alet davranışlarıyla ilgili — Bölüm 14’ün ROUGE tokenlaştırıcı hatası, Bölüm 16’nın küçük harfe çevirme arızaları — ve daha yeni bir sürüm, bir bölümün gösterdiği şeyi düzeltmiş olabilir. Bu, dünya için iyi bir sonuç ve alıştırmanın ortasında kafa karıştırıcı bir sonuç.

A.2 Hızlandırıcılar

pip install torch her platformda farklı bir wheel (önceden derlenmiş Python kurulum paketi) çözüyor ve fine-tuning bölümleri farklı backend’lerde (hesabı yürüten CPU, CUDA ya da MPS altyapısı) biraz farklı sayılar üretiyor. Kitabın fine-tuning ve embedding (gömme) ölçümleri Apple Silicon üzerinde PyTorch’un MPS backend’iyle koşuldu — dört bölüm kendi sürüm tablosunda bunu söylüyor — yani sayıların geldiği yapılandırma bu.

Apple Silicon. pip install torch yeterli; MPS gömülü. Hâlâ MPS çekirdeği olmayan birkaç işlemde sert bir arızayı önlemek için PYTORCH_ENABLE_MPS_FALLBACK=1 ayarlayın.
NVIDIA. CUDA wheel’ini pip’in seçmesine bırakmak yerine açıkça kurun, yoksa sessizce CPU derlemesini alabilirsiniz: pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cu126.
Yalnızca CPU. Bellek yeterse kod koşuyor. Fine-tuning bölümleri birkaç kat uzun sürüyor ve sonuçlar aşağıdaki küçük sayısal farklar dışında aynı.

Backend’ler arasında küçük sayısal farklar bekleyin. Bölüm 13 ya da Bölüm 15’teki bir fine-tuning sonucu kitaptakinden bir iki puan uzaktaysa, ilk bakılacak şey backend’dir, ama tek olası neden o değildir. Paket sürümleri ve seed (rastgelelik başlangıç değeri) de sonucu oynatabilir — Bölüm 13, seed 42 ile yapılmış tek koşuları raporluyor.

A.3 Yerel bir model

IV–VII. kısımlar çağrılacak bir modele ihtiyaç duyuyor. ollama’yı kurun, sonra:

ollama pull qwen3.5:9b        # ~6 GB   — kitabın ölçümlerinin çoğu
ollama pull llama3.2:3b       # ~2 GB   — küçük model satırları ve servis bölümleri
ollama pull gemma3:27b        # ~17 GB  — kabaca 20 GB bellek ister
ollama pull qwen3.6:35b       # ~21 GB  — kabaca 24 GB bellek ister
ollama pull nomic-embed-text  # ~0,3 GB — geçit bölümünün gömme yolu
ollama pull qwen2.5:7b        # ~4,7 GB — 35., 36. ve 38. bölümler ve aşağıdaki ilk çağrı
ollama serve                  # zaten servis olarak çalışıyorsa atlayın

Masaüstü uygulaması ile Homebrew ya da systemd servisi sunucuyu zaten başlatıyor ve ikinci bir ollama serve, adresin zaten kullanımda olduğunu bildiren bir hatayla (address already in use) sonlanır. curl -s http://127.0.0.1:11434/api/version hangi durumda olduğunuzu söylüyor.

Kitap ollama 0.24.0 kullandı. Bir bölümün hangi modeli kullandığı o bölümün durum kutusunda ve dağılım hiç dengeli değil:

Hangi bölüm hangi modeli ister
model	onunla ölçen bölümler
`qwen3.5:9b`	12, 13, 14, 15, 17, 18, 20, 22, 23, 24, 25, 26, 27, 29, 30, 38 — varsayılan ve önce çekilecek olan
`llama3.2:3b`	12, 18, 31, 33, 34, 38
`gemma3:27b`	12, 14, 21, 22, 38
`qwen3.6:35b`	7, 12
`qwen2.5:7b`	35, 36, 38
`nomic-embed-text`	32

Belleğiniz darsa ilk ikisini çekip gerisini atlayın. Büyük model kullanan bölümlerin çoğu daha küçük bir model de raporluyor, ama hepsi değil — Bölüm 21’in görme deneyi yalnızca 27B modeli kullandı — dolayısıyla küçük model satırı olduğunu varsaymadan önce bölümün durum kutusuna bakın.

Her şey doğrudan HTTP API’siyle konuşuyor:

curl -s http://127.0.0.1:11434/api/generate \
  -d '{"model":"qwen2.5:7b","prompt":"Merhaba","stream":false}'

Bir şeyi bir saat boyunca ayıklamadan önce bilinmeye değen iki bayrak. "format": "json" ayrıştırılabilir çıktıyı zorluyor ve bütün bir puanlama hatası sınıfını ortadan kaldırıyor. Ve "think": false akıl yürüten modeller için önemli — düşünme açıkken ollama akıl yürütmeyi ayrı bir thinking alanında döndürüyor ve model token bütçesini orada tüketirse response alanı boş geliyor, ki bu sıfır olarak puanlanıyor ve felaket bir kalite sonucu gibi görünüyor. Bölüm 38’in ölçümü tam da buna çarptı. Boş bir response bir kural değil bir belirti; dolayısıyla iki alanı da okuyun, done_reason’a bakın — length tavana çarptığınız anlamına gelir — ve kalite hakkında bir sonuç çıkarmadan önce num_predict’i yükseltin. Aynısı "format": "json" için de geçerli: tamamlanmış bir üretimin biçimini kısıtlar, kırpılmış olan yine ayrıştırılamaz.

A.4 Diskte ve bellekte maliyeti

İlk pull’dan sonra değil önce bilmeye değer.

Başlamadan önce bütçe
koşturmak istediğiniz	disk	bellek
I–III. kısımlar (model sunucusu yok)	~4 GB	8 GB
Üstüne `qwen3.5:9b` kullanan ölçümler	~10 GB	16 GB
Üstüne `llama3.2:3b`, `nomic-embed-text` ve `qwen2.5:7b`	~17 GB	16 GB
Üstüne `gemma3:27b`	~34 GB	20 GB+
Üstüne bir de `qwen3.6:35b`	~55 GB	24 GB+

Buradaki bellek, modelin bellekte durması gereken miktar; birleşik bellekli bir makinede bu, editörünüzün de kullandığı havuzun aynısı. Asıl bağlayıcı sayının neden ağırlıklar değil KV önbelleği olduğunu ve yapılandırdığınız bağlam uzunluğunun neden bir bellek kararı olduğunu Bölüm 31 anlatıyor.

A.5 Colab

Fine-tuning bölümleri için bir GPU’ya giden en kısa yol Colab ve not defterleri henüz yayımlanmadı — rozetler kitapta değil yol haritasında, dolayısıyla şimdilik kod bloklarını kopyalayın. Yerel model kullanan bölümler Colab’ın ücretsiz katmanında uyarlanmadan çalışmıyor; yerine barındırılan bir API koyun ve sayılarınızın kitabınkilerden farklı olmasını bekleyin, ki bu da sabitleme hakkında başlı başına yararlı bir ders.

A.6 Windows

Kitabın ölçümleri macOS ve Linux’ta koşuldu; yani Windows, bu ekin en az test ettiği platform. Buradaki hiçbir şey ilkesel olarak Windows’a özgü değil; pratikte üç şey farklı.

Sanal ortamı source yerine .venv\Scripts\activate ile etkinleştirin. Bir şey sorun çıkarırsa WSL2 kullanın — kitabın ölçümleri macOS ve Linux’ta koşuldu ve onlara ulaşmanın en kısa yolu WSL2. Ve PYTHONUTF8=1 ayarlayın, çünkü Windows hâlâ bazı dosya okumalarında UTF-8 olmayan bir kodlamaya düşüyor, ki bu da Türkçe metni sessizce bozuyor. Sonuncusu, Bölüm 16’nın savının siz daha bir model yüklemeden gelmesi.

A.7 Yardım almak

Başlığa bölüm adını yazarak bir GitHub issue’su açın. Kitaptaki bir sayı yeniden üretilmiyorsa bu bir issue açmaya değer — hangi bölüm, sizde hangi paket ve model sürümleri var, hangi hızlandırıcı backend’i ve ne aldığınızı söyleyin. Cevap genellikle ilk üçünde.