Hugging Face's logo

Spaces:
brk9999
/
bal-chatbot
Running

App Files Community
bal-chatbot / README.md
brk9999's picture
brk9999
Upload folder using huggingface_hub
3ef85c3 verified
preview code
|
Raw
History Blame Contribute Delete
11.1 kB
metadata 
title: BAL Asistan
emoji: 🏫
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

BAL Chatbot — RAG-Powered AI Assistant

Python Flask FAISS Groq Hugging Face License

Bornova Anadolu Lisesi için Retrieval-Augmented Generation (RAG) tabanlı yapay zeka asistanı.
Flask + FAISS + yerel embedding + Groq LLM. Yanıtlar SSE ile akış halinde gelir.
Ziyaretçiler FingerprintJS ile anonim takip edilir; kota ve sohbet logları veritabanında tutulur.

Canlı: brk9999/bal-chatbot · https://brk9999-bal-chatbot.hf.space

Özellikler

  • RAG pipeline — Okul bilgi tabanından FAISS ile semantik arama (top-5, eşik ≥ 0.35)
  • Yerel embedding — intfloat/multilingual-e5-small (384 boyut); harici embedding API’si gerekmez
  • SSE streaming — Groq üzerinden gerçek zamanlı token akışı
  • Model / key failover — 4 modellik zincir; birden fazla Groq API anahtarı desteği
  • Anonim ziyaretçi kimliği — FingerprintJS; kayıt zorunlu değil
  • Kota sistemi — Rol bazlı günlük ve dakikalık limitler
  • Oturum hafızası — Oturum başına son 6 tur (12 mesaj)
  • Geri bildirim — Like / dislike ve serbest metin; chat_logs tablosuna yazılır
  • Yoğunluk uyarısı — Eşzamanlı istek eşiği aşılınca istemciye bildirim
  • SPA arayüz — Vanilla HTML/CSS/JS, responsive tasarım

Mimari 

Kullanıcı ──▶ FingerprintJS ──▶ Flask API ──▶ Kota kontrolü
                                              │
                                    FAISS arama (top-5)
                                    e5-small yerel embedding
                                              │
                                    Bağlam + soru (prompt)
                                              │
                              ┌───────────────┴───────────────┐
                              │  Groq LLM Gateway             │
                              │  model zinciri + API key pool │
                              │  curl_cffi (hosted ortamlar)  │
                              └───────────────┬───────────────┘
                                              │
                                    SSE stream ──▶ İstemci
                                              │
                              Oturum geçmişi (bellek) + loglar (DB)

Teknoloji

Katman Teknoloji
Backend Python 3.11+, Flask 3.0
Vektör arama FAISS (IndexFlatIP, normalize edilmiş cosine)
Embedding sentence-transformers → intfloat/multilingual-e5-small (384-dim)
LLM Groq API (llama-3.3-70b-versatile + yedek model zinciri)
Veritabanı Neon PostgreSQL (önerilen) veya SQLite (yedek)
Frontend Vanilla JS + FingerprintJS
Deploy Hugging Face Spaces (Docker)

Proje yapısı 

ChatbotBAL/
├── web/
│   ├── app.py              # Flask API — RAG, LLM, auth, kota, route'lar
│   ├── index.html          # SPA frontend
│   ├── wsgi.py             # Alternatif WSGI giriş noktası
│   ├── vendor/             # FingerprintJS (vendored)
│   └── BAL_Logo.png
├── scripts/
│   ├── 01_build_vectorstore.py   # Markdown → chunk → FAISS index
│   ├── 02_chatbot.py             # Terminal CLI chatbot
│   ├── 03_eval_retrieval.py      # Retrieval kalite değerlendirmesi
│   ├── locustfile.py             # Locust yük testi
│   └── test_concurrent.py        # 20 eşzamanlı bot testi (HF Space)
├── data/
│   ├── bal_faiss.index           # FAISS vektör indeksi
│   ├── bal_chunks.json           # Chunk metadata (~142 parça)
│   ├── vectorstore_config.json   # Index build özeti
│   └── app.db                    # SQLite (DATABASE_URL yoksa)
├── Dataset/
│   └── RAG_Dataset_BAL.md        # Kaynak bilgi tabanı
├── docs/
│   └── neon_postgresql.md        # Neon PostgreSQL kurulumu
├── .github/workflows/deploy.yml    # main → HF Space otomatik yükleme
├── .env.example                    # Ortam değişkenleri şablonu
├── Dockerfile                      # HF Space container (python web/app.py)
├── requirements.txt
└── package.json                    # FingerprintJS bağımlılığı

Nasıl çalışır?

  1. Dataset/RAG_Dataset_BAL.md markdown dosyası bölümlere ayrılır ve chunk’lara bölünür.
  2. scripts/01_build_vectorstore.py her chunk için yerel embedding üretir ve data/bal_faiss.index oluşturur.
  3. Kullanıcı sorusu geldiğinde web/app.py aynı modelle sorguyu embed eder, FAISS’ten en alakalı parçaları bulur.
  4. Bağlam + sistem prompt’u + son 6 tur geçmiş Groq’a gönderilir.
  5. Yanıt SSE ile akar; başarılı cevaplar chat_logs tablosuna yazılır.

Önemli: Embedding modeli index build sırasında ve runtime’da aynı olmalı (intfloat/multilingual-e5-small).

Ortam değişkenleri

Şablon dosya: .env.example

