📖 مَوروث | Mawrooth

نموذج ذكاء اصطناعي لشرح الشعر النبطي السعودي بالاعتماد على قاموس متخصص وتقنية Chain-of-Thought.

📋 نظرة عامة

مَوروث هو نموذج مُدرَّب لشرح الأبيات النبطية بشكل احترافي، يُخرج كل شرح بخمسة أقسام:

🎯 المزايا

• ✅ عربية فصيحة — لا خلط لغات
• ✅ قاموس نبطي يحتوي ~1000 مصطلح
• ✅ لا اختراع معلومات — يستعين بالقاموس
• ✅ تحليل منطقي للبيت قبل الشرح
• ✅ وصف بصري جاهز لتوليد الصور

🚀 الاستخدام

⚠️ مهم جدًا — نوع النموذج

هذا المستودع يحتوي على نموذج مدموج (merged model). لذلك لا تستخدم PeftModel — استخدم AutoModelForCausalLM مباشرة.

التثبيت

!pip install transformers>=4.47.0 bitsandbytes>=0.44.0 accelerate>=1.2.0

كود التحميل

from huggingface_hub import hf_hub_download
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
import torch
import json

MODEL_ID = "NorahAlobaied/Mawrooth-ALLaM-7B"

# 1. تحميل النموذج المدموج
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=True,
)

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)
model.eval()

# 2. تحميل القاموس المرفق مع النموذج
dict_path = hf_hub_download(repo_id=MODEL_ID, filename="mawrooth_dictionary.json")
with open(dict_path, 'r', encoding='utf-8') as f:
    DICTIONARY = json.load(f)

print(f"✅ جاهز — {len(DICTIONARY)} مصطلح نبطي")

كود الاستدلال الكامل

import re

SYSTEM_PROMPT = """أنت خبير في الشعر النبطي السعودي.

قواعد:
1. استخدم القاموس لشرح المفردات الصعبة.
2. لا تخترع معلومات غير موجودة في البيت أو القاموس.
3. اتبع الترتيب بدقة:
   [المفردات] كلمة: معناها.
   [تحليل البيت] فكك البيت خطوة بخطوة.
   [السياق الثقافي] معلومة ثقافية عامة صحيحة.
   [الشرح] إعادة صياغة معنى البيت.
   [الوصف] English visual description.
4. اكتب بالعربية فقط، ما عدا [الوصف] فبالإنجليزية."""

STOPWORDS = {'في','من','على','إلى','مع','عن','هذا','هذه','اللي','كان','ما','لا','أن','إن','هو','هي','هم','ثم','أو','و','ف','ب','ل','يا','قد','كل','بعض','غير','بين','عند','اذا','لم','لن','له','لها','لهم','به','بها','بهم','منه','منها','منهم','هنا','هناك','الا','لكن','حتى'}

def extract_terms(verse, dictionary, max_terms=20):
    verse_words = set(re.findall(r'\b[\u0600-\u06FF]+\b', verse))
    found = {}
    for term, meaning in dictionary.items():
        if term in STOPWORDS or len(term) < 3:
            continue
        term_base = term.replace('ال', '', 1) if term.startswith('ال') else term
        if term in verse_words or term_base in verse_words:
            found[term] = meaning
            if len(found) >= max_terms:
                break
    return found

def build_prompt(verse):
    verse_clean = verse.replace('اشرح هذا البيت:', '').strip()
    terms = extract_terms(verse_clean, DICTIONARY)
    context = "\n".join([f"- {k}: {v}" for k, v in terms.items()]) if terms else "(لا توجد مصطلحات صعبة)"
    return f"""[القاموس المرجعي]
{context}

[المهمة]
اشرح هذا البيت: {verse_clean}

[التعليمات]
- ارجع للقاموس أعلاه.
- لا تخترع معلومات.
- اتبع الصيغة: [المفردات] [تحليل البيت] [السياق الثقافي] [الشرح] [الوصف]"""

def explain_verse(verse, max_tokens=500):
    user_prompt = build_prompt(verse)
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_prompt},
    ]
    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=2048).to("cuda")
    
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=max_tokens,
            temperature=0.3,
            top_p=0.9,
            repetition_penalty=1.15,
            do_sample=True,
            pad_token_id=tokenizer.pad_token_id,
            eos_token_id=tokenizer.eos_token_id,
        )
    return tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True).strip()

# مثال
result = explain_verse("مع صحصح كنه قفا الترس مقلوب")
print(result)

📊 تفاصيل التدريب

• النموذج الأساسي: humain-ai/ALLaM-7B-Instruct-preview
• التقنية: LoRA (r=16, alpha=32)
• البيانات: 587 مثال نبطي
• Token Accuracy: 85.75%
• Overfitting لا يوجد (eval ≈ train)
• اللغة عربية فصحى + لهجة نجدية

🏗️ البنية التقنية

[بيت نبطي] 
    ↓
[extract_terms] ← استخراج المفردات من القاموس
    ↓
[build_prompt] ← تكوين prompt مع القاموس المصغّر
    ↓
[Mawrooth Model] ← ALLaM-7B المدموج
    ↓
[5 أقسام]: مفردات، تحليل، سياق، شرح، وصف

📚 القاموس النبطي

· ~1000 مصطلح متخصص · يشمل: مفردات نبطية، أسماء نجوم، أدوات قهوة، أسماء إبل، ظواهر جوية · مرفق مع النموذج في mawrooth_dictionary.json

📖 مصادر بيانات المعجم وآلية الجمع (Lexicon Methodology)

تم بناء معجم المفردات النبطية عبر مراحل منظمة:

1. المصادر المرجعية (Data Sources)

• أمهات معاجم الألفاظ الشعبية والنبطية المعروفة.
• سياقات المفردات الواردة في دواوين القصائد التراثية المتداولة.
• المراجعة الشفهية من كبار السن المهتمين بالتراث النبطي.

2. المعالجة والهندسة (Data Processing)

• استخراج المفردات: استخلاص الكلمات الغريبة أو التراثية من النصوص الشعرية.
• التنقيب: تطبيق تقنيات معالجة اللغة الطبيعية (NLP) لضبط جذور الكلمات وتصنيفها.
• المراجعة البشرية: تحقق أعضاء الفريق يدويًا من كل معنى، بالتنسيق مع أدوات AI مساعدة للتحقق من الدقة.
• التصنيف السياقي: تنظيم المفردات في مجالات (طبيعة، قهوة، إبل، مشاعر، إلخ).

3. التحقق النهائي

• مراجعة كل مصطلح لضمان دقة الشرح والضبط اللغوي.
• استبعاد أي مدخل غير موثوق.

🎓 أمثلة

مثال 1

البيت: مع صحصح كنه قفا الترس مقلوب

المخرجات:

مثال 2

البيت: يا ذيب ضيعني سراب بصحاريك

المخرجات:

⚠️ ملاحظات مهمة

1. لا تستخدم PeftModel — النموذج مدموج
2. حمّل القاموس عبر hf_hub_download
3. يحتاج GPU — 4-bit على T4 كافٍ
4. الوصف بالإنجليزية — جاهز لتوليد الصور

✒️ الاقتباس

@misc{mawrooth2026,
  title={Mawrooth: Arabic Nabati Poetry Explainer},
  author={Mawrooth Team},
  for={Arabthon2026},
  year={2026},
  publisher={Hugging Face},
  howpublished={\url{https://huggingface.co/NorahAlobaied/Mawrooth-ALLaM-7B}}
}

📧 التواصل

للاستفسارات: [nourahalobaeid@gmail.com]

صُنع بـ ❤️ للتراث السعودي