Llama Cpp Python: التثبيت وبناء GPU والمعاملات

llama-cpp-python هو ربط Python لـ llama.cpp. يتم تحميله نماذج GGUF في العملية، ويفضح غلاف 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 تعيين، يقوم CMake بتكوين backend CPU العام وهذا ما تحصل عليه، بشكل دائم، حتى تعيد البناء. على macOS arm64 هذا أقل إشكالية لأن الإصدارات الحديثة تفعّل Metal backend بشكل افتراضي، لكن على Linux و Windows سيعمل التثبيت العادي بالكامل على وحدة المعالجة المركزية الخاصة بك.

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

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

الخيار 1: عجلات مدمجة مسبقاً (لا يتطلب مترجماً)

ينشر المشروع فهارس عجلات، بما في ذلك فهرس CPU على https://abetlen.github.io/llama-cpp-python/whl/cpu ومتغيرات CUDA التي يشفر segment المسار إصدار 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 تعود بصمت إلى البناء من المصدر.

الخيار 2: البناء من المصدر (Linux، CUDA)

تحتاج إلى مجموعة أدوات C++، CMake، وToolkit 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، والupstream الحالي يستخدم GGML_ بادئة. إذا فشل بناء على خيار CMake غير معروف، فعادة ما يكون هذا هو السبب. تتبع الbackends الأخرى نفس النمط — Vulkan هو -DGGML_VULKAN=on، SYCL هو -DGGML_SYCL=on، وخيار AMD/ROCm تمت إعادة تسميته أكثر من مرة، لذا اقرأ ملف README للإصدار المثبت لديك بدلاً من نسخ العلم من منشور في منتدى.

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

الخيار 3: macOS مع Metal

xcode-select --install

CMAKE_ARGS="-DGGML_METAL=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall

على Apple Silicon، تحقق من أنك لا تقوم بتشغيل Python x86 على Rosetta: python -c "import platform; print(platform.machine())" يجب أن يطبع arm64. مفسر x86_64 ينتج بناءً بدون Metal backend بغض النظر عن CMAKE_ARGS الذي تمرره. لأن GPU و CPU يشاركان الذاكرة على Apple Silicon، n_gpu_layers=-1 هو دائماً تقريباً الإعداد الصحيح هناك.

الخيار 4: Windows مع CUDA

ثبّت Visual Studio Build Tools 2022 مع workload «Desktop development with C++» الأول، ثم CUDA Toolkit، بحيث يقوم 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 هو المسار الأكثر عرضة للفشل من بين المنصات الثلاث؛ إذا كنت تريد فقط الاستدلال وليس بناءً مخصصاً، فإن عجلات CUDA المدمجة مسبقاً أو WSL2 كلاهما أقل إيلاماً.

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

الفحص الأكثر موثوقية هو مخرجات Loader المفصلة، وهي غير معتمدة على الإصدار:

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

على بناء CUDA ستري خطوط تهيئة backend تذكر CUDA واسم جهاز، بالإضافة إلى خط تحميل tensor يبلغ عن عدد طبقات النموذج التي تم نقلها إلى GPU. على Metal ستري خطوط Metal device بدلاً من ذلك. بناء يعتمد على CPU فقط لا يطبع أياً منها ويبلغ عن صفر طبقات مُنقولة. تحقق بالتبادل مع nvidia-smi أثناء الإنشاء: إذا كانت عملية Python الخاصة بك لا تحتفظ بـ 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("Q: What is a GGUF file? A:", max_tokens=128, stop=["Q:"]) واقرأ out["choices"][0]["text"].

بث الرموز

مرر stream=True وكرّر. شكل الاستجابة يعكس تنسيق البث في OpenAI، لذا الجزء الأول عادة يحمل الدور فقط والأجزاء اللاحقة تحمل content التغييرات:

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "اكتب Haiku عن ملفات 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 استعرض الخيارات الموجودة بكمية محدودة وأحجامها في قاعدة بيانات نماذج الذكاء الاصطناعي.

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

