---
title: "Tablo2SQL-TR Kullanım Kılavuzu"
subtitle: "PDF'teki tablolara Türkçe soru sormanın en kısa yolu"
lang: tr
toc-title: "İçindekiler"
---
## Bu yazılım nedir, ne işe yarar?
**Tablo2SQL-TR**, Türkçe PDF ve HTML belgelerindeki tabloları okuyup düzenli bir veritabanına dönüştüren ve bu veritabanına **günlük Türkçeyle soru sormanızı** sağlayan, kendi bilgisayarınızda çalışan ve tarayıcıda açılan bir uygulamadır. SQL, Excel formülü ya da programlama bilmeniz gerekmez. Sorunuzu yazarsınız, cevabı tablodaki gerçek değerlerden alırsınız.
Kısaca: *raporların içinde kilitli kalan sayıları, sorulabilir bilgiye dönüştürür.*
### Neden böyle bir yazılıma ihtiyaç var?
Kamu kurumları, belediyeler ve şirketler bilgilerinin büyük kısmını PDF raporlarla yayımlar: faaliyet raporları, bütçe gerçekleşme tabloları, finansal tablolar, istatistik bültenleri, ücret tarifeleri. Bu belgelerdeki bilgiye ulaşmak bugün hâlâ büyük ölçüde elle yapılan bir iştir.
Bir örnek: Elinizde 80 sayfalık bir belediye faaliyet raporu var. Size sorulan soru basit: *"2024'te personel giderleri bütçesinin yüzde kaçı gerçekleşti?"* Cevap raporun bir yerindeki bir tabloda duruyor. Ama:
- Tabloda **birleşik başlık hücreleri** var ("2024" başlığının altında "Bütçe" ve "Gerçekleşme").
- Sayılar **Türkçe biçimde** yazılmış: `1.234.567,89`. İngilizce varsayımla çalışan araçlar bunu ya hiç okuyamaz ya da yanlış bir sayıya çevirir.
- Negatif değerler **parantez içinde**, yüzdeler `%4,5` biçiminde, tarihler `15.03.2025` biçiminde.
- Birim çoğu zaman yalnızca tablo başlığında yazar ("bin TL").
- En altta belgenin kendi **"Toplam" satırı** var. Habersiz yapılan bir toplama işlemi sonucu iki katına çıkarır.
Bunu Excel'e kopyalamayı deneyen herkes sonucu bilir: kaymış sütunlar, metin olarak kalmış sayılar, saatlerce düzeltme. Genel amaçlı yapay zekâ sohbet araçları ise bu tür sorulara çoğu zaman **emin görünen ama uydurulmuş sayılarla** cevap verir. Cevabın nereden geldiğini de göstermez.
Ölçtük: aynı tablolar Türkçe sayı biçimi dikkate alınmadan veritabanına aktarıldığında, sorgular kusursuz olsa bile cevapların yaklaşık dörtte üçü bozuluyor. Tablo2SQL-TR tam olarak bu boşluğu doldurmak için geliştirildi.
### Ne yapar?
Tablo2SQL-TR işi üç adıma indirir:
1. **Çıkar.** PDF/HTML belgelerdeki tabloları bulur, birleşik hücreleri ve çok satırlı başlıkları çözer.
2. **Aktar.** Türkçe sayı, tarih ve birimleri doğru tiplere çevirip tabloları bir SQLite veritabanına yazar. "Toplam" satırlarını işaretler, birimleri saklar.
3. **Sor.** Türkçe sorunuzu SQL'e çevirir, sonucu çalıştırır, hatalıysa kendini düzeltir. Cevap tablolarda yoksa uydurmaz; **"bu bilgi tablolarda yok"** der.
Oluşturulan veritabanını Excel, CSV, SQLite veya SQL dökümü olarak indirip başka araçlarda da kullanabilirsiniz.
### Kimler için?
- **Kamu ve belediye çalışanları:** faaliyet raporlarından, bütçe tablolarından hızlıca rakam çekmek için.
- **Finans ve denetim ekipleri:** şirket raporlarındaki gelir tablosu ve gider kalemleri üzerinde karşılaştırma yapmak için.
- **Gazeteciler ve araştırmacılar:** resmî istatistik bültenlerini sorgulanabilir veriye çevirmek için.
- **Analistler:** PDF tablolarını temiz bir Excel/CSV dosyasına dönüştürmek için. Soru sormasanız bile çıkarım ve dışa aktarma tek başına işe yarar.
- **Text-to-SQL üzerine çalışan akademisyenler:** Türkçe test kümesi, hata kataloğu ve değerlendirme araçlarıyla bir araştırma platformu olarak.
### Onu farklı kılan ne?
- **Türkçe biçimleri anlar.** `1.234,56`, `(12,5)`, `%3,4`, `Ocak 2024`, `İ/ı` harfleri ve "İzmir'in" gibi ekli adlar doğru işlenir.
- **Şeffaftır.** Her cevabın yanında üretilen SQL ve sistemin attığı her adım görünür. Cevabı kaynak tabloyla karşılaştırabilirsiniz.
- **Bilmediğini söyler.** Tablolarda olmayan bir bilgi sorulduğunda sayı uydurmak yerine açıkça reddeder ve nedenini söyler.
- **Hatalarını sınıflandırır.** Bir şey ters giderse hatanın türünü (tarih biçimi, birim, değer eşleme, hesap hatası…) belirler ve kendini buna göre düzeltir.
- **Yapay zekâ zorunlu değildir.** Kural tabanlı motor internet bağlantısı ve API anahtarı olmadan çalışır; test kümesinde %92,9 doğruluğa ulaşır. İsterseniz Claude, OpenAI ya da bilgisayarınızda çalışan Ollama'yı bağlayabilirsiniz.
- **Verileriniz sizde kalır.** Kural tabanlı modda ve Ollama ile hiçbir veri bilgisayarınızdan çıkmaz.
### Ne değildir?
- Taranmış (resim hâlindeki) belgeleri okuyamaz. Önce bir OCR aracıyla metin katmanı eklenmelidir.
- Belgeleri ya da veritabanını değiştirmez; yalnızca okur ve sorgular.
- Önemli kararlarda insan kontrolünün yerini almaz. Bu yüzden her cevabın nasıl üretildiğini açıkça gösterir.
### Bu kılavuz hakkında
Kılavuz uygulamayı ilk açılıştan ileri kullanıma kadar adım adım anlatıyor. Yapay zekâ (AI) olmadan da her şey çalışır. Claude, OpenAI ya da yerel Ollama bağladığınızda uygulamanın neredeyse her köşesi akıllanır.
> **Ekran görüntüleri hakkında:** AI'lı ekran görüntüleri, gerçek API'leri taklit eden bir test sunucusuyla alındı. Bu yüzden AI metinleri **`[MOCK]`** ile başlıyor. Gerçek bir modelle cümleler farklı (ve daha zengin) olacaktır.
---
## 1. Beş dakikada başlangıç
### Kurulum
Projeyi indirip klasörü açın. İşletim sisteminize uygun başlatıcıya çift tıklayın:
| Sistem | Dosya | Not |
|---|---|---|
| Windows | `baslat.bat` | SmartScreen uyarısında **Ek bilgi → Yine de çalıştır** |
| macOS | `baslat.command` | İlk seferde **sağ tık → Aç** (Gatekeeper) |
| Linux | `baslat.sh` | Gerekirse `chmod +x baslat.sh` |
Başlatıcı şunları kendisi halleder:
- Python 3.10+ var mı diye bakar. Yoksa kurmayı dener (winget / Homebrew / apt) ya da nereden indireceğinizi söyler.
- Bir sanal ortam (`.venv`) kurar, eksik paketleri yükler.
- Ollama ve API anahtarlarını denetleyip öneri verir. Bunlar zorunlu değildir.
- Boş bir port bulur (8501'den başlayarak) ve tarayıcıyı açar.
- İlk seferde masaüstü kısayolu oluşturmayı önerir. Sonradan `kisayol_olustur.*` dosyalarıyla da yapabilirsiniz.
İlk açılış paket kurulumu yüzünden birkaç dakika sürebilir. Sonraki açılışlar saniyeler içinde gerçekleşir.
### İlk bakış
Ekran iki parçadan oluşur:
- **Sol kenar çubuğu:** dil ve tema, yapay zekâ sağlayıcısı, ajan ayarları ve bilgi tabanı işlemleri.
- **Ana alan:** iş akışını izleyen beş sekme. ① Belgeler & çıkarım → ② Bilgi tabanı → ③ Soru sor → ④ Hata kataloğu → ⑤ Değerlendirme.
Uygulama altı **sentetik örnek belgeyle** gelir: belediye faaliyet raporu, il enerji tüketimi, şirket finansal raporu, su istatistikleri, fiyat endeksi bülteni ve ücret tarifesi. Bilgi tabanı bunlarla dolu başlar, yani hiçbir şey yüklemeden doğrudan ③ sekmesinde soru sorabilirsiniz.
---
## 2. Kenar çubuğu turu
**Dil / Tema.** Türkçe ⇄ English ve Aydınlık ⇄ Karanlık. Seçimleriniz hatırlanır.
**Yapay zekâ.** En üstte üç sağlayıcının durumu görünür (Ollama, OpenAI, Claude: *Bağlı · N model* ya da *Bağlı değil*). **🔌 Model bağlantıları** düğmesi bağlantı panelini açar (bkz. Bölüm 6). *Varsayılan model* listesinde kural tabanlı motorla birlikte bağlı sağlayıcıların senkronize edilmiş bütün modelleri bulunur. Seçtiğiniz model, kendi seçimi olmayan her sekmede kullanılır. Altındaki rozet AI'nın açık mı kapalı mı olduğunu ve oturumdaki kullanım sayacını gösterir. "AI kullanılan yerler" kutusu, AI'nın uygulamada nelere dokunduğunu listeler.
**Ajan.**
- *Kendini düzeltme döngüsü:* hatalı SQL'i otomatik onarır.
- *En fazla deneme:* varsayılan 3.
- *Cevabı AI ile cümleleştir:* sonucu doğal bir cümleye çevirir.
- *AI hata verirse kural tabanlıya geç:* ağ ya da kota sorununda bile cevap almanızı sağlar.
Son iki anahtar yalnızca bir AI sağlayıcı seçiliyken etkindir.
**Bilgi tabanı.** Kaç tablo olduğu ve veritabanı dosyasının yeri görünür. *Örneklerle sıfırla*, *Boşalt* ve dört biçimde indirme düğmeleri buradadır.
---
## 3. Adım ①: Belgeyi yükle, tabloları çıkar
1. **PDF, HTML, CSV veya XLSX** dosyanızı sürükleyip bırakın ya da örnek belgelerden birini seçin.
2. **PDF çıkarıcı** seçin:
- `auto` *(önerilen)*: önce pdfplumber ile çizgili tabloları dener, bulamazsa Camelot-stream'e geçer.
- `pdfplumber`: çizgili tablolar.
- `camelot-lattice`: çizgili tablolar, alternatif.
- `camelot-stream`: çizgisiz, boşlukla hizalanmış tablolar.
3. **Sayı ayrıştırma** kipini seçin:
- `tr` *(doğru olan)*: `1.234,56 → 1234.56`, `(12,5) → −12.5`, `%3,4 → 3.4`.
- `en`: sayıları İngilizce biçim varsayar. Karşılaştırma için.
- `text`: sayıları metin olarak bırakır. Karşılaştırma için.
4. **🔍 Tabloları çıkar**'a basın.
Her tablo için açılan kutuda **ham ızgarayı** görürsünüz. Birleşik hücreler renkle vurgulanır, yanında çözümlenmiş başlıklar, her sütunun tipi ve birimi, oluşacak şema yer alır:
Bu ekranda nelere dikkat etmeli?
- **Başlık satırları:** "2023 / 2024" gibi iki katlı başlıklar `butce_2024`, `gerceklesme_2024` gibi tek sütun adlarına dönüştürülür.
- **Birim:** "(bin TL)" gibi ifadeler tablo başlığından ya da sütun başlığından okunur ve sütuna yazılır.
- **Toplam satırı:** belgenin kendi "Toplam" satırı silinmez, `toplam_satiri = 1` ile işaretlenir. Böylece `SUM()` çift saymaz.
- **Ayrıştırılamayan değerler:** sayı olması gerekip okunamayan hücreler uyarı olarak listelenir.
Her şey yolundaysa **⬇️ Tümünü veritabanına aktar**'a basın. Aynı belgeyi ikinci kez aktarırsanız eski kopyası silinip yenisi yazılır, yani tablolar çoğalmaz.
---
## 4. Adım ②: Bilgi tabanı ve indirme
Bu sekmede veritabanındaki her tablonun kaynağını, sütunlarını, tiplerini, birimlerini ve verisini görürsünüz. Modele gönderilen şema açıklaması da buradadır. AI etkinse buna tablo özeti ve sütun açıklamaları eklenir.
SQL biliyorsanız **SQL konsolu (salt okunur)** ile kendi `SELECT` sorgularınızı da çalıştırabilirsiniz. Konsol veritabanını değiştiren hiçbir komutu kabul etmez.
**Veritabanını indirme.** İşini bitirdiğiniz bilgi tabanını dört biçimde dışarı alabilirsiniz:
| Biçim | Ne zaman? |
|---|---|
| **SQLite (.db)** | DB Browser, DBeaver, Python veya R ile çalışmak için. Meta tablolar (`_tablolar`, `_sutunlar`) dahil. |
| **Excel (.xlsx)** | Her tablo ayrı bir sayfada. Sayılar gerçek sayı olarak gelir, metin değil. |
| **CSV (.zip)** | Her tablo bir CSV. UTF-8 BOM ile kaydedilir, Excel'de Türkçe karakterler bozulmaz. |
| **SQL dökümü (.sql)** | Başka bir veritabanına yüklemek ya da sürüm kontrolüne koymak için. |
> **İpucu:** Excel'de `1.234,56` gibi görünen bir değer aslında `1234.56` sayısıdır. Türkçe bölge ayarlarında Excel onu doğru gösterir. Toplama ve formüllerde sorun çıkmaz.
---
## 5. Adım ③: Soru sorun
③ sekmesine geçip sorunuzu yazın. Örnek:
> *İzmir'in 2024 elektrik tüketimi ne kadar?*
Her cevabın üstünde küçük rozetler vardır: **durum** (cevaplandı / cevapsız), **deneme sayısı**, **kullanılan motor** ve **süre**. Altında üretilen SQL görünür. **Ajan adımları** kutusunu açtığınızda sistemin ne yaptığını adım adım izlersiniz:
1. 🧭 **Şema bağlama:** soruyla ilgili tablolar seçilir.
2. ✍️ **Deneme N: aday SQL:** SQL üretilir.
3. 🔎 **Statik denetim:** SQL çalıştırılmadan önce tipik hatalar aranır. Örneğin `'15.03.2025'` gibi Türkçe bir tarih, `'1.234,56'` gibi bir sayı ya da şemada olmayan bir sütun.
4. ▶️ **Yürütme:** SQL salt-okunur bağlantıyla çalıştırılır. Veritabanınız asla değişmez.
5. 🔁 **Geri besleme:** hata varsa türü ve çözüm önerisi bir sonraki denemeye verilir.
6. ✅ **Sonuç** veya 🚫 **Cevapsız.**
### "Bu bilgi tablolarda yok"
Bu sistemin en önemli özelliği belki de *bilmediğini söylemesi*. Örnek belgelerde Mersin yok:
Sistem sorudaki değeri ("Mersin") veritabanında arar. Bulamazsa ya da sorgu boş dönerse **sayı uydurmaz**, nedenini de söyleyerek reddeder. Test kümesindeki cevapsız soruların %90,9'unu doğru reddeder. Cevaplanabilir sorularda yanlış alarm oranı ise %5,7'dir.
### İyi soru sormanın püf noktaları
- **Tabloda geçen adları kullanın.** "İzmir", "Personel Giderleri", "2024" gibi.
- **Dönem belirtin.** "2024'te …" sorusu "son yıl …" sorusundan daha güvenilir sonuç verir.
- **Sayıları ve tarihleri Türkçe yazabilirsiniz.** `15.03.2025` ya da `1.250` sorun değil. Sistem bunları kendisi çevirir.
- **Hesap sorabilirsiniz.** Toplam, ortalama, en yüksek/en düşük, yüzde değişim, oran ("… kişi başına …").
- **Kural tabanlı motor yalnızca Türkçe soruları anlar.** İngilizce soru sormak isterseniz bir AI sağlayıcı açın.
---
## 6. Yapay zekâyı açmak
AI olmadan da uygulama tam çalışır. Kural tabanlı motor test kümesinde %92,9 doğruluğa ulaşır. AI'yı açmak ise şunları getirir:
- Serbest ve dolaylı soruları anlamak ("hangi ilçede su aboneleri en çok arttı?")
- İngilizce soru sorabilmek
- Cevapları doğal cümlelere çevirmek
- Uygulamanın her yerinde akıllı öneriler
### Model bağlantıları paneli
Kenar çubuğundaki **🔌 Model bağlantıları** düğmesi, üç sağlayıcıyı tek yerde yöneten paneli açar:
| Sağlayıcı | Gerekli | Veri nereye gider? | Maliyet |
|---|---|---|---|
| **Ollama** (yerel) | Ollama kurulu ve çalışıyor | **Bilgisayarınızdan çıkmaz** | Ücretsiz |
| **OpenAI** (bulut) | API anahtarı (+ isteğe bağlı sunucu adresi) | OpenAI ya da seçtiğiniz OpenAI uyumlu sunucu (OpenRouter, vLLM, LM Studio…) | Kullanım başına |
| **Claude** (bulut) | API anahtarı | Anthropic API | Kullanım başına |
**Bulut sağlayıcıyı bağlamak.** Anahtarı *API anahtarı* kutusuna yapıştırıp **Kaydet ve senkronize et**'e basın. Uygulama anahtarı kaydeder ve sağlayıcının API'sinden kullanılabilir modelleri hemen çeker. Kart *Bağlı · N model* olur ve kayıtlı anahtarın yalnızca maskelenmiş hâli görünür (ör. `sk-…F1cA`). *Anahtar al ↗* bağlantısı sağlayıcının anahtar sayfasını açar. OpenAI uyumlu başka bir sunucu kullanacaksanız *Sunucu adresi (isteğe bağlı)* alanına adresini yazın. **Bağlantıyı kes** anahtarı ve model listesini siler; o sağlayıcıya ait model seçimleri kural tabanlı motora döner.
**Model listesi kendiliğinden güncellenir.** Model adını hiçbir yerde elle yazmazsınız. Uygulama her açılışta bağlı sağlayıcıları denetler; liste boşsa ya da 12 saatten eskiyse yeniden senkronize eder. İsterseniz **Modelleri senkronize et** ile hemen yenileyebilirsiniz. *Modelleri göster* listesi o an kullanılabilen modelleri gösterir.
- **Claude:** liste en yeniden eskiye sıralanır.
- **OpenAI:** resmî uç noktada yalnızca sohbet modelleri listelenir. Gömme, ses ve görüntü modelleri ayıklanır.
- **Ollama:** bilgisayarınızda kurulu modeller, boyut ve niceleme bilgisiyle listelenir.
Ardından kenar çubuğundaki **🔌 Bağlantıyı test et** ile tek küçük bir istek göndererek her şeyin çalıştığını doğrulayabilirsiniz.
**Her sekmede ayrı model.** Her sekmenin başında *Bu sekmedeki model* seçicisi vardır. Varsayılan olarak kenar çubuğundaki model kullanılır; örneğin tablo önerileri için hızlı ve ucuz bir model, soru sormak için daha güçlü bir model seçebilirsiniz.
**Ayar dosyası.** Bütün ayarlar (API anahtarları, Ollama adresi ve aygıtı, dil, tema, model ve sekme seçimleri) uygulama klasöründeki `ayarlar/tablo2sql-ayarlar.json` dosyasında tutulur. Başka bir bilgisayara taşımak için dosyayı oradaki uygulama klasöründe aynı yere kopyalayın ya da paneldeki **Ayar dosyasını indir** ve **Ayar dosyası yükle…** düğmelerini kullanın. Dosya anahtarlarınızı düz metin olarak içerir: paylaşmayın, e-postayla göndermeyin. Anahtarı bu dosya yerine `.env` dosyasına (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) yazarsanız uygulama onu da okur; kartta "(ortam değişkeni)" notu görünür.
### Ollama: tamamen yerel ve ücretsiz
1. [ollama.com](https://ollama.com) adresinden Ollama'yı kurun ve çalıştırın. Uygulama `http://localhost:11434` adresini kendiliğinden dener; farklı bir adres için *Sunucu adresini değiştir*'i kullanın.
2. Hiç modeliniz yoksa **Hangi Ollama modeli?** bölümünü açın. Text-to-SQL için önerilen modeller boyut ve bellek gereksinimleriyle listelenir; kurulu olanların yanında ✓ vardır. Birini seçip **⬇️ Model indir**'e basın. İlerleme çubuğu uygulamanın içinde görünür, terminale gerek yoktur.
3. **Hesaplama aygıtını** seçin:
- *Otomatik* (önerilen): Ollama karar verir; ekran kartına sığmayan kısım CPU'da çalışır.
- *GPU*: modelin tüm katmanları ekran kartına yüklenir. Bellek yetmezse model açılmayabilir.
- *CPU*: ekran kartı kullanılmaz; yavaştır ama her bilgisayarda çalışır.
Bu seçim varsayılandır; Değerlendirme sekmesinde her çalıştırma için ayrıca değiştirilebilir. Bulut modellerini etkilemez.
> **Hangi modeli seçmeli?** Başlangıç için `qwen2.5-coder:7b` (yaklaşık 4,7 GB, 8 GB bellekte çalışır). Ekran kartınızda 16 GB varsa `qwen2.5-coder:14b` ya da `gpt-oss:20b` belirgin biçimde daha isabetlidir. Türkçe ağırlıklı serbest sorular için `gemma3:12b` ya da `qwen3:8b` denenebilir. Hangisinin sizin belgelerinizde daha iyi olduğunu Değerlendirme sekmesindeki **Model karşılaştırma** ile ölçebilirsiniz (Bölüm 8).
### AI açıkken neler değişir?
Kenar çubuğundaki "AI kullanılan yerler" kutusunun özeti:
**① Çıkarım: AI önerileri.** Her tablo için:
- kısa ve anlamlı bir ad (ör. `il_elektrik_tuketimi`)
- bir-iki cümlelik özet
- sütun açıklamaları ve birim önerileri
- ayrıştırmada şüpheli durumlar için uyarılar
Önerileri **uygulamak isteğe bağlıdır.** Bunu "AI önerilerini aktarırken uygula" anahtarı belirler. Deterministik çıkarım her zaman birincil kaynaktır. Uygulanan özet ve açıklamalar şemaya eklenir, bu da SQL üretimine doğrudan yardım eder.
**③ Soru sor: soru önerileri.** AI, veritabanınızdaki gerçek değerleri kullanarak sorulabilecek soruları önerir. Bir öneriye tıklamak soruyu doğrudan sorar. Yeni öneriler için yanındaki yenile düğmesini kullanın.
**③ Soru sor: kendini düzelten SQL.** Aşağıdaki örnekte model ilk denemede tarihi Türkçe yazdı (`'15.03.2025'`). Statik denetim bunu **TARIH_BICIMI** hatası olarak yakaladı ve "tarihler ISO biçiminde saklanır" önerisini geri besledi. İkinci denemede sorgu doğru çalıştı:
Diğer AI özellikleri:
- **Cevabı cümleleştirme:** "Cevap: 1.048,33 TL" yerine tam bir cümle. Sayılar seçili dilin biçiminde yazılır.
- **Şema daraltma:** veritabanında çok tablo varsa AI, soruyla ilgili olanları seçer.
- **④ Hata kataloğu:** hataları teknik olmayan bir dille açıklar (aşağıda).
- **⑤ Değerlendirme:** başarısız örnekleri temalara ayırır.
- **Kural tabanlıya geri düşme:** AI yanıt vermezse (ağ, kota, hatalı anahtar) soru kural tabanlı motorla cevaplanır. Bu durum ajan adımlarında "geri düşme" olarak görünür.
**Maliyet kontrolü.** Kenar çubuğundaki sayaç, oturumda yapılan istek ve token sayısını gösterir. AI yanıtları diskte önbelleğe alınır. Aynı tablo ya da hata için ikinci kez ödeme yapmazsınız.
### Gizlilik: AI'a ne gönderiliyor?
Bulut sağlayıcı (Claude/OpenAI) seçtiğinizde aşağıdaki veriler o sağlayıcıya gider:
| Özellik | Gönderilen |
|---|---|
| SQL üretimi | Soru + şema: tablo/sütun adları, açıklamalar, metin sütunu başına en çok 25 farklı değer ve örnek değerler |
| Tablo önerileri | Tablo başlığı, sütun bilgileri, **ilk 5 satır** |
| Cevap cümleleştirme | Soru, SQL ve sonucun ilk 20 satırı |
| Hata açıklama | Hata kaydı: soru, SQL, hata mesajı |
| Değerlendirme analizi | Başarısız örneklerin soru/SQL/cevap bilgisi |
Gizli belgelerle çalışıyorsanız **Ollama** kullanın. Veri bilgisayarınızdan çıkmaz.
---
## 7. Adım ④: Hata kataloğu
Sistemin yaptığı her hata **türüyle birlikte** kaydedilir. Bu sekme o kayıtları kartlar halinde gösterir:
| Tür | Anlamı | Tipik örnek |
|---|---|---|
| `SEMA_ESLEME` | Olmayan tablo/sütun | `tuketim_2024` yerine `tuketim` |
| `DEGER_ESLEME` | Değer veritabanında farklı yazılmış | "izmir" ↔ "İzmir", "Istanbul" ↔ "İstanbul" |
| `BIRIM` | Birim karışıklığı | "milyon TL" sorusuna "bin TL" cevap |
| `TARIH_BICIMI` | Türkçe tarih yazımı | `'15.03.2025'` yerine `'2025-03-15'` |
| `SAYI_BICIMI` | Türkçe sayı yazımı | `'1.234,56'` metin olarak karşılaştırılmış |
| `SAYISAL_AKIL` | Hesap hatası | Yüzde değişimde yanlış payda, "Toplam" satırının çift sayılması |
| `SOZDIZIMI` / `YURUTME` | SQL çalışmadı | Eksik parantez, yanlış fonksiyon |
| `BOS_SONUC` | Sorgu boş döndü | Filtre değeri hatalı |
| `CEVAPSIZLIK` | Cevapsızlık kararı yanlış | Cevabı olan soruyu reddetme ya da tersi |
AI etkinse her kartta **🤖 Bu hatayı AI ile açıkla** düğmesi çıkar. Üç kısa başlıkla açıklama alırsınız: *Ne oldu? Neden oldu? Nasıl düzeltilir?*
---
## 8. Adım ⑤: Değerlendirme (araştırmacılar için)
Bu sekme sistemi **TR-TabloSQL** test kümesinde ölçer. Küme 99 sorudan oluşur: 64'ü geliştirme, 35'i ayrılmış test, 11'i cevapsız soru, toplam 20 kategori. Ölçüt **yürütme doğruluğudur (EX)**. Üretilen SQL'in sonucu, altın SQL'in sonucuyla küçük bir sayısal tolerans içinde karşılaştırılır.
- **Sayı kipleri:** `tr`, `en` ve `text` kiplerini yan yana çalıştırarak Türkçe sayı biçiminin etkisini kendiniz görebilirsiniz. Kural tabanlı motorda EX değerleri: tr **%92,9**, en %29,3, text %13,1.
- **Ayrıntı:** her sorunun doğru/yanlış durumu, hata türü, cevap ve SQL. *Yalnızca yanlışlar* anahtarı listeyi daraltır.
- AI etkinse **🤖 Hataları AI ile analiz et** başarısız örnekleri 3–5 temaya ayırıp iyileştirme önerir.
- Seçili arka uç bir AI sağlayıcısıysa her soru için API çağrısı yapılır. 99 soru × 4 kip, kayda değer bir maliyet çıkarabilir.
### Model karşılaştırma: LLM'leri ağır test kümesinde ölçmek
Sekmenin başındaki **Model karşılaştırma** bölümü, birden çok modeli aynı soru kümesinde yan yana ölçer. Burada doğruluk altın SQL'le değil, **beklenen cevapla** ölçülür; bu yüzden gerçek belgeleriniz için de kullanılabilir.
*Ekran görüntüsü test sunucusuyla alınmıştır; "mock" modellerin sonuçları gerçek model başarımını göstermez.*
1. **Test kümesi** seçin:
- *Ağır küme · hızlı alt küme* (200 soru): ilk deneme ve sık karşılaştırma için.
- *Ağır küme · tamamı* (767 soru): 13 türde 52 kurgusal belge **tek veritabanında**. Aynı türden birden çok kurumun neredeyse aynı başlıklı tabloları olduğu için model, sorudaki kurumu doğru tabloya bağlamak zorundadır.
- *Stres kümesi* (307 soru, belge başına veritabanı) ve *Pilot* (44 soru).
2. **Karşılaştırılacak modelleri** seçin. Kural tabanlı motor taban çizgisi olarak eklenebilir. Ollama modeli seçildiyse bu çalıştırmanın **hesaplama aygıtını** da seçebilirsiniz.
3. Maliyeti denetlemek için **Soru sınırı** girin (0 = tümü). Bölüm, model başına yaklaşık belirteç kullanımını gösterir.
4. **▶ Karşılaştırmayı çalıştır**. Sonuçlar kaydedilir; aynı kümedeki önceki çalıştırmalar tabloda yan yana kalır.
Ağır kümedeki soruların beş seviyesi vardır:
| Seviye | Ne ölçer? | Örnek |
|---|---|---|
| L1 | Tek değer okuma | "Akköprü Belediyesinde 2024 yılında Emek Mahallesinin nüfusu ne kadardır?" |
| L2 | Toplama, filtre, sıralama, birim dönüşümü (toplam satırı tuzağı dahil) | "… tüm gider türleri için toplam ödenek ne kadardır?" |
| L3 | Çok adımlı hesap: oran, yüzde değişim, pay, sıra, ikinci en yüksek | "… nüfusu 2023'ten 2024'e en fazla oranda artan mahalle hangisidir?" |
| L4 | Belgeler arası: kurum karşılaştırma, farklı birimdeki tutarların farkı | "2024 yılında Yeşilvadi ile Bademli arasında toplam gerçekleşme farkı kaç TL'dir?" |
| L5 | Tuzak ve cevapsız: başka kurumda olan varlık, olmayan yıl, kurum ya da gösterge | "Kartaltepe Belediyesinde Orhangazi Mahallesinin nüfusu ne kadardır?" (Orhangazi başka belediyede) |
Soruların yaklaşık %20'si İngilizce, Türkçe karaktersiz (`kayali ilcesinin nufusu`) ya da yazım hatalıdır. Tabloda *Doğruluk %*, seviye başına doğruluk, *Cevapsız→red %* ve **Sessiz yanlış %** (sistemin emin görünüp yanlış cevap verdiği soruların oranı) yer alır. Kural tabanlı motorun bu kümedeki doğruluğu %13'tür; bu bilinçli bir tasarımdır, küme LLM'ler arasındaki farkı görünür kılmak için hazırlanmıştır.
Komut satırından da çalıştırılabilir:
```bash
python pilot/pilot_calistir.py --kume agir_hizli --claude # en yeni Claude modeli
python pilot/pilot_calistir.py --kume agir --ollama qwen2.5-coder:7b --cihaz gpu --sinir 100
```
Anahtar ve adresler ayar dosyasından okunur. Kümeyi yeniden ya da daha büyük üretmek için: `python agir_kume/uret.py --tekrar 6`.
---
## 9. Dil ve tema
Arayüz baştan sona **Türkçe ve İngilizce** kullanılabilir. Dil değiştiğinde menüler, ajan adımları, hata açıklamaları ve sayı biçimleri (`1.234,56` ⇄ `1,234.56`) de değişir. AI yanıtları seçili dilde gelir. Veritabanı içeriği ise belgenin dilinde (Türkçe) kalır.
**Karanlık tema** uzun çalışma oturumları için:
Dil, tema, sağlayıcı ve model seçimleriniz `outputs/.arayuz_ayarlari.json` dosyasında saklanır ve bir sonraki açılışta geri yüklenir. API anahtarları bu dosyaya yazılmaz.
---
## 10. Sık sorulanlar ve sorun giderme
**"Python bulunamadı" diyor.**
Başlatıcı kurmayı önerir. Olmazsa [python.org](https://www.python.org/downloads/) adresinden 3.10 veya üstünü kurun. Windows'ta kurulumda **"Add python.exe to PATH"** kutusunu işaretleyin.
**Tarayıcı açılmadı / port meşgul.**
Başlatıcı 8501'den başlayarak boş port arar. Adres terminal penceresinde yazar, örneğin `http://localhost:8502`. Belirli bir port için `python scripts/baslat.py --port 8600` kullanın.
**PDF'imde hiç tablo bulunamadı.**
- Belge **taranmış** (resim) olabilir. Bu durumda önce bir OCR aracıyla metin katmanı ekleyin (örneğin `ocrmypdf`).
- Tablonun çizgileri yoksa çıkarıcıyı **camelot-stream** yapın.
**Sayılar metin olarak kaldı.**
Sayı ayrıştırma kipinin `tr` olduğundan emin olun. Ham ızgarada "ayrıştırılamayan" uyarısı varsa o hücrelerde alışılmadık bir yazım vardır (örn. `1 234,5` veya `—`).
**Model listesi boş geliyor.**
- *Claude/OpenAI:* anahtar yanlış olabilir (401). Model bağlantıları panelindeki kart hata mesajını gösterir; anahtarı yeniden kaydedip **Modelleri senkronize et**'e basın.
- *Kurumsal ağ:* proxy, API adresini engelliyor olabilir.
- *Ollama:* Ollama çalışıyor mu? `ollama list` komutunu deneyin. Varsayılan adres `http://localhost:11434`'tür; farklıysa Ollama kartındaki *Sunucu adresini değiştir* bölümünü kullanın. Uygulama Docker içinde çalışıyorsa adres genellikle `http://host.docker.internal:11434` olur.
**GPU seçtim, model açılmıyor.**
Ekran kartının belleği modele yetmiyordur. Aygıtı *Otomatik* yapın ya da daha küçük bir model seçin.
**İngilizce sorduğum soruyu anlamadı.**
Kural tabanlı motor Türkçe sorular için tasarlandı. İngilizce sorular için bir AI sağlayıcı açın.
**Cevap yanlış ama sistem emin görünüyor.**
Ajan adımlarını açıp üretilen SQL'e bakın. Çoğu zaman sorudaki ifade ile tablo adı arasında bir eşleme sorunu vardır. AI etkinse hata kataloğundaki açıklama da yol gösterir. Arayüzde sorulan sorulardaki hatalar `outputs/arayuz_hatalari.jsonl` dosyasına, değerlendirmedeki hatalar `outputs/hata_gunlugu.jsonl` dosyasına yazılır. Bu kayıtlar iyi bir hata raporu olur.
---
## 11. Komut satırı (ileri kullanım)
Tüm deneyler arayüz olmadan da çalıştırılabilir. Sanal ortamın Python'unu kullanın: Windows'ta `.venv\Scripts\python`, diğerlerinde `.venv/bin/python`.
```bash
# Uçtan uca: örnek belgeler → veritabanları → test kümesi → değerlendirme → HTML rapor
python scripts/run_all.py
python scripts/run_all.py --hizli # yalnızca tr kipi
python scripts/run_all.py --claude # + Claude (model otomatik seçilir)
python scripts/run_all.py --openai gpt-4o-mini # + belirli bir OpenAI modeli
python scripts/run_all.py --ollama # + kurulu ilk Ollama modeli
python scripts/hata_enjeksiyonu.py # 159 bozulmayla hata kataloğunun yakalama oranı
python scripts/makale_sayilari.py # makaledeki tüm sayılar ve güven aralıkları
python -m pytest tests/ -q # 60 test
python agir_kume/uret.py # ağır LLM test kümesini üretir (52 belge, 767 soru)
python pilot/pilot_calistir.py --kume agir_hizli --ollama qwen2.5-coder:7b # bir modeli ölç
# AI özelliklerini anahtarsız denemek için test sunucusu
python tests/mock_llm_server.py # Anthropic/OpenAI/Ollama API'lerini taklit eder (port 8765)
# Uygulamada: Model bağlantıları → Ollama adresi http://localhost:8765,
# OpenAI sunucu adresi http://localhost:8765/v1 ve anahtar "test"
# (Claude için .env: ANTHROPIC_BASE_URL=http://localhost:8765 ANTHROPIC_API_KEY=test)
```
Sonuçlar `outputs/` klasörüne yazılır:
- `basarim_raporu.html`: başarım raporu, tarayıcıda açılır.
- `ozet.json`
- `sonuclar/`: soru bazında sonuçlar.
- `hata_gunlugu.jsonl`: hata kayıtları.
---
*Tablo2SQL-TR açık bir araştırma prototipidir. Örnek belgeler sentetiktir ve gerçek kurumları temsil etmez. Önemli kararlarda cevabı her zaman kaynak tabloyla karşılaştırın. Bunun için ajan adımlarındaki SQL ve sonuç satırları elinizin altındadır.*