SevdanurGenc/Text-to-SQL

Tablo2SQL-TR ve TR-TabloSQL

Türkçe belgelerdeki tabloları sorgulanabilir bir bilgi tabanına dönüştüren uçtan uca sistem, test kümeleri ve LLM deney sonuçları.

Tablo2SQL-TR, PDF, HTML, CSV ve XLSX belgelerdeki tabloları çıkarır. Birleşik hücreleri ve çok satırlı başlıkları çözer. Türkçe sayı, tarih ve birim yazımlarını normalleştirir (1.234,56 → 1234.56, (1.200) → −1200, Ocak 2024 → 2024-01). Tabloları meta veriyle birlikte SQLite'a aktarır. Türkçe soruları kendini düzelten bir ajanla SQL'e çevirir. Cevap tablolarda yoksa uydurmak yerine bunu açıkça söyler.

Bu depoda üç şey bir arada:

1. Uygulama: kaynak kod, web arayüzü ve tek tıkla başlatıcılar.
2. Test kümeleri: 5 küme, 1.406 soru.
3. Deney sonuçları: kural tabanlı üretici ve 6 LLM için soru düzeyinde 5.012 kayıt.

English summary at the end.

Öne çıkan sonuçlar

Doğruluk, cevap düzeyinde ölçüldü. Her sistem aynı sorulara, aynı veritabanlarında cevap verdi.

Küme	Kural tabanlı	Claude Opus 5.5	GPT-6.1-sol	Qwen2.5-Coder-32B (yerel)
Stres (33 belge, 307 soru)	%42,7	%89,9	%76,9¹	%62,5
Ağır, hızlı alt küme (200 soru)	%14,5	%90,0	%83,0	%63,5
Gerçek belge pilotu (18 belge, 189 soru)	%19,6	%59,8	%62,4	%28,6
Sessiz yanlış, gerçek belgeler	%40,7	%2,6	%5,3	%9,5

¹ Bu çalıştırmada 34 soruda API hata döndürdü. Bu sorular dışarıda tutulursa sonuç %85,0.

• Yerel sayı biçimi bir ön koşul. TR-TabloSQL'de Türkçe normalizasyonla kural tabanlı üretici %92,9'a ulaşıyor. İngilizce yerel ayar varsayıldığında, kusursuz altın SQL sorgularının bile yalnızca %28,4'ü doğru sonuç veriyor ve hiçbir hata mesajı çıkmıyor.
• Güçlü LLM'lerle darboğaz tablo çıkarımına kayıyor. Gerçek belgelerde değeri veritabanına doğru okunamamış 32 sorudan her model yalnızca ikisini çözebildi. Bu sorular dışarıda tutulunca bulut modelleri %70,7–73,9'a çıkıyor.
• Denetim zinciri sessiz hataları yakalıyor. 159 bozuk sorguyla yapılan hata enjeksiyonunda hataların %92,5'i yakalandı ve hiç yanlış alarm üretilmedi.

Ekran görüntüleri

Belgeler: tablo çıkarma; birleşik hücreler mavi, Türkçe sayılar çözümlenmiş	Bilgi tabanı: aktarılan tablolar, meta veri, SQL konsolu ve dışa aktarma
Soru sor: cevap ve SQL; tablolarda olmayan bir varlık için gerekçeli red	Hata kataloğu: Türkçeye özgü hata tipleri, örnekler ve önlemler
Değerlendirme: modelleri test kümelerinde karşılaştırma, seviyelere göre doğruluk	Otomasyon: testleri ve modelleri seçip arka planda çalıştırma
Raporlar: geçmiş çalıştırmalar; raporları tek tek ya da ZIP olarak indirme	Genel rapor (HTML/PDF, TR/EN): aydınlık/karanlık tema
Test raporu: soru tipi, zorluk ve soru ailesine göre kırılım

Hızlı başlangıç

# Windows: baslat.bat (çift tık) · macOS: baslat.command · Linux:
bash baslat.sh