المعامل	ما الذي يفعله	الإرشادات العملية
n_gpu_layers	عدد طبقات المحول المراد نقلها إلى GPU. القيمة الافتراضية 0، أي CPU فقط. -1 تعني كلها.	ابدأ من -1إذا حصلت على خطأ نفاد الذاكرة عند التحميل، قلل تدريجياً حتى يتسع.
n_ctx	نافذة السياق بالرموز. القيمة الافتراضية صغيرة عن قصد (512 في الإصدارات الحالية). مرور 0 يخبر llama.cpp بأخذ القيمة من البيانات الوصفية للنموذج نفسه.	عيّنها بصراحة. 0 قانوني لكن نموذج مدرب على سياق 128K سيحاول تخصيص ذاكرة KV لـ 128K رمز، وهذا عادة ما ينفجر VRAM الخاص بك.
n_batch	حجم الدفعة المنطقية لمعالجة المدخلات (التعبئة المسبقة)، وليس الإنشاء.	512 هو الافتراضي الشائع. رفعه إلى 1024–2048 يسرع المدخلات الطويلة على GPU على حساب مزيد من الذاكرة؛ خفّضه إذا رأيت أخطاء تخصيص المخزن المؤقت.
n_ubatch	الدفعة الصغيرة الفعلية المرسلة فعلاً إلى الواجهة الخلفية.	اتركه وشأنه إلا إذا كنت تعاني من قيود الذاكرة، حيث تقلل قيمة أصغر حجم مخزن مؤقت الحوسبة الذروة.
n_threads	الخيوط للإنشاء. n_threads_batch تغطي معالجة المدخلات.	يعني فقط للعمل لا يزال على CPU. عيّنه للأنوية الفيزيائية، وليس المنطقية (فائقة الخيوط).
offload_kqv	ما إذا كانت ذاكرة KV تعيش على GPU.	مفعّل افتراضياً وعادة ما تريده؛ تعطيله يحرر VRAM لكنه يكلف سرعة كبيرة.
use_mmap / use_mlock	خريطة الذاكرة للملف؛ قفله في الذاكرة.	احتفظ بـ mmap مفعّلاً. استخدم mlock فقط إذا كان نظام التشغيل يرسل أوزان النموذج إلى الصفحات.
chat_format	يتجاوز قالب الدردشة المضمن.	عيّنه عندما يكون القالب المدمج في النموذج مفقوداً أو خاطئاً.

لاحظ أن الانتباه السريع وكمّ ذاكرة KV (type_k / type_v) تحركت بين الإصدارات — مفتاح الانتباه السريع كان منطقياً في بعض الإصدارات وإعداد ثلاثي auto/on/off في إصدارات أخرى. شغّل help(Llama) ضد إصدارك المثبت بدلاً من الوثوق باسم العلم من منشور مدونة.

الضبط في الممارسة

الإعدادان اللذان يتفاعلان هما n_gpu_layers و n_ctx. تتنافس الأوزان وذاكرة KV على نفس VRAM، وتتسع ذاكرة KV تقريباً بشكل خطي مع طول السياق. تقليل n_ctx من 8192 إلى 4096 غالباً يحرر ذاكرة كافية لتحميل عدة طبقات إضافية، وهذا عادة ما يكون الخيار الأفضل. احسب الميزانية قبل أن تبدأ بالتخمين باستخدام حاسبة VRAM، أو تحقق من الأرقام حسب كل نموذج في مرجع متطلبات VRAM.

التحميل الجزئي يعمل — وهو الميزة المميزة لـ llama.cpp — لكن توقع انخفاضاً حاداً بمجرد بقاء أي طبقة على وحدة المعالجة المركزية، لأن كل رمز يجب أن يعبر ناقل 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

أعلام الخادم تعكس حجج المُنشئ، مع الشرطات السفلية. تحصل على /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",  # ignored unless you set model aliases
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

لأكثر من نموذج واحد، مرر --config_file config.json مع النماذج مصفوفة، يعطي كل إدخال النموذج مسار، و model_alias يمكن للعملاء طلبه بالاسم، وخاصه n_gpu_layers / n_ctx. أضف --api_key إذا كان الميناء قابلاً للوصول خارج localhost. موازنة هذا مع نقطة نهاية مستضافة؟ self-hosting vs API break-even calculator يضع الأرقام عليها.

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

الأعراض	السبب	الحل
التثبيت ينجح لكن لا توجد خطوط GPU في المخرجات التفصيلية	pip أعاد استخدام عجلة CPU مخزنة مؤقتاً	أعد التثبيت مع --no-cache-dir --force-reinstall
فشل بناء العجلة، CMake غير موجود	لا توجد سلسلة أدوات بناء	Linux: build-essential بالإضافة إلى CMake. macOS: xcode-select --install. Windows: VS Build Tools، مكون C++ workload
nvcc غير موجود أثناء التكوين	برنامج التشغيل موجود، المجموعة الأدوات مفقودة	ثبّت CUDA Toolkit. إصدار CUDA في nvidia-smi هو الحد الأقصى لبرنامج التشغيل، وليس مجموعة أدوات مثبتة
«unsupported GNU version» من nvcc	gcc على النظام أحدث مما يدعمه CUDA الخاص بك	وجّه CUDA نحو مترجم أقدم باستخدام -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-12
الآلة تتجمد أو تنفد الذاكرة أثناء الترجمة	عدد كبير جداً من وظائف البناء المتوازية	اضبط CMAKE_BUILD_PARALLEL_LEVEL=4 قبل pip install
«unknown model architecture» عند التحميل	GGUF أحدث من إصدار llama.cpp الخاص بك	ارقِ llama-cpp-python؛ إعادة بناء مطلوبة، وليس فقط تغيير الإعدادات
CUDA نفد من الذاكرة وقت التحميل	الأوزان بالإضافة إلى ذاكرة KV تتجاوز VRAM	أقل n_ctx أولاً، ثم n_gpu_layers
فشل في تخصيص مخازن مؤقتة للحوسبة	n_batch كبير جداً للذاكرة المتاحة	قلل n_batch (و n_ubatch)

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

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

لا. llama.cpp هو محرك الاستدلال C/C++؛ llama-cpp-python يتضمن التزام محدد منه ويلفه لـ Python. لأن الإصدار المضمن مثبت لكل إصدار، يمكن أن تتخلف الربط عن التطور الأساسي بأيام أو أسابيع — وهذا مهم عندما تهبط معمارية نموذج جديدة تماماً في llama.cpp ولكن ليس بعد في إصدار ربط منشور.

كيف أؤكد أن GPU يتم استخدامه فعلاً؟

حمّل باستخدام verbose=True وابحث عن سطور تهيئة الخادم الخلفي وتقرير بالطبقات المُنقولة إلى GPU. ثم راقب nvidia-smi (أو سجل GPU في Activity Monitor على macOS) أثناء التوليد. إذا لم يرتفع استخدام VRAM والرموز المولدة في الثانية تبدو كأرقام CPU، فأنت تستخدم بناء CPU فقط.

هل يمكنني تجنب الترجمة بالكامل؟

غالباً نعم — استخدم فهارس العجلات المُبنية مسبقاً للمشروع مع --extra-index-url، مع مطابقة وسم CUDA لمجموعة أدواتك. عندما لا توجد عجلة مطابقة لإصدار Python ونظام التشغيل لديك، يعود pip إلى بناء من المصدر، والذي يستغرق عادة عدة دقائق مع تفعيل CUDA.

Should I use llama-cpp-python, Ollama, or LM Studio?

استخدم llama-cpp-python عندما تريد النموذج داخل عملية Python الخاصة بك، مع التحكم المباشر في العينات واللوغاريتمات والنحويات. فضّل Ollama للحصول على خادم مُدار مع سحب النماذج والتعامل التلقائي مع الذاكرة، أو LM Studio للحصول على واجهة رسومية. كل ثلاثة منها يستقر على llama.cpp، لذا الجودة قابلة للمقارنة؛ الفرق هو سهولة الاستخدام.

هل يمكنني تشغيل نموذج أكبر من VRAM الخاص بي؟

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

هل يعمل دعم GPU على Windows بدون WSL؟

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