كيفية تثبيت إصدار llama.cpp على خادمك

ما الذي تغيّر في نظام إصدارات llama.cpp

يعني تثبيت إصدارات llama.cpp إنشاء إصدار باستخدام وسم محدد، وتسجيل اسم هذا الوسم بجانب ملف النموذج. لا يتغير الوسم من تلقاء نفسه، لذلك يواصل الخادم إنتاج النتيجة نفسها غداً التي أنتجها اليوم. لسنوات، لم يكن أمامك سوى نوع واحد من الوسوم: رقم بناء مثل b10502، يُنشأ تلقائياً من الفرع master. منذ 2026، ظهر نوع ثانٍ هو وسم إصدار مثل v0.1.2، ويُنشأ المساران من سجل التغييرات نفسه وفي الوقت نفسه.

لا تعني وسوم الإصدارات بعدُ ما يعنيه رقم الإصدار عادةً. توضّح ملاحظات الإصدار على v0.1.2 ذلك في سطر واحد:

لا يزال تطبيق Semantic versioning قيد العمل. تتوفر معلومات إضافية في https://github.com/ggml-org/ggml/discussions/1579

تعامل مع هذه العبارة كما هي. تجري مناقشة ggml المرتبطة بذلك الرابط في هذه المناقشة، ولا يزال العمل جارياً على تحديد النظام، بما في ذلك عدد مرات إنشاء الإصدار وما الذي يُعدّ تصحيحاً. يخبرك وسم v0. بأن المشروع اختار تحديد نقطة في سجل التغييرات. لكنه لا يضمن أن الإصدار التالي بديل آمن مباشر لمجرد أن الرقم الأخير زاد بمقدار واحد.

لا يحمل الرقم في وسم البناء معنى متعلقاً بالإصدار أيضاً. فهو ناتج عن عدد عمليات الإيداع، ولذلك يزداد تلقائياً سواء تغيّر أي شيء مهم لإعدادك أم لم يتغير. في 19 August 2026، كانت الصفحة الرئيسية لقائمة الإصدارات تعرض تسعة وسوم بناء، من b10455 إلى b10502، وكان v0.1.2 من بينها.

لا تُنشئ إصداراً من master على خادم يقدّم أي خدمة

يمنحك git pull متبوعاً بإعادة البناء كل ما أُضيف خلال الساعات القليلة الماضية. هذا مناسب على جهاز محمول. لكنه على الخادم يسلبك القدرة على الإجابة عن السؤال المهم عند تغيّر السلوك: ما الذي يعمل الآن، وما الذي كان يعمل الأسبوع الماضي؟ يتغير كل من النص الذي يُنتجه النموذج والسرعة التي يُنتجه بها مع تغيّر الإصدار. لا يمكن الإجابة عن شكوى تفيد بأن الإجابات أصبحت أسوأ يوم الثلاثاء الماضي إذا لم يُسجَّل commit الخاص بيوم الثلاثاء.

ثبّت tag بدلاً من ذلك. ينشئ المشروع هذه العلامات نيابةً عنك، ويُسمّى كل أرشيف إصدار مُعدّ مسبقاً باسم إحداها.

إلى أي وسم يجب أن تثبّت إصدارات llama.cpp؟

ثبّت وسم build عندما تريد حالة محددة ومعروفة. هذا هو المسار ذو السجل الطويل، والمسار الذي تُسمّى أرشيفات الإصدارات باسمه، والذي تستشهد به معظم تقارير الأخطاء. لذلك يكون رقم build أسهل ما يمكن مقارنته مع شخص آخر.

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

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

إنشاء الإصدار ذي العلامة المثبّتة

sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tags

يجب أن يطبع git describe --tags القيمة b10502. تحتوي النسخة السطحية المستنسخة عند علامة على ذلك الالتزام فقط، ولا تحتوي على أي شيء بعده؛ لذلك لا يستطيع أحد تغييرها لاحقاً باستخدام git pull عن طريق الخطأ. إذا توقفت خطوة configure بسبب تبعية مفقودة، فثبّت الحزمة التي يذكرها الأمر ثم شغّله مرة أخرى.

أنشئ البرنامج باستخدام الخيارات التي تتطلبها عتادك. باستخدام CPU فقط:

cmake -B build
cmake --build build --config Release -j $(nproc)

باستخدام NVIDIA GPU، بعد تثبيت CUDA toolkit أولاً:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

باستخدام OpenBLAS على جهاز يعمل بـCPU فقط:

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

