MasryGPT Chat — Egyptian Dialect Conversational AI 🇪🇬

Naming note: The repository name is retained for backward compatibility; the recommended project title is MasryGPT Chat. Try the model: Open MasryGPT_Chat_Test.ipynb in Colab with a T4 GPU, or follow TESTING.md.

Qwen2.5-1.5B-Instruct • Fine-tuned for Egyptian Arabic (Masry) • QLoRA + Unsloth

80,000 Egyptian terms • 2,500 steps • Loss 0.079 • 2.9GB 16-bit Merged

English | بالمصري

🇬🇧 English - Professional Documentation

Table of Contents

1. Project Overview
2. Motivation
3. Model Details
4. Dataset
5. Training Pipeline & Deep Analysis
6. Evaluation & Benchmarks
7. Usage
8. Limitations & Error Analysis
9. Ethics & Bias
10. Roadmap
11. File Structure
12. Citation & Contribution

1. Project Overview

MasryGPT Chat is an experimental open-source Egyptian Arabic (Masry / عامية القاهرة) chat model based on Qwen2.5-1.5B-Instruct. This project explores the gap between Modern Standard Arabic and authentic Egyptian daily speech, humor, and idioms. The results below are an internal pilot and are not an independent benchmark.

Goal: Build a lightweight (1.5B), fast, and deployable model that speaks like an Egyptian — not a textbook — for chatbots, customer service, social media, and education in Egypt.

Internal pilot result: After 1 epoch on 80k Egyptian examples, training loss moved from 0.091 → 0.074 (-18.7%) with an average of 0.079. A 100-prompt internal review by 3 native speakers reported 4.6/5 for Egyptian-dialect fluency; this is not an independent benchmark. Inference is ready for a single T4 in 4-bit mode (about 1.2GB VRAM).

2. Motivation

• MSA vs Dialect Gap: Existing Arabic LLMs (Qwen, Jais, AceGPT) optimize for MSA, but 105M Egyptians speak Masry daily. "ازيك" vs "كيف حالك" — difference is cultural.
• Lightweight Deployment: 7B models need 14GB+ VRAM. 1.5B runs on mobile/T4/edge, perfect for startups in Egypt with limited GPU.
• Unsloth Efficiency: 2x faster fine-tuning on free Kaggle T4 x2 without A100.

3. Model Details

4. Dataset

Name: qwen_egyptian_80k_terms.jsonl — 80,000 examples

Source & Curation:

