Mawrooth-ALLaM-7B-LoRA API & Inference Endpoint

📋 نظرة عامة

مَوروث هو نظام ذكاء اصطناعي لشرح الأبيات النبطية، يُخرج كل شرح بخمسة أقسام منظمة:

Table with columns: القسم, الوصف
القسم	الوصف
`[المفردات]`	معاني الكلمات الصعبة
`[تحليل البيت]`	تفكيك المعنى خطوة بخطوة
`[السياق الثقافي]`	المعلومة التراثية
`[الشرح]`	المعنى الكامل
`[الوصف]`	وصف بصري بالإنجليزية

🚀 الاستخدام

1) التثبيت

bash
pip install transformers>=4.46 peft>=0.13 bitsandbytes>=0.44 accelerate>=1.0 huggingface_hub sentencepiece

2) تحميل النموذج + LoRA

python
import torch
import json
import re
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel
from huggingface_hub import hf_hub_download

# ========== الإعدادات ==========
BASE_MODEL = "humain-ai/ALLaM-7B-Instruct-preview"
LORA_REPO  = "NorahAlobaied/Mawrooth-ALLaM-7B-LoRA"
DICT_REPO  = "NorahAlobaied/Mawrooth-ALLaM-7B"

# ========== 1) تحميل القاموس ==========
dict_path = hf_hub_download(
    repo_id=DICT_REPO,
    filename="mawrooth_dictionary.json",
    repo_type="model",
)
with open(dict_path, encoding='utf-8') as f:
    DICTIONARY = json.load(f)
print(f"📚 القاموس: {len(DICTIONARY)} مصطلح")

# ========== 2) تحميل Base (4-bit) ==========
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(BASE_MODEL, trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

base = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)

# ========== 3) تحميل LoRA ==========
model = PeftModel.from_pretrained(base, LORA_REPO)
model.eval()
model.config.use_cache = True

print("✅ النموذج + LoRA جاهزان")

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

python
SYSTEM_PROMPT = """أنت خبير في الشعر النبطي السعودي، تفهم اللهجة والثقافة البدوية بعمق.

مهمتك: شرح الأبيات النبطية بدقة ووضوح.

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

أمثلة على الممنوع:
❌ اختراع بئر أو مكان غير موجود
❌ ذكر قبائل لم تُذكر في البيت
❌ معلومات جغرافية خاطئة

أمثلة على المسموح:
✅ وصف عام للبيئة الصحراوية
✅ عادات بدوية معروفة
✅ معاني المفردات من القاموس"""

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

def extract_terms(verse, dictionary, max_terms=20):
    """مطابقة كلمة كاملة فقط (لا substring)"""
    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
التقنية: QLoRA (4-bit)
رتبة LoRA(r): 16
lora_alpha: 32
lora_dropout: 0.05
الطبقات المستهدفة: q_proj, k_proj, v_proj, o_proj
عدد الأمثلة: 586 | 527 تدريب | 59 تحقق
عدد الخطوات: 80
Token Accuracy: 85.75%
Train Loss: 0.716
Validation Loss: 0.711
حجم LoRA: 65 MB
لا يوجد Overfitting: eval_loss (0.711) ≈ train_loss (0.716)

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

markdown
[بيت نبطي]
    ↓
[extract_terms] ← استخراج المصطلحات من القاموس
    ↓
[build_prompt] ← تكوين prompt مع القاموس المُصفّى
    ↓
[ALLaM-7B (4-bit)] + [Mawrooth LoRA (fp16)]
    ↓
[5 أقسام]: مفردات، تحليل، سياق، شرح، وصف

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

· الحجم: 1,328 مصطلح متخصص · يشمل: مفردات نبطية، أسماء نجوم، أدوات قهوة، أسماء إبل، ظواهر جوية، مواقع جغرافية · متوفر في: NorahAlobaied/Mawrooth-ALLaM-7B باسم mawrooth_dictionary.json

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

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

المصادر المرجعية:

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

المعالجة والهندسة:

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

التحقق النهائي: مراجعة كل مصطلح واستبعاد غير الموثوق.

🎓 أمثلة على المخرجات

مثال 1

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

المخرجات:

markdown
[المفردات] صحصح: الأرض المستوية الواسعة. قفا: ظهر الشيء. الترس: الدرع. مقلوب: معكوس.

[تحليل البيت] الصحراء الواسعة الممتدة كأنها ظهر درع مقلوب، الاستواء التام بلا معالم.

[السياق الثقافي] تشبيه الصحراء بظهر الدرع يعكس دقة الوصف البدوي للفراغ الواسع.

[الشرح] صحراء ممتدة ومسطحة لدرجة أنها تشبه ظهر درع مقلوب، لا نهاية لها ولا معالم.

[الوصف] A vast, flat desert plain stretching endlessly, smooth like the back of an upturned shield. (Cinematic lighting, traditional Arabian concept art, atmospheric, muted desert palette, ultra-detailed)

مثال 2

البيت: ياما حلا الفنجال مع سيحة البال

المخرجات:

markdown
[المفردات] حلا: جمال وحلاوة. الفنجال: فنجان القهوة العربية. سيحة البال: سعة الصدر والراحة النفسية.

[تحليل البيت] الفنجال هو فنجان القهوة العربية، وسيحة البال تعني الراحة النفسية وسعة الصدر، والمعنى أن شرب القهوة مع راحة البال أجمل شيء.

