Llama Cpp Python: التثبيت، وبناء الإصدار المدعوم بالوحدة الرسومية (GPU)، والمعامِلات

llama-cpp-python هو الربط البرمجي بلغة بايثون لمكتبة llama.cpp. وهو يقوم بتحميل نماذج تنسيق GGUF داخل العملية (in-process)، ويقدِّم غلافًا منخفض المستوى مبنيًّا على مكتبة ctypes، بالإضافة إلى واجهة برمجية عالية المستوى من نوع Llama فئة (class)، ويضم خادم HTTP متوافقًا مع واجهة برمجة تطبيقات OpenAI. أما التثبيت الافتراضي عبر pip فيقوم بتجميع إصدار يعمل على وحدة المعالجة المركزية (CPU) فقط. وللاستفادة من دعم الوحدة الرسومية (GPU)، يجب تثبيت حزمة GPU wheel أو إعادة البناء من الكود المصدري مع CMAKE_ARGS, ثم تمرير n_gpu_layers.

لماذا يكون التثبيت الافتراضي مقتصرًا على وحدة المعالجة المركزية (CPU) فقط

الحزمة عبارة عن رابط خفيف حول مكتبة بلغة C++ يجب ترجمتها مع دعم للمنصات الخلفية المدمج مسبقًا وقت البناء. ولا توجد علامة (flag) تشغيلية تفعّل CUDA لاحقًا. وعندما يقوم pip ببناء حزمة المصدر (sdist) دون تحديد أي علامة، فإن أداة CMake تقوم تلقائيًّا بتكوين منصة CPU العامة، وهذه هي النتيجة التي تحصل عليها دائمًا — حتى تقوم بإعادة البناء من جديد. CMAKE_ARGS وعلى نظام macOS arm64، هذه المسألة أقل إشكالية لأن الإصدارات الحديثة تفعّل منصة Metal افتراضيًّا، أما على أنظمة Linux وWindows فإن التثبيت العادي يعمل بالكامل على وحدة المعالجة المركزية (CPU) فقط.

وهنا نتيجتان جديرتان بالتأمل: أولًا، n_gpu_layers=-1 في بناء يعتمد على وحدة المعالجة المركزية فقط لا يؤدي أي فعلٍ مفيدٍ بصمت، ولذلك يستنتج الكثيرون خطأً أن بطاقتهم الرسومية «بطيئة جدًّا»، في حين أنها لم تُستَخدم أساسًا. ثانيًا، يقوم pip بتخزين عجلات (wheels) التثبيت المبنية مسبقًا في ذاكرة التخزين المؤقت. وبالتالي، قد يؤدي إعادة تشغيل أمر التثبيت باستخدام علامات مختلفة إلى تحميل عجلة CPU المُخزَّنة مسبقًا مرة أخرى، ولذلك تتضمّن كل أوامر إعادة البناء أدناه الخيار CMAKE_ARGS --no-cache-dir --force-reinstall الخيار الأول: عجلات مبنية مسبقًا (لا حاجة لمُجمِّع).

تثبيت llama-cpp-python مع دعم الوحدة الرسومية (GPU)

يُنشئ المشروع فهارس عجلات جاهزة، بما في ذلك فهرس مخصص لوحدة المعالجة المركزية (CPU) موجود على الرابط

https://abetlen.github.io/llama-cpp-python/whl/cpu وبالنسبة لإصدارات CUDA، فإن الجزء الخاص بالمسار في الرابط يُشير إلى إصدار CUDA المستخدم، مثل .../whl/cu124 . للتثبيت، استخدم الأمر التالي:pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

وتتغيّر العلامات الخاصة بـ CUDA والإصدارات المدعومة من Python من إصدار إلى آخر، وقد يتأخر الفهرس أحيانًا عن أحدث إصدار متاح على PyPI. لذا يُرجى الاطلاع على ملف README الخاص بالمشروع للتحقق من العلامات المتاحة حاليًّا بدلًا من افتراض وجود علامة معينة — إذ إن استخدام علامة غير صحيحة يؤدي إلى خطأ 404، ويقوم pip آنذاك بالعودة تلقائيًّا وبصمت إلى البناء من الكود المصدري.