• Synthetic generation from Egyptian lexicon + manual filtering of vulgarity.
• Format: {"messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "مصري..."}]}
• Preprocessing: get_chat_template(tokenizer, chat_template="qwen-2.5") + tokenizer.apply_chat_template(..., tokenize=False) → field text with packing.

Distribution:

• Greetings & Daily Chat: 35%
• Humor & Jokes: 15%
• Expressions & Idioms: 15%
• Customer Service & Instructions: 20%
• Culture & Food: 15%

Example:

{"messages": [{"role": "user", "content": "يعني ايه عيش وملح؟"}, {"role": "assistant", "content": "عيش وملح يعني العشرة والعهد بين الصحاب، اللي كل معاك عيش وملح ميخونكش"}]}

Preprocessing Code:

from datasets import load_dataset
from unsloth import get_chat_template
tokenizer = get_chat_template(tokenizer, chat_template="qwen-2.5")
def formatting_prompts_func(examples):
    convos = examples["messages"]
    texts = [tokenizer.apply_chat_template(c, tokenize=False, add_generation_prompt=False) for c in convos]
    return {"text": texts}
dataset = dataset.map(formatting_prompts_func, batched=True)

5. Training Pipeline & Deep Analysis

Pipeline: Hugging Face Hub (ISLAM-PO/MasryGPT) → FastLanguageModel.from_pretrained (4bit) → get_peft_model (QLoRA) → SFTTrainer (TRL) → save_pretrained_merged (16bit) → Hugging Face

Hyperparameters (Final Fast Config — Kaggle T4 x2):

Deep Loss Analysis (2,500 steps, 2h13m):

Step 10: 0.091025
Step 100: 0.098729 → initial spike (warmup)
Step 500: 0.082923
Step 1000: 0.081538
Step 1500: 0.077019
Step 2000: 0.074811
Step 2500: 0.074394
Avg: 0.07995 | Perplexity exp(0.079) ≈ 1.083

• Convergence: Smooth 18.7% drop, no divergence. Loss stabilizes at 0.074-0.077 after step 1500 → model saturated on 80k. More epochs would overfit.
• FLOPs: 1.05e17 total → ~13.1 TFLOPs/s on T4.
• Throughput: 10.002 samples/sec, 0.313 steps/sec (Unsloth 2x faster vs vanilla).
• GPU Utilization: 2.4GB/15GB (GPU0 93%) + 4.1GB/15GB (GPU1 51%) — low memory is feature of 4-bit + Unsloth, not bug. Compute is high, memory is low.
• CPU 100%, RAM 6-7GB — CPU is bottleneck for tokenization, not GPU.

Why Not 10GB VRAM? 1.5B 4-bit quantized weights = 0.8GB. Even batch 32 only adds ~1.5GB activations. To force 10GB you need load_in_4bit=False (full 16-bit = 3GB base + 6GB optimizer) — but that's 3x slower and unnecessary. Current 2-4GB is optimal.

6. Evaluation & Benchmarks

Evaluation status: The figures in this section are an internal pilot, not an independently reproduced benchmark. See EVALUATION.md for the protocol and limitations.

Quantitative:

Qualitative Examples:

• ✅ User: ازيك؟ → ازيك يا باشا عامل ايه النهاردة؟ (natural)
• ❌ User: يعني ايه عيش وملح؟ → كلمة عيش وملس معناها خبز مصري (FAIL — needs idiom data)
• ✅ User: احكيلي نكتة → generates short joke (needs longer max_new_tokens=256 + temperature 0.8)

Comparison vs Base: Base Qwen answers in MSA: "كيف حالك؟" → MasryGPT answers "ازيك يا باشا؟" — 48% more Egyptian as judged by 3 native speakers.

7. Usage

A. Unsloth (Recommended, Fast):

from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="ISLAM-PO/MasryGPT-Chat-1.5B",
    max_seq_length=2048, dtype=None, load_in_4bit=True,
)
FastLanguageModel.for_inference(model)
messages=[{"role":"user","content":"ازيك يا باشا؟"}]
inputs=tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt", return_dict=True).to("cuda")
outputs=model.generate(**inputs, max_new_tokens=256, temperature=0.8, top_p=0.95, do_sample=True, repetition_penalty=1.1)
print(tokenizer.batch_decode(outputs[:, inputs["input_ids"].shape[1]:], skip_special_tokens=True)[0])

B. Transformers (Standard):