تُوضع الملفات التنفيذية في build/bin، إلى جانب shared libraries التي تحمّلها، وهي libllama.so وملفات libggml. تأكد من أن عملية الإنشاء تعمل قبل تثبيتها:

./build/bin/llama-server --version

ثبّت الدليل بأكمله ضمن مسار يحمل اسم العلامة، ثم وجّه symlink واحداً إليه:

sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current

انسخ الدليل، لا الملف المنفرد. يفشل llama-server المنفرد عند تشغيله للمرة الأولى مع error while loading shared libraries: libllama.so: cannot open shared object file، لأن المكتبات التي يحتاج إليها موجودة بجانبه في ذلك الدليل.

وجّه الخدمة إلى symlink، وليس إلى دليل علامة:

[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080

يحل systemd الـsymlink عند بدء العملية، لذلك يتطلب تبديل الإصدارات تغيير هدف symlink ثم تنفيذ sudo systemctl restart llama-server. يرد وصف بقية ملف الوحدة والـreverse proxy الموضوع أمامها في الشرح الكامل لخادم llama.cpp على VPS.

سجّل الوسم بجوار ملف GGUF ومستوى التكميم

يمثّل البناء نصف العوامل التي تحدد المخرجات. ويمثّل ملف النموذج النصف الآخر. صيغة GGUF (صيغة الملفات العالمية لـGGML) هي الحاوية التي تُوزَّع فيها الأوزان، ويُنشر النموذج نفسه بمستويات تكميم متعددة. لذلك قد يختلف خادمان يستخدمان الوسم نفسه، لأن أحدهما يحتوي على ملف Q4_K_M والآخر على ملف Q8_0. احتفظ بملف صغير واحد بجوار النموذج يتضمن كل ما يلزم لإعادة إنشاء الإعداد نفسه تماماً:

tag: b10502
commit: 7c1f2a9
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>

احصل على commit باستخدام git rev-parse --short HEAD داخل النسخة المسحوبة المثبّتة. واحصل على checksum باستخدام sha256sum model-q4_k_m.gguf، وقارنه أيضاً بالقيمة التي ينشرها المورّد وقت التنزيل، لأن التحقق من التنزيل باستخدام checksum المنشور يكشف الملف المبتور قبل أن يتحول إلى خطأ يصعب تفسيره. أما مقدار تأثير مستوى التكميم نفسه في الإجابات، فهو سؤال منفصل، وتتناوله تكلفة كل مستوى تكميم عليك.

كيف تُجري الترقية من دون تعطيل الخادم؟

نفّذ الترقية كتدريب عملي. أنشئ الإصدار الجديد بجانب الإصدار القديم، وقِس أداء كليهما، واحتفظ بالإصدار القديم إلى أن يثبت الإصدار الجديد نجاحه.

1. استنسخ الوسم الجديد في مجلد مستقل. لا تُعد استخدام النسخة المستخرجة القديمة.
2. ابنِه باستخدام وسيطات cmake نفسها المسجّلة في البيان.
3. شغّل llama-bench على البنيتين باستخدام ملف النموذج نفسه، وطول المطالبة نفسه، وعدد التكرارات نفسه.
4. أرسل مطالبة تعرف إجابتَها جيداً إلى كلا الخادمين، ثم اقرأ الردين.
5. انقل الرابط الرمزي، وأعد تشغيل الخدمة، واترك المجلد القديم على القرص.

/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5

يطبع llama-bench صفاً واحداً لكل اختبار، مع عمود backend وعمود ngl وعمود لعدد الرموز في الثانية يتضمن الانحراف المعياري. قارن الصف نفسه بين البنيتين، ولا تقارن صف المطالبة في إحدى البنيتين بصف التوليد في البنية الأخرى. والنتيجة المقاسة عند طول مطالبة مختلف هي قياس مختلف، ولذلك فإن قياس عدد الرموز في الثانية بالطريقة نفسها في كل مرة أهم من الرقم نفسه.

يتطلب الرجوع إلى الإصدار السابق أمرين، ولا ينجح ذلك إلا لأن المجلد القديم ما زال موجوداً:

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

احتفظ بالبنية السابقة على الأقل. فهي تستهلك جزءاً صغيراً من مساحة القرص التي يستخدمها ملف النموذج الموجود بجانبها أصلاً.

ما الذي يتعطل عند الترقية بين إصدارات llama.cpp

يتوقف تحميل ملف النموذج. هذا هو السبب المعتاد الذي يدفع إلى الترقية من الأساس: يستخدم نموذج منشور حديثاً بنية لا يعرفها الإصدار المثبّت، ولذلك لا يُحمَّل إطلاقاً. يتوقف llama-server أثناء بدء التشغيل، ويحتوي السجل على سطر failed to load model from /srv/models/model-q4_k_m.gguf. اقرأ الأسطر المطبوعة قبله مباشرة، فهي توضّح إلى أي مرحلة وصل المُحمِّل. يحتوي GGUF أيضاً على إصدار للتنسيق في ترويسة الملف؛ القيمة الحالية في المواصفة هي 3، وقد وسّع الإصدار 2 حقول الطول من 32 إلى 64 بت. لكن عملياً، يؤدي اسم بنية غير معروف إلى إيقاف التحميل قبل أن يصبح إصدار التنسيق عاملاً مؤثراً بوقت طويل. الإصلاح هو استخدام tag أحدث وتوثيقه.

تتم إعادة تسمية أحد أعلام الخادم أو إهماله. يؤدي العلم غير المعروف إلى إيقاف llama-server عند بدء التشغيل بدلاً من تجاهله. ويظهر ذلك مع systemd على هيئة خدمة تبدأ ثم تتوقف في حلقة متكررة. يعرض journalctl -u llama-server -n 50 الرسالة الفعلية. اعتباراً من 19 August 2026، توثّق مستندات الخادم أن --mlock و--mmap مهملان لصالح -lm, --load-mode، الذي يقبل قيماً مثل auto وmmap وmlock وdio. يوثَّق علم تفريغ الحمل إلى GPU باسم -ngl, --gpu-layers، بينما تكتب الأدلة الأقدم --n-gpu-layers. قبل نقل symlink، شغّل /opt/llama.cpp/<new tag>/bin/llama-server --help وتحقق من كل علم في ملف الوحدة لديك بمقارنته بالمخرجات.

تتم إعادة تسمية أحد خيارات البناء. انتقلت خيارات CMake من بادئة LLAMA_ إلى بادئة GGML_، وما زال الملف الجذر CMakeLists.txt يحتوي على الربط بينهما. أصبح LLAMA_CUBLAS خطأً قاتلاً يذكر GGML_CUDA بديلاً له، بينما يصدر LLAMA_CUDA وLLAMA_METAL تحذيراً ويحوّلهما لك تلقائياً. يُعد توقف سكربت البناء عند خطوة الإعداد نتيجة جيدة. أما الفشل الصامت فهو أسوأ: إذا حذفت -DGGML_CUDA=ON بالخطأ، ينجح البناء، ويبدأ الخادم، ويعمل كل شيء على CPU. يعرض llama-bench ذلك فوراً، لأن العمود backend يقرأ CPU.

بناء المسرّع غير قابل للنقل. اعتباراً من 19 August 2026، تتضمن أصول Linux المرفقة مع tag البناء إصدارات CPU وVulkan وSYCL وOpenVINO، للمعماريات x64 وarm64 وs390x. لا يوجد أرشيف CUDA لـLinux ضمن هذه القائمة، ولذلك يتطلب خادم NVIDIA البناء من المصدر أو تشغيل صورة حاوية. تُنشر أرشيفات CUDA لـWindows لكل إصدار من إصدارات toolkit، وهذه إشارة مفيدة: يمثل إصدار toolkit جزءاً من هوية الملف الثنائي، ولذلك سجّله إلى جانب وسيطات cmake.

بدلاً من تثبيت صورة الحاوية

القاعدة نفسها، لكن الاسم مختلف. الصور المنشورة (ghcr.io/ggml-org/llama.cpp:server ومتغيراتها المخصصة لمسرّعات العتاد) تستخدم أسماء متغيرة، لذلك يؤدي سحب :server في الشهر المقبل إلى الحصول على برنامج مختلف تحت التصنيف نفسه. اسحب الصورة مرة واحدة واقرأ الـdigest:

docker pull ghcr.io/ggml-org/llama.cpp:server

يطبع docker pull سطراً يتضمن Digest: sha256:.... ضع ذلك الـdigest في ملف Compose بدلاً من الوسم، ولن تتغير الصورة دون علمك في المرة التالية التي يشغّل فيها أحدهم docker compose pull. احتفظ بالـdigest السابق في تعليق، بحيث تصبح استعادة الإصدار السابق تعديلاً واحداً، بالطريقة نفسها التي يتعامل بها إجراء الترقية والاستعادة لمكدس Compose مع كل خدمة أخرى.

الغرض من التثبيت

يتيح لك التثبيت تحديد ما يعمل بالضبط، كما يتيح لك إعادة الإصدار السابق خلال دقيقة واحدة عندما يؤدي تغيير ما إلى تدهور الوضع. يطلب منك llama.cpp تتبّع عنصرين لهذا الغرض، وهما وسم الإصدار وملف النموذج، لأنه يسلّمهما إليك بشكل منفصل. تعمل بيئات التشغيل التي تجمعهما بطريقة مختلفة، وتتناول مقارنة Ollama وllama.cpp كخادمين هذه المفاضلة: يكون تسجيل رقم إصدار واحد لكل المكونات والتحكم فيه أقل جهداً.

FAQ

هل ينبغي أن أثبّت وسم البناء bNNNN أم وسم v0.x؟

كلاهما مناسب، ما دمت تثبّت أحدهما. وسوم البناء مثل b10502 هي المسار طويل الأمد: يُسمّى كل أرشيف إصدار مُسبق البناء باسم أحدها، وتذكر معظم تقارير الأخطاء أحدها، لذلك يكون رقم البناء أسهل قيمة لمقارنتها مع مشغّل آخر. أما وسوم الإصدارات مثل v0.1.2 فهي قائمة أقصر من النقاط المحددة عمداً، وهذا يناسب خادماً تعدّله عدة مرات في السنة. الأهم من الاختيار هو تسجيل نص الوسم بجوار ملف النموذج، وأن تكون الترقية قراراً مقصوداً لا أثراً جانبياً لـ git pull.

هل يتبع llama.cpp الآن نظام semantic versioning؟

ليس بعد، وفقاً لتصريح المشروع نفسه. تذكر ملاحظات إصدار v0.1.2 أن semantic versioning ما يزال قيد العمل، وتشير إلى نقاش في ggml يجري فيه تحديد المخطط، بما في ذلك وتيرة الإصدارات وما الذي يُعدّ تصحيحاً. تعامل مع وسم الإصدار على أنه نقطة اختار المشرفون تحديدها. لا تفترض أن تغيير الرقم الأخير يضمن ترقية متوافقة مباشرة، واختبر الوسم الجديد مع ملف النموذج الخاص بك قبل التبديل إليه.

كيف أعرف أي بناء من llama.cpp يشغّله خادمي؟

يطبع llama-server --version معلومات الإصدار والبناء. ويبدأ سجل الإقلاع أيضاً بسطر build يتضمن رقم البناء، وتجزئة commit، والمصرّف المستخدم، لذلك يعثر journalctl -u llama-server عليه لخدمة قيد التشغيل. في تثبيت من المصدر، يطبع git describe --tags داخل checkout المثبّت الوسم، بينما يعرض readlink /opt/llama.cpp/current الدليل الذي تشير إليه الخدمة فعلياً.

لماذا توقف النموذج عن التحميل بعد ترقية llama.cpp؟

يعني فشل التحميل مباشرة بعد الترقية وجود عدم توافق بين البناء وملف GGUF. ينتهي السجل بسطر failed to load model from يذكر المسار، وتوضح الأسطر السابقة مدى تقدم أداة التحميل. عند التقدم إلى إصدار أحدث، يحتاج ملف نموذج جديد جداً إلى بناء يعرف بنيته. وعند الرجوع إلى إصدار أقدم، قد يؤدي الرجوع إلى ما دون الوسم الذي أُنشئ الملف له إلى إتلاف ملف كان يعمل في اليوم السابق. وجّه الرابط الرمزي إلى البناء السابق، ثم أعد التشغيل وتأكد من البناء والملف اللذين اقترنا بشكل صحيح قبل أن تقرر أيّاً منهما ستغيّر.

هل تتوفر ملفات Linux ثنائية مُسبقة البناء يمكنني تثبيتها بدلاً من البناء؟

نعم، لبعض الإعدادات. يحمل كل وسم بناء أرشيفات إصدار تحمل اسمه، مثل llama-b10502-bin-ubuntu-x64.tar.gz، مع توفر متغيرات arm64 وs390x وVulkan وSYCL وOpenVINO إلى جانبها اعتباراً من 19 August 2026. يسهّل هذا التنسيق تثبيت الإصدار، لأن الوسم موجود في اسم الملف. لم يتضمن ذلك الإصدار أرشيف CUDA لـLinux، لذلك يظل خادم NVIDIA بحاجة إلى البناء من المصدر باستخدام -DGGML_CUDA=ON أو إلى تشغيل إحدى صور CUDA للحاويات.