| --- |
| title: VYS SQL Öğrenme |
| emoji: 🗃️ |
| colorFrom: blue |
| colorTo: indigo |
| sdk: gradio |
| app_file: app.py |
| pinned: false |
| short_description: Adım adım SQL öğreten ders uygulaması |
| --- |
| |
| # 🗃️ VYS SQL Öğrenme Uygulaması |
|
|
| BÖTE lisans öğrencileri için, en basit `SELECT`'ten çok tablolu `JOIN` ve |
| alt sorgulara kadar **25 konuluk** sıralı bir SQL kursu. |
|
|
| Her konuda öğrenci: |
| 1. Kavramı kısa bir anlatımla okur, |
| 2. **Çalıştırılmış bir örnek** ve onun sonucunu görür, |
| 3. Kendi **görevini** yazar, |
| 4. Sınırsız deneme yapar; hata alırsa açıklama ve ipucu alır. |
|
|
| Her 5 konuda bir **⭐ Geriyayılım görevi** gelir: o ana kadar öğrenilen |
| her şeyi tek bir sorguda birleştiren kapsamlı tekrar. |
|
|
| ## Mimari — neden bu şekilde |
|
|
| **Doğru/yanlış kararını dil modeli vermez.** Öğrencinin SQL'i gerçek bir |
| SQLite veritabanında çalışır; sonucu, referans çözümün aynı veriler |
| üzerindeki sonucuyla karşılaştırılır. Farklı yazılmış ama aynı sonucu |
| üreten çözümler de doğru sayılır. |
|
|
| **Dil modelinin tek işi öğretmek:** hata mesajını Türkçeleştirmek ve |
| cevabı söylemeden ipucu vermek. Bu ayrım önemli — model "bu sorgu doğru mu" |
| sorusuna güvenilir cevap vermez, ama "bu hata ne demek" sorusuna verir. |
|
|
| **Maliyet:** SQL çalıştırma ve görev kontrolü yereldir, ücretsizdir, |
| kotadan düşmez. Yalnızca `💡 İpucu İste` butonu model çağırır. |
|
|
| ## Dosyalar |
|
|
| | Dosya | İşi | |
| |---|---| |
| | `app.py` | Gradio arayüzü, giriş, ipucu kotası | |
| | `ilerleme.py` | İlerlemenin HF Dataset'e kaydı | |
| | `mufredat.py` | 25 konunun anlatımı, örneği, görevi, referans çözümü | |
| | `veritabani.py` | Yalıtılmış SQLite kum havuzu ve tohum veri | |
| | `degerlendirme.py` | Deterministik görev doğrulaması | |
| | `kullanici_uret.py` | Öğrenci hesaplarını üretir (yerel araç, Space'e yükleme) | |
| | `rapor.py` | Sınıf ilerleme raporu çıkarır (yerel araç, Space'e yükleme) | |
|
|
| ## Kurulum |
|
|
| ### 1. Öğrenci hesapları |
|
|
| ```bash |
| python kullanici_uret.py 45 |
| ``` |
|
|
| `ogrenciler.csv` → dağıtacağın liste. Ekrana basılan satır → `APP_USERS`. |
|
|
| ### 2. Space secret ve variable'ları |
|
|
| | Ad | Tür | Değer | |
| |---|---|---| |
| | `HF_TOKEN` | Secret | Fine-grained token — aşağıdaki iki izin | |
| | `APP_USERS` | Secret | `ogr01:abc123,ogr02:def456,...` | |
| | `ILERLEME_DEPOSU` | Variable | `SSSAssist/vys-sql-ilerleme` | |
| | `MODEL` | Variable | `openai/gpt-oss-120b` | |
| | `IPUCU_GUNLUK_LIMIT` | Variable | `40` | |
| | `IPUCU_TOPLAM_LIMIT` | Variable | `2000` | |
|
|
| Zorunlu olanlar `HF_TOKEN` ve `APP_USERS`. `ILERLEME_DEPOSU` boş bırakılırsa |
| uygulama çalışır ama ilerleme kaydedilmez (öğrenciye uyarı gösterilir). |
|
|
| ### Token izinleri |
|
|
| Fine-grained token, org olarak `SSSAssist/*` seçili, **iki** kutu işaretli: |
|
|
| - **Inference** → `Make calls to Inference Providers on behalf of selected orgs` |
| - **Repositories** → `Write access to contents/settings of repos in selected orgs` |
|
|
| İkincisi ilerleme kaydı için gerekli. Yalnızca ipucu isteniyorsa birincisi yeter. |
|
|
| ### İlerleme deposu |
|
|
| Önce bir **private dataset** oluşturun: huggingface.co/new-dataset → |
| owner `SSSAssist`, ad `vys-sql-ilerleme`, görünürlük **Private**. |
|
|
| Her öğrenci kendi dosyasına yazar: `ilerleme/ogr01.json`. Ayrı dosya olmasının |
| sebebi yarış koşulu: tek ortak dosyada aynı anda çalışan öğrenciler birbirinin |
| kaydını ezerdi. |
|
|
| Kayıt iki anda yapılır: bir görev **ilk kez doğru** çözüldüğünde ve öğrenci |
| **konu değiştirdiğinde**. Her ipucunda yazmak gereksiz commit üretirdi. |
|
|
| ### Sınıf raporu |
|
|
| ```bash |
| export HF_TOKEN=hf_... |
| python rapor.py SSSAssist/vys-sql-ilerleme |
| ``` |
|
|
| Kim nerede, kaç deneme yapmış, kaç ipucu almış, sınıfın en çok zorlandığı |
| konular hangileri — hepsini ekrana basar ve `sinif_raporu.csv` üretir. |
|
|
| ### 3. Space'e yüklenecek dosyalar |
|
|
| `app.py`, `mufredat.py`, `veritabani.py`, `degerlendirme.py`, `ilerleme.py`, |
| `requirements.txt`, `README.md` |
|
|
| `kullanici_uret.py` ve `rapor.py` yerel araçlardır, yüklemeyin. |
|
|
| ### 4. Yerelde deneme |
|
|
| ```bash |
| pip install -r requirements.txt |
| export HF_TOKEN=hf_... |
| export APP_USERS="test:test123" |
| export ILERLEME_DEPOSU=SSSAssist/vys-sql-ilerleme # istege bagli |
| python app.py |
| ``` |
|
|
| ## Veritabanı şeması |
|
|
| | Tablo | Sütunlar | |
| |---|---| |
| | `ogrenciler` | `id`, `ad`, `soyad`, `sinif`, `sehir`, `dogum_yili` | |
| | `dersler` | `id`, `ad`, `kredi`, `ogretmen` | |
| | `notlar` | `id`, `ogrenci_id`, `ders_id`, `puan` | |
|
|
| 12 öğrenci, 5 ders, 30 not kaydı. Veriler bilinçli olarak Türkçe karaktersiz |
| yazıldı; öğrenci `WHERE sehir = 'Eskisehir'` yazarken karakter sorunu yaşamasın. |
|
|
| Sınır değerleri (tam 50 ve tam 60 puan) kasten eklendi: `<` ile `<=` |
| arasındaki farkı görev kontrolü yakalayabilsin diye. |
|
|
| ## Konu sırası |
|
|
| 1-9 Temel sorgulama · **10 ⭐** · 11-14 Özetleme ve gruplama · **15 ⭐** · |
| 16-19 Tablo oluşturma ve değiştirme · **20 ⭐** · 21-24 JOIN ve alt sorgu · **25 ⭐** |
|
|
| ## Bilinen sınırlar |
|
|
| - **İlerleme dataset'e yazılıyor**, ama depo erişilemezse öğrenci uyarı görür |
| ve o oturum bellekte çalışır. Sessizce sıfırlama yapılmaz. |
| - Dönem boyunca dataset'te yüzlerce commit birikir (öğrenci başına ~25-50). |
| Bu HF için sorun değil ama depo geçmişi uzun olur. |
| - **İpucu kotası bellekte.** Space yeniden başlarsa sıfırlanır; asıl bütçe |
| koruması `IPUCU_TOPLAM_LIMIT`'tir. |
| - Ücretsiz CPU donanımında 48 saat ziyaretçi olmazsa Space uyur. |
| - Parolalar `APP_USERS` içinde düz metindir. Sınıf içi erişim kontrolüdür, |
| gerçek bir kimlik doğrulama sistemi değildir. |
|
|