الخيار الثاني: البناء من الكود المصدري (Linux مع دعم CUDA)

تحتاج إلى مجموعة أدوات لبرمجة C++، وأداة CMake، وحزمة أدوات CUDA مع وجود الأمر

nvcc في متغير البيئة PATH. nvcc --version # يجب أن يطبع هذا الأمر رقم الإصدار، وليس رسالة "command not found"CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

وقد تغيّرت تسمية العلامة خلال عمر المشروع: فالتوجيهات القديمة جدًّا تستخدم

-DLLAMA_CUBLAS=on ، بينما تستخدم التوجيهات الصادرة منتصف عام 2024-DLLAMA_CUDA=on ، أما الإصدار الحالي الرسمي فيستخدم البادئةGGML_ . وإذا أدى البناء إلى خطأ بسبب خيار غير معروف في CMake، فغالبًا ما يكون السبب هو عدم التطابق بين العلامة المستخدمة والإصدار الحالي. وتتبع المنصات الخلفية الأخرى نفس النمط: فلمنصة Vulkan العلامة -DGGML_VULKAN=on ، ولمنصة SYCL العلامة-DGGML_SYCL=on ، أما الخيار الخاص ببطاقات AMD/ROCm فقد تم تغيير اسمه أكثر من مرة، لذا يُرجى قراءة ملف README الخاص بالإصدار الذي قمت بتثبيته بدلًا من نسخ علامة من منشور على منتدى.ويمكنك تقليص وقت الترجمة بشكل كبير عبر البناء المخصص لقدرة الحوسبة (compute capability) الخاصة ببطاقتك الرسومية فقط، مثل

-DCMAKE_CUDA_ARCHITECTURES=89 لبطاقة من فئة Ada مثل RTX 4090، أو لبطاقة RTX 3090. ويمكنك الاطلاع على قدرة الحوسبة الخاصة ببطاقتك في القائمة الرسمية لشركة NVIDIA؛ وإذا كنت لا تزال تختار الأجهزة المناسبة، فإن دليلنا المعنون 86 أفضل وحدات معالجة رسومية (GPUs) لتشغيل نماذج اللغة الكبيرة محليًّا يتناول مقارنة سعة الذاكرة الرسومية (VRAM) مقابل السعر. الخيار الثالث: نظام macOS مع دعم Metal

xcode-select --installCMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python --no-cache-dir --force-reinstall

على معالجات Apple Silicon، تأكّد من أنك لا تستخدم تفسير بايثون (Python interpreter) يعمل عبر Rosetta بمعمارية x86: الأمر

python -c "import platform; print(platform.machine())" يجب أن يطبع arm64 . أما إذا طبع الأمر "x86_64"، فسيؤدي ذلك إلى بناء لا يتضمّن دعم Metal مهما كانت العلامات التي مرّرتها عبر CMAKE_ARGS. وبما أن وحدة المعالجة الرسومية ووحدة المعالجة المركزية تشاركان الذاكرة نفسها على معالجات Apple Silicon، فإن الإعدادn_gpu_layers=-1 n_gpu_layers=-1 هو عمومًا الإعداد الأمثل في هذه الحالة.

الخيار الرابع: نظام Windows مع دعم CUDA

قم بتثبيت أدوات بناء Visual Studio 2022 مع خيار "تطوير سطح المكتب باستخدام C++" (Desktop development with C++) الأولثم قم بتثبيت حزمة أدوات CUDA، بحيث تقوم CUDA بتثبيت تكاملها مع MSBuild ضمن بيئة Visual Studio الموجودة مسبقًا. وبعد ذلك، في PowerShell، استخدم الأمر التالي:

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

في أما في cmd.exe، فالعبارة المكافئة هي set CMAKE_ARGS=-DGGML_CUDA=on المكتوبة في سطر منفصل. ويعتبر البناء من الكود المصدري على نظام Windows أكثر المسارات عُرضةً للفشل بين المنصات الثلاث؛ لذا، إذا كنت ترغب فقط في الاستنتاج (inference) دون الحاجة إلى بناء مخصّص، فإن استخدام العجلات الجاهزة المبنية لـ CUDA أو بيئة WSL2 سيكونان خيارين أقل تعقيدًا.

