📘 التوثيق الرسمي — نموذج Gemma للهجة العراقية (المدمج v2)
المستودع:
ameer4wisam/gemma-iraqi-finetune-v2(مدمج، جاهز مباشرة) نسخة الـ Adapter المنفصل:ameer4wisam/gemma-iraqi-finetune(للمطورين)
1. نظرة عامة
نموذج محادثة باللهجة العراقية مبني على google/gemma-4-E12B-it بتقنية LoRA ثم دُمج بالأوزان الأساسية (bf16). متخصص بمحادثات البيع والشراء والخدمات والحياة اليومية، ويلتزم بأسلوب الرد القصير المباشر للبائع العراقي.
| البند | القيمة |
|---|
| النموذج الأساسي | google/gemma-4-E12B-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. ⚠️ القيود المعروفة
- الأرقام بدون كتالوج غير موثوقة — النموذج يولّد أسعاراً من توزيع التدريب. الحل: حقن الكتالوج بالسياق دائماً (إلزامي للإنتاج).
- الحساب ضعيف — الخصومات والمجاميع تُحسب بالكود وتُحقن جاهزة، لا يُعتمد على النموذج.
- العشوائية تفسد الحقائق — حتى 0.3 قد يُزحزح رقماً عن الكتالوج؛ الردود الحقائقية حتمية إجبارياً.
- قد يبيع بديلاً بدل الرفض — بدون القاعدة 4 بالبرومبت، طلبُ منتجٍ غير متوفر قد يُقابَل بعرض منتج آخر وكأنه المطلوب.
- القدرة العامة محدودة — متخصص بالبيع/الخدمات؛ خارج هذا النطاق الجودة تتفاوت.
- لم يُدرَّب على 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 توكن).