Hugging Face's logo

SevdanurGenc
/
Text-to-SQL

Turkish
English
text-to-sql
turkish
table-extraction
pdf
benchmark
llm-evaluation
Model card Files
xet
 Community
Text-to-SQL / KURULUM.md
SevdanurGenc's picture
SevdanurGenc
Upload 466 files
a72d1cf verified
preview code
|
Raw History Blame Contribute Delete
18.3 kB

Tablo2SQL-TR — Kurulum ve ayrıntılı kullanım

Dokümanlardaki Tabloların Yapılandırılmış Bilgi Tabanına Dönüştürülmesi ve Doğal Dille Sorgulanması (Text-to-SQL)

PDF / HTML / CSV / XLSX belgelerindeki tabloları çıkarır, birleşik hücreleri ve çok satırlı başlıkları çözer, Türkçe sayı/tarih/birim normalizasyonuyla SQLite'a aktarır ve Türkçe soruları kendini düzelten bir ajanla SQL'e çevirir. Cevap tablolarda yoksa bunu açıkça söyler.

📘 Kullanım kılavuzu (ekran görüntülü): Türkçe · çevrimdışı HTML · Word

📗 User guide (with screenshots): English · offline HTML · Word

Belge (PDF/HTML) ─► Çıkarım (pdfplumber · Camelot · BeautifulSoup)
                    └► Çözümleme: rowspan/colspan, çok satırlı başlık, başlık/açıklama satırı ayıklama
                       └► Normalizasyon: '1.234,56'→1234.56 · '(1.200)'→-1200 · '%4,5'→4.5
                          'Ocak 2024'→'2024-01' · birim ('bin TL', 'bin MWh') · 'Toplam' satırı bayrağı
                          └► SQLite + meta tablolar (_tablolar, _sutunlar)
Soru (TR) ─► Ajan: şema bağlama → SQL üretimi (LLM veya kural tabanlı) → statik denetim
             → yürütme → sonuç denetimi → hata tipiyle geri besleme (≤N deneme) → Türkçe cevap / "cevap yok"

Hızlı başlangıç (tek tık)

Zip'i bir klasöre çıkarın ve işletim sisteminize uygun başlatıcıyı çalıştırın:

Sistem Çalıştırın Masaüstü kısayolu
Windows 10/11 baslat.bat (çift tık) kisayol_olustur.bat
macOS baslat.command (ilk seferde sağ tık › Aç) kisayol_olustur.command → Masaüstü'nde Tablo2SQL.app
Linux bash baslat.sh bash kisayol_olustur.sh → uygulama menüsü + masaüstü

