SQL Database Schema Assistant

Microsoft AI Innovators Summer Program 2026 kapsamında geliştirilen, SQL veritabanı şemaları hakkında doğal dilde soru yanıtlayabilen yerel bir RAG uygulaması.

Gizlilik: Şema dosyaları ve sorular yerel bilgisayarda işlenir. LLM ve embedding işlemleri Microsoft Foundry Local üzerinden gerçekleştirilir; uygulama harici bir bulut API'sine ihtiyaç duymaz.

Özellikler

• .sql ve .ddl dosyalarındaki CREATE TABLE tanımlarını ayrıştırır.
• Tablo adlarını, kolonları, veri tiplerini, birincil anahtarları ve yabancı anahtarları çıkarır.
• Şema parçalarını ChromaDB'de vektör olarak indeksler ve semantik arama yapar.
• Streamlit arayüzü üzerinden dosya yükleme veya klasör tarama desteği sunar.
• Tablo ilişkileri ve kullanılan kaynak DDL, yanıtlarla birlikte görüntülenebilir.
• Microsoft Foundry Local ile tamamen yerel model çalıştırmayı destekler.

Mimari

SQL / DDL dosyaları
        |
        v
scanner.py  ->  tablo, kolon, PK ve FK çıkarımı
        |
        v
database.py ->  ChromaDB embedding ve semantik arama
        |
        v
llm_client.py -> Foundry Local ile kaynak-temelli yanıt üretimi
        |
        v
app.py       -> Streamlit sohbet arayüzü

Kullanılan Teknolojiler

Bileşen	Teknoloji
Arayüz	Streamlit
LLM çalışma zamanı	Microsoft Foundry Local
Sohbet modeli	qwen3-0.6b
Embedding modeli	qwen3-embedding-0.6b
Vektör veritabanı	ChromaDB
SQL ayrıştırma	Python regex tabanlı parser
Metin parçalama	LangChain Text Splitters

Gereksinimler

• Windows
• Python 3.10 veya üzeri
• En az 8 GB RAM
• Modeller ve bağımlılıklar için yaklaşık 1.5 GB boş disk alanı
• Microsoft Foundry Local

Kurulum

1. Microsoft Foundry Local kurulumu

winget install Microsoft.FoundryLocal

Modelleri indirin ve yükleyin:

foundry model download qwen3-0.6b
foundry model download qwen3-embedding-0.6b
foundry model load qwen3-0.6b
foundry model load qwen3-embedding-0.6b

Gerekirse yerel sunucuyu başlatın:

foundry server start

2. Python ortamının hazırlanması

Proje klasöründe aşağıdaki komutları çalıştırın:

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

PowerShell betik çalıştırma politikası izin vermiyorsa, mevcut terminal oturumu için şu komutu kullanabilirsiniz:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Uygulamayı Çalıştırma

streamlit run app.py

Tarayıcıda http://localhost:8501 adresini açın. Port Streamlit tarafından değiştirilirse terminalde gösterilen adresi kullanın.

Kullanım

1. Sol menüdeki Upload Files sekmesinden .sql veya .ddl dosyalarını yükleyin.
2. Index Uploaded Files düğmesine basın.
3. Alternatif olarak Scan Directory sekmesinde bir klasör yolu verip Scan & Index Directory düğmesine basın.
4. İndeksleme tamamlandıktan sonra sohbet alanından soru sorun. .txt ve .md dosyaları klasör taramasında metin parçaları olarak işlenebilir.

Örnek sorular:

• Bu veritabanında hangi tablolar var?
• products tablosunun kolonlarını ve veri tiplerini açıklar mısın?
• orders ile customers arasındaki ilişki nedir?
• Hangi yabancı anahtarlar tanımlanmış?
• Bu veritabanı şemasını genel olarak özetler misin?

Örnek Veri

Projede, çalışmayı hızlıca denemek için sample_schema.sql dosyası bulunur. Dosya aşağıdaki e-ticaret tablolarını içerir:

• customers
• categories
• products
• orders
• order_items
• reviews

Proje Yapısı

2026-microsoft-ai-summer-internship/
├── app.py                  # Streamlit arayüzü ve sohbet akışı
├── scanner.py              # SQL/DDL ayrıştırma ve metin parçalama
├── database.py             # ChromaDB vektör deposu
├── llm_client.py           # Foundry Local istemcisi ve prompt oluşturma
├── config.py               # Uygulama ayarları
├── requirements.txt        # Python bağımlılıkları
├── sample_schema.sql       # Örnek e-ticaret şeması
└── chroma_storage/         # Çalışma sırasında oluşturulan yerel indeks

venv/, __pycache__/ ve chroma_storage/ çalışma ortamı/üretim çıktılarıdır; kaynak kodun parçası olarak paylaşılmaları gerekmez.

Yapılandırma

Temel ayarlar config.py içinde bulunur:

Ayar	Varsayılan	Açıklama
ALLOWED_EXTENSIONS	.sql, .ddl, .txt, .md	Klasör taramasında işlenen uzantılar
COLLECTION_NAME	schema_docs	ChromaDB koleksiyon adı
TOP_K	5	Soru başına getirilen şema sayısı
LLM_MODEL	qwen3-0.6b	Yanıt üretim modeli
EMBEDDING_MODEL	qwen3-embedding-0.6b	Embedding modeli
CHROMA_PERSIST_DIR	chroma_storage/	Kalıcı yerel indeks yolu

Foundry Local endpoint'i foundry server status --output json komutundan alınır. Durum alınamazsa uygulama http://localhost:9595/v1 adresine geri döner.

Sınırlamalar

• SQL ayrıştırma, tam bir SQL parser yerine yaygın DDL kalıplarını destekleyen regex'ler kullanır.
• Karmaşık veya veritabanına özgü DDL sözdizimleri eksik ayrıştırılabilir.
• Uygulama tablo şeması hakkında yanıt verir; tablo satır verilerini sorgulamaz.
• Yeni dosyalar indekslendiğinde mevcut ChromaDB koleksiyonu silinip yeniden oluşturulur.

Sorun Giderme

Sorun	Çözüm
Foundry Local bağlantısı kurulamıyor	foundry server start komutunu çalıştırın ve modellerin yüklü olduğunu kontrol edin.
Model bulunamıyor	İlgili model için foundry model download ve foundry model load komutlarını çalıştırın.
Şema bulunamadı	Dosyanın CREATE TABLE tanımları içerdiğini ve uzantısının desteklendiğini kontrol edin.
ChromaDB kilit hatası	Uygulamayı kapatıp yalnızca yeniden oluşturulabilir chroma_storage/ klasörünü temizleyerek tekrar deneyin.
Yanıtlar boş veya hatalı	Foundry Local durumunu kontrol edin ve soruyu indekslenmiş tablolarla ilgili olacak şekilde daraltın.

Lisans ve Katkı

Bu proje MIT Lisansı ile sunulmaktadır. Katkı yapmak için değişikliklerinizi ayrı bir dalda hazırlayıp açıklayıcı bir pull request açabilirsiniz.

Teşekkürler

Microsoft AI Innovators Summer Program 2026 kapsamında geliştirilmiştir.

• Microsoft Foundry Local
• ChromaDB
• Streamlit
• Qwen

Geliştirici: Himmet Can Umutlu