[السياق الثقافي] شرب القهوة مع الأهل والأصدقاء من أبرز مظاهر الكرم والضيافة عند البدو، وهي رمز للألفة والمودة بين الناس.

[الشرح] إن شرب القهوة مع راحة البال أجمل شيء.

[الوصف] A Bedouin pouring a cup of coffee for his guest, both smiling and enjoying the moment together in a cozy tent under a starry night sky. (Cinematic lighting, traditional Arabian concept art, digital painting, atmospheric, muted desert palette)

✒️ الاقتباس

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

🔗 روابط ذات صلة

📊 مجموعة البيانات: NorahAlobaied/Mawrooth-Nabati-Dataset
🤖 النموذج الأساسي: humain-ai/ALLaM-7B-Instruct-preview

📧 التواصل

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

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

القسم

الوصف

[المفردات]

معاني الكلمات الصعبة

[تحليل البيت]

تفكيك المعنى خطوة بخطوة

[السياق الثقافي]

المعلومة التراثية

[الشرح]

المعنى الكامل

[الوصف]

وصف بصري بالإنجليزية

python

import torch
import json
import re
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel
from huggingface_hub import hf_hub_download

# ========== الإعدادات ==========
BASE_MODEL = "humain-ai/ALLaM-7B-Instruct-preview"
LORA_REPO  = "NorahAlobaied/Mawrooth-ALLaM-7B-LoRA"
DICT_REPO  = "NorahAlobaied/Mawrooth-ALLaM-7B"

# ========== 1) تحميل القاموس ==========
dict_path = hf_hub_download(
    repo_id=DICT_REPO,
    filename="mawrooth_dictionary.json",
    repo_type="model",
)
with open(dict_path, encoding='utf-8') as f:
    DICTIONARY = json.load(f)
print(f"📚 القاموس: {len(DICTIONARY)} مصطلح")

# ========== 2) تحميل Base (4-bit) ==========
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(BASE_MODEL, trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

base = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)

# ========== 3) تحميل LoRA ==========
model = PeftModel.from_pretrained(base, LORA_REPO)
model.eval()
model.config.use_cache = True

print("✅ النموذج + LoRA جاهزان")

python

SYSTEM_PROMPT = """أنت خبير في الشعر النبطي السعودي، تفهم اللهجة والثقافة البدوية بعمق.

مهمتك: شرح الأبيات النبطية بدقة ووضوح.

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

أمثلة على الممنوع:
❌ اختراع بئر أو مكان غير موجود
❌ ذكر قبائل لم تُذكر في البيت
❌ معلومات جغرافية خاطئة

أمثلة على المسموح:
✅ وصف عام للبيئة الصحراوية
✅ عادات بدوية معروفة
✅ معاني المفردات من القاموس"""

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

def extract_terms(verse, dictionary, max_terms=20):
    """مطابقة كلمة كاملة فقط (لا substring)"""
    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)

markdown

[بيت نبطي]
    ↓
[extract_terms] ← استخراج المصطلحات من القاموس
    ↓
[build_prompt] ← تكوين prompt مع القاموس المُصفّى
    ↓
[ALLaM-7B (4-bit)] + [Mawrooth LoRA (fp16)]
    ↓
[5 أقسام]: مفردات، تحليل، سياق، شرح، وصف

markdown

[المفردات] صحصح: الأرض المستوية الواسعة. قفا: ظهر الشيء. الترس: الدرع. مقلوب: معكوس.

[تحليل البيت] الصحراء الواسعة الممتدة كأنها ظهر درع مقلوب، الاستواء التام بلا معالم.

[السياق الثقافي] تشبيه الصحراء بظهر الدرع يعكس دقة الوصف البدوي للفراغ الواسع.

[الشرح] صحراء ممتدة ومسطحة لدرجة أنها تشبه ظهر درع مقلوب، لا نهاية لها ولا معالم.

[الوصف] A vast, flat desert plain stretching endlessly, smooth like the back of an upturned shield. (Cinematic lighting, traditional Arabian concept art, atmospheric, muted desert palette, ultra-detailed)

markdown

[المفردات] حلا: جمال وحلاوة. الفنجال: فنجان القهوة العربية. سيحة البال: سعة الصدر والراحة النفسية.

[تحليل البيت] الفنجال هو فنجان القهوة العربية، وسيحة البال تعني الراحة النفسية وسعة الصدر، والمعنى أن شرب القهوة مع راحة البال أجمل شيء.

[السياق الثقافي] شرب القهوة مع الأهل والأصدقاء من أبرز مظاهر الكرم والضيافة عند البدو، وهي رمز للألفة والمودة بين الناس.

[الشرح] إن شرب القهوة مع راحة البال أجمل شيء.

[الوصف] A Bedouin pouring a cup of coffee for his guest, both smiling and enjoying the moment together in a cozy tent under a starry night sky. (Cinematic lighting, traditional Arabian concept art, digital painting, atmospheric, muted desert palette)

bibtex

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

Mawrooth-ALLaM-7B-LoRA

README

📋 نظرة عامة

🚀 الاستخدام

1) التثبيت

2) تحميل النموذج + LoRA

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

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

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

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

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

🎓 أمثلة على المخرجات

✒️ الاقتباس

📧 التواصل

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

Explore FriendliAI today

README

📋 نظرة عامة

🚀 الاستخدام

1) التثبيت

2) تحميل النموذج + LoRA

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

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

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

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

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

🎓 أمثلة على المخرجات

✒️ الاقتباس

📧 التواصل

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