ameer4wisam/gemma-iraqi-finetune-v2

📘 التوثيق الرسمي — نموذج Gemma للهجة العراقية (المدمج v2)

المستودع: ameer4wisam/gemma-iraqi-finetune-v2 (مدمج، جاهز مباشرة) نسخة الـ Adapter المنفصل: ameer4wisam/gemma-iraqi-finetune (للمطورين)

---

1. نظرة عامة

نموذج محادثة باللهجة العراقية مبني على google/gemma-4-E4B-it بتقنية LoRA ثم دُمج بالأوزان الأساسية (bf16). متخصص بمحادثات البيع والشراء والخدمات والحياة اليومية، ويلتزم بأسلوب الرد القصير المباشر للبائع العراقي.

| البند | القيمة | |---| | النموذج الأساسي | google/gemma-4-E4B-it | | التقنية | LoRA (r=16, alpha=32, dropout=0.05) ثم دمج bf16 | | الطبقات المستهدفة | q/k/v/o_proj + gate/up/down_proj (نموذج اللغة فقط، regex يستثني أبراج الرؤية/الصوت) | | بيانات التدريب | 163,429 محادثة تدريب / 10,330 تقييم (iraqi_train_v4) | | الحقب | 1 epoch (20,429 خطوة) | | معدل التعلم | 5e-5 | | حجم الدفعة | 8 (A100 40GB) | | النتائج | Validation Loss: 0.215 — Token Accuracy: 93.8% |

---

2. ⚙️ وصفة الاستدلال الإلزامية

هذه الإعدادات مثبتة بالاختبارات — أي انحراف عنها يُنتج مخرجات مشوهة (سلطة كلمات) رغم سلامة النموذج:

| الإعداد | القيمة | السبب | |---| | eos_token_id | يُكتشف تلقائياً من القالب (id=106 + eos) | كتابة اسم التوكن يدوياً ترجع UNK بصمت والتوليد لا يتوقف | | attn_implementation | "eager" | مطلوب لمعمارية E4B | | max_new_tokens | 64 | أجوبة بيانات التدريب قصيرة (10–30 توكن)؛ الطول الزائد = هذيان | | الوضع الافتراضي | do_sample=False (حتمي) | إلزامي لأي رد فيه أرقام/أسعار/حقائق | | الوضع الإبداعي | temperature=0.3, top_p=0.8, top_k=20 | للتحيات والدردشة فقط | | repetition_penalty | ❌ ممنوع نهائياً | يعاقب مفردات اللهجة المتكررة ويدفع لكلمات مخترعة | | temperature > 0.3 | ❌ ممنوع | التوزيع متخصص وضيق؛ العشوائية الواسعة تكسره |

مثال استدلال كامل (انسخه كما هو):

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

MODEL_ID = "ameer4wisam/gemma-iraqi-finetune-v2"
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID, torch_dtype=torch.bfloat16,
    device_map="auto", attn_implementation="eager",
).eval()

# اكتشاف توكن التوقف تلقائياً (لا تكتبه يدوياً)
_probe = tokenizer.apply_chat_template(
    [{"role": "user", "content": "هلو"},
     {"role": "assistant", "content": "هلا بيك"}],
    add_generation_prompt=False)
special = set(tokenizer.all_special_ids)
stop_ids = list({int(t) for t in _probe[-3:] if int(t) in special}
                | {tokenizer.eos_token_id})

def chat(messages, deterministic=True):
    enc = tokenizer.apply_chat_template(
        messages, add_generation_prompt=True,
        return_tensors="pt", return_dict=True)
    cfg = (dict(do_sample=False) if deterministic
           else dict(do_sample=True, temperature=0.3, top_p=0.8, top_k=20))
    out = model.generate(
        input_ids=enc["input_ids"].to(model.device),
        attention_mask=enc["attention_mask"].to(model.device),
        eos_token_id=stop_ids, max_new_tokens=64, **cfg)
    return tokenizer.decode(
        out[0][enc["input_ids"].shape[1]:],
        skip_special_tokens=True).strip()

---

3. 🧾 System Prompt الرسمي (بائع + كتالوج)

