# 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](docs/KULLANIM_KILAVUZU.md) · [çevrimdışı HTML](docs/kullanim_kilavuzu.html) · [Word](docs/Tablo2SQL-TR_Kullanim_Kilavuzu.docx) > > 📗 **User guide (with screenshots):** [English](docs/USER_GUIDE.md) · [offline HTML](docs/user_guide.html) · [Word](docs/Tablo2SQL-TR_User_Guide.docx) ``` 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 ```bash 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ı): ```bash 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//` — `genel_rapor_{tr,en}.{html,pdf}`, `testler/NN___/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: ```bash 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 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: ```bash 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ı): ```bash python scripts/llm_deneyi.py --saglayici claude --model --kuru # önce token tahmini python scripts/llm_deneyi.py --saglayici claude --model 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//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/.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.