Başlatıcı şunları kendisi yapar:

• Gerekirse Python'u kurar.
• Bir sanal ortam oluşturur ve paketleri yükler.
• Tarayıcıda http://localhost:8501 adresini açar.

Uygulama LLM olmadan, kural tabanlı üreticiyle çalışır. Claude, OpenAI ya da yerel Ollama modelleri Bağlantılar düğmesinden eklenir.

Docker ile çalıştırmak için:

docker compose up -d        # durdurmak için: docker compose stop

Elle kurulum, tüm seçenekler ve deneyleri yeniden üretme adımları için KURULUM.md dosyasına bakın. Ekran görüntülü kullanım kılavuzları için: Türkçe · English.

Güvenlik: API anahtarları ayarlar/tablo2sql-ayarlar.json dosyasına düz metin olarak yazılır. Bu dosya pakette yoktur. Kendi kopyanızı paylaşmayın ve depoya yüklemeyin.

Test kümeleri

Küme	Belge	Soru	İçerik	Konum
TR-TabloSQL	6 sentetik (4 PDF, 2 HTML), 7 tablo	99 (64 geliştirme / 35 test)	Altın SQL; Spider/BIRD tiplerinden uyarlama; 11 cevapsız soru	benchmark/, data/
Pilot	3	44	Ana kümeden bilerek farklı düzenler	pilot/
Stres	33 (11 tür × 3)	307 (39 cevapsız)	Izgara, yalnız yatay çizgi, çizgisiz PDF ve HTML	stres_kumesi/
Ağır	52, tek veritabanında	767 (200'lük hızlı alt küme)	L1–L5 seviyeleri; %20'si İngilizce, Türkçe karaktersiz ya da yazım hatalı	agir_kume/
Gerçek belge pilotu	7 kurumdan 18 gerçek PDF	189 (19 cevapsız)	Bağımsız yazılmış ve denetlenmiş sorular	gercek_pilot/

Sentetik belgeler tohumlanmış rastgele sayılarla üretilir. Gerçek kurum verisi içermezler, ama Türk kamu belgelerinin düzenini ve yazım kurallarını taklit ederler. Belgeleri yeniden üreten betikler her klasördedir.

Gerçek belgeler bu pakette yoktur, çünkü belgelerin hakları ilgili kurumlara aittir. Belgeler kurumların internet sitelerinden indirilmeli:

• Kaynakların listesi gercek_pilot/README.md dosyasında.
• İndirilen dosyaların doğru sürüm olduğu SHA-256 özetleriyle denetlenebilir. Komut gercek_pilot klasöründen çalıştırılır: sha256sum -c belgeler.sha256.

Kod deneylerden önce donduruldu. Dosyaların SHA-256 özetleri kod_parmak_izi.txt dosyalarında; çalıştırma betikleri bu özetleri kontrol eder.

Hugging Face veri görüntüleyicisi (veri/)

Soru kümeleri ve sonuçlar, veri görüntüleyicide açılabilsin diye düz JSONL olarak da verildi:

from datasets import load_dataset
gercek = load_dataset("<kullanıcı>/tr-tablosql", "gercek", split="train")
sonuc  = load_dataset("<kullanıcı>/tr-tablosql", "sonuclar", split="train")

Yapılandırma	Satır	Alanlar
tr_tablosql	99	id, bolum, soru, altin_sql, cevaplanabilir, zorluk, kategoriler, kanit, tablolar
pilot, stres, agir, gercek	44 / 307 / 767 / 189	id, belge, soru, tip, cevap_json, aile, zorluk ve kümeye özgü alanlar (seviye, dil, cizim, sayfa, tablo …)
sonuclar	5.012	kume, model, calistirma, id, dogru, durum, bulunan, beklenen_json, sql

Cevaplar farklı tiplerde olabilir (sayı, metin ya da liste). Bu yüzden JSON metni olarak saklandılar: json.loads(r["cevap_json"]).

Deney sonuçları (sonuclar_llm/)

Klasör	İçerik
20261026-021813/	26.10.2026 çalıştırması: her test için rastgele seçilen üst kademe model. TR-TabloSQL'de GPT-5.2, pilotta Claude Opus 5.5, stresde GPT-6.1-sol, ağır hızlı alt kümede Claude Opus 4.5, ağır tam kümede GPT-5.
20261027-043315/	27.10.2026 çalıştırması: stres, ağır hızlı alt küme ve gerçek belge kümelerinin her biri üç modelle. 4 sa 51 dk sürdü.
kural_tabanli/	Kural tabanlı üreticinin aynı kümelerdeki sonuçları.
analiz.py, llm_analiz.json, gercek_kirilim.json	Güven aralıkları, McNemar testleri ve gerçek belgelerde belge türüne göre kırılım.

Her test klasöründe soru başına SQL, cevap ve hakem kararı (sonuclar.json, ozet_normal.json) ile Türkçe ve İngilizce HTML/PDF raporlar bulunur.

Bulut modelleri sağlayıcı API'leriyle çalıştırıldı. API'ler sıcaklık parametresini kabul etmediği için sağlayıcının varsayılan ayarı kullanıldı; bu nedenle sonuçlar soru düzeyinde küçük farklarla değişebilir. Yerel model Ollama ile, sıcaklık 0'da çalıştırıldı.

Klasör yapısı

app.py, arayuz_tema.py   web arayüzü (Streamlit)
t2s/                     çıkarma, normalizasyon, ajan, denetim zinciri, LLM istemcileri
otomasyon/               arka planda çoklu test/model çalıştırma ve rapor üretimi
benchmark/, data/        TR-TabloSQL soruları, sentetik belgeler, doğru içerik dosyaları
pilot/, stres_kumesi/, agir_kume/, gercek_pilot/   diğer test kümeleri ve raporları
veri/                    Hugging Face görüntüleyicisi için JSONL dosyaları
sonuclar_llm/            LLM ve kural tabanlı deneylerin ham sonuçları
outputs/                 TR-TabloSQL, ablasyon ve hata enjeksiyonu çıktıları
scripts/, tests/         yardımcı betikler ve testler (pytest)
docs/                    kullanım kılavuzları ve ekran görüntüleri

Lisans

• Kod: MIT.
• Test kümeleri ve sonuçlar: CC BY 4.0.

Ayrıntılar LICENSE dosyasında. Gerçek belgelerin hakları ilgili kurumlara aittir.

Atıf

Makale değerlendirme sürecindedir. Atıf bilgisi yayımlandıktan sonra eklenecektir.

---

English summary

Tablo2SQL-TR is an end-to-end system for question answering over tables in Turkish documents. It:

• extracts tables from PDF, HTML, CSV and XLSX files and resolves merged cells and multi-row headers;
• normalises Turkish number, date and unit notations;
• loads the tables with metadata into SQLite;
• answers Turkish or English questions with a self-correcting Text-to-SQL agent that abstains when the answer is not in the tables.

This repository contains:

• the code and web app;
• five benchmarks with 1,406 questions in total: TR-TabloSQL, pilot, stress, heavy, and an 18-document real-world pilot. Real PDFs are not redistributed; sources and SHA-256 hashes are given.
• question-level results of a rule-based generator and six LLMs (5,012 records).

The main findings:

• Locale-aware normalisation is a prerequisite. Under an English-locale assumption, even gold SQL returns correct results for only 28.4% of questions, with no error raised.
• With strong LLMs (Claude Opus 5.5 reaches 89.9–90.0% on synthetic sets and 59.8% on real documents; GPT-6.1-sol 62.4% on real documents), the bottleneck shifts from SQL generation to table extraction.

Quick start: bash baslat.sh (or baslat.bat / baslat.command), or docker compose up -d. The interface is available in English via the TR/EN switch. See docs/USER_GUIDE.md.