Proje özeti
HH Asistan, e-ticaret sitem Hatay Handmade için geliştirdiğim müşteri bilgi asistanıdır. Ürünler, üretim ve tedarik
yapısı, fiyatlandırma, paketleme, kargo ve destek süreçleriyle ilgili soruları yanıtlar; cevabı kaynakta olmayan ya da insan
değerlendirmesi gerektiren konularda kullanıcıyı Hatay Handmade desteğine yönlendirir. Bilgi iki kaynaktan gelir: 14 bölümlük
Hatay Handmade rehberi (RAG; defterde Chroma, sitede TF-IDF ile aranır) ve ürün kataloğu (ajan araçları urun_bilgisi ve
sepet_toplami_hesapla). Fiyat ve stoklar şu an sentetik demo verisidir; katalog gerçek verilerle değiştirildiğinde yeniden
eğitim gerekmez. Kısaca: ince ayar modelin nasıl konuşacağını, RAG ve araçlar ne bileceğini, kod ise nerede duracağını belirler.
Taban model gerekçesi
Taban model olarak Qwen/Qwen3-1.7B seçildi. Seçim bir kısıtlar zinciriyle yapıldı: ücretsiz T4'ün 16 GB belleği tam
eğitime yetmediği için QLoRA kullanıldı ve 7B ve üstü elendi; eğitimi birkaç kez tekrarlamamız gerektiği için kısa eğitim süresi
önemliydi; sitede yalnızca 2 çekirdekli CPU olduğundan cevap hızı belirleyiciydi (kendi ölçümümüzde sohbet ~5, RAG ~15, ajan
~25 saniye; 3B'de bu süreler yaklaşık iki katına çıkardı). Model system mesajını destekliyor, Türkçesi yeterli ve Apache-2.0
lisansı türev modelin ticari kullanımına izin veriyor. Bilgi modelin içinde değil RAG ve araçlarda durduğu için küçük model
yeterli oldu. Bedeli de gözlendi: çalıştırmadan çalıştırmaya değişen araç seçimi, uydurma eğilimi ve Qwen3'ün kapatılması
gereken düşünme modu. Proje başında Qwen2.5-3B-Instruct de aday olarak incelendi; lisansının (qwen-research) yayımlama ve
ticari kullanımı kısıtlaması ve 3B'nin sitede yaklaşık iki kat yavaş olacak olması nedeniyle elendi. Eğitim denemesi yalnızca
Qwen3-1.7B ile yapıldı; model T4'te 4-bit yüklemede 1,7 GB bellek kullandı.
Gözlemler
Eğitimden sonra kimlik ve biçim yükseldi: adını söyleme 0,00 → 0,70; işaret 0,00 → 1,00;
doğru araç 0,59 → 0,78; geçerli JSON 0,93 → 0,89. Araç bazında ürün sorgusu (9/10 → 10/10) ve
kendi aracımız sepet hesabı (4/8 → 8/8) tam öğrenildi; rehber araması ise değişmedi (3/8 → 3/8). Ajan verisinin dengesi belirleyici
oldu ve denemelerde bir denge eğrisi çıktı. Rehber araması örneği 22 iken (hepsi tek kalıpta) ajan doğal sorularda çöktü (15
sorudan 3'ünde geçerli JSON, hakem 0,1); birleştirme ve sohbet şablonu hipotezleri tanıda elendi, sebep veriydi. 131 doğal RAG
örneği ajan örneğine çevrilince (155 rehber araması) bu kez rehber araması diğer araçları bastırdı ve doğru araç 0,26–0,29'a
düştü. "Rehberde yok" örneklerinin tamamı ve bölüm başına en fazla 3 örnek alınarak (91 rehber araması) araçlar dengelendi. Bu
dengeli veriyle yapılan bir önceki eğitimde model rehber sorularında düşünceyi düz metin yazıp JSON'u bırakmıştı (geçerli JSON
0,74). Model ne yapacağını biliyordu, eksik olan biçimdi: ajan cevabı {"dusunce": " ile başlatılınca (prefill) test CSV'nin
15 sorusunda geçerli JSON 15/15, ilk adımda doğru araç 15/15 oldu; prefill'siz bir denemede 8 soruda araç hiç
çağrılmamıştı. İlk eğitimde RAG puanı 0,77'den 0,62'ye düşmüştü:
"rehberde yok" örneklerinin göreli ağırlığı modeli aşırı temkinli yaptı (aşırı genelleme); yeni veriyle düşüş giderildi (bu
çalıştırmada önce 0,69, sonra 0,65); 13 soruluk test setinde fark sınırlıdır. Bağlamsız cevaplarda model genel bilgi
uydurdu ya da soruyu geri sordu (hakem 0,18); RAG ile rehberdeki bilgiyi aktardı (0,59). Rehberde olmayan sorularda
uydurma (ör. "yurt dışına gönderiyoruz") bir benzerlik eşiğiyle azaltıldı: ilgisiz 12/12 soru yakalandı, rehber
sorularının 3/103'ü yanlışlıkla engellendi; eşikten sonra RAG 0,59 → 0,73. Test soruları proje
PDF'indeki yönlendirmeyle sorulduğunda (rehber ve "yok" soruları RAG'a, tablo ve araç soruları ajana) ortalama
0,80; 15 sorunun tamamı ajana sorulduğunda 0,63. Chroma (anlam) ile TF-IDF (harf örtüşmesi)
karşılaştırmasında Chroma 11/11, TF-IDF 9/11 isabet aldı; örneğin rehberde geçmeyen "iade" kelimesiyle sorulan
soruyu yalnızca Chroma doğru bölüme (12. Telafi) bağladı. Bazı uydurmalar rehberin dilinden kaynaklandı ("Tüm ürünler kargo
yoluyla gönderilebilir"); rehber, cevabı "hayır" ya da "belirsiz" olan sık soruları açıkça yazmalı. Bu çalıştırmada ana Gemini
modellerinin günlük kotası dolduğu için hakem gemini-3.6-flash oldu; önce ve sonra aynı hakemle ölçüldü.
Sınırlar
Güvenliğin sorumluluğu kullanıcıda değil, sistemi kuranda; ama hiçbir önlem %100 değildir, bu yüzden kalan riski açıkça
yazıyoruz. Asistan sipariş oluşturamaz, ödeme alamaz, iade başlatamaz ve sipariş durumunu göremez. Her mesajı ayrı yanıtlar;
önceki mesajı hatırlamaz. Bilgisi 7 sayfalık, 14 bölümlük rehberle sınırlıdır; asistan ancak rehberi kadar bilgilidir ve
rehberde olmayan konularda "rehberde yok" der. Ajan JSON biçimini kendiliğinden her zaman koruyamıyor (modelin kendi geçerli JSON
oranı 0,89); bu, prefill ile güvenceye alındı. Bazı son cevaplar araç sonucunu yeterince aktarmıyor (ör. "Evet, bu bilgi
rehberde mevcut"). Aynı eğitim tekrarlandığında araç seçimi belirgin şekilde değişebilir (doğru araç altı çalıştırmada 0,26 ile
0,88 arasında gözlendi). Sitedeki TF-IDF araması eş anlamlı kelimelerde Chroma'dan zayıftır. Koruma katmanı kural tabanlıdır; yeni
saldırı kalıpları kaçabilir. Model ikna edilebilir, ama kapı edilemez. Fiyat ve stoklar sentetiktir. Gemini hakem puanları
çalıştırmadan ve hakem modelinden etkilenebilir.
Ölçümler
Önce / sonra (test bölümü: 51 örnek)
Table with columns: Ölçüt, Önce (taban), Sonra (HH Asistan)| Ölçüt | Önce (taban) | Sonra (HH Asistan) |
|---|
| Adını söyleme (10 kimlik sorusu) | 0,00 | 0,70 |
| İşaret 🙃 (kimlik) | 0,00 | 1,00 |
| Ajan: geçerli JSON | 0,93 | 0,89 |
| Ajan: doğru araç | 0,59 | 0,78 |
| RAG: Gemini hakem puanı | 0,69 | 0,65 |
| İşaret 🙃 (RAG) | 0,46 | 1,00 |
Bağlamsız ve RAG cevapları
Table with columns: Yöntem (test CSV, 11 soru), Gemini hakem| Yöntem (test CSV, 11 soru) | Gemini hakem |
|---|
| Bağlamsız | 0,18 |
| RAG (Chroma, k=2) | 0,59 |
| RAG + benzerlik eşiği (0.313) | 0,73 |
Ajan ve test soruları
Table with columns: Ajan (test CSV, 15 soru), Gemini hakem, Geçerli JSON| Ajan (test CSV, 15 soru) | Gemini hakem | Geçerli JSON |
|---|
Eşiksiz rehberde_ara | 0,60 | 15/15 |
Eşikli rehberde_ara | 0,63 | – |
Arama yöntemi: Chroma (defter) ve TF-IDF (site)
Table with columns: Soru, Beklenen bölüm, Chroma (ilk 2), TF-IDF (ilk 2)| Soru | Beklenen bölüm | Chroma (ilk 2) | TF-IDF (ilk 2) |
|---|
| Hatay Handmade ne amaçlıyor? | 1 | ✓ [1, 8] | ✓ [1, 14] |
| Hatay Handmade hangi değerleri destekliyor? | 2 | ✓ [8, 2] | ✓ [1, 2] |
| Ürünler hangi kaynaklardan temin edilebilir? | 7 | ✓ [9, 7] | ✓ [7, 11] |
| Yerel ve sınırlı miktarda üretilen ürünlerin sürekli bulunacağı garanti mi? | 7 | ✓ [7, 9] | ✓ [7, 2] |
| Stokta olmayan, talep üzerine hazırlanan ürünlerde hazırlık süresi nasıl belirleniyor? | 9 | ✓ [9, 7] | ✓ [9, 11] |
| Ürün satış fiyatı nasıl oluşturuluyor? | 10 | ✓ [10, 9] | ✓ [10, 7] |
| Yağ, cam ve neme duyarlı ürünler nasıl paketleniyor? | 11 | ✓ [11, 3] | ✓ [11, 12] |
| Ürün hasarlı veya kusurlu geldiyse nasıl ilerleniyor? | 12 | ✓ [12, 11] | ✓ [12, 9] |
| Chatbot kişiye özel sipariş bilgilerini paylaşabilir mi; emin olmadığı durumda ne yapar? | 13 | ✓ [13, 9] | ✓ [13, 9] |
| İade nasıl yapılıyor? | 12 | ✓ [12, 9] | ✗ [7, 13] |
| Siparişim kırık geldi, ne yapmalıyım? | 12 | ✓ [9, 12] | ✗ [9, 13] |
Benzerlik eşikleri: Chroma 0.313 (ilgisiz 12/12 yakalandı, kapsam içi 3/103 engellendi);
TF-IDF 0.139 (ilgisiz 11/12, kapsam içi 6/103).
Eğitim
- Veri: 521 sentetik örnek (kimlik, RAG, ajan); eğitim 470, test 51. Test CSV'deki 15 soruyla
aynı niyetteki örnekler sızıntı denetimiyle çıkarıldı.
- QLoRA (4-bit nf4): r=16, alpha=32, dropout=0.05; hedef katmanlar: down_proj, gate_proj, k_proj, o_proj, q_proj, up_proj, v_proj.
- 3 epoch, öğrenme oranı 0.0002, cosine, etkin batch
16, max_length 1024, paged_adamw_8bit; GPU: NVIDIA L4.
- Qwen3 düşünme modu kapalı (
enable_thinking=False); her cevap 🙃 ile biter.
Koruma katmanı
Modelden bağımsız koruma.py: Türkçe/İngilizce manipülasyon ve rol değiştirme kalıpları (gizlenmiş yazımlar dahil), kapsam dışı
istek reddi, kişisel veri maskeleme (e-posta, telefon, TC kimlik, kart, IBAN), sistem talimatı sızıntısı denetimi (tek cevapta ve
oturumlar arası birikimli), hız sınırı, tekrar engeli, günlük bütçe tavanı, devre kesici, önbellek, ajan döngü tespiti, ham metin
tutmayan olay kaydı.
Kullanım
from transformers import AutoTokenizer, AutoModelForCausalLMtok = AutoTokenizer.from_pretrained("dduraceii/HH-Asistan-1.7B")model = AutoModelForCausalLM.from_pretrained("dduraceii/HH-Asistan-1.7B", device_map="auto")mesajlar = [{"role": "user", "content": "Sen kimsin?"}]girdi = tok.apply_chat_template(mesajlar, add_generation_prompt=True, enable_thinking=False, return_tensors="pt", return_dict=True).to(model.device)print(tok.decode(model.generate(**girdi, max_new_tokens=120)[0, girdi["input_ids"].shape[1]:], skip_special_tokens=True))
RAG ve ajan kullanımı için GGUF deposundaki space/app.py dosyasına bakın.
Test soruları (rehber ve "yok" soruları → RAG, tablo ve araç soruları → ajan)
Table with columns: #, Soru, Kaynak, Yöntem, Cevap, Puan| # | Soru | Kaynak | Yöntem | Cevap | Puan |
|---|
| 1 | Hatay Handmade ne amaçlıyor? | rehber:1 Hatay Handmade Hakkında | RAG | Hatay Handmade, yerel üretim ve geleneksel el emeğini daha geniş kitlelerle buluşturmayı amaçlar. Bu, yerel ek… | 1.0 |
| 2 | Hatay Handmade hangi değerleri destekliyor? | rehber:2 Desteklenen Değerler | RAG | Kadın emeği ve el işçiliği, yerel ve doğal ürünler, geleneksel üretim ve el sanatları, ev üretimi ve yerel üre… | 0.5 |
| 3 | Ürünler hangi kaynaklardan temin edilebilir? | rehber:7 Üretim ve Tedarik Yapısı | RAG | Rehbere göre Hatay Handmade, ailelerin kendi ihtiyaçları için yaptığı üretimden arta kalan miktarı, mahalleler… | 1.0 |
| 4 | Yerel ve sınırlı miktarda üretilen ürünlerin sürekli bulunacağı garanti mi? | rehber:7 Üretim ve Tedarik Yapısı | RAG | Hayır, bu ürünlerin mevcut bütçeye göre satın alınabileceği için süreklilik garanti edilemeyebilir. 🙃 | 0.5 |
| 5 | Stokta olmayan, talep üzerine hazırlanan ürünlerde hazırlık süresi nasıl belirle… | rehber:9 Tedarik, Stok ve Hazırlanma Süresi | RAG | Rehbere göre stokta olmayan ürünler için "Stok geldiğinde haber ver" seçeneği sunulabilir. Ürünün hazırlanma k… | 0.5 |
| 6 | Ürün satış fiyatı nasıl oluşturuluyor? | rehber:10 Fiyatlandırma | RAG | Rehbere göre satış fiyatı üreticinin belirlediği başlangıç fiyatından ve paketleme, kargolama gibi maliyetlerd… | 0.5 |
| 7 | Yağ, cam ve neme duyarlı ürünler nasıl paketleniyor? | rehber:11 Paketleme ve Kargo | RAG | Hatay Handmade, ürünlerin özelliklerine göre uygun yöntemleri kullanır. Sızan ürün başka ürünlere zarar verebi… | 1.0 |
| 8 | Ürün hasarlı veya kusurlu geldiyse nasıl ilerleniyor? | rehber:12 Müşteri Memnuniyeti ve Telafi | RAG | Hasarlı veya kusurlu ürünlerde öncelikle uygun bir telafi çözümü değerlendirilir. Telafi yöntemi ürünün durumu… | 0.5 |
| 9 | Chatbot kişiye özel sipariş bilgilerini paylaşabilir mi; emin olmadığı durumda n… | rehber:13 Sipariş Takibi, Destek ve Asistanın Sınırları | RAG | Hayır, kişisel bilgilerin paylaşılmasına izin verilmez. Sipariş bilgileri, ürün ve satış koşullarının açıkça t… | 0.5 |
| 10 | Sentetik demo katalogda Kekik - 100g ürününün fiyatı ve stok miktarı nedir? | tablo | Ajan (urun_bilgisi) | Demo katalogda Kekik - 100g için: 100 g, 12 adet stok; fiyatı 95 TL (sentetik demo). 🙃 | 1.0 |
| 11 | Sentetik demo katalog fiyatlarıyla Kekik - 100g ürününden 2 paket ve Defne yapra… | tablo + hesap | Ajan (sepet_toplami_hesapla) | Demo katalog fiyatlarıyla 2 adet Kekik - 100g ve 1 adet Defne yaprağı - 50g için sentetik toplam 285.0 TL. 🙃 | 1.0 |
| 12 | Yurt dışına gönderim yapıyor musunuz? | yok | RAG | Bu bilgi rehberde yok. Kesin bilgi için Hatay Handmade desteğine danışabilirsiniz. | 1.0 |
| 13 | Hasarlı ürün bildirimi için kaç gün içinde başvuru yapılmalı? | yok | RAG | Bu bilgi rehberde yok. Kesin bilgi için Hatay Handmade desteğine danışabilirsiniz. | 1.0 |
| 14 | Kekik - 100g ürününden 2 paket ve Defne yaprağı - 50g ürününden 1 paket için sen… | araç: sepet_toplami_hesapla | Ajan (sepet_toplami_hesapla) | Demo katalog verileriyle 2 adet Kekik - 100g ve 1 adet Defne yaprağı - 50g için sentetik toplam 285.0 TL. 🙃 | 1.0 |
| 15 | Baş biber - 20adet ürününden 1 paket ve Defne sabunu - 1kg ürününden 2 paket içi… | araç: sepet_toplami_hesapla | Ajan (sepet_toplami_hesapla) | Demo katalog verileriyle 1 baş biber - 20adet ve 2 defne sabunu - 1kg için sentetik toplam 1490.0 TL. 🙃 | 1.0 |
Test soruları ortalaması (Gemini hakem): 0,80
Bilinen eksikler ve iyileştirme planı
Table with columns: #, Alan, Eksik, Öneri, Öncelik| # | Alan | Eksik | Öneri | Öncelik |
|---|
| 1 | Ajan | Araç seçimi çalıştırmadan çalıştırmaya değişiyor (Kekik sorusunda rehberde_ara) | Ürün adı geçen doğal sorularla urun_bilgisi örneklerini çeşitlendirmek | Yüksek |
| 2 | Ajan | Bazen içi boş son cevap ("bu bilgi rehberde mevcut") | Son cevap örneklerinde bilgiyi aktarmayı zorunlu kılmak | Yüksek |
| 3 | Kimlik | İngilizce soruda taban kimlik sızıyor; veda ve kapsam dışı cevaplarda ad geçmiyor | İngilizce ve çok dilli kimlik örneklerini artırmak | Orta |
| 4 | Rehber | Cevabı "hayır" ya da "belirsiz" olan sık sorular (yurt dışı, iade süresi) yazılı değil | Rehbere açık cümleler eklemek | Yüksek |
| 5 | Veri | Fiyat ve stoklar sentetik; 79 varyantın fiyatı doğrulanmamış | Gerçek katalogla değiştirmek (yeniden eğitim gerekmez) | Yüksek |
| 6 | Sohbet | Tek turlu; önceki mesajı hatırlamıyor | Kısa ve korumalı sohbet geçmişi, çok turlu eğitim örnekleri | Orta |
| 7 | Arama | Sitede TF-IDF eş anlamlılarda zayıf | Hafif bir embedding modeli ya da hibrit arama | Orta |
| 8 | Model | 1.7B küçük; uydurma eğilimi ve kararsızlık | 3B/4B taban model (GPU'lu Space ya da PRO ile) | Orta |
| 9 | Ölçüm | Test seti küçük (13 RAG, 15 CSV sorusu); hakem puanı değişken | Daha büyük test seti, birden çok çalıştırmanın ortalaması | Orta |
| 10 | Güvenlik | Koruma kural tabanlı; sayaçlar bellekte, sunucu yeniden başlayınca sıfırlanıyor | Saldırı sınıflandırıcısı (Prompt Guard), kalıcı sayaçlar | Orta |
| 11 | Hukuk | Demo bilgilendirme metni var, resmî KVKK aydınlatma metni yok | Hukukçu kontrolünde aydınlatma metni | Yüksek (canlıya geçmeden önce) |
| 12 | Maliyet | Ücretli model için kimlik doğrulama ve sağlayıcı tarafında harcama tavanı yok | Giriş zorunluluğu, hesap kotası, konsolda bütçe uyarısı | Yüksek (ücretli modelde) |
| 13 | Evrensellik | Adım 45–59 HH'ye özel; tablo aracı HH sütunlarına bağlı | Standart 3 dosya ve ayar hücresiyle genel şablon; Kivi Elektronik paketiyle kanıt | Orta |
| 14 | Site | Kendi Space'imiz yok (PRO gerekli) | PRO ile kendi hesabında yayın | Düşük |
Adım listesi
Defterin her adımı (araç, kaynak/konum, işlev, açıklama): HH_Adim_Listesi.md · CSV, süre ve evrensel/HH'ye özel bilgisiyle
Kullanıcı Bilgilendirme Metni
Bu asistan nedir? HH Asistan, Tech Istanbul Uygulamalı Yapay Zekâ Geliştirme Bootcamp'i bitirme projesi
kapsamında geliştirilmiş bir demodur. Hatay Handmade'in resmî müşteri hizmetleri kanalı değildir.
Bilgiyi nereden alır? Hatay Handmade rehberinden (14 bölüm) ve sentetik demo ürün kataloğundan. Fiyat ve stoklar
gerçek değildir. Asistan internete bağlanmaz; rehberde olmayan konularda "Bu bilgi rehberde yok" der.
Neleri yapamaz? Sipariş oluşturamaz, ödeme alamaz, iade veya telafi işlemi başlatamaz; sipariş durumunu ve
kişisel hesap bilgilerini göremez. Önceki mesajları hatırlamaz; her mesaj ayrı yanıtlanır. Küçük bir dil modelidir
(1.7 milyar parametre) ve hata yapabilir. Önemli konularda Hatay Handmade desteğine danışın.
Verileriniz: Lütfen ad, telefon, e-posta, TC kimlik, kart veya IBAN gibi kişisel bilgiler paylaşmayın.
Paylaşırsanız sistem bunları otomatik olarak maskeler ve modele göndermez. Sohbet içerikleri uygulama tarafından
kaydedilmez; yalnızca kimliksiz güvenlik sayaçları ve mesajların geri döndürülemez özetleri geçici olarak bellekte
tutulur. Barındırma platformu (Hugging Face) kendi sunucu kayıtlarını kendi politikasına göre tutabilir.
Üçüncü taraflar: Asistan çalışırken mesajlarınızı harici bir yapay zekâ servisine göndermez; model sunucuda
çalışır. (Gemini yalnızca geliştirme sırasında cevap kalitesini ölçmek için kullanıldı.)
Kötüye kullanım: Talimatları değiştirme, iç yapılandırmayı açığa çıkarma ya da kapsam dışı kullanım
girişimleri otomatik olarak engellenir; çok sık gönderilen istekler sınırlandırılır.
Bu metin bir demo için hazırlanmış bilgilendirmedir; resmî KVKK aydınlatma metni yerine geçmez.