---
title: "الجلسة السادسة | LLM Engineering — APIs, Prompting & RAG"
aliases:
  - "Session 06 - LLM Engineering"
  - "AI Camp v2 - Session 06"
tags:
  - AI-Camp-v2
  - Systems
  - LLM-Engineering
  - RAG
  - Prompt-Engineering
  - Retrieval
session: 6
duration: "3 hours"
duration_minutes: 180
track: Systems
status: planned
language: ar
project: "AI Camp Knowledge Assistant"
---

# الجلسة السادسة: LLM Engineering — From Model APIs to RAG Applications



##  نظرة عامة

تمثل هذه الجلسة انتقالًا مهمًا من **تدريب النماذج وفهم بنيتها** إلى **هندسة تطبيقات تعتمد على النماذج اللغوية الكبيرة (LLMs)**.

بدلًا من استخدام النموذج كصندوق محادثة عام، يتعلم الطالب كيف يدمجه في تطبيق يمتلك بيانات محددة، ويتعامل مع المدخلات والمخرجات بصورة منظمة، ويسترجع الأدلة المناسبة قبل توليد الإجابة، ويعرض المصادر للمستخدم.

> [!abstract] الهدف الرئيسي
> بناء تطبيق **Retrieval-Augmented Generation (RAG)** يستطيع الإجابة عن أسئلة مرتبطة بوثائق المعسكر، مع **إجابات مستندة إلى محتوى مسترجع، ومراجع ظاهرة، واختبارات أولية للجودة**.

##  مخرجات التعلّم

بنهاية الجلسة، يُتوقع أن يستطيع الطالب:

- استدعاء نموذج لغوي عبر API أو استخدام واجهة متوافقة مع نموذج محلي مجهّز مسبقًا.
- كتابة تعليمات واضحة وضبط حدود السياق وشكل الإجابة.
- فهم **Structured Outputs** والتحقق من المخرجات باستخدام **Pydantic**.
- شرح مفهوم **Function/Tool Calling** ودور التطبيق في تنفيذ الأداة والتحقق من مدخلاتها.
- بناء خط تجهيز مستندات يتضمن **Chunking وEmbeddings وVector Store**.
- بناء Retrieval Pipeline يختار المقاطع المناسبة لسؤال المستخدم.
- دمج السياق المسترجع في Prompt للإجابة مع **إحالات إلى المصادر**.
- إنشاء واجهة محادثة بسيطة باستخدام **Streamlit**.
- اختبار الإجابات القابلة للتحقق والأسئلة غير المدعومة بالمستندات.
- توثيق ملاحظات عن **زمن الاستجابة والتكلفة والمخاطر الأمنية الأساسية**.

---

##  المحاور النظرية

### 1. Working with LLMs — التعامل مع النماذج الجاهزة

| المسار | الفكرة | أمثلة |
|---|---|---|
| **Hosted APIs** | استدعاء نموذج مستضاف عن بعد باستخدام API. | OpenAI أو Anthropic |
| **Local Inference** | تشغيل نموذج مفتوح الأوزان على الجهاز عند توفر الموارد المناسبة. | Ollama |
| **Model Serving** | تقديم نموذج على هيئة خدمة يمكن للتطبيقات استدعاؤها. | vLLM |

**المفاهيم التي يجب فهمها:**

- طلب API: المدخلات، الإعدادات، المخرجات، والتعامل مع الأخطاء.
- الفرق بين **Model Provider** وتطبيق العميل الذي يستخدم النموذج.
- زمن الاستجابة (**Latency**) والتكلفة والاستهلاك التقريبي للـTokens.
- حماية مفاتيح API وعدم تضمينها في الشيفرة أو Pull Requests.

> [!note] اختيار المسار داخل الجلسة
> يكفي **مسار تشغيل واحد يعمل بصورة موثوقة** لإنجاز المشروع. لا يلزم تشغيل OpenAI وAnthropic وOllama وvLLM جميعها خلال ثلاث ساعات؛ تُعرض بقية الخيارات للمقارنة والتوسّع.

### 2. Prompt Engineering & Context Engineering