كيف تعرف أي إصدار لديك

وأكثر طريقة موثوقة للتحقق هي مخرجات محمل النموذج التفصيلية (verbose loader output)، وهي مستقلة عن رقم الإصدار:

from llama_cpp import Llama
llm = Llama(model_path="./models/model.gguf", n_gpu_layers=-1, verbose=True)

وفي حالة البناء المدعوم بـ CUDA، ستظهر سطور تهيئة المنصة الخلفية التي تشير إلى CUDA واسم الجهاز، بالإضافة إلى سطر تحميل التنسورات الذي يوضح عدد الطبقات التي تم تفريغها (offload) إلى وحدة المعالجة الرسومية. أما في حالة Metal، فستظهر سطور تشير إلى جهاز Metal بدلًا من ذلك. أما في حالة البناء الذي يعتمد على وحدة المعالجة المركزية فقط، فلن تظهر أي من هاتين المجموعتين من السطور، وسيتم الإبلاغ عن صفر طبقات تم تفريغها. وقم بالتحقق المتقاطع مع nvidia-smi أثناء التوليد: إذا لم تكن عملية بايثون الخاصة بك تحتفظ بذاكرة VRAM، فهذا يعني أنه لا شيء يعمل على وحدة معالجة الرسومات (GPU).

الإصدارات الحديثة تعرض أيضًا فحصًا مباشرًا للقدرات:

from llama_cpp import llama_cpp, __version__
print(__version__)
print(llama_cpp.llama_supports_gpu_offload())

إذا أدى الوصول إلى هذه السمة إلى استثناء من نوع AttributeError، فهذا يعني أن إصدار المكتبة الذي قمت ببنائه يسبق ظهور هذه السمة — ارجع عندئذٍ إلى الطريقة القديمة التي تعتمد على سجلات التفصيل.

تحميل ملف GGUF وتشغيل أول عملية إكمال

نقطة model_path إلى أي ملف بصيغة GGUF. وإذا كنت تفضل تنزيل النموذج مباشرةً من منصة Hugging Face، فيمكنك استخدام Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) والتي تقوم تلقائيًا بتنزيل الملف عند huggingface-hub المثبتة مسبقًا.

from llama_cpp import Llama

llm = Llama(
    model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf",
    n_gpu_layers=-1,
    n_ctx=4096,
    n_batch=512,
    verbose=False,
)

out = llm.create_chat_completion(
    messages=[{"role": "user", "content": "اشرح مفهوم ذاكرة التخزين المؤقت KV في جملتين."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

للاستمرار في توليد نص عادي (بدون تنسيق دردشة)، يمكنك استدعاء الكائن مباشرةً: llm("س: ما هي ملفات GGUF؟ ج:", max_tokens=128, stop=["س:"]) واقرأ out["choices"][0]["text"].

تدفق الرموز (Streaming tokens)

مرر القيمة stream=True وكرّر التكرار على الناتج. ويُحاكي شكل الاستجابة تنسيق OpenAI الخاص بالتدفق، لذا فإن الجزء الأول عادةً ما يحتوي فقط على دور (role)، بينما تحتوي الأجزاء اللاحقة على اختلافات (deltas) في content كالتالي:

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "اكتب قصيدة هايكي عن ملفات GGUF."}],
    stream=True,
)
for chunk in stream:
    delta = chunk["choices"][0]["delta"]
    if "content" in delta:
        print(delta["content"], end="", flush=True)

تحتوي معظم ملفات GGUF على قالب دردشة مضمن يتم تطبيقه تلقائيًا بواسطة llama-cpp-python. وعندما يبدو الإخراج مشوّشًا أو لا يتوقف النموذج أبدًا عن التوليد، فإن القالب يكون أول ما يجب الشك فيه — ويمكنك تجاوزه باستخدام وسيطة chat_format استعرض الخيارات المُكمَّنة (quantised) وأحجامها في قسم قاعدة بيانات نماذج الذكاء الاصطناعي.

المُعطيات التي تهمّ فعليًّا

