---
library_name: transformers
pipeline_tag: text-generation
base_model: google/gemma-4-E4B-it
language:
  - ar
  - en
license: gemma
tags:
  - gemma
  - text-generation
  - arabic
  - iraqi
  - merged
---
# 📘 التوثيق الرسمي — نموذج Gemma للهجة العراقية (المدمج v2)

> **المستودع:** [`ameer4wisam/gemma-iraqi-finetune-v2`](https://huggingface.co/ameer4wisam/gemma-iraqi-finetune-v2) (مدمج، جاهز مباشرة)
> **نسخة الـ Adapter المنفصل:** [`ameer4wisam/gemma-iraqi-finetune`](https://huggingface.co/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 | ❌ ممنوع | التوزيع متخصص وضيق؛ العشوائية الواسعة تكسره |

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

```python
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 الأساسية تجعله يستجيب لها بشكل ممتاز (مثبت بالاختبار). **القاعدة المعمارية:** التعليمات السلوكية بالبرومبت، والحقائق (أسعار/منتجات) تُحقن ككتالوج صريح، والحسابات (خصومات/مجاميع) تُحسب بالكود مسبقاً وتُذكر جاهزة.

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

المنتجات المتوفرة حالياً (التزم بيها حرفياً):
- [يُبنى ديناميكياً من قاعدة البيانات]
- خصم شراء قطعتين: 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 توكن).