- كتابة تعليمات دقيقة تحدد المهمة والسياق والحدود.
- فصل **تعليمات التطبيق** عن **محتوى المستندات المسترجعة**.
- تحديد صيغة الإجابة والتعامل مع نقص المعلومات.
- تقديم أمثلة قصيرة (**Few-shot Examples**) عندما تكون مفيدة.
- تقليل السياق غير الضروري وتجنب تعليمات متضاربة.

> [!tip] مبدأ مهم
> Prompt جيد لا يعوض البيانات غير الصحيحة أو عملية Retrieval ضعيفة. جودة تطبيق RAG تعتمد على **اختيار الأدلة الصحيحة** بقدر اعتمادها على صياغة التعليمات.

### 3. Structured Outputs & Pydantic

**Structured Output** يعني أن التطبيق يتوقع بنية محددة للمخرجات، مثل JSON يحوي حقولًا معروفة، ثم يتحقق من شكلها.

مثال تعليمي لبنية متوقعة:

```json
{
  "answer": "The session covers Git and GitHub workflows.",
  "source_ids": ["session-01"],
  "supported_by_sources": true
}
```

- تعريف Schema للحقول المطلوبة.
- التحقق من الأنواع والحقول باستخدام **Pydantic**.
- التعامل مع أخطاء التحقق أو غياب الحقول.
- التمييز بين **صحة شكل JSON** و**صحة المعلومة نفسها**.

> [!warning] لا تخلط بين الشكل والحقيقة
> اجتياز فحص Pydantic لا يعني أن الإجابة صحيحة أو مستندة فعلًا إلى الوثائق. يجب التحقق من أن مراجع الإجابة موجودة في المقاطع المسترجعة، وأن المحتوى مدعوم بها.

### 4. Function Calling — مقدمة إلى استخدام الأدوات

يسمح **Tool Calling** للنموذج بأن يطلب من التطبيق تنفيذ دالة محددة مع معاملات منظمة، بدل الاقتصار على إخراج إجابة نصية.

مثال مبسط: يطلب المستخدم معرفة عدد جلسات المعسكر؛ فيستطيع التطبيق تنفيذ دالة **للقراءة فقط** من بيانات الجلسات، ثم إعادة النتيجة إلى النموذج.

**النقاط الأساسية:**

1. يحدد المطور الأدوات المتاحة وصيغ مدخلاتها.
2. يختار النموذج طلب استخدام أداة عند الحاجة.
3. يتحقق التطبيق من الطلب ويقرر إن كان التنفيذ مسموحًا.
4. ينفذ التطبيق الأداة ثم يعيد نتيجتها.
5. يستخدم النموذج النتيجة لإعداد رد للمستخدم.

> [!note] نطاق هذه الجلسة
> هذا **مدخل مفاهيمي وتطبيق قصير**؛ ستُناقش حلقات التنفيذ وتخطيط المهام وMCP ووكلاء AI بالتفصيل في جلسة **Agentic AI**.

### 5. Retrieval-Augmented Generation (RAG)

RAG أسلوب لبناء تطبيقات تسترجع معلومات ذات صلة من مصدر معرفة خارجي ثم تقدمها للنموذج لتوليد إجابة أكثر ارتباطًا بالمصدر.

#### A. تجهيز المعرفة — Offline / Indexing

1. تحميل المستندات المسموح باستخدامها.
2. استخراج النص وتنظيفه.
3. تقسيم المحتوى إلى مقاطع (**Chunking**) مع حفظ بيانات المصدر.
4. تحويل المقاطع إلى **Embeddings**.
5. تخزين المتجهات والنصوص والبيانات الوصفية في **Vector Store**.

#### B. الإجابة عن سؤال — Online / Retrieval

1. استقبال سؤال المستخدم.
2. تمثيل السؤال باستخدام نموذج Embeddings متوافق.
3. استرجاع المقاطع الأكثر صلة.
4. إعادة ترتيبها اختياريًا (**Reranking**) عندما يتطلب الأمر.
5. بناء سياق يتضمن المقاطع ومعرفات المصادر.
6. طلب إجابة من LLM بالاعتماد على السياق.
7. عرض الإجابة وإحالاتها، أو التصريح بعدم كفاية الأدلة.

