# القسم 2: دليل تنفيذ Llama.cpp

## جدول المحتويات
1. [المقدمة](../../../Module04)
2. [ما هو Llama.cpp؟](../../../Module04)
3. [التثبيت](../../../Module04)
4. [البناء من المصدر](../../../Module04)
5. [تكميم النماذج](../../../Module04)
6. [الاستخدام الأساسي](../../../Module04)
7. [الميزات المتقدمة](../../../Module04)
8. [التكامل مع بايثون](../../../Module04)
9. [استكشاف الأخطاء وإصلاحها](../../../Module04)
10. [أفضل الممارسات](../../../Module04)

## المقدمة

هذا الدليل الشامل سيأخذك خطوة بخطوة لفهم كل ما تحتاجه حول Llama.cpp، بدءًا من التثبيت الأساسي وصولاً إلى سيناريوهات الاستخدام المتقدمة. Llama.cpp هو تنفيذ قوي بلغة C++ يتيح استنتاج نماذج اللغة الكبيرة (LLMs) بكفاءة مع إعداد بسيط وأداء ممتاز عبر مختلف تكوينات الأجهزة.

## ما هو Llama.cpp؟

Llama.cpp هو إطار عمل لاستنتاج نماذج اللغة الكبيرة مكتوب بلغة C/C++، يتيح تشغيل هذه النماذج محليًا مع إعداد بسيط وأداء متقدم على مجموعة واسعة من الأجهزة. الميزات الرئيسية تشمل:

### الميزات الأساسية
- **تنفيذ بلغة C/C++ فقط** بدون تبعيات
- **التوافق عبر الأنظمة** (ويندوز، macOS، لينكس)
- **تحسين الأجهزة** لمختلف المعماريات
- **دعم التكميم** (من 1.5 بت إلى 8 بت)
- **تسريع باستخدام المعالج المركزي ومعالج الرسومات**
- **كفاءة في استخدام الذاكرة** للبيئات ذات الموارد المحدودة

### المزايا
- يعمل بكفاءة على المعالج المركزي دون الحاجة إلى أجهزة متخصصة
- يدعم العديد من واجهات معالج الرسومات (CUDA، Metal، OpenCL، Vulkan)
- خفيف الوزن وقابل للنقل
- أجهزة Apple silicon مدعومة بشكل ممتاز - محسنة باستخدام ARM NEON، Accelerate، وMetal
- يدعم مستويات تكميم مختلفة لتقليل استخدام الذاكرة

## التثبيت

### الطريقة الأولى: الملفات التنفيذية الجاهزة (موصى بها للمبتدئين)

