AlienTurk/Turkish-Asistant-gguf

Mira Turkish Assistant v6N (Qwen2.5-3B-IT-TR) — Doğal Dil SFT

v6N = v6 Natural. Bu sürüm JSON artefaktı içermez. Model, eğitim sırasında doğrudan doğal Türkçe yanıt üretmeyi öğrendi. Yapısal veri (intent, datetime, task_id) çıkarımı Hybrid NLP Engine tarafından runtime'da paralel olarak yapılır.

Bu model Qwen2.5-3B-Instruct baz modeli üzerine Unsloth + TRL ile ince ayar yapılmış, doğal dil SFT (Supervised Fine-Tuning) ile eğitilmiş Türkçe kişisel asistan modelidir.

JSON mimarisi (v5_hybrid, v5.1) terk edilmiştir. Bunun yerine:

• LLM: Doğal Türkçe yanıt üretir (assistant_text)
• NLPEngine: Paralel olarak regex/heuristik tabanlı intent/taskTitle/datetime çıkarır
• Engine guard'lar: Title recovery, notal override, multi-turn confirmation, P33 disambiguation

Engine guard'lar LLM çıktısını sadece gerekli durumlarda override eder (saat uydurma, not-al semantik, P33 listeleme). Normal akışta LLM'in doğal yanıtı kullanıcıya ulaşır.

v6N vs v5.1 — Temel Farklar

Özellik	v5.1 (eski)	v6N (bu)
Çıktı formatı	JSON şeması ({intent, task_id, ...})	Doğal Türkçe metin
JSON artefaktı	Olabilir (3B model ara sıra JSON dışı çıktı)	Yok (sadece doğal dil öğretildi)
Yapısal veri	LLM üretir	NLPEngine paralel çıkarır
Senaryo 1.4 reply	LLM kendi yazıyordu (format değişken)	"Yarın saat 10:00 X için hatırlatıcın 1 saat önce kuruldu." (sabit)
Senaryo 2/1.5 "not al"	NLPEngine fallback	"Yarın için X görevi kuruldu." (Senaryo 1.5 template)
Senaryo 1.3 offset	Default 1 saat	"30 dakika/saat/gün önce" kullanıcı verisine göre
11:30/12:30 tokenizasyon	Zayıf	12 varyasyon eğitildi
P33 disambiguation	Engine + LLM clarification	Engine + K15 training
Dataset	712 dialog (JSON)	757 dialog (doğal dil)
Pack	JSON: {messages, _meta}	Doğal dil: {messages} (meta strip)

Model Detayları

• Base model: Qwen/Qwen2.5-3B-Instruct
• Fine-tune yöntemi: QLoRA (r=16, alpha=32, target_modules: q,k,v,o,gate,up,down)
• Veri seti: 757 unique doğal Türkçe diyalog (SFT, ChatML format, 17 K-seri)
• Eğitim: 3 epoch, validation split %8, early stopping (patience=2, threshold=0.005), LR=3e-5 (QLoRA için orta yol), cosine_with_restarts scheduler, packing=True
• Framework: Unsloth + Transformers + TRL (Google Colab L4 GPU)
• Quantization: Q4_K_M (~1.93 GB)
• Context window: 1024 token (eğitim), 2048 token (runtime iOS), 768 token (Android)

Mimari: LLM + Hybrid NLP Engine

User mesajı
  ↓
LLM (Qwen2.5-3B v6N) ← ─ → NLPEngine (rule-based) [paralel]
  ↓                              ↓
Doğal yanıt                Intent + taskTitle + datetime
  ↓                              ↓
  └────── → ActionDispatcher → DB + notification

• LLM kişilik, doğal konuşma, onay formatı, saat sorusu sorma, P33 clarification
• NLPEngine tarih/saat parse, intent sınıflandırma, title extraction
• ActionDispatcher DB insert/update/delete + notification schedule/cancel + P33 disambiguation
• Engine guard'lar (mimari seviye, fine-tune gerekmez): TimeFabricationGuard, NotAlOverrideGuard, ChatUpdateCancelRecoveryGuard, MultiTurnConfirmationRecoveryGuard