> [!important] فصل المفاهيم
> **RAG لا يعني تدريب النموذج على الوثائق أو تعديل أوزانه.** إنه يتيح للتطبيق تزويد النموذج بمعلومات مسترجعة أثناء معالجة السؤال.

### 6. LLM System Quality — الجودة والأداء والأمان

- **Retrieval Quality:** هل وصلنا إلى المقطع الذي يتضمن الإجابة؟
- **Groundedness:** هل تستند الإجابة فعلًا إلى الأدلة المسترجعة؟
- **Citations:** هل تشير الإحالات إلى المصادر الصحيحة؟
- **Abstention:** هل يمتنع النظام عن اختلاق إجابة عندما لا يجد معلومة كافية؟
- **Latency & Cost:** الزمن وعدد الطلبات والـTokens والتخزين المؤقت.
- **Security:** عدم الثقة بالتعليمات الموجودة داخل المستندات المسترجعة، وحماية الأسرار والبيانات الخاصة.

---

##  المشروع الرئيسي: AI Camp Knowledge Assistant

### فكرة المشروع

بناء مساعد أسئلة وأجوبة يستطيع الإجابة عن استفسارات الطلاب حول **وثائق المعسكر، والجلسات، والمتطلبات، والتكليفات**، مع إظهار المستندات أو المقاطع التي استندت إليها الإجابة.

**مثال:** «ما المطلوب تسليمه بعد جلسة Computer Vision؟»

يبحث النظام في ملفات المعسكر، ويسترجع القسم المناسب، ثم يقدم إجابة موجزة مع مصدرها. وإذا سُئل عن معلومة غير موجودة، يوضح عدم كفاية المستندات المتاحة.

### معمارية التطبيق

```mermaid
flowchart TD
    A["Camp Documents"] --> B["Chunking + Metadata"]
    B --> C["Embeddings + Vector Store"]
    D["Student Question"] --> E["Relevant Chunk Retrieval"]
    C --> E
    E --> F["Prompt + LLM"]
    F --> G["Answer + Source Citations"]
    G --> H["Streamlit Chat UI"]
```

### المرحلة 1 — Preparing the Knowledge Base

- [ ] اختيار مجموعة صغيرة من ملفات Markdown أو PDF الخاصة بالمعسكر.
- [ ] استخراج المحتوى وتقسيمه إلى مقاطع مناسبة.
- [ ] حفظ **اسم المصدر ومعرف المقطع** مع كل جزء.
- [ ] إنشاء Embeddings وحفظها في Vector Store محلي بسيط.
- [ ] اختبار البحث باستخدام سؤالين معروفَي الإجابة.

### المرحلة 2 — Retrieval Pipeline

- [ ] تحويل سؤال المستخدم إلى تمثيل مناسب للبحث.
- [ ] استرجاع عدد محدود من المقاطع الأكثر صلة.
- [ ] عرض المقاطع المسترجعة وبياناتها الوصفية أثناء التطوير.
- [ ] تعديل حجم المقاطع أو عدد النتائج عند ظهور مشكلة استرجاع واضحة.

### المرحلة 3 — Grounded Answer Generation

- [ ] بناء Prompt يحدد دور المساعد ونطاق معرفته.
- [ ] تمرير المقاطع المسترجعة مع معرفات المصادر.
- [ ] توجيه النموذج إلى استخدام الأدلة وعدم اختلاق معلومات غير موجودة.
- [ ] عرض الإجابة مع المصدر/المصادر المرتبطة بها.
- [ ] التعامل مع حالة عدم وجود دليل كافٍ.

### المرحلة 4 — Streamlit Interface

- [ ] إنشاء واجهة محادثة باستخدام عناصر Streamlit.
- [ ] استقبال سؤال الطالب وعرض الإجابة.
- [ ] إظهار المصادر الداعمة للإجابة بصورة واضحة.
- [ ] تقديم رسالة مفهومة عند فشل خدمة النموذج أو الاسترجاع.

### المرحلة 5 — Evaluation & Debugging

يُحضَّر **Mini Evaluation Set** يتضمن أسئلة يمكن الإجابة عنها من الوثائق وأخرى لا تتوفر لها إجابات.