#### التحميل من GitHub Releases
1. قم بزيارة [إصدارات Llama.cpp على GitHub](https://github.com/ggml-org/llama.cpp/releases)
2. قم بتحميل الملف المناسب لنظامك:
   - `llama-<version>-bin-win-<feature>-<arch>.zip` لويندوز
   - `llama-<version>-bin-macos-<feature>-<arch>.zip` لنظام macOS
   - `llama-<version>-bin-linux-<feature>-<arch>.zip` لنظام لينكس

3. قم باستخراج الأرشيف وأضف الدليل إلى PATH الخاص بنظامك

#### باستخدام مديري الحزم

**macOS (Homebrew):**
```bash
brew install llama.cpp
```

**لينكس (توزيعات مختلفة):**
```bash
# Ubuntu/Debian
sudo apt install llama.cpp

# Arch Linux
sudo pacman -S llama.cpp
```

### الطريقة الثانية: حزمة بايثون (llama-cpp-python)

#### التثبيت الأساسي
```bash
pip install llama-cpp-python
```

#### مع تسريع الأجهزة
```bash
# For CUDA (NVIDIA GPUs)
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python

# For Metal (Apple Silicon)
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python

# For OpenBLAS (CPU optimization)
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python
```

## البناء من المصدر

### المتطلبات الأساسية

**متطلبات النظام:**
- مترجم C++ (GCC، Clang، أو MSVC)
- CMake (الإصدار 3.14 أو أعلى)
- Git
- أدوات البناء لنظامك

**تثبيت المتطلبات الأساسية:**

**macOS:**
```bash
xcode-select --install
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install build-essential cmake git
```

**ويندوز:**
- قم بتثبيت Visual Studio 2022 مع أدوات تطوير C++
- قم بتثبيت CMake من الموقع الرسمي
- قم بتثبيت Git

### عملية البناء الأساسية

1. **استنساخ المستودع:**
```bash
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
```

2. **تهيئة البناء:**
```bash
cmake -B build
```

3. **بناء المشروع:**
```bash
cmake --build build --config Release
```

للتسريع، استخدم الوظائف المتوازية:
```bash
cmake --build build --config Release -j 8
```

### بناء مخصص للأجهزة

#### دعم CUDA (معالجات NVIDIA)
```bash
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release
```

#### دعم Metal (Apple Silicon)
```bash
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release
```

#### دعم OpenBLAS (تحسين المعالج المركزي)
```bash
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release
```

#### دعم Vulkan
```bash
cmake -B build -DGGML_VULKAN=1
cmake --build build --config Release
```

### خيارات بناء متقدمة

#### بناء للتصحيح
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```

#### مع ميزات إضافية
```bash
cmake -B build \
    -DGGML_CUDA=ON \
    -DGGML_BLAS=ON \
    -DGGML_BLAS_VENDOR=OpenBLAS \
    -DBUILD_SHARED_LIBS=ON
```

## تكميم النماذج

### فهم صيغة GGUF

GGUF (صيغة GGML الموحدة العامة) هي صيغة ملفات محسنة مصممة لتشغيل نماذج اللغة الكبيرة بكفاءة باستخدام Llama.cpp وأطر عمل أخرى. توفر:

- تخزين موحد لأوزان النماذج
- تحسين التوافق عبر الأنظمة
- أداء معزز
- معالجة فعالة للبيانات الوصفية

### أنواع التكميم

يدعم Llama.cpp مستويات تكميم مختلفة:

| النوع | البتات | الوصف | حالة الاستخدام |
|-------|-------|-------|----------------|
| F16 | 16 | دقة نصفية | جودة عالية، ذاكرة كبيرة |
| Q8_0 | 8 | تكميم 8 بت | توازن جيد |
| Q4_0 | 4 | تكميم 4 بت | جودة متوسطة، حجم أصغر |
| Q2_K | 2 | تكميم 2 بت | أصغر حجم، جودة أقل |

### تحويل النماذج

#### من PyTorch إلى GGUF
```bash
# Convert Hugging Face model
python convert_hf_to_gguf.py path/to/model --outdir ./models

# Quantize the model
./llama-quantize ./models/model.gguf ./models/model-q4_0.gguf q4_0
```

#### التحميل المباشر من Hugging Face
العديد من النماذج متوفرة بصيغة GGUF على Hugging Face:
- ابحث عن النماذج التي تحتوي على "GGUF" في الاسم
- قم بتحميل مستوى التكميم المناسب
- استخدمها مباشرة مع Llama.cpp

## الاستخدام الأساسي

### واجهة سطر الأوامر

#### توليد نص بسيط
```bash
# Basic text completion
./llama-cli -m model.gguf -p "Hello, my name is" -n 50

# Interactive chat mode
./llama-cli -m model.gguf -cnv
```

#### استخدام نماذج من Hugging Face
```bash
# Download and run directly
./llama-cli -hf microsoft/DialoGPT-medium
```

#### وضع الخادم
```bash
# Start server
./llama-server -m model.gguf --host 0.0.0.0 --port 8080

# With GPU acceleration
./llama-server -m model.gguf --n-gpu-layers 32
```

### المعلمات الشائعة

| المعلمة | الوصف | المثال |
|---------|-------|--------|
| `-m` | مسار ملف النموذج | `-m model.gguf` |
| `-p` | نص التوجيه | `-p "Hello world"` |
| `-n` | عدد الرموز المراد توليدها | `-n 100` |
| `-c` | حجم السياق | `-c 4096` |
| `-t` | عدد الخيوط | `-t 8` |
| `-ngl` | طبقات معالج الرسومات | `-ngl 32` |
| `-temp` | درجة الحرارة | `-temp 0.7` |

### الوضع التفاعلي

```bash
# Start interactive session
./llama-cli -m model.gguf -cnv

# Example conversation:
# > Hello, how are you?
# Hi there! I'm doing well, thank you for asking...
# > What can you help me with?
# I can assist with various tasks such as...
```

## الميزات المتقدمة

### واجهة برمجة التطبيقات للخادم

#### بدء تشغيل الخادم
```bash
./llama-server -m model.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    --ctx-size 4096 \
    --n-gpu-layers 32
```

#### استخدام واجهة برمجة التطبيقات
```bash
# Chat completion
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

# Text completion
curl -X POST http://localhost:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The capital of France is",
    "n_predict": 50
  }'
```

### تحسين الأداء

#### إدارة الذاكرة
```bash
# Set context size
./llama-cli -m model.gguf -c 2048

# Enable memory mapping
./llama-cli -m model.gguf --mlock
```

#### تعدد الخيوط
```bash
# Use all CPU cores
./llama-cli -m model.gguf -t $(nproc)

# Specific thread count
./llama-cli -m model.gguf -t 8
```

#### تسريع معالج الرسومات
```bash
# Offload layers to GPU
./llama-cli -m model.gguf -ngl 32

# Use specific GPU
CUDA_VISIBLE_DEVICES=0 ./llama-cli -m model.gguf -ngl 32
```

## التكامل مع بايثون

### الاستخدام الأساسي مع llama-cpp-python

```python
from llama_cpp import Llama

# Initialize model
llm = Llama(
    model_path="./models/model.gguf",
    n_ctx=2048,
    n_threads=8,
    n_gpu_layers=32
)

# Generate text
output = llm("Hello, my name is", max_tokens=50)
print(output['choices'][0]['text'])
```

### واجهة الدردشة

```python
from llama_cpp import Llama

llm = Llama(model_path="./models/chat-model.gguf")

# Chat completion
response = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=100
)

print(response['choices'][0]['message']['content'])
```

### استجابة متدفقة

```python
# Streaming text generation
stream = llm("Tell me a story", max_tokens=200, stream=True)