لاحظ أن تقنية الانتباه الفلاشية (flash attention) وكمّنة ذاكرة التخزين المؤقت KV (KV-cache quantization) (type_k / type_vانتقلت بين الإصدارات — فقد كانت خاصية التبديل الخاصة بـ Flash Attention عبارة عن قيمة منطقية (Boolean) في بعض الإصدارات، بينما كانت إعدادًا ثلاثيّ القيمة (تلقائي/مُفعَّل/معطَّل) في إصدارات أخرى. نفِّذ help(Llama) على النسخة المثبتة لديك بدل الاعتماد على اسم معلِّمة ورد في منشور مدوّنة ما.

الضبط العملي

الإ(settingان اللذان يتفاعلان مع بعضهما هما n_gpu_layers و n_ctx. فالمُعاملات (الوزنات) وذاكرة التخزين المؤقت للمفاتيح والقيم (KV cache) تتنافس على نفس ذاكرة الوصول العشوائي للوحدة الرسومية (VRAM)، وتزداد هذه الذاكرة تقريبيًّا بشكل خطي مع طول السياق. وغالبًا ما يؤدي تخفيض قيمة n_ctx من 8192 إلى 4096 إلى تحرير كمية كافية من الذاكرة لنقل عدة طبقات إضافية إلى وحدة المعالجة المركزية (CPU)، وهي عادةً أفضل صفقة. احسب الميزانية المتاحة قبل أن تبدأ بالتخمين باستخدام أداة حاسبة الذاكرة المخصصة للرسومات (VRAM)، أو راجع الأرقام الخاصة بكل نموذج في قسم مرجع متطلبات الذاكرة VRAM.

يعمل التحميل الجزئي (Partial offload) — وهي الميزة المميَّزة لمكتبة llama.cpp — لكنك ستلاحظ انخفاضًا حادًّا في الأداء بمجرد بقاء أي طبقة على وحدة المعالجة المركزية (CPU)، لأن كل رمزٍ (token) يجب أن يعبر حافلة PCIe. لذا إن أمكنك تحميل جميع الطبقات في الذاكرة، فافعل ذلك.

وضع الخادم المتوافق مع OpenAI

pip install "llama-cpp-python[server]"

python -m llama_cpp.server 
  --model ./models/qwen2.5-7b-instruct-q4_k_m.gguf 
  --n_gpu_layers -1 
  --n_ctx 4096 
  --host 0.0.0.0 --port 8000

تعكس مُعطيات الخادم (Server flags) الوسيطات المُستخدمة في دالة البناء (constructor arguments)، بما في ذلك الشرطة السفلية (_). وستحصل على /v1/chat/completions, /v1/completions, /v1/models، ووثائق تفاعلية عند العنوان /docs. ويتوافق أي عميل OpenAI مع هذا الخادم، كما يدعم البث الحي عبر بروتوكول SSE:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
for event in client.chat.completions.create(
    model="gpt-3.5-turbo",  # يتم تجاهلها ما لم تُعيَّن أسماء بديلة للنماذج
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

لتشغيل أكثر من نموذج واحد، مرر المعلِّمة --config_file config.json تحتوي على مصفوفة (array)، بحيث يحتوي كل عنصر فيها على النماذج مسار (path)، و النموذج اسم بديل للنموذج (model_alias) يمكن للعملاء طلبه باسمه، بالإضافة إلى إعداداته الخاصة من . وأضف المعلِّمة n_gpu_layers / n_ctx--api_key إذا كان المنفذ (port) قابلاً للوصول من خارج localhost. هل تفكر في مقارنة هذا الحل مع نقطة نهاية مستضافة؟ إن تقرير يقدّم الأرقام الدقيقة لذلك. حاسبة نقطة التعادل بين الاستضافة الذاتية وواجهات برمجة التطبيقات (API) يقدّم الأرقام الدقيقة لذلك.

أخطاء البناء الشائعة والحلول المُقترحة لها

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

هل llama-cpp-python هو نفسه llama.cpp؟

كلا. إن llama.cpp هو محرك الاستنتاج المكتوب بلغتي C/C++؛ أما llama-cpp-python فيُضمِّن إصدارًا محدَّدًا من هذا المحرك ويُغلفه للاستخدام مع بايثون. وبما أن الإصدار المُضمَّن يُثبَّت لكل إصدار منطقي، فقد تتأخَّر واجهات الربط هذه عن التحديثات الأصلية (upstream) بيومٍ أو أكثر — وهذا أمرٌ بالغ الأهمية عندما يظهر هيكل نموذج جديد تمامًا في llama.cpp لكنه لم يُدمج بعدُ في إصدار منشور من واجهات الربط.

كيف أتأكد من أن وحدة معالجة الرسومات (GPU) تُستخدم فعليًّا؟

قم بالتحميل باستخدام verbose=True وابحث عن سطور تهيئة واجهة التشغيل (backend) وتقريرٍ يوضح عدد الطبقات التي تم تحميلها على وحدة معالجة الرسومات. ثم راقب استخدام وحدة معالجة الرسومات عبر أداة nvidia-smi (أو سجل استخدام وحدة معالجة الرسومات في «مراقب النشاط» Activity Monitor على نظام macOS) أثناء توليد النصوص. فإذا لم يزد استهلاك ذاكرة VRAM، وبقيت سرعة توليد الرموز (tokens per second) عند مستويات مشابهة لتلك الخاصة بالمعالج المركزي (CPU)، فهذا يعني أنك تستخدم بناءً لا يدعم وحدة معالجة الرسومات إطلاقًا.

هل يمكنني تجنُّب عملية التجميع تمامًا؟

غالبًا نعم — استخدم فهارس الحزم الجاهزة (prebuilt wheel indexes) الخاصة بالمشروع مع الخيار --extra-index-url، واجعل علامة CUDA متوافقة مع مجموعة أدواتك. وعندما لا يتوفر حزمة جاهزة (wheel) مطابقة لإصدار بايثون ومنصتك، يعود pip تلقائيًّا إلى البناء من الكود المصدري، وهي عملية تستغرق عادةً عدة دقائق عند تفعيل دعم CUDA.

هل ينبغي عليّ استخدام llama-cpp-python أم Ollama أم LM Studio?

استخدم llama-cpp-python عندما ترغب في تشغيل النموذج داخل عملية بايثون الخاصة بك، مع تحكُّم مباشر في طرق أخذ العيِّنات (sampling) والقيم اللوجستية (logits) وقواعد اللغة (grammars). ويفضَّل استخدام Ollama كمُخدِّم مُدار (managed daemon) يدعم تنزيل النماذج ومعالجة الذاكرة تلقائيًّا، أو استخدام LM Studio لواجهة رسومية (GUI). وكلُّ هذه الأدوات الثلاثة تعتمد على llama.cpp، وبالتالي فإن جودة الأداء متساوية تقريبًا؛ أما الاختلاف فيكمن في سهولة الاستخدام والتكامل.

هل يمكنني تشغيل نموذجٍ أكبر من سعة ذاكرة VRAM المتاحة لديّ؟

نعم. عيِّن المعلَّمة n_gpu_layers إلى قيمة أقل من عدد طبقات النموذج، وسيتم تشغيل ما تبقى من الطبقات على المعالج المركزي (CPU) باستخدام الذاكرة النظامية (RAM). وهذه الطريقة تعمل بموثوقية، لكن العقوبة الزمنية (speed penalty) تكون شديدة جدًّا بمجرد أن تبقى نسبة كبيرة من الطبقات على المعالج المركزي، ولذلك فإن استخدام نموذج أصغر مع تكميم (quantization) أعلى غالبًا ما يكون أفضل من استخدام نموذج كبير يتم تفريغ جزءٍ منه فقط إلى وحدة معالجة الرسومات.

هل يعمل دعم وحدة معالجة الرسومات (GPU) على نظام Windows دون الحاجة إلى WSL؟

نعم، يعمل ذلك. يمكنك إما تثبيت حزمة جاهزة (prebuilt CUDA wheel) أو البناء من الكود المصدري باستخدام أدوات بناء Visual Studio 2022 (Desktop development with C++) المثبتة قبل تثبيت مجموعة أدوات CUDA، مع ضبط المتغير $env:CMAKE_ARGS في بيئة PowerShell. ولا يزال استخدام WSL2 يُعدُّ الخيار الأسهل إذا كنت مرتاحًا للعمل ضمنه، لأن إرشادات البناء على نظام Linux أكثر انتشارًا وتجربةً.