Kurulum sorunları

Önce npm run doctor. Her ✗ satırı sorunu ve çözümünü birlikte yazar. Sorunsuz bir makinede çıktı şöyle:

$ npm run doctor

━━ DOCTOR
         ✓ Node.js                      22.22.2
         ✓ Ollama                       http://localhost:11434
         ✓ model gemma3:4b
         ✓ model bge-m3
         ✓ Chroma                       http://localhost:8000
         ✓ corpus/2025                  8 documents · 7 en, 1 tr
         ✓ embed one sentence           1024 numbers · 150 ms
         ✓ one answer                   176 ms · "Ankara"

Ready.

Corpus satırı dokümanları sayar: 7’si İngilizce, 1’i Türkçe. one answer satırı sohbet modeline kısa bir deneme sorusu sorar: Türkiye’nin başkenti. Cevabın başını gösterir.

Aşağıdaki mesajlar repodaki kodda yazıldığı gibi; <…> olan yerlere sizin değeriniz gelir.

Bir adım bilinen bir sorunla karşılaşınca tek satır yazar: ✗ ve mesaj. Bilinmeyen bir hatada bütün yığın izini (stack trace) basar; o zaman ilk satırı okuyun.

Ollama

Chroma

data/ dosyaları — her adım bir öncekinin dosyasını okur ve onun güncel olup olmadığını kontrol eder:

Corpus ve ayarlar

Komut biçimi — argüman eksik ya da yanlışsa komut nasıl kullanılacağını yazar:

İki fonksiyon bilerek boş bırakıldı; siz yazana kadar şu mesajları verirler:

Çözüm: fonksiyonu yazın. Üstündeki YOUR TURN notu nasıl yazacağınızı anlatıyor. Bir üçüncü parça daha var: src/steps/2-clean.ts içindeki turkishConfidential kuralı. Mesaj vermez. Siz yazana kadar npm run step -- 2, it-security için −12 değil −8 gürültü satırı gösterir. Bitmiş hâlleri solutions/ klasöründe.

Compose olmadan, aynı Chroma tek satırda (compose.yaml’ın başındaki yorumdan):

podman run -d --name chroma -p 8000:8000 -v chroma-data:/data docker.io/chromadb/chroma:1.5.9

8000 portu doluysa, 8001’e alın ve yeni adresi pipeline’a bildirin:

podman run -d --name chroma -p 8001:8000 -v chroma-data:/data docker.io/chromadb/chroma:1.5.9
echo "CHROMA_URL=http://localhost:8001" >> .env

podman run -d --name chroma -p 8001:8000 -v chroma-data:/data docker.io/chromadb/chroma:1.5.9
Add-Content .env "CHROMA_URL=http://localhost:8001"

Hiç container yok — .env içine STORE=json; ayrıntısı Kurulum sayfasında.

Yönetici yetkisi olmadan Podman — Podman’ı kurmak ve sanal makinesini ilk kez açmak yönetici yetkisi isteyebilir; Windows’ta sanal makine WSL2 ya da Hyper-V üzerinde çalışır ve bunlar kapalıysa açmak bir kez yönetici yetkisi ister. Yetki alınamazsa STORE=json; yalnızca Chroma’nın içine bakan kısımlar (Bruno’nun 01-chroma klasörü) çalışmaz.

• VAR=x npm run … çalışmaz. Bu biçim yalnızca Mac/Linux kabuklarında var. Repo bu yüzden her ayarı ya bayrakla (npm run step -- 5 --store json) ya da .env dosyasıyla alır.
• PowerShell’de npm açılmıyorsa ve hata running scripts is disabled on this system diyorsa: npm yerine npm.cmd yazın (npm.cmd run doctor) ya da, şirket politikası izin veriyorsa, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
• Bir bayrak işlemiyor gibiyse (--store json yok sayılıyorsa): aynı ayarı .env dosyasına yazın. .env kabuktan bağımsızdır; PowerShell’de, cmd’de ve zsh’de aynı çalışır.
• Satır sonları sorun değil: repo .gitattributes ile LF kullanır, 1-load.ts de \r\n’i \n’e çevirir.

Aşağıdakiler, şifreli bağlantıları inceleyen bir proxy’nin arkasındaki bir kurum ağında denendi.

Sertifika. Böyle bir ağda npm ci ve Node, şirketin kök sertifikasını (CA) tanımadıkça bağlanamaz. Sertifika dosyasının yolunu Node’a verin; npm de Node ile çalıştığı için aynı ayarı kullanır. Dosyanın yerini şirketinizin BT ekibi bilir.

echo 'export NODE_EXTRA_CA_CERTS=<ca-bundle.pem>' >> ~/.zshrc

setx NODE_EXTRA_CA_CERTS "<ca-bundle.pem>"

Ayar yeni açılan terminallerde geçerli olur: terminali kapatıp açın, sonra npm ci.

İndirmeler. Aynı proxy üzerinden:

• ollama pull registry.ollama.ai’ye ulaşıyor; model dosyaları da iniyor.
• podman pull docker.io/chromadb/chroma:1.5.9 çalışıyor (649 MB).
• Tek bir indirme saniyede 4–8 MB hızla iniyor. İki modeli ve imajı eğitim gününden önce indirin: eğitim sabahı herkes aynı ağdan aynı anda indirirse bu hız paylaşılır.

Repoyu senkronize edilen bir klasöre klonlamayın. npm ci çok sayıda küçük dosya yazar ve senkronizasyon onları kilitlemeye başlar: kurulum çok yavaşlar ya da EPERM/EBUSY gibi dosya erişim hatalarıyla durabilir. Windows’ta Masaüstü ve Belgeler çoğu zaman OneDrive’dadır: $HOME\dev gibi bir klasör kullanın. Mac’te iCloud’un Masaüstü ve Belgeler senkronizasyonu açıksa aynısı: ~/dev.

Zaten OneDrive’a klonladıysanız en temizi: klasörü silin, $HOME\dev altına yeniden klonlayın, npm ci.

git pull şu mesajla durabilir: cannot pull with rebase: You have unstaged changes. Repo klasöründe şunları sırayla çalıştırın:

git stash
git pull
podman compose up -d
npm run catchup -- 0

.cache/question-ledger.jsonl dosyasını silin. Sonra npm run doctor çalıştırın. Corpus satırında 8 documents · 7 en, 1 tr yazmalı.

Takıldınız ya da kodu bozdunuz; örneğin 5-store.ts bittikten sonra devam etmek için:

npm run catchup -- 5

// npm run catchup -- <n>
// Lost? This puts you exactly at the end of step n — without touching the code you wrote.
//   1. every TOGGLE block goes back to its default line (the one marked "// default")
//   2. data/ is emptied and the store is reset
//   3. steps 1..n run again
//   n = 0 is the start of the day: nothing is run, so `npm run question` asks the bare model again.
// Your own functions (the YOUR TURN exercises) are left as they are.

Yani: her TOGGLE bloğu varsayılan satırına döner. data/ boşalır, vector DB de her N için sıfırlanır. Chroma çalışmıyorsa catch-up bunu tek satırla söyler, sıfırlamayı atlar ve devam eder. Sonra 1’den N’ye kadar bütün adımlar çalışır. Sizin yazdığınız fonksiyonlara da, günün sorusunun defterine de dokunmaz. Embedding’ler .cache/ klasöründe saklı kaldığı için yeniden hesaplanmaz; catch-up hızlıdır.

Yalnızca vector DB’yi sıfırlayıp dokümanları yeniden yüklemek için: npm run ingest -- --reset.