|
Download KURULUM.md from SevdanurGenc/Text-to-SQL: direct link, hf CLI and curl.
- Browser
- Download file 18.3 kB
-
https://huggingface.co/SevdanurGenc/Text-to-SQL/resolve/main/KURULUM.md
- Command line
-
hf download hf://SevdanurGenc/Text-to-SQL/KURULUM.md
-
curl -L -o KURULUM.md https://huggingface.co/SevdanurGenc/Text-to-SQL/resolve/main/KURULUM.md
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](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/<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: | |
| ```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 <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 <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. | |