| --- |
| 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. | |
|
|