from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("ISLAM-PO/MasryGPT-Chat-1.5B", device_map="auto", trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained("ISLAM-PO/MasryGPT-Chat-1.5B")
# same generate code

C. API & Gradio:

pip install gradio
# then wrap generate() in gr.Interface

Generation Tips:

• temperature 0.7-0.8 best for Masry creativity, 0.3 for factual.
• Always set return_dict=True to fix attention_mask warning.
• If you see fix_mistral_regex warning, add fix_mistral_regex=True when loading tokenizer via AutoTokenizer.

8. Limitations & Error Analysis

1. Idioms Weakness: "عيش وملح = العهد" fails 60% → dataset has only 15% idioms, needs 5k more real idiom pairs.
2. Hallucination: May invent Egyptian facts. No RAG.
3. Short Responses: Trained on short text packing → tends to 20-30 tokens. Increase max_new_tokens and use repetition_penalty.
4. MSA Degradation: -10% MSA due to catastrophic forgetting (1 epoch minimizes it, but still).
5. No Safety Filter: Beyond base Qwen, may repeat vulgar terms if in data.

Failure Mode Analysis (2500 steps): Loss plateau at 1500 steps → dataset saturated. Solution: add 40k diverse real conversations + 1 more epoch with LR 1e-4.

9. Ethics & Bias

• Data is synthetic Egyptian, may reflect Cairo dialect bias over Upper Egypt/Saidi.
• No PII. Vulgarity filtered but not perfect.
• Use responsibly: not for medical/legal advice in Egyptian.
• Model inherits Qwen license and potential biases.

10. Roadmap

• v1.1: Add 5k idioms + 10k real chat logs → target idiom 90%
• v2.0: DPO/RLHF for Egyptian humor alignment
• v2.5: 3B version for better reasoning, keep 1.5B lite
• Deployment: GGUF + Ollama + ONNX

Training data and reproducibility

The 80k training JSONL referenced by this model is not published in this repository. Treat the reported metrics as an internal pilot until the exact dataset, generation script, filtering rules, and evaluation prompts are released or linked. This prevents overstating reproducibility while preserving the existing model weights.

11. File Structure

MasryGPT-merged/
├── config.json               # Qwen2 config, model_type=qwen2, vocab 151936
├── model.safetensors         # 2.9GB 16-bit merged (1.05GB 4-bit before merge)
├── tokenizer.json            # 11.4 MB
├── tokenizer_config.json     # 7.03 kB (fix_mistral_regex warning documented)
├── chat_template.jinja       # qwen-2.5 template
├── generation_config.json    # eos 151645, pad 151654
└── README.md                 # This file

12. Citation & Contribution

Citation:

@misc{masrygpt_chat2026,
  author = {ISLAM-PO},
  title = {MasryGPT Chat: Egyptian Dialect Qwen2.5-1.5B-Instruct via QLoRA & Unsloth},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/ISLAM-PO/MasryGPT-Chat-1.5B},
  note = {80k terms, 2500 steps, loss 0.079}
}

Contribution — We Need You!

• Found a wrong Masry word? Open Issue with prompt + expected answer.
• Have Egyptian chat data (Facebook or WhatsApp, properly anonymized and with documented permission)? Propose a separate dataset repository after privacy and provenance review.
• Want to help evaluate? Run eval_masry.py (100 prompts) and submit scores.

Contact: Hugging Face Discussion tab — ISLAM-PO

🇪🇬 بالمصري - الوثائق الاحترافية

الفهرس

1. نظرة عامة
2. ليه عملنا المشروع ده؟
3. تفاصيل الموديل
4. الداتا
5. التدريب وتحليل عميق
6. التقييم
7. ازاي تستخدمه
8. عيوبه
9. الأخلاقيات
10. الخطة الجاية

1. نظرة عامة

MasryGPT Chat هو أول موديل مفتوح المصدر بيتكلم مصري عامي أصلي مش فصحى مترجمة. مبني على Qwen 1.5B ومتدرب بـ QLoRA على 80 ألف تعبير مصري. هدفه: أي حد في مصر يشغل شات بوت بيتكلم زيه بالظبط على موبايل أو لاب توب ضعيف، من غير ما يحتاج سيرفر غالي.

نتيجة التقييم الداخلي: بعد epoch واحد على 80 ألف مثال مصري، انخفض Loss من 0.091 إلى 0.074 خلال ساعتين و13 دقيقة على بطاقتي T4. قيّم 3 متحدثين أصليين 100 prompt بمتوسط 4.6/5 لطلاقة اللهجة المصرية؛ هذا تقييم داخلي وليس benchmark مستقلًا.

2. ليه عملنا المشروع ده؟

• الفصحى مش كفاية: كل الموديلات العربية بتتكلم "كيف حالك" لكن المصري بيقول "ازيك يا باشا؟" الفرق ثقافي مش لغوي.
• موديل خفيف: 7B محتاج 14GB كارت، 1.5B يشتغل على 4GB — مناسب لشركات ناشئة في مصر.
• سرعة Unsloth: بيدرب 2x أسرع ببلاش.

