Blame for DENEY_KILAVUZU.md

---
title: "Tablo2SQL-TR Deney Kılavuzu"
subtitle: "LLM deneylerini kendi bilgisayarında çalıştırmak için adım adım yönerge"
cover: "no"
---

# Bu kılavuz ne için?

Makaledeki sonuçlar şimdiye kadar yalnızca kural tabanlı motorla alındı. Bu kılavuzla aynı deneyleri **büyük dil modelleriyle (LLM)** çalıştıracaksın. İki deney var:

| Deney | Ne ölçer? | Çıktı klasörü |
|---|---|---|
| **1. Makale protokolü** | 99 soruluk ana test kümesi beş koşulda: döngü açık/kapalı, statik denetim kapalı, sayılar metin, İngilizce yerel ayar. Ardından pilot, stres kümesi ve ağır kümenin 200 soruluk hızlı alt kümesi. | `outputs/llm/<sağlayıcı>_<model>/` |
| **2. Gerçek belge pilotu** | 7 kurumdan 18 gerçek belge üzerinde 189 soru | `gercek_pilot/sonuclar/` |

Her iki deneyi de seçilen **her model için birer kez** çalıştıracaksın. Kodda hiçbir değişiklik yapma; ayrıntısı Bölüm 9'da.

**İki kurulum yolu var; birini seç:**

| | A. Sanal ortam (başlatıcı) | B. Docker |
|---|---|---|
| Kurulum | `baslat.bat`'a çift tıkla | Docker Desktop'u kur, `docker_baslat.bat`'a çift tıkla |
| Paket sürümleri | Başlatıcı uygun sürümleri kurar; küçük farklar olabilir | Makaledeki sonuçların alındığı sürümlerle **birebir aynı** |
| Kime uygun | Docker kullanmayanlara | Docker'ı zaten kullananlara; en güvenilir tekrar üretim |
| Bölümler | 3, 6, 7, 8 | 3B, 7B, 8B |

Deney komutları iki yolda da terminalden çalıştırılır (Bölüm 6). İki yolda da Bölüm 2 (dosyalar), 4 (model bağlantıları), 5 (model seçimi), 9 (kurallar) ve 10 (geri gönderim) aynıdır.

# 1. Gerekenler