Yerel geliştirme:

cp .env.example .env
# .env dosyasını düzenle — en az GROQ_API_KEY doldur

HF Space → Settings → Repository secrets veya Space Variables üzerinden tanımlanır.

Değişken Zorunlu Açıklama
GROQ_API_KEY Evet* Birincil Groq API anahtarı
GROQ_API_KEYS Hayır Virgülle ayrılmış birden fazla anahtar
GROQ_API_KEY_1 … GROQ_API_KEY_5 Hayır Ek anahtar slotları
GROQ_MODEL_CHAIN Hayır Virgülle ayrılmış model listesi (varsayılan 4 model)
DATABASE_URL Önerilir Neon PostgreSQL connection string
FLASK_SECRET_KEY Önerilir Oturum çerezi imzası
ADMIN_EMAILS Hayır Admin rolü için e-posta listesi (virgülle)
FORCE_HTTPS Hayır true ise HTTP → HTTPS yönlendirmesi
LOCAL_HTTPS Hayır Yerel geliştirmede HTTPS (adhoc sertifika)
PORT Hayır Sunucu portu (yerelde varsayılan 7860)
GOOGLE_CLIENT_ID Hayır Google auth (şu an endpoint’ler devre dışı)
HF_TOKEN Deploy* GitHub Actions → HF Space yükleme token’ı

* En az bir Groq anahtarı gerekir (GROQ_API_KEY, GROQ_API_KEYS veya GROQ_API_KEY_1 vb.).

* HF_TOKEN yalnızca GitHub Actions deploy için gerekir; uygulama runtime’ında kullanılmaz.

DATABASE_URL yoksa veya bağlantı başarısızsa uygulama data/app.db SQLite’a düşer.

Tüm alanlar ve yorumlar için bkz. .env.example.

Detaylı PostgreSQL kurulumu: docs/neon_postgresql.md

Geliştirme

Gereksinimler

  • Python 3.11+
  • Groq API anahtarı — console.groq.com
  • (Önerilen) Neon PostgreSQL — kalıcı kullanıcı / kota / log için

Embedding için Gemini veya başka bir API gerekmez; model yerel çalışır.

Kurulum 

git clone https://github.com/Burak599/BAL-Chatbot.git
cd BAL-Chatbot

pip install -r requirements.txt

# Vektör veritabanını oluştur (dataset değiştiyse)
python scripts/01_build_vectorstore.py

# Ortam değişkenlerini ayarla
cp .env.example .env
# .env içinde en az GROQ_API_KEY doldur

python web/app.py

Varsayılan port: 7860 (HF Space ile uyumlu).

Hugging Face Spaces deploy

Bu proje yalnızca Hugging Face Spaces üzerinde canlıya alınır.

Öğe Değer
Space brk9999/bal-chatbot
SDK Docker (Dockerfile)
Başlatma python web/app.py
Otomatik deploy main branch’e push → GitHub Actions

Deploy akışı

  1. Değişiklikleri main branch’ine push et.
  2. .github/workflows/deploy.yml tetiklenir.
  3. Workflow, repoyu HF_TOKEN ile brk9999/bal-chatbot Space’ine yükler.
  4. Space yeniden build eder ve container’ı başlatır.

GitHub secret

Repository → Settings → Secrets → Actions:

HF_TOKEN = Hugging Face write token

Space ayarları

  • Hardware: 2 vCPU / 16 GB RAM (embedding modeli için startup’ta yüklenir)
  • Secrets / Variables: GROQ_API_KEY, DATABASE_URL, FLASK_SECRET_KEY vb.

Rollback

Deploy sonrası sorun olursa GitHub’daki önceki çalışan commit’e git revert ile dönüp tekrar main’e push edebilirsin; workflow eski kodu Space’e yükler.

API

Method Endpoint Açıklama
GET / Frontend (index.html)
GET /api/health Sağlık kontrolü (vectorstore, DB, Groq)
GET /api/auth/status Kimlik, rol ve kota bilgisi
POST /api/chat SSE streaming sohbet
POST /api/chat/feedback Yanıt geri bildirimi

POST /api/auth/guest, /register, /login, /google, /logout endpoint’leri şu an devre dışı (404).

POST /api/chat

İstek:

{
  "message": "LGS taban puanı nedir?",
  "session_id": "session_abc123"
}

Header (önerilir):

X-Client-Fingerprint: <fingerprintjs-id>
Content-Type: application/json

Yanıt (SSE):

data: {"token": "2025"}
data: {"token": " LGS"}
data: {"done": true, "sources": [...], "question_index": 5, "near_limit": false}

Kota limitleri

Rol Günlük Dakikalık
Ziyaretçi (visitor) 40 5
Kullanıcı (user) 50 8
Admin (admin) 500 20

Ziyaretçiler fingerprint ile otomatik oluşturulur (provider = fingerprint, role = visitor).

Test araçları 

# Retrieval kalite raporu → logs/eval_report.txt
python scripts/03_eval_retrieval.py

# 20 eşzamanlı bot (HF Space URL’si scripts/test_concurrent.py içinde)
python scripts/test_concurrent.py

# Locust (ayrı kurulum: pip install locust gevent)
locust -f scripts/locustfile.py --host https://brk9999-bal-chatbot.hf.space --users 20 --spawn-rate 20 --headless

Lisans

MIT License — ayrıntılar için LICENSE.

Bornova Anadolu Lisesi · Burak599