Başlatıcı şunları kendiliğinden yapar:

  1. Python ≥ 3.10'u arar (py başlatıcısı, PATH, Homebrew, python.org kurulumları, uv). Bulamazsa izin isteyerek kurar:
    • Windows: winget → yoksa python.org kurulum dosyasını indirip sessizce kullanıcı hesabına kurar
    • macOS: Homebrew → yoksa uv (yönetici izni gerekmez) → yoksa python.org paketini indirip açar
    • Linux: apt / dnf / pacman / zypper / apk (sudo) → yoksa uv (yönetici izni gerekmez)
    • Hiçbiri olmazsa ne yapılacağını adım adım yazar ve indirme sayfasını açar
  2. Proje içinde sanal ortam (.venv) kurar; Debian/Ubuntu'da eksik python3-venv paketini önerir. Klasör taşındığı için bozulmuş bir .venv'i fark edip yeniden oluşturur.
  3. Paketleri requirements.txt'den kurar (dosya değişmedikçe tekrar kurmaz) ve tek tek içe aktararak doğrular.
  4. İsteğe bağlı bileşenler için öneri verir: LLM API anahtarı, Ollama (kurulu/çalışıyor mu, model var mı).
  5. Örnek belgeler eksikse üretir, boş bir port bulur (8501'den başlayarak), arayüzü başlatır, hazır olunca tarayıcıyı açar. Uygulama zaten çalışıyorsa yenisini başlatmaz, mevcut sayfayı açar.
  6. İlk çalıştırmada masaüstü kısayolu oluşturmayı önerir.

Ek seçenekler (her üç başlatıcıda aynı): --kontrol (yalnızca denetle), --sifirla (.venv'i silip yeniden kur), --port 8600, --tarayici-yok, --kisayol. Arayüz günlüğü: outputs/arayuz.log.

Güvenlik uyarıları: İnternetten indirilen betikler için Windows SmartScreen "Windows bilgisayarınızı korudu" derse Ek bilgi › Yine de çalıştır; macOS "geliştirici doğrulanamadı" derse sağ tık › Aç (veya Sistem Ayarları › Gizlilik ve Güvenlik › Yine de Aç). Kısayol oluşturucu macOS'ta proje klasöründeki karantina işaretini kaldırır.

Elle kurulum ve çalıştırma 

python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

python scripts/run_all.py          # örnek belgeler → veritabanları → test kümesi → değerlendirme → rapor
streamlit run app.py               # arayüz: http://localhost:8501
pytest -q                          # 42 birim/entegrasyon testi

# Test edilen sürümler (Python 3.13): streamlit 1.65, pandas 3.0, camelot-py 2.0, pdfplumber 0.11, reportlab 5.0

LLM arka uçları (isteğe bağlı):

export ANTHROPIC_API_KEY=...       && python scripts/run_all.py --claude              # Claude
export OPENAI_API_KEY=...          && python scripts/run_all.py --openai gpt-4o-mini  # OpenAI uyumlu
ollama pull qwen2.5-coder:7b       && python scripts/run_all.py --ollama qwen2.5-coder:7b  # yerel, ücretsiz

Arayüzde varsayılan model sağ üstteki model menüsünden seçilir; anahtarlar Bağlantılar penceresinden girilir.

Arayüz

Sayfalar üstteki gezinme çubuğundadır (dar pencerede sığmayanlar "more" menüsüne, telefonda yan menüye geçer). Üst çubuğun sağında: varsayılan model ve ajan ayarları menüsü, 🔌 Bağlantılar, dil (TR / EN) ve tema (☀ / 🌙). Tercihler saklanır ve uygulama yeniden açıldığında korunur.

Sekme İçerik
① Belgeler & çıkarım Dosya yükle / örnek seç, çıkarıcı ve sayı kipi seç. Her tablo için ham ızgara (birleşik hücreler vurgulu), çözümlenmiş tablo, şema önizlemesi. AI açıksa: önerilen tablo adı, tablo özeti, sütun açıklamaları ve ayrıştırma uyarıları. Aktarım sonrası veritabanı hemen indirilebilir.
② Bilgi tabanı Tablolar ve meta veriler, veri görünümü, salt-okunur SQL konsolu. Veritabanını indir: SQLite (.db), Excel (.xlsx), CSV (.zip), SQL dökümü (.sql); tek tablo CSV/XLSX. AI açıksa tabloyu açıklama.
③ Soru sor Sohbet. Durum rozeti, SQL ve ajan adımları. AI açıksa: veritabanına özel örnek sorular, cümleleştirilmiş cevap, İngilizce soru desteği.
④ Hata kataloğu Hata tiplerinin tanımı/örneği/önlemi, kaydedilen hatalar. AI açıksa seçilen hatayı sade dille açıklama.
⑤ Değerlendirme Seçili arka uçla EX çalıştırma, soru bazında yanlışlar. AI açıksa başarısız örnekleri temalara ayıran analiz.
⑥ Otomasyon Seçilen testleri arka planda sırayla çalıştırır (tarayıcı kapansa da sürer). Önce tüm modelleri sınar; rastgele (üst model ağırlıklı), tek model ya da her model kipinde çalışır. Her test için Türkçe/İngilizce HTML ve PDF rapor + genel rapor; bitince bir kez uyarı penceresi. Ayrıntı: aşağıda Otomasyon.
⑦ Raporlar Geçmiş otomasyon çalıştırmaları: genel raporu sayfada görüntüleme, raporları tek tek ya da ZIP olarak indirme, çalıştırma silme.

Otomasyon (⑥ sekmesi)

Başında beklemeden çok sayıda testi çalıştırmak için.

  1. Testleri seç. Liste uygulamadaki tüm kümeleri (TR-TabloSQL ana küme, pilot, stres, ağır, ağır hızlı; PDF'ler varsa gerçek belge pilotu) ve dışarıdan eklenen testleri gösterir. Dışarıdan test ekle: belgeler (PDF/HTML/CSV/XLSX) + sorular.json ya da hepsi tek ZIP. Örnek sorular.json sekmeden indirilebilir; dış testler testler/ klasörüne kaydedilir.
  2. Model seçimi.
    • Rastgele: her test için çalışan modeller arasından seçer; üst kademe (ör. Opus/Fable, GPT-5/6, 30B+ yerel) modeller daha sık seçilir (üst model ağırlığı). Çok pahalı -pro ve sohbet dışı modeller varsayılan olarak havuz dışıdır.
    • Tek model: tüm testler aynı modelle.
    • Her model: her test seçilen her modelle (karşılaştırma için).
  3. Model sınaması. İş başlarken her model kısa bir ping ve küçük bir SQL göreviyle sınanır; cevap vermeyen ya da SQL yazamayan modeller kullanılmaz. Rastgele kipte bir model test sırasında çökerse (çağrıların yarısından fazlası hata) test başka bir modelle yeniden çalıştırılır.
  4. Seçenekler. Test başına soru sınırı (tohuma göre tekrarlanabilir örneklem), kendini düzeltme, deneme sayısı, rapor dilleri ve biçimleri.
  5. Başlat. İş ayrı bir süreçte çalışır; sayfada ve üst çubukta canlı ilerleme görünür, Durdur ile mevcut sorudan sonra durur. Bitince özetle bir uyarı penceresi açılır (sayfa o sırada kapalıysa bir sonraki açılışta, yalnızca bir kez). Hiçbir dosya kendiliğinden indirilmez.
  6. Raporlar sekmesi: geçmiş çalıştırmalar; genel raporu sayfada görüntüleme, raporları tek tek ya da hepsini ZIP olarak indirme.

Çıktılar: outputs/otomasyon/isler/<tarih-saat>/ — genel_rapor_{tr,en}.{html,pdf}, testler/NN_<test>__<model>/rapor_{tr,en}.{html,pdf} + sonuclar.json, model_sinamasi.json, gunluk.txt, tum_raporlar.zip. Otomasyon, deney için dondurulmuş t2s/ koduna dokunmaz; yalnızca onu kullanır.

Yapay zekâ (isteğe bağlı)

Sağlayıcı sağ üstteki model menüsünden seçilir: Kural tabanlı (AI kapalı), Claude, OpenAI / uyumlu, Ollama (yerel).

  • Model senkronizasyonu: Model listesi sağlayıcının API'sinden otomatik çekilir (Claude /v1/models, OpenAI /v1/models, Ollama /api/tags); model adını elle yazmak gerekmez. 🔄 düğmesi listeyi yeniler. Ollama'da model yoksa önerilen modeller arayüzden indirilebilir. Komut satırında --claude, --openai, --ollama model adı verilmeden kullanılırsa en yeni model otomatik seçilir.
  • Anahtarlar: .env.example dosyasını .env olarak kopyalayıp doldurun ya da arayüze yazın (arayüze yazılan anahtar yalnızca oturumda tutulur).
  • AI'nın kullanıldığı yerler: SQL üretimi ve kendini düzeltme · tablo adı/özet/sütun açıklaması önerisi · örnek soru önerisi · cevabı cümleleştirme · hata açıklaması · değerlendirme analizi · çok tablolu veritabanlarında şema seçimi. AI yalnızca öneri üretir; tablo çıkarma, sayı ayrıştırma ve denetimler deterministik kalır. AI çıktıları arayüzde “AI tarafından üretildi” notuyla işaretlenir.
  • Hibrit çalışma: AI'ya ulaşılamazsa soru otomatik olarak kural tabanlı üreticiyle yanıtlanır.
  • Önbellek ve kullanım: Aynı AI isteği tekrar ücretlendirilmez (outputs/.ai_onbellek.json); kenar çubuğunda çağrı ve belirteç sayısı gösterilir.
  • Test: tests/mock_llm_server.py, üç sağlayıcının API biçimini taklit eden sahte bir sunucudur (gerçek model değildir); entegrasyon testleri anahtar olmadan bununla çalışır.

Ekran görüntüleri: outputs/ekran/ (v2_* dosyaları sahte sunucuyla alınmıştır; cevaplardaki [MOCK] öneki bunu gösterir).

Çıktılar

Çıktı Yer
Tablo çıkarma ve dönüştürme hattı t2s/extract.py, t2s/schema.py, t2s/trnum.py, t2s/pipeline.py
Text-to-SQL modülü (ajan + LLM + kural tabanlı) t2s/agent.py, t2s/llm.py, t2s/rulebased.py
Hata kataloğu t2s/errors.py (tanımlar + çalışma zamanı sınıflandırıcı + değerlendirme teşhisi), outputs/hata_gunlugu.jsonl
Türkçe test kümesi (TR-TabloSQL, 99 soru) benchmark/tr_tablosoru.json, üretici: benchmark/build_benchmark.py
Karşılaştırmalı başarım raporu outputs/basarim_raporu.html, ham sonuçlar outputs/sonuclar/, outputs/ozet.json

Mevcut sonuçlar (LLM'siz çalıştırma)

Sistem EX Ayrılmış test EX Cevapsız sorularda doğru red
Kural tabanlı · TR normalizasyon %92,9 %88,6 %90,9
Kural tabanlı · naif İngilizce yerel ayar %29,3 %28,6 %90,9
Kural tabanlı · sayılar metin %13,1 %14,3 %90,9

Türkçe sayı biçimi etkisi: Doğru (altın) SQL sorguları, naif ayrıştırılmış veritabanlarında çalıştırıldığında cevapların %71,6'sı (en kipi) ve %80,7'si (metin kipi) bozuluyor. Ör. '1.346' → 1,346 (1000 kat hata), '4,5' → 45, SUM('1.234,56') → 1,234.

Tablo çıkarma: auto kipi 7 tablonun tamamında %100 hücre doğruluğu. pdfplumber ve Camelot-lattice çizgisiz tabloyu bulamıyor; Camelot-stream çizgili ve çok satırlı başlıklı tablolarda başlık yapısını bozuyor (ort. %71,9).

Docker ile çalıştırma

Makaledeki sonuçların üretildiği paket sürümleri requirements-docker.txt dosyasında sabitlenmiştir.

Windows'ta docker_baslat.bat'a çift tıklamak yeterli (macOS: docker_baslat.command, Linux: ./docker_baslat.sh); durdurmak için docker_durdur.bat (konteyneri yalnızca durdurur, silmez). Terminalden:

docker compose build                 # imajı bir kez kur
docker compose up -d uygulama        # arayüz: http://localhost:8501
docker compose run --rm deney scripts/llm_deneyi.py --saglayici claude --model <MODEL>
docker compose run --rm -w /app/gercek_pilot deney calistir.py --arka-uc kural

LLM deneylerinin adım adım yönergesi: DENEY_KILAVUZU.md (Word: Tablo2SQL-TR_Deney_Kilavuzu.docx).

Model bağlantıları (Ollama, OpenAI, Claude)

Üst çubuktaki 🔌 Bağlantılar düğmesi üç sağlayıcıyı tek yerde yönetir:

  • Ollama (yerel): sunucu adresi, bağlantı durumu, kurulu modeller, Text-to-SQL için önerilen modeller ve uygulama içinden indirme, hesaplama aygıtı (Otomatik / GPU / CPU).
  • OpenAI ve Claude (bulut): anahtarı yapıştırıp Kaydet ve senkronize et; model listesi API'den çekilir. Anahtar yalnızca maskeli gösterilir (sk-…F1cA). OpenAI için isteğe bağlı sunucu adresi (OpenAI uyumlu sunucular).
  • Model listeleri açılışta kendiliğinden yenilenir. Varsayılan model sağ üstteki model menüsünden, her sekmenin modeli o sekmenin başından seçilir.
  • Bütün ayarlar ayarlar/tablo2sql-ayarlar.json dosyasındadır (anahtarlar düz metin; paylaşmayın). Panelden indirilip başka bilgisayarda yüklenebilir.

LLM'leri ölçmek: ağır test kümesi

agir_kume/ klasöründe LLM'ler için hazırlanmış ağır bir küme var: 13 türde 52 kurgusal belge tek veritabanında, 767 soru, beş seviye (L1 değer okuma · L2 toplama/filtre · L3 çok adımlı hesap · L4 belgeler arası · L5 tuzak ve cevapsız) ve İngilizce, Türkçe karaktersiz ve yazım hatalı sorular. 200 soruluk tabakalı bir hızlı alt küme de vardır. Kural tabanlı motor bu kümede %13'te kalır; küme modeller arasındaki farkı görünür kılmak için tasarlandı. Ayrıntılar: agir_kume/README.md.

Arayüzde ⑤ Değerlendirme → Model karşılaştırma bölümü, seçilen modelleri aynı kümede yan yana çalıştırır ve seviye bazında doğruluk, cevapsızda red ve sessiz yanlış oranını gösterir. Komut satırından:

python pilot/pilot_calistir.py --kume agir_hizli --claude                # en yeni Claude modeli
python pilot/pilot_calistir.py --kume agir --openai gpt-4.1-mini --sinir 100
python pilot/pilot_calistir.py --kume agir --ollama qwen2.5-coder:7b --cihaz gpu

Makale protokolü (altın SQL'li kıyaslama + cevap düzeyindeki kümeler)

Makaledeki sonuçlar kural tabanlı üreticiyle alınmıştır. LLM'lerin başarımı için tek komutluk protokol (sabit model sürümü, sıcaklık 0, hibrit geri düşme kapalı):

python scripts/llm_deneyi.py --saglayici claude --model <sabit-model-sürümü> --kuru   # önce token tahmini
python scripts/llm_deneyi.py --saglayici claude --model <sabit-model-sürümü>
python scripts/llm_deneyi.py --saglayici ollama --model qwen2.5-coder:7b              # yerel, ücretsiz

Beş koşul çalışır: döngü açık (ana sonuç), döngü kapalı (K = 1), statik denetim kapalı, sayılar metin olarak saklanmış veritabanı ve İngilizce yerel ayarlı veritabanı. Ardından pilot, stres kümesi ve ağır kümenin hızlı alt kümesi cevap düzeyinde çalıştırılır. Sonuçlar, güven aralıkları ve McNemar karşılaştırmaları outputs/llm/<sağlayıcı_model>/rapor.md dosyasına yazılır.

Stres testi (görülmemiş belge düzenleri)

pilot/ klasöründe kurgusal üç belge ve 44 soruyla stres testi bulunur; gerçek belgeler aynı düzenekle değerlendirilebilir. Ayrıntılar: pilot/README.md ve pilot/PILOT_RAPORU.md.

Daha geniş küme stres_kumesi/ klasöründedir: 11 belge türünden 33 kurgusal belge (ızgara, yatay çizgili, çizgisiz PDF ve HTML) ve 307 soru. python stres_kumesi/uret.py --tekrar N ile istenen büyüklükte yeniden üretilebilir. Ayrıntılar: stres_kumesi/README.md ve stres_kumesi/STRES_RAPORU.md.

Dürüstlük notları

  • Örnek belgeler sentetiktir (gerçek kurum verisi değildir); gerçek Türk raporlarının yapısal zorluklarını taşıyacak şekilde tasarlandı. Gerçek belgeler için: PDF'leri data/docs/'a koyun veya arayüzden yükleyin.
  • Kural tabanlı sistem geliştirme bölümündeki 64 soru üzerinde ayarlandı; bu nedenle genelleme ölçüsü ayrılmış test bölümüdür (35 soru, geliştirmede hiç kullanılmadı).
  • Kural tabanlı üretici neredeyse hiç çalışma zamanı hatası yapmadığı için kendini düzeltmenin katkısı orada görünmüyor; döngü asıl olarak LLM arka uçları için tasarlandı. Bu ortamda API anahtarı olmadığından LLM yolu canlı modelle değil, betikli test arka ucuyla (tests/test_sistem.py: şema hatası, İ/I değer eşleme, toplam satırı) doğrulandı. Gerçek LLM sayıları için --claude/--openai/--ollama ile çalıştırın; rapor otomatik olarak karşılaştırmaya ekler.
  • Taranmış (görüntü) PDF'ler için OCR adımı yoktur (ör. ocrmypdf ile önce metin katmanı eklenebilir).

Test kümesini genişletme

  1. Belgeyi data/docs/'a koyun, data/ground_truth/<id>.json dosyasına doğru başlık ve gövdeyi yazın (biçim için mevcut dosyalara bakın; referans veritabanı buradan kurulur).
  2. benchmark/build_benchmark.py içindeki Q (geliştirme) veya QT (test) listesine (soru, altın_sql | None, zorluk, kategoriler, kanıt, uyarlama) ekleyin. Betik her altın SQL'i çalıştırıp doğrular.