for output in stream:
    print(output['choices'][0]['text'], end='', flush=True)
```

### التكامل مع LangChain

```python
from langchain.llms import LlamaCpp
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# Initialize LLM
llm = LlamaCpp(
    model_path="./models/model.gguf",
    n_ctx=2048,
    n_threads=8
)

# Create prompt template
template = "Question: {question}\nAnswer:"
prompt = PromptTemplate(template=template, input_variables=["question"])

# Create chain
chain = LLMChain(llm=llm, prompt=prompt)

# Use the chain
result = chain.run(question="What is artificial intelligence?")
print(result)
```

## استكشاف الأخطاء وإصلاحها

### المشاكل الشائعة وحلولها

#### أخطاء البناء

**المشكلة: CMake غير موجود**
```bash
# Solution: Install CMake
# Ubuntu/Debian
sudo apt install cmake

# macOS
brew install cmake
```

**المشكلة: المترجم غير موجود**
```bash
# Solution: Install build tools
# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install
```

#### مشاكل وقت التشغيل

**المشكلة: فشل تحميل النموذج**
- تحقق من مسار ملف النموذج
- تحقق من أذونات الملف
- تأكد من توفر ذاكرة كافية
- جرب مستويات تكميم مختلفة

**المشكلة: أداء ضعيف**
- قم بتمكين تسريع الأجهزة
- قم بزيادة عدد الخيوط
- استخدم التكميم المناسب
- تحقق من استخدام ذاكرة معالج الرسومات

#### مشاكل الذاكرة

**المشكلة: نفاد الذاكرة**
```bash
# Solutions:
# 1. Use smaller quantization
./llama-cli -m model-q4_0.gguf

# 2. Reduce context size
./llama-cli -m model.gguf -c 1024

# 3. Offload to GPU
./llama-cli -m model.gguf -ngl 32
```

### مشاكل خاصة بالنظام

#### ويندوز
- استخدم مترجم MinGW أو Visual Studio
- تأكد من تكوين PATH بشكل صحيح
- تحقق من تدخل برامج مكافحة الفيروسات

#### macOS
- قم بتمكين Metal لأجهزة Apple Silicon
- استخدم Rosetta 2 للتوافق إذا لزم الأمر
- تحقق من أدوات سطر الأوامر لـ Xcode

#### لينكس
- قم بتثبيت حزم التطوير
- تحقق من إصدارات برامج تشغيل معالج الرسومات
- تحقق من تثبيت مجموعة أدوات CUDA

## أفضل الممارسات

### اختيار النموذج
1. **اختر مستوى التكميم المناسب** بناءً على أجهزتك
2. **ضع في اعتبارك حجم النموذج** مقابل جودة الأداء
3. **اختبر نماذج مختلفة** لحالتك الخاصة

### تحسين الأداء
1. **استخدم تسريع معالج الرسومات** عند توفره
2. **قم بتحسين عدد الخيوط** لمعالجك المركزي
3. **حدد حجم السياق المناسب** لحالتك
4. **قم بتمكين تعيين الذاكرة** للنماذج الكبيرة

### نشر الإنتاج
1. **استخدم وضع الخادم** للوصول إلى واجهة برمجة التطبيقات
2. **قم بتنفيذ معالجة الأخطاء بشكل صحيح**
3. **راقب استخدام الموارد**
4. **قم بإعداد تسجيل ومراقبة**

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

### اعتبارات الأمان
1. **تحقق من صحة النصوص المدخلة**
2. **قم بتنفيذ تحديد المعدل**
3. **قم بتأمين نقاط نهاية واجهة برمجة التطبيقات**
4. **راقب أنماط الإساءة**

## الخاتمة

يوفر Llama.cpp طريقة قوية وفعالة لتشغيل نماذج اللغة الكبيرة محليًا عبر مختلف تكوينات الأجهزة. سواء كنت تطور تطبيقات الذكاء الاصطناعي، تجري أبحاثًا، أو تجرب نماذج اللغة الكبيرة، فإن هذا الإطار يوفر المرونة والأداء اللازمين لمجموعة واسعة من الاستخدامات.

النقاط الرئيسية:
- اختر طريقة التثبيت التي تناسب احتياجاتك
- قم بتحسين التكوين الخاص بأجهزتك
- ابدأ بالاستخدام الأساسي واستكشف الميزات المتقدمة تدريجيًا
- ضع في اعتبارك استخدام روابط بايثون لتسهيل التكامل
- اتبع أفضل الممارسات للنشر في الإنتاج

للمزيد من المعلومات والتحديثات، قم بزيارة [المستودع الرسمي لـ Llama.cpp](https://github.com/ggml-org/llama.cpp) وراجع الوثائق الشاملة والموارد المجتمعية المتاحة.

## ➡️ ما التالي؟

- [03: مجموعة تحسين Microsoft Olive](./03.MicrosoftOlive.md)

---

**إخلاء المسؤولية**:  
تم ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو معلومات غير دقيقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق. للحصول على معلومات حاسمة، يُوصى بالاستعانة بترجمة بشرية احترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.