Kullanım

llama.cpp ile (komut satırı)

llama.cpp/main -m qwen2.5-3b-it-tr-asistant-v6N.Q4_K_M.gguf \
  -c 2048 \
  -n 512 \
  --threads 3 \
  -p "<|im_start|>system\nSen Türkçe kişisel asistansın. BUGÜN: 14 Haziran 2026, Pazar.<|im_end|>\n<|im_start|>user\nYarın saat 14'te fatura ödemeyi unutma.<|im_end|>\n<|im_start|>assistant\n"

llama-cpp-python ile (doğal dil — JSON yok)

from llama_cpp import Llama
from datetime import datetime

llm = Llama(
    model_path="qwen2.5-3b-it-tr-asistant-v6N.Q4_K_M.gguf",
    n_threads=3,
    n_ctx=2048,
)

today_str = "14 Haziran 2026, Pazar"
SYSTEM_PROMPT = f"""Sen son derece yardımcı, nazik, empatik ve organize bir Türkçe kişisel asistansın.
BUGÜN: {today_str}.
Temel görevlerin:
- Kullanıcıyla doğal, samimi ve akıcı bir sohbet kurmak.
- Kullanıcının görevlerini, randevularını ve hatırlatıcılarını yönetmek.
- Detaylar (özellikle saat) eksikse kibarca sor. Detaylar netse, işlemi yaptığınız doğal bir dille onayla.
- Asla ham JSON, kod bloğu veya teknik terimler kullanma. Sadece doğal Türkçe konuş."""

output = llm.create_chat_completion(
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": "Yarın saat 14'te fatura ödemeyi unutma."},
    ],
    max_tokens=256,
    stop=["<|im_end|>"],
)
print(output["choices"][0]["message"]["content"])
# Örnek çıktı: "Yarın saat 14:00 Fatura ödeme için hatırlatıcın 1 saat önce kuruldu."

Native çıktıda yapısal veri (NLPEngine tarafı — ayrı)

LLM doğal yanıt üretir; intent, taskTitle, datetime gibi yapısal alanlar Hybrid NLP Engine (lib/core/services/hybrid_nlp_engine.dart) tarafından runtime'da paralel olarak çıkarılır. Bu nedenle inference kodunuzda:

1. LLM'i doğal yanıt için kullanın (chat UI'a yazacağınız metin)
2. NLPEngine'i arka planda çalıştırın → DB aksiyonu (SET_REMINDER, ADD_TASK, vb.)
3. Engine guard'lar kritik durumlarda LLM çıktısını override eder (saat uydurma, P33 vb.)

Reply Formatları (docs/uygulama_kurallari.md)

Senaryo	Format	Örnek
1.1 (saat sorma)	"Anladım [Gün] '[Aktivite]' için hangi saatte hatırlatma istersiniz? Hatırlatıcı kurmamı isterseniz saat verin, sadece görev kaydetmek isterseniz 'not al' yazmanız yeterli."	"Anladım Pazartesi 'Kahve' için hangi saatte..."
1.2 (default 1 saat önce)	(kullanıcı süre vermedi → 1 saat)	—
1.3 (offset)	"[Gün] saat [HH:MM] [Aktivite] için hatırlatıcın [Süre] önce kuruldu."	"Yarın saat 10:00 Doktor için hatırlatıcın 30 dakika önce kuruldu."
1.4 (onay)	"[Gün] saat [HH:MM] [Aktivite] için hatırlatıcın [Süre] önce kuruldu."	"Yarın saat 12:00 Kahve için hatırlatıcın 1 saat önce kuruldu."
1.5 / Senaryo 2 ("not al")	"[Gün] için [Aktivite] görevi kuruldu."	"Pazartesi için Kahve görevi kuruldu."
3 (iptal onay)	"Tamam, '[Aktivite]' görevi silindi." / "korundu."	(dispatcher override eder)
4 (P33 disambiguation)	"Birden fazla '[Aktivite]' göreviniz var: 1) ... 2) ..."	(engine injection)
5 (UPDATE)	"[Gün] '[Aktivite]' '[Saat]' için [Süre] önce hatırlatacak şekilde güncellendi."	"Yarın 'Spor Salonu' '20:00' için 1 saat önce hatırlatacak şekilde güncellendi."