- **Bilgisayar:** Windows 10/11, macOS ya da Linux. En az 8 GB RAM ve 3 GB boş disk.
- **Python 3.10, 3.11 ya da 3.12.** Yoksa başlatıcı kurmayı önerir. Windows'ta kurulum sırasında **"Add python.exe to PATH"** kutusunu işaretle.
- **İnternet bağlantısı:** Paket kurulumu ve bulut modelleri için gerekli.
- **B yolu için:** [Docker Desktop](https://www.docker.com/products/docker-desktop/). A yolunda gerekmez; B yolunda Python kurmak gerekmez.
- **API anahtarları ve kredi:**
  - Claude için: [console.anthropic.com](https://console.anthropic.com/settings/keys)
  - OpenAI için: [platform.openai.com](https://platform.openai.com/api-keys)
  - Hesaplarda kullanım kredisi tanımlı olmalı.
- **Yerel model için Ollama:** [ollama.com/download](https://ollama.com/download).
  - En az 8 GB belleği olan bir ekran kartı önerilir.
  - Ekran kartı yoksa çalışır ama deneyler çok uzun sürer (bir günden fazla olabilir).

# 2. Dosyaları yerleştir

Sana iki dosya gelecek:

1. **`tablo2sql.zip`:** Uygulama, test kümeleri ve betikler.
2. **`gercek_belgeler.zip`:** 18 gerçek belge (PDF, yaklaşık 115 MB).

Adımlar:

1. `tablo2sql.zip`'i kısa, boşluksuz ve Türkçe karaktersiz bir yola aç. Örneğin Windows'ta `C:\tablo2sql`, macOS'ta `~/tablo2sql`.
2. `gercek_belgeler.zip`'i **`tablo2sql/gercek_pilot/test_belgeler/`** klasörünün içine aç. Klasörde 18 PDF olmalı ve doğrudan bu klasörde durmalı, alt klasörde değil. Dosya adlarını değiştirme.

```
tablo2sql/
├── baslat.bat / baslat.command / baslat.sh
├── scripts/llm_deneyi.py              ← Deney 1
├── gercek_pilot/
│   ├── calistir.py                    ← Deney 2
│   ├── db_kur.py
│   └── test_belgeler/                 ← 18 PDF buraya
└── ...
```

# 3. Kurulum (A yolu: sanal ortam)

1. Başlatıcıya çift tıkla:
   - Windows: `baslat.bat`
   - macOS: `baslat.command`
   - Linux: terminalde `./baslat.sh`
2. İlk açılışta başlatıcı `.venv` adında bir sanal ortam kurar ve gerekli paketleri indirir. Bu 5–10 dakika sürebilir.
3. Kurulum bitince tarayıcıda uygulama açılır. Terminal penceresini kapatma; uygulama o pencere açık kaldıkça çalışır.

# 4. Model bağlantılarını kur

Uygulamada sağ üstteki **🔌 Bağlantılar** düğmesine bas.

- **Claude:** API anahtarını yapıştır ve **Kaydet ve senkronize et**'e bas. Kart *Bağlı · N model* olmalı.
- **OpenAI:** Aynı şekilde anahtarı yapıştır. Sunucu adresi alanını boş bırak.
- **Ollama:**
  1. Ollama uygulaması açık olmalı. Kart *Bağlı* görünmüyorsa Ollama'yı başlat ve **Modelleri senkronize et**'e bas.
  2. **Hangi Ollama modeli?** bölümünü aç, `qwen2.5-coder:7b`'yi seç ve **⬇️ Model indir**'e bas. Yaklaşık 4,7 GB indirilir.
  3. Hesaplama aygıtını **Otomatik** bırak.

Anahtarlar `tablo2sql/ayarlar/tablo2sql-ayarlar.json` dosyasına kaydedilir ve deney betikleri anahtarı oradan okur. **Bu dosyayı kimseyle paylaşma.** İçinde anahtarlar düz metin olarak durur.

# 5. Modelleri önceden seç ve not et

Hakemler, birkaç model deneyip yalnızca en iyisinin raporlanmasını kabul etmez. Bu yüzden **çalıştırmaya başlamadan önce** üç modeli seç ve aşağıdaki tabloya yaz. Sonra bu üçünün hepsini, sonuç ne çıkarsa çıksın, çalıştır.

| Rol | Sağlayıcı | Model kimliği |
|---|---|---|
| Güçlü bulut modeli | claude | ………………………… |
| İkinci bulut modeli | openai | ………………………… |
| Yerel model | ollama | qwen2.5-coder:7b |

**Model kimliği nasıl bulunur:** Model bağlantıları panelinde ilgili kartın **Modelleri göster** listesindeki `model` sütunundan aynen kopyala. Kimlik genelde tarih içerir, örneğin `claude-…-2025….`. Takma ad yerine tarihli sürüm varsa onu seç; böylece aynı model yeniden kullanılabilir. Komutlarda `<MODEL>` yazan yere bu kimliği koyacaksın.

# 6. Terminali aç

Komutlar `tablo2sql` klasöründe çalıştırılır.

- **Windows:**
  1. Dosya Gezgini'nde `tablo2sql` klasörünü aç.
  2. Üstteki adres çubuğuna `cmd` yaz ve Enter'a bas.
  3. Açılan pencerede bir kez şunu çalıştır: `set PYTHONUTF8=1`
  4. Python komutu: `.venv\Scripts\python`
- **macOS / Linux:**
  1. Terminalde `cd ~/tablo2sql` ile klasöre geç.
  2. Python komutu: `.venv/bin/python`

Aşağıdaki örnekler Windows içindir. macOS/Linux'ta `.venv\Scripts\python` yerine `.venv/bin/python` yaz, ters eğik çizgileri `/` yap.

# 7. Deney 1: Makale protokolü (A yolu)

Her model için önce maliyet tahminini al, sonra deneyi çalıştır:

```
.venv\Scripts\python scripts\llm_deneyi.py --saglayici claude --model <MODEL> --kuru
.venv\Scripts\python scripts\llm_deneyi.py --saglayici claude --model <MODEL>
```

- `--kuru` hiçbir istek göndermez. Yalnızca yaklaşık token sayısını yazar. Toplam yaklaşık 4–5 milyon giriş tokenı beklenir.
- İkinci komut bağlantıyı dener ("Bağlantı denemesi… tamam"), sonra sırasıyla şunları çalıştırır:
  1. Ana test kümesi, 5 koşulda.
  2. Pilot.
  3. Stres kümesi.
  4. Ağır küme hızlı alt kümesi.
- Süre bulut modellerinde birkaç saat sürebilir. Yerel model ekran kartıyla benzer, ekran kartı olmadan çok daha uzundur.
- Bitince ekrana bir özet basılır. Sonuçlar `outputs\llm\claude_<MODEL>\` klasörüne yazılır; en önemli dosyalar `rapor.md` ve `ozet.json`.

Diğer iki model için `--saglayici` değerini değiştir:

```
.venv\Scripts\python scripts\llm_deneyi.py --saglayici openai --model <MODEL>
.venv\Scripts\python scripts\llm_deneyi.py --saglayici ollama --model qwen2.5-coder:7b
```

# 8. Deney 2: Gerçek belge pilotu (A yolu)

Bu deney `gercek_pilot` klasöründe çalışır.

```
cd gercek_pilot
..\.venv\Scripts\python db_kur.py
..\.venv\Scripts\python calistir.py --arka-uc kural
```

1. **`db_kur.py`:** 18 belgenin her biri için bir veritabanı kurar. Yalnızca bir kez gerekir ve 20–40 dakika sürer.
2. **`calistir.py --arka-uc kural`:** Ortamın doğru kurulduğunu doğrulayan **kontrol çalıştırmasıdır.** Sonunda `"basari": 19.6` görmelisin; bu, raporladığımız sonuçla aynı. Farklı bir sayı çıkarsa LLM deneylerine geçme ve bize haber ver (Bölüm 10). Büyük olasılıkla bir paket sürümü farklıdır.
3. Ardından seçtiğin üç model:

```
..\.venv\Scripts\python calistir.py --arka-uc claude:<MODEL>
..\.venv\Scripts\python calistir.py --arka-uc openai:<MODEL>
..\.venv\Scripts\python calistir.py --arka-uc ollama:qwen2.5-coder:7b
```

- `--arka-uc` biçimi şöyle: `sağlayıcı:model-kimliği`. Ollama modelinin adında da `:` var; bu sorun değil.
- Her çalıştırma `gercek_pilot\sonuclar\sonuclar_<arka-uç>.json` dosyasını üretir.
- Önce bağlantıyı denemek istersen `--sinir 5` ekle. Yalnızca 5 soru çalışır. Bu deneme çalıştırmasının sonucu raporlanmaz.

# Docker ile (B yolu)

Bu yolda Python ve paketler bir Docker imajının içindedir. Proje klasörü konteynere bağlanır; ayarlar, veritabanları ve sonuçlar doğrudan bilgisayarındaki `tablo2sql` klasörüne yazılır. Böylece konteyner silinse de hiçbir şey kaybolmaz.

## 3B. Kurulum (bir kez)

1. [Docker Desktop](https://www.docker.com/products/docker-desktop/)'ı kur ve aç. Windows'ta WSL 2 seçeneğini kabul et.
2. Bölüm 2'deki gibi dosyaları yerleştir.
3. Başlatıcıya çift tıkla:
   - Windows: **`docker_baslat.bat`**
   - macOS: `docker_baslat.command`
   - Linux: terminalde `./docker_baslat.sh`

   Başlatıcı şu adımları sırayla yapar:
   1. Docker Desktop kapalıysa açar.
   2. İlk seferde imajı kurar. Bu 5–10 dakika sürer ve makaledeki sonuçların üretildiği paket sürümlerini (`requirements-docker.txt`) kullanır.
   3. Uygulamayı başlatır ve tarayıcıda **http://localhost:8501** adresini açar.

   Başlatıcının penceresini kapatabilirsin; uygulama arka planda çalışmaya devam eder.
4. Bölüm 4'teki gibi model bağlantılarını kur.

Aynı işleri terminalden de yapabilirsin: `docker compose build`, ardından `docker compose up -d uygulama`.

**Ollama hakkında:**
- Ollama'yı bilgisayarın kendisine kur, Docker'ın içine değil. Böylece ekran kartını doğrudan kullanır.
- Konteyner Ollama'ya `http://host.docker.internal:11434` adresiyle ulaşır. Ayar dosyası ilk kez Docker içinde oluşursa bu adres kendiliğinden yazılır.
- Daha önce A yoluyla uygulamayı açtıysan Ollama kartında **Sunucu adresini değiştir**'i aç ve bu adresi gir.

Uygulamayı kapatmak için **`docker_durdur.bat`**'a çift tıkla (konteyner silinmez, yalnızca durur) (macOS/Linux: `./docker_baslat.sh durdur`). Paketler güncellenirse imajı yeniden kurmak için: `docker_baslat.bat yeniden-kur`.

## 7B. Deney 1 (Docker ile)

```
docker compose run --rm deney scripts/llm_deneyi.py --saglayici claude --model <MODEL> --kuru
docker compose run --rm deney scripts/llm_deneyi.py --saglayici claude --model <MODEL>
docker compose run --rm deney scripts/llm_deneyi.py --saglayici openai --model <MODEL>
docker compose run --rm deney scripts/llm_deneyi.py --saglayici ollama --model qwen2.5-coder:7b
```

Sonuçlar bilgisayarındaki `tablo2sql/outputs/llm/` klasörüne yazılır.

## 8B. Deney 2 (Docker ile)

```
docker compose run --rm -w /app/gercek_pilot deney db_kur.py
docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc kural
docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc claude:<MODEL>
docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc openai:<MODEL>
docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc ollama:qwen2.5-coder:7b
```

Kontrol çalıştırmasında (`--arka-uc kural`) sonuç yine **%19,6** olmalı. Sonuçlar `tablo2sql/gercek_pilot/sonuclar/` klasörüne yazılır.

**Uzun çalıştırmalar için:** Terminal penceresini kapatırsan `docker compose run` da durur. Bilgisayarın uyku moduna girmemesine dikkat et.

# 9. Kurallar

1. **Koddaki hiçbir dosyayı değiştirme.**
   - `calistir.py` başlarken kodun dondurulduğu andaki parmak izini doğrular. Kod değişmişse "KOD DEĞİŞMİŞ, çalıştırma durduruldu" der ve çalışmaz.
   - Bu hatayı görürsen düzeltmeye çalışma; bize bildir.
2. **Her modeli bir kez çalıştır.**
   - Bir çalıştırma ağ hatası ya da elektrik kesintisi yüzünden yarıda kesilirse aynı komutu baştan çalıştır ve bunu not al.
   - Sonuç beğenilmediği için tekrar çalıştırma.
3. **Seçtiğin üç modelin hepsini raporla.** Sonucu kötü olan model de makalede yer alacak.
4. **Ayarları değiştirme.** Model sıcaklığı 0, deneme sayısı 3 ve hibrit geri düşme kapalı olarak betiklerde sabit.

# 10. Sonuçları geri gönder

Deneyler bitince şu klasörleri tek bir zip dosyasında topla:

- `tablo2sql\outputs\llm\` (Deney 1, tüm modeller)
- `tablo2sql\gercek_pilot\sonuclar\` (Deney 2, tüm modeller ve kontrol çalıştırması)
- `tablo2sql\gercek_pilot\db_test\kurulum_gunlugu.json`
- Model kimliklerini yazdığın tablo (Bölüm 5) ve varsa yarıda kesilen çalıştırma notları.

**Gönderme:** `ayarlar` klasörünü (API anahtarları) ve `.env` dosyasını gönderme.

# 11. Sorun giderme

| Belirti | Çözüm |
|---|---|
| `401` / "invalid x-api-key" / "Incorrect API key" | Anahtar yanlış ya da süresi dolmuş. Model bağlantıları'nda yeni anahtarı kaydet. |
| `429` / "rate limit" / "overloaded" | Sağlayıcının hız sınırı. 10–15 dakika bekleyip aynı komutu yeniden çalıştır. |
| "credit balance is too low" / "insufficient_quota" | Hesaba kredi yükle. |
| Ollama: "model not found" | Model indirilmemiş. Model bağlantıları → Ollama → Model indir. |
| Ollama: model açılmıyor ya da bellek hatası | Hesaplama aygıtını *Otomatik* yap ya da başka uygulamaları kapat. |
| "No module named t2s" | Komutu yanlış klasörde çalıştırdın. Deney 1 `tablo2sql` içinde, Deney 2 `tablo2sql\gercek_pilot` içinde çalışır. |
| Türkçe karakterlerde hata (`UnicodeEncodeError`) | Windows'ta önce `set PYTHONUTF8=1` çalıştır. |
| `db_kur.py` bir belgede hata verdi | O belgenin dosya adını kontrol et (Bölüm 2); hata mesajını not al ve gönder. |
| Docker: "Cannot connect to the Docker daemon" | Docker Desktop açık değil; aç ve bir dakika bekle. |
| Docker: Ollama kartı "Ulaşılamıyor" | Ollama bilgisayarda açık mı? Kart adresi `http://host.docker.internal:11434` olmalı. |
| Docker: 8501 portu dolu | `docker-compose.yml`'de `"8501:8501"` satırını `"8502:8501"` yap ve http://localhost:8502 adresini aç. |
| Kontrol çalıştırmasında %19,6'dan farklı sonuç | LLM deneylerine geçmeden önce terminal çıktısını gönder. A yolunda paketleri birebir sabitlemek için: `.venv\Scripts\python -m pip install -r requirements-docker.txt` (Python 3.13 gerekir) ya da B yolunu (Docker) kullan. |