3. تفاصيل الموديل

4. الداتا

80 ألف مثال بصيغة messages:

• سلامات ودردشة يومية 35%
• هزار ونكت 15%
• أمثال وتعبيرات 15% (قليل وده سبب غلط "عيش وملح")
• خدمة عملاء 20%
• ثقافة وأكل 15%

مثال: User: يعني ايه عيش وملح؟ → Assistant: يعني العشرة والعهد، اللي كلت معاه عيش وملح مستحيل يخونك

الكود: get_chat_template(tokenizer, chat_template="qwen-2.5") + packing=True عشان الجمل القصيرة تتجمع.

5. التدريب وتحليل عميق

الخطوات: Hub → 4bit → QLoRA → SFTTrainer → دمج 16bit

الإعدادات النهائية (اللي خلصت في 2:13): batch 32, lr 2e-4 cosine, optim adamw_8bit (على الكارت مش الرام), max_seq 2048, warmup 20, 1 epoch

تحليل الـ Loss بعمق: 0.091 → 0.074 نزول 18.7%. في الأول طلع لـ 0.098 بسبب warmup وبعدين نزل بثبات لحد 1500 خطوة ووقف عند 0.074 — معناها الداتا خلصت والموديل حفظها. لو كملنا Epoch تاني هيحفظ غلط (overfit). الـ Perplexity 1.08 ممتازة (1 = مثالي).

السرعة: 10 sample/sec, 0.313 step/sec, 1.05e17 FLOPs. الـ GPU استهلك 2.4GB و 4.1GB بس — ده توفير مقصود من Unsloth مش ضعف. الـ CPU 100% هو اللي كان مخنوق من تحضير الداتا.

ليه مش 10GB؟ الموديل 1.5B 4-bit وزنه 0.8GB بس، حتى batch 32 يزود 1.5GB. عشان توصل 10GB لازم تلغي 4-bit وتشغله 16-bit كامل — أبطأ 3x وملوش لازمة.

6. التقييم

أمثلة:

• ✅ ازيك؟ → ازيك يا باشا عامل ايه النهاردة؟ (ممتاز)
• ❌ عيش وملح → عيش وملس = خبز (غلط — محتاج داتا أمثال)
• ✅ نكتة → بيحكي نكتة قصيرة لو زودت temperature 0.8

7. ازاي تستخدمه

نفس كود الانجليزي فوق، بس غير الرسالة:

messages = [{"role": "user", "content": "احكيلي نكتة مصرية قصيرة"}]
# أو
messages = [{"role": "user", "content": "اشرح لخواجة يعني ايه يخرم بيتك بالمصري"}]

نصيحة: temperature 0.8 للهزار، 0.3 للمعلومات.

8. عيوبه

1. الأمثال لسه ضعيف — محتاج 5k مثل زيادة.
2. بيألف أحياناً — مفيش RAG.
3. ردوده قصيرة — زود max_new_tokens=256.
4. الفصحى قلت شوية.
5. مفيش فلتر شتايم قوي.

9. الأخلاقيات

الداتا فيها لهجة قاهرية أكتر من الصعيدي — فيه انحياز. مفيش معلومات شخصية. متستخدموش في نصايح طبية/قانونية.

10. الخطة الجاية

• v1.1: نزود 5k مثل + 10k شات حقيقي → نوصل 90% أمثال
• v2.0: DPO للهزار
• v2.5: نسخة 3B أقوى ونسيب 1.5B خفيفة
• تحويل لـ GGUF لـ Ollama

ملفات الموديل: config.json, model.safetensors 2.9GB, tokenizer.json 11MB, chat_template.jinja

المساهمة: لقيت كلمة غلط؟ افتح Issue. عندك داتا مصري؟ ابعت PR. عايز تقيم؟ جرب 100 سؤال وابعت النتيجة!

الترخيص: Apache 2.0