--- license: cc-by-4.0 language: - tr - en pretty_name: "TR-TabloSQL: Türkçe belge tablolarında Text-to-SQL" task_categories: - table-question-answering - question-answering tags: - text-to-sql - turkish - table-extraction - pdf - benchmark - llm-evaluation size_categories: - 1K **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`](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: ```python from datasets import load_dataset gercek = load_dataset("/tr-tablosql", "gercek", split="train") sonuc = load_dataset("/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](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](docs/USER_GUIDE.md).