--- 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/_/` | | **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 `` 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 --kuru .venv\Scripts\python scripts\llm_deneyi.py --saglayici claude --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_\` 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 .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: ..\.venv\Scripts\python calistir.py --arka-uc openai: ..\.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_.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 --kuru docker compose run --rm deney scripts/llm_deneyi.py --saglayici claude --model docker compose run --rm deney scripts/llm_deneyi.py --saglayici openai --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: docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc openai: 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. |