النموذج لم يُدرَّب على system prompts، لكن قدرة Gemma الأساسية تجعله يستجيب لها بشكل ممتاز (مثبت بالاختبار). القاعدة المعمارية: التعليمات السلوكية بالبرومبت، والحقائق (أسعار/منتجات) تُحقن ككتالوج صريح، والحسابات (خصومات/مجاميع) تُحسب بالكود مسبقاً وتُذكر جاهزة.

أنت بائع عراقي محترف بمحل أجهزة كهربائية.

المنتجات المتوفرة حالياً (التزم بيها حرفياً):
- [يُبنى ديناميكياً من قاعدة البيانات]
- خصم شراء قطعتين: 5% (المجموع بعد الخصم: [محسوب مسبقاً])

قواعد صارمة:
1. جاوب باللهجة العراقية الأصيلة فقط: شنو، شلون، هسه، اكو، ماكو، زين، خوش، شكد.
2. جاوب قصير ومباشر، جملة أو جملتين مثل البائع الحقيقي.
3. الأسعار والأرقام من القائمة أعلاه فقط - لا تخترع أي رقم.
4. بِع فقط المنتجات المذكورة بالقائمة. إذا طلب الزبون منتج غير موجود،
   گله بصراحة: "والله هذا ماكو عدنا هسه" واعرض البديل إذا مناسب.
5. تذكر تفاصيل الزبون (اسمه، شنو يريد) واستعملها بردودك.
6. إذا ما تعرف معلومة، گول "أتأكدلك" ولا تخترع جواب.

---

4. 📊 نتائج التحقق الموثقة

| الاختبار | النتيجة | |---| | محادثة مبيعات 12 دور (حتمي + كتالوج) | ✅ أسعار من الكتالوج، ثابتة عبر الأدوار، لهجة سليمة | | سياق طويل حتى 785 توكن (~4× أطول مثال تدريب) | ✅ لا تدهور — قدرة السياق من Gemma الأساسي | | تذكر اسم الزبون وطلبه بعد 5 أدوار | ✅ مع system prompt (بدونه يتذكر الطلب فقط) | | أسئلة متابعة بالسياق ("وتعطي خصم للاثنين؟") | ✅ يفهم المرجعية من المحادثة | | التحيات والمجاملات | ✅ طبيعية (أمثلة v4 المضافة) |

5. ⚠️ القيود المعروفة

1. الأرقام بدون كتالوج غير موثوقة — النموذج يولّد أسعاراً من توزيع التدريب. الحل: حقن الكتالوج بالسياق دائماً (إلزامي للإنتاج).
2. الحساب ضعيف — الخصومات والمجاميع تُحسب بالكود وتُحقن جاهزة، لا يُعتمد على النموذج.
3. العشوائية تفسد الحقائق — حتى 0.3 قد يُزحزح رقماً عن الكتالوج؛ الردود الحقائقية حتمية إجبارياً.
4. قد يبيع بديلاً بدل الرفض — بدون القاعدة 4 بالبرومبت، طلبُ منتجٍ غير متوفر قد يُقابَل بعرض منتج آخر وكأنه المطلوب.
5. القدرة العامة محدودة — متخصص بالبيع/الخدمات؛ خارج هذا النطاق الجودة تتفاوت.
6. لم يُدرَّب على system prompts — الاستجابة لها من Gemma الأساسي؛ قد تضعف مع برومبتات معقدة جداً.

6. 🔁 سجل الدروس التقنية (لإعادة التدريب مستقبلاً)

• لا تضع use_cache=False أبداً مع E4B (يفسد مشاركة KV بين الطبقات — transformers issue #45242). كذلك gradient_checkpointing=False إلزامي لنفس السبب.
• target_modules بقائمة صريحة عبر regex يستثني أبراج الرؤية/الصوت — وليس "all-linear".
• الدمج فوق bf16 فقط — الدمج فوق أوزان مكممة (4/8-bit) يراكم أخطاء ويخرب النموذج.
• بعد أي دمج: اختبار مقارنة حتمي قبل/بعد بنفس الأسئلة (E4B حساسة معمارياً).
• لبيانات v5 المقترحة: أمثلة رفض، أمثلة التزام بكتالوج محقون، أمثلة تذكّر تفاصيل الزبون، محادثات أطول (400–800 توكن).