NOT: Senaryo 3 (iptal) ve Senaryo 5 (UPDATE) reply'leri runtime'da ActionDispatcher tarafından override edilir (Sprint 11 + Sprint 13 fix). LLM'in bu senaryolardaki doğal reply'i gösterilmez.

Eğitim Veri Seti (757 dialog)

Kısım	Açıklama	Adet
1	Persona & Selam (jenerik)	70
2	Tek-tur SET_REMINDER (7 domain × time × title) — Senaryo 1.4 format	220
3	Çok-turlu SET_REMINDER ("ne zaman?" → yanıt → kur) — Senaryo 1.4 format	140
4	ADD_TASK	41
5	LIST_TASKS + NAVIGATE	31
6	Negasyon / İptal (domain'ler arası)	30
7	Düzeltme / Güncelleme (narrative)	12
8	Genel sohbet (hava, motivasyon, günlük, teknoloji, kitap, film, yemek)	54
9	Karma uzun diyaloglar (5-8 turlu, domain'ler arası) — filter düzeltildi	24
10	Typo / STT dayanıklılık (tüm domain'lerde ağır bozulma) — Senaryo 1.4 format	40
11	"güncellendi" reply polish (UPDATE sonrası)	10
12	Empatik CHAT (duygusal içerik yanıtları)	15
13	UPDATE_TASK (saat güncelleme)	10
14	CANCEL_TASK (basit iptal)	10
15	CANCEL_TASK (ambiguous / clarification → P33)	5
16	"not al" saatsiz görev (Senaryo 2) — YENİ	25
17	"X dakika/saat/gün önce" offset (Senaryo 1.3) — YENİ	20

Domain dağılımı (7 domain): sağlık, iş/kariyer, finans/fatura, eğitim, seyahat/ulaşım, sosyal/kişisel, ev/günlük yaşam.

Tüm diyaloglar doğal Türkçedir. JSON şeması, intent alanı, task_id alanı yoktur. Asistan yalnızca konuşma metni üretir.

Engine Guard'lar (kod tarafı, fine-tune gerektirmez)

• TimeFabricationGuard — LLM saat uydurduğunda (kullanıcı saat vermedi) → saat sorma template'ı
• NotAlOverrideGuard — "not al" semantiği → saatsiz görev olarak işle
• MultiTurnConfirmationRecoveryGuard — Çok-turlu onay (CHAT veya SET_REMINDER+title null)
• ChatUpdateCancelRecoveryGuard — Multi-turn update/cancel + history-aware vazgeç
• P33 Disambiguation (task_id_resolver) — 2+ match'te kullanıcıya seçim listele

v6N Tasarım Kararları

1. JSON mimarisinin tamamen terk edilmesi: v5.1'de LLM'in JSON üretemediği durumlar (3B model "ecops", "turn", bozuk JSON) sıkça yaşanıyordu. v6N'da LLM sadece doğal dil öğrendi — bu sorun kaynağında çözüldü.
2. _meta artifact kaçağı olmaması: Generation sırasında intent/task_id analiz için _meta'da tutulur, ancak final_train_qwen_v8_natural.jsonl'e yazılmaz. Model bunları öğrenmez.
3. Senaryo 1.4 reply template sabit: K2, K3, K10 reply'leri tek fonksiyondan üretilir (_reminder_reply()), format drift riski yok.
4. Senaryo 2/1.5 (not al) K16 eklendi: Sprint 8 sim smoke'da tespit edilen "not al" pattern'inin LLM'in doğal reply formatı eğitildi. NLPEngine NotAlOverrideGuard ile mimari seviye fallback hâlâ aktif.
5. Senaryo 1.3 (offset) K17 eklendi: "30 dakika önce", "1 saat önce", "1 gün önce" gibi spesifik sürelerin LLM doğal reply formatı.
6. K9 sağlık senaryosu filter düzeltmesi: Önceki (t[0] in u2) yaklaşımı "önümüzdeki cuma 9'da" gibi ifadeleri bulamıyor, random fallback saat uyumsuzluğuna neden oluyordu. Yeni manuel eşleme (_HEALTH_TIME_MAP).
7. 11:30 / 12:30 tokenizasyon varyasyonları: "saat 12 30 dk önce hatırlat" gibi STT/parse sorunlarına doğrudan eğitim verisi ile müdahale.
8. packing=True (Unsloth): v7_natural'da packing=False idi, eğitim hızı düşüktü. v6N'da Unsloth performans önerisiyle True.
9. TRL DataCollatorForCompletionOnlyLM (built-in): Custom collator sınıfı kaldırıldı, TRL'in built-in maskeleme mekanizması kullanılıyor (daha az özel kod, aynı işlevsellik).

Sınırlamalar

Kapsam dışı istekler (model bunlara doğal CHAT yanıtı verir): yemek siparişi, web arama, hava durumu, müzik, e-posta, çeviri, taksi, telefon, SMS, haber, alışveriş (kendi market listesi hariç), banka, sosyal medya, video, borsa, kripto, matematik, tarif, kamera, şarkı sözü, bilet, döviz, şaka, akıllı ev, hikaye yazma.

STT gürbüzlüğü: Eğitim verisinde SMS kısaltmaları (yrn, sbh, aksm), Türkçe karakter düşmeleri (hastane→hastne, yarın→yrn), sesli harf kayıpları (dişçi→diş), devrik cümle, birleşik kelime (kanka, hocm), aşırı kısaltma (slm, tmm) için 40 örnek vardır (KISIM 10).

Negation tespiti: "Vazgeçtim", "istemiyorum", "yapma", "iptal", "gerek yok", "bırak" gibi 30+ diyalogla (KISIM 6) eğitildi; model bunları kalıcı olarak CHAT'e yönlendirir ve yeni SET_REMINDER üretmez.

Context: 1024 token (eğitim) / 2048 token (iOS runtime). Multi-turn diyalogda 5+ tur geçince eski bağlam düşebilir — KISIM 9 (karma 5-8 turlu diyaloglar) bu duruma karşı eğitildi. Runtime tarafında RAG injection ile aktif görev listesi prompt'a enjekte edilir.

Donanım Doğrulamaları (Mobile)

Cihaz	Backend	Threads	Context	Warm Response	RAM Kullanımı
POCO X4 GT (Dimensity 8100)	CPU	2	768	~6s	~3 GB (8 GB cihazda rahat)
iPhone 17 Pro (M3 Max sim)	CPU	6	2048	<2s	~2.5 GB unified memory

Vulkan backend Dimensity 8100 Android 14'te ggml_backend_alloc_ctx_tensors_from_buft SIGSEGV hatası veriyor (driver coopmat bug). OpenCL llama-cpp-dart 0.6.15'te implemente edilmiyor. NPU (APU 580) için llama.cpp backend'i yok.

Lisans

Apache 2.0 (Qwen2.5 base modeliyle uyumlu).

Atıf

@misc{mira-turkish-assistant-v6n-2026,
  author = {Algoritma Turk},
  title = {Mira Turkish Assistant v6N (Natural): Qwen2.5-3B Fine-tuned with Natural-Language SFT for Turkish Personal Assistant Tasks},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/AlienTurk/Turkish-Asistant-gguf}
}

Bağlantılar

• Base model: https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
• Quantized GGUF: https://huggingface.co/AlienTurk/Turkish-Asistant-gguf
• Fine-tune framework: Unsloth
• Mobil uygulama (runtime): Hybrid NLP Engine mimarisi