| حالة الاختبار | السلوك المتوقع |
|---|---|
| سؤال موجود جوابه في مستند | إجابة صحيحة مع مصدر مناسب |
| سؤال موجود في مقطع بعيد | استرجاع المقطع الصحيح أو كشف قصور Retrieval |
| سؤال خارج نطاق المستندات | إقرار بعدم وجود دليل كافٍ |
| معلومة متشابهة بين مستندين | تحديد المصدر الصحيح وتجنب الخلط |
| نص مسترجع يتضمن تعليمات غير موثوقة | التعامل معه بوصفه **محتوى بيانات** وليس تعليمات للتطبيق |

**مخرجات التقييم:** عدد الأسئلة التي استرجعت مصادر مناسبة، وعدد الإجابات المدعومة، والأخطاء المرصودة، وزمن الاستجابة التقريبي.

> [!tip] تشخيص المشكلة قبل تعديل Prompt
> إذا كانت الإجابة خاطئة، اسأل أولًا: **هل استُرجع المقطع الصحيح؟** إذا لم يُسترجع، فالمشكلة في Retrieval أو البيانات؛ أما إذا وُجد الدليل الصحيح وتجاهله النموذج، فالمشكلة أقرب إلى توليد الإجابة أو صياغة السياق.

---


##  التسليم المطلوب (Deliverables)

- [ ] تطبيق **Streamlit RAG** يستطيع الإجابة عن أسئلة متعلقة بوثائق المعسكر.
- [ ] شيفرة واضحة لتجهيز المستندات وفهرستها.
- [ ] مسار Retrieval يعرض مصادر المقاطع المسترجعة.
- [ ] إجابات تتضمن إشارات للمصادر، مع التعامل مع الأسئلة غير المدعومة.
- [ ] ملف تقييم مختصر يتضمن حالات نجاح وفشل وملاحظات التحسين.
- [ ] `README.md` يشرح المتطلبات وطريقة التشغيل والإعدادات.
- [ ] `.env.example` يوضح أسماء المتغيرات المطلوبة دون أسرار.
- [ ] **Pull Request** لتسليم التطبيق.
- [ ] فريق Capstone ومقترح أولي من فقرة واحدة.

### Capstone Proposal — المطلوب بنهاية الجلسة

يقدم كل فريق فقرة قصيرة تجيب عن:

1. ما المشكلة الواقعية التي نريد حلّها؟
2. من المستخدم المستهدف؟
3. ما المدخلات والمخرجات المتوقعة؟
4. ما المكونات الذكية المطلوبة، ولماذا؟
5. كيف سنقيس نجاح الحل؟

> [!important] تجنب التعقيد غير الضروري
> لا ينبغي أن يتضمن كل Capstone بالضرورة RAG أو Agents أو Voice AI. **اختيار المعمارية يعتمد على المشكلة**، وليس على عدد التقنيات المستخدمة.

---


- لا تضع مفاتيح API أو بيانات شخصية حقيقية داخل وثائق المختبر.
- تحقق من مدخلات الأدوات ومخرجات JSON قبل استخدامها.
- لا تعتبر وجود Citation دليلًا كافيًا على صحة الإجابة؛ راجع مدى دعم المصدر لها.
- راقب تكلفة الاستدعاءات وزمن الاستجابة وحدود الاستخدام.

##  المراجع الرسمية

- [OpenAI API Documentation](https://platform.openai.com/docs/)
- [Anthropic API Documentation](https://platform.claude.com/docs/en/home)
- [Pydantic Documentation](https://pydantic.dev/docs/validation/latest/get-started/)
- [Streamlit — Chat Elements](https://docs.streamlit.io/develop/api-reference/chat)
- [Ollama Documentation](https://docs.ollama.com/)
- [vLLM Documentation](https://docs.vllm.ai/)

---

##  خلاصة الجلسة

يتعلم الطالب في الجلسة السادسة أن **LLM Engineering** لا تعني مجرد كتابة Prompt جيد، بل تعني تصميم تطبيق يدير النماذج والبيانات والسياق والمخرجات والمراجع والتقييم والتكلفة بطريقة متكاملة.

> [!success] الرسالة الأساسية
> **A reliable LLM application combines retrieval quality, grounded generation, structured interfaces, evaluation, and responsible engineering — not prompting alone.**
