Text-to-SQL / DENEY_KILAVUZU.md

Upload 466 files

a72d1cf verified 8 days ago

14.6 kB

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. A yolunda gerekmez; B yolunda Python kurmak gerekmez.
API anahtarları ve kredi:
- Claude için: console.anthropic.com
- OpenAI için: platform.openai.com
- Hesaplarda kullanım kredisi tanımlı olmalı.
Yerel model için Ollama: 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:

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

Adımlar:

tablo2sql.zip'i kısa, boşluksuz ve Türkçe karaktersiz bir yola aç. Örneğin Windows'ta C:\tablo2sql, macOS'ta ~/tablo2sql.
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)

Başlatıcıya çift tıkla:
- Windows: baslat.bat
- macOS: baslat.command
- Linux: terminalde ./baslat.sh
İlk açılışta başlatıcı .venv adında bir sanal ortam kurar ve gerekli paketleri indirir. Bu 5–10 dakika sürebilir.
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

db_kur.py: 18 belgenin her biri için bir veritabanı kurar. Yalnızca bir kez gerekir ve 20–40 dakika sürer.
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.
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)

Docker Desktop'ı kur ve aç. Windows'ta WSL 2 seçeneğini kabul et.
Bölüm 2'deki gibi dosyaları yerleştir.
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.
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

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.
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.
Seçtiğin üç modelin hepsini raporla. Sonucu kötü olan model de makalede yer alacak.
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.