🤖 تثبيت llama.cpp — سيرفر استدلال LLM خفيف الوزن

انشر سيرفر llama.cpp على Ubuntu بواسطة Docker — شغّل نماذج لغة بصيغة GGUF محلياً بواجهة API متوافقة مع OpenAI، وبكفاءة تكفي للعمل على المعالج (CPU) فقط، على المنفذ 8283.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر سيرفر llama.cpp على المنفذ 8283 بواجهة API متوافقة مع OpenAI. يجب وضع نموذج .gguf في مجلد models وإعادة التشغيل قبل أن يستطيع الرد.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/ai/llamacpp/llamacpp-ubuntu.sh
chmod +x llamacpp-ubuntu.sh
./llamacpp-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/ai/llamacpp/llamacpp-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x llamacpp-ubuntu.sh

3 تشغيل المثبّت

./llamacpp-ubuntu.sh

4 إضافة نموذج GGUF وإعادة التشغيل

docker restart llamacpp

المنافذ المستخدمة

المنفذالغرض
8283OpenAI-compatible API (mapped from container port 8080)

نظرة عامة

llama.cpp هو محرك استدلال LLM مجاني ومفتوح المصدر مكتوب بلغة C/C++ بدون اعتماديات تشغيل ثقيلة، مصمم لتشغيل نماذج اللغة الكبيرة بكفاءة على أجهزة عادية — بما فيها المعالجات (CPU) العادية فقط. قدّم صيغة نموذج GGUF، التي أصبحت الآن المعيار الفعلي للنماذج المُكمَّمة (quantized) المُشغَّلة محلياً، ومحرك الاستدلال الخاص به يشغّل جزءاً كبيراً من منظومة LLM المحلية، بما فيها Ollama وLocalAI. وضع السيرفر المستخدم في هذا النشر يعرض واجهة API متوافقة مع OpenAI، فيمكنك توجيه أدوات وتطبيقات مبنية على SDK الخاص بـ OpenAI مباشرة إلى نموذجك ذاتي الاستضافة.

لماذا تستخدمه

معظم أدوات LLM المحلية — بما فيها Ollama — هي طبقات راحة مبنية فوق محرك استدلال llama.cpp، فتشغيل سيرفر llama.cpp مباشرة يمنحك نفس الأداء بدون أي طبقة تجريد بينك وبينه: تحكم كامل في مستوى التكميم وحجم السياق وتفريغ العمل على GPU وكل علم من أعلام السيرفر. وبما أنه مكتوب بلغة C/C++ باعتماديات قليلة، يعمل جيداً على أجهزة متواضعة، بما فيها سيرفرات CPU فقط، بفضل نماذج GGUF المُكمَّمة التي تتنازل عن قدر ضئيل من الدقة مقابل متطلبات ذاكرة ومعالجة أقل بشكل كبير. لأي شخص يريد فهم أو ضبط سلوك سيرفر الاستدلال المحلي بدقة بدلاً من الثقة بإعدادات أداة غلاف افتراضية، llama.cpp هو المحرك الكامن خلف كل شيء تقريباً.

متى تحتاجه

  • تريد تشغيل نماذج LLM مفتوحة المصدر محلياً على سيرفر يعتمد على CPU فقط أو جهاز بدون GPU مخصص
  • تحتاج نقطة نهاية API متوافقة مع OpenAI حتى تتحدث التطبيقات القائمة المبنية على SDK الخاص بـ OpenAI مع نموذج ذاتي الاستضافة دون أي تغيير في الكود
  • تريد تحكماً دقيقاً في التكميم وطول السياق ومعاملات الاستدلال التي تُخفيها أدوات أعلى مستوى مثل Ollama
  • تبني مباشرة فوق llama.cpp، أو تُصحّح سلوك أداة (مثل Ollama) مبنية عليه
  • تريد إبقاء المحفزات (prompts) ومخرجات النموذج خاصة تماماً وغير متصلة، دون مغادرة أي بيانات لسيرفرك أبداً
  • تحتاج تشغيل استدلال على جهاز محدود الموارد حيث لا تكون منظومة استدلال قائمة على GPU كاملة عملية

من يحتاجه

  • المطورون والهواة الذين يشغّلون نماذج LLM محلياً على سيرفر منزلي أو NAS أو VPS اقتصادي بدون GPU
  • المهندسون الذين يريدون فهم أو تخصيص سلوك سيرفر الاستدلال المحلي بدقة على مستوى منخفض
  • المستخدمون والمؤسسات المهتمون بالخصوصية الذين يحتاجون استدلال النموذج بالكامل دون اتصال، بدون أي استدعاءات API لمزوّد سحابي
  • الفرق التي تبني تطبيقات على SDK الخاص بـ OpenAI وتريد خلفية ذاتية الاستضافة بديلة جاهزة بدلاً من API مدفوع
  • هواة الذكاء الاصطناعي وتعلم الآلة الذين يجربون مستويات تكميم GGUF مختلفة لموازنة السرعة واستخدام الذاكرة وجودة المخرجات
  • أي شخص يشغّل أو يُصحّح Ollama أو LocalAI أو أداة أخرى، فهم llama.cpp يوضّح ما يحدث تحت الغطاء

حالات الاستخدام الشائعة

  • استضافة خلفية شات بوت ذاتياً لتطبيق باستخدام نقطة نهاية إكمالات المحادثة المتوافقة مع OpenAI
  • تشغيل مساعد برمجة أو كتابة خاص دون اتصال بالكامل على سيرفر منزلي يعتمد على CPU فقط
  • تقديم embeddings لخط أنابيب استرجاع مُعزَّز بالتوليد (RAG) ذاتي الاستضافة
  • اختبار ومقارنة نماذج GGUF مُكمَّمة مختلفة لإيجاد أفضل موازنة سرعة/جودة للأجهزة المتاحة
  • تشغيل ميزة ذكاء اصطناعي محلية في تطبيق ذاتي الاستضافة (مثل أداة تدوين ملاحظات أو مساعد أتمتة منزلية) بدون اعتماد سحابي
  • تشغيل استدلال LLM على سيرفر منخفض الطاقة أو محدود الموارد حيث الحلول القائمة على GPU ليست خياراً

الميزات الرئيسية

  • واجهة API متوافقة مع OpenAI، تشمل نقاط نهاية إكمالات المحادثة والإكمالات وembeddings — معظم كود SDK الخاص بـ OpenAI يعمل بتغيير رابط أساسي فقط
  • دعم صيغة نموذج GGUF بتكميم من 1.5 بت إلى 8 بت، ما يتيح تشغيل نماذج كبيرة بجزء صغير من بصمتها الأصلية في الذاكرة
  • استدلال فعّال على CPU كهدف تصميم أساسي، بالإضافة إلى تسريع GPU اختياري (CUDA وMetal وVulkan وROCm) عندما يدعمه الجهاز
  • واجهة ويب مدمجة للدردشة مع النموذج المُحمَّل مباشرة من المتصفح، بدون واجهة أمامية منفصلة مطلوبة
  • معالجة طلبات متوازية (slots) حتى يستطيع السيرفر معالجة عدة طلبات متزامنة ضد نفس النموذج المُحمَّل
  • استدعاء دوال وتوليد مقيّد بالقواعد (GBNF) لصيغ مخرجات منظمة وموثوقة
  • دعم فك الترميز التخميني لتسريع التوليد باستخدام نموذج مسودة أصغر جنباً إلى جنب مع النموذج الرئيسي
  • اعتماديات قليلة وبصمة ملف تنفيذي صغيرة، ما يجعل تشغيله مباشراً على سيرفرات محدودة أو بدون واجهة رسومية

كيفية الاستخدام بعد التثبيت

  • نزّل ملف نموذج .gguf من مصدر مثل Hugging Face — اختر مستوى تكميم (مثل Q4_K_M) يناسب ذاكرة RAM المتاحة لديك
  • ضع الملف المُنزَّل في مجلد models وأعد تسميته إلى model.gguf، تماماً كما يتوقعه السيرفر
  • أعد تشغيل الحاوية بـ docker restart llamacpp حتى يُحمّل السيرفر النموذج المُضاف حديثاً
  • اختبر نقطة النهاية المتوافقة مع OpenAI بطلب curl إلى http://your-server-ip:8283/v1/chat/completions للتأكد أن النموذج يستجيب
  • افتح واجهة الويب المدمجة في متصفحك على نفس العنوان للدردشة مع النموذج مباشرة بدون كتابة أي كود
  • وجّه أي تطبيق مبني على SDK الخاص بـ OpenAI إلى رابط سيرفرك الأساسي (http://your-server-ip:8283/v1) لاستخدامه كخلفية بديلة جاهزة
  • جرّب مستويات تكميم مختلفة إذا كانت الردود بطيئة جداً أو استخدام الذاكرة مرتفعاً جداً — التكميم بعدد بتات أقل يتنازل عن بعض الدقة مقابل سرعة وبصمة أصغر
  • راقب استخدام المعالج والذاكرة أثناء الاستدلال لفهم حدود سيرفرك العملية قبل نشر أي شيء يواجه المستخدم

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

  • يأتي هذا النشر بدون أي مصادقة افتراضياً — لا تكشف المنفذ 8283 للإنترنت العام بدون إضافة مفتاح API أو مصادقة عبر وكيل عكسي
  • ضع السيرفر خلف وكيل عكسي بـ HTTPS وتحكم وصول إذا احتاج أن يكون متاحاً خارج شبكتك المحلية
  • قيّد الوصول على الشبكات الموثوقة أو VPN، لأن أي شخص يستطيع الوصول للمنفذ يمكنه إرسال محفزات واستهلاك موارد السيرفر
  • انتبه أن المحفزات والردود تُعالَج بدون تشفير بين العميل والسيرفر ما لم تضف إنهاء TLS أمامه
  • حافظ على تحديث صورة Docker، لأن llama.cpp يُطوَّر بنشاط وغالباً ما تتضمن التحديثات إصلاحات أداء وأمان
  • إذا كشفت السيرفر لعدة مستخدمين، فكّر في تحديد المعدل على مستوى الوكيل العكسي لمنع استنزاف الموارد من طلبات متزامنة

المنافذ وإعدادات جدار الحماية

يستمع سيرفر llama.cpp على منفذ المضيف 8283، المُعيَّن من منفذ الحاوية الداخلي 8080، ويخدم واجهة API المتوافقة مع OpenAI وواجهة الويب المدمجة على نفس المنفذ. لا توجد طبقة مصادقة مدمجة افتراضياً، فيجب ألا يُكشف هذا المنفذ أبداً مباشرة للإنترنت — تعامل معه كلوحة إدارة غير محمية بمصادقة. لأي وصول يتجاوز شبكتك المحلية، ضعه خلف وكيل عكسي مثل Nginx Proxy Manager يضيف TLS، ويُفضَّل أيضاً فحص مفتاح API أو مصادقة أساسية قبل وصول الطلبات للسيرفر. إذا كنت تحتاج فقط وصولاً محلياً، أبقِ المنفذ مغلقاً تماماً أمام حركة المرور الخارجية في الجدار الناري واتصل عبر شبكتك المحلية أو VPN.

النسخ الاحتياطي والصيانة

  • انسخ ملفات نموذج .gguf المُنزَّلة احتياطياً بشكل منفصل، لأن ملفات النماذج الكبيرة غالباً ما تُستبعد من مهام النسخ الاحتياطي الروتينية بسبب حجمها
  • انسخ docker-compose.yml أو أمر التشغيل احتياطياً حتى يمكن إعادة إنشاء السيرفر بنفس تعيينات المنافذ وإعدادات الأحجام
  • وثّق مستوى التكميم وإصدار النموذج الذي تشغّله، لأن إعادة تنزيل نفس ملف GGUF بالضبط يضمن سلوكاً متسقاً بعد إعادة البناء
  • لا توجد قاعدة بيانات من جانب السيرفر أو بيانات مستخدم لنسخها احتياطياً — ملف النموذج والإعدادات هما الأصلان الدائمان الوحيدان
  • إذا خصّصت أعلام بدء تشغيل السيرفر (حجم السياق، طبقات GPU، إلخ)، احفظ تلك الإعدادات مع ملف compose الخاص بك
  • اختبر أن حاوية جديدة بملف نموذج وإعدادات مُستعادة تخدم نفس نقطة النهاية المتوافقة مع OpenAI بشكل صحيح

الأخطاء الشائعة

  • توقّع أن يرد السيرفر فوراً بعد التثبيت — يأتي بدون نموذج حتى تضيف ملف .gguf يدوياً وتعيد التشغيل
  • نسيان إعادة تشغيل الحاوية بعد وضع ملف نموذج جديد — يُحمّل السيرفر النموذج فقط عند بدء التشغيل
  • تسمية ملف النموذج بشكل خاطئ — يجب وضعه باسم model.gguf بالضبط، مطابقاً لما يتوقعه السيرفر
  • كشف المنفذ 8283 مباشرة للإنترنت بدون أي مصادقة أو وكيل عكسي أمامه
  • اختيار مستوى تكميم أكبر من ذاكرة RAM المتاحة، ما يسبب استدلالاً بطيئاً جداً أو أخطاء نفاد ذاكرة
  • افتراض أن تسريع GPU تلقائي — هذا النشر مُعدّ لاستدلال CPU، ودعم GPU يتطلب بناء/إعداداً مختلفاً
  • عدم الاختبار بنموذج صغير أولاً قبل الالتزام بنموذج كبير، ما يجعل من الصعب عزل ما إذا كان البطء بسبب حجم النموذج أو حدود الجهاز

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

  • السيرفر يرد بأخطاء أو إكمالات فارغة — تأكد أن ملف model.gguf موجود فعلاً في مجلد models وأن الحاوية أُعيد تشغيلها بعد إضافته
  • الحاوية تبدأ لكن نقطة نهاية API غير متاحة — تحقق أن المنفذ 8283 مُعيَّن بشكل صحيح وغير محظور بجدار الحماية للمضيف
  • الاستدلال بطيء جداً — جرّب نموذجاً أصغر أو أكثر تكميماً، وتحقق ما إذا كان المعالج مُستغَلاً بالكامل أو مُقيَّداً
  • أخطاء نفاد الذاكرة أو تعطل الحاوية — على الأرجح أن مستوى تكميم النموذج المختار يتجاوز ذاكرة RAM المتاحة؛ انتقل لتكميم أصغر (مثل Q4 بدلاً من Q8)
  • كود SDK الخاص بـ OpenAI القائم يفشل في الاتصال — تحقق مرتين أن الرابط الأساسي يطابق سيرفرك (http://your-server-ip:8283/v1) وأن مكتبة العميل تسمح برابط أساسي مخصص
  • واجهة الويب تُحمَّل لكن الدردشة لا تستجيب — راجع سجلات الحاوية لأخطاء التحميل وتأكد أن ملف GGUF غير تالف أو نُزِّل بشكل غير كامل
  • الردود أقل جودة من المتوقع — جرّب مستوى تكميم أقل حدة (مثل Q6_K أو Q8_0) إذا سمحت الذاكرة، لأن التكميم الأثقل يتنازل عن الدقة مقابل الحجم

البدائل

Ollama مبني مباشرة فوق llama.cpp لكنه يضيف مكتبة نماذج وتنزيلات بأمر واحد وإدارة نماذج تلقائية وواجهة API أكثر صقلاً — إنه الخيار الأفضل إذا كنت تريد الراحة على حساب التحكم اليدوي. LocalAI يغلّف llama.cpp أيضاً (ومحركات أخرى) خلف سطح API أوسع متوافق مع OpenAI، يشمل نماذج صور وصوت. LM Studio يقدم واجهة رسومية سطح مكتب مصقولة فوق llama.cpp للمستخدمين الذين يفضلون تطبيقاً رسومياً بدلاً من سيرفر وسطر أوامر. لاستدلال إنتاجي كثيف GPU على نطاق واسع، يقدم vLLM إنتاجية أعلى على الأجهزة المدعومة لكن بإعداد أكثر تعقيداً ولا يستهدف عمليات النشر بـ CPU فقط كما يفعل llama.cpp. إذا كنت تريد تحديداً أخف محرك استدلال وأكثره قابلية للتحكم بدون طبقة تجريد بينك وبين النموذج، فـ llama.cpp نفسه — مُشغَّلاً مباشرة كما في هذا الدرس — يبقى الخيار الأكثر شفافية.

متى لا تستخدمه

إذا كنت تريد فقط تشغيل نماذج محلية بأقل إعداد ولا يهمك التحكم اليدوي، يمنحك Ollama نفس محرك llama.cpp تحت الغطاء بمقاومة أقل بكثير — تنزيلات النماذج وتحديثاتها وإدارتها كلها مُتكفَّل بها لك. إذا كان عملك يتطلب أقصى إنتاجية على أجهزة GPU قوية على نطاق واسع، فمحرك خدمة مُصمَّم لهذا الغرض مثل vLLM سيتفوق عادة على دعم GPU في llama.cpp لأعباء عمل إنتاجية عالية التزامن. إذا كنت تريد تجربة سطح مكتب رسومية بدلاً من سيرفر تُعدّه يدوياً، فـ LM Studio يغلّف نفس المحرك الأساسي بواجهة أكثر ودية. وإذا كنت تحتاج مصادقة مدمجة أو إدارة مستخدمين أو واجهة دردشة مصقولة جاهزة من الصندوق، فإقران llama.cpp مع Open WebUI (أو التحول لأداة تتضمن هذه الميزات) سيوفر جهد إعداد كبير مقارنة ببنائها بنفسك على السيرفر العاري.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هو llama.cpp؟

إنه محرك استدلال مفتوح المصدر وفعّال مكتوب بلغة C/C++ يُبنى عليه جزء كبير من منظومة LLM المحلية — بما فيها Ollama وLocalAI. يشغّل نماذج لغة بصيغة GGUF باعتماديات قليلة، بكفاءة تكفي للعمل جيداً حتى على أجهزة CPU فقط.

ما المنفذ الذي يستخدمه وكيف أستدعيه؟

يستمع السيرفر على منفذ المضيف 8283، المُعيَّن من منفذ الحاوية الداخلي 8080. يعرض واجهة API متوافقة مع OpenAI، والأكثر فائدة على http://your-server-ip:8283/v1/chat/completions، فيعمل كود SDK الخاص بـ OpenAI القائم بتغيير رابط أساسي فقط.

لماذا لا يرد فور التثبيت؟

لأنه لم يُعطَ نموذجاً بعد. يتوقع السيرفر ملف GGUF عند /models/model.gguf، وهذا النشر يأتي بدونه بالتصميم. نزّل نموذج .gguf، ضعه في مجلد models باسم model.gguf، ثم أعد تشغيل الحاوية بـ docker restart llamacpp حتى يُحمَّل.

هل أحتاج GPU؟

لا — هذا النشر مُعدّ لاستدلال CPU، وهو أحد نقاط قوة llama.cpp الأساسية. النماذج المُكمَّمة بصيغة GGUF مضغوطة بما يكفي للعمل على معالجات عادية وذاكرة RAM متواضعة. المقايضة هي السرعة: النماذج الكبيرة على CPU تولّد النص أبطأ من نفس النموذج على GPU.

ما الفرق بينه وبين Ollama؟

Ollama مبني مباشرة فوق llama.cpp لكنه يضيف مكتبة نماذج وتنزيلات بأمر واحد وإدارة نماذج تلقائية وواجهة API أكثر صقلاً — إنه يُخفي بالضبط الخطوات اليدوية (تنزيل ملف GGUF ووضعه بشكل صحيح وإعادة تشغيل الحاوية) التي يكشفها هذا النشر. تشغيل سيرفر llama.cpp مباشرة يمنحك نفس محرك الاستدلال بتحكم كامل وبدون طبقة تجريد بينكما.