كوبولد سي بي بي: الدليل الشامل لبرنامج التشغيل المحلي الوحيد للنماذج اللغوية (LLM)

KoboldCpp هو ملف واحد نموذج لغوي محلي (LLM) يُنفَّذ فوق llama.cpp. نزِّل ملفًا تنفيذيًّا واحدًا، وأشر إليه بملف نموذج GGUF، وستحصل فورًا على واجهة دردشة قائمة على المتصفح وواجهة برمجية REST متوافقة مع OpenAI — دون الحاجة إلى مدير حزم، أو خدمة تعمل في الخلفية، أو أي خطوة تثبيت. وهو يعمل على أنظمة Windows وmacOS وLinux مع دعم اختياري لتسريع الأداء عبر وحدة معالجة الرسومات (GPU) باستخدام CUDA أو Metal أو Vulkan أو OpenCL.

تنزيل KoboldCpp

يتم نشر الإصدارات على صفحة إصدارات KoboldCpp على GitHubويشمل كل إصدار ملفات تنفيذية مخصصة لكل منصة؛ اختر الملف الذي يتوافق مع أجهزتك.

ويندوز

تنزيل koboldcpp.exe لدعم وحدات معالجة الرسومات من شركة NVIDIA (مع تضمين مكتبات CUDA — فلا حاجة لتثبيت حزمة أدوات CUDA بشكل منفصل، بل يكفي تثبيت برنامج تشغيل عرض NVIDIA القياسي). وإذا لم تكن تمتلك وحدة معالجة رسومات من NVIDIA، فنزِّل بدلًا منها koboldcpp_nocuda.exe وبمجرد النقر المزدوج على الملف التنفيذي (.exe)، يفتح مشغّل رسومي يمكنك من خلاله تصفح ملف النموذج وضبط الإعدادات قبل بدء الخادم. ولتجاوز المشغّل والبدء مباشرةً من سطر الأوامر، استخدم العلم —skiplauncher .

ماك أو إس

نزِّل الملف التنفيذي لأنظمة macOS من صفحة الإصدارات (عادةً ما يكون اسمه koboldcpp_mac أو يوزَّع كملف .dmg). ويتم تضمين تسريع أداء وحدة معالجة الرسومات عبر Metal تلقائيًّا — فلا حاجة لعلم إضافي؛ إذ يكتشف KoboldCpp أجهزة Apple Silicon ويستخدم Metal افتراضيًّا. وعند التشغيل الأولي لأنظمة macOS، قد تظهر رسالة تحذير تفيد بأن الملف التنفيذي مصدره مطوّر غير معروف؛ انقر بزر الماوس الأيمن واختر «فتح» لتخطي نظام Gatekeeper.

لينكس

نزِّل الملف التنفيذي لأنظمة Linux واجعله قابلاً للتنفيذ:

chmod +x koboldcpp
./koboldcpp --model /path/to/model.gguf

تشمل الملفات التنفيذية الجاهزة لأنظمة Linux دعم المعالج المركزي (CPU) وVulkan. أما لدعم CUDA على بطاقات NVIDIA، فابحث عن أصل إصدار يحتوي على لاحقة cu في اسم الملف، أو قم بالترجمة من الكود المصدري باستخدام الأمر make LLAMA_CUDA=1. وإذا كان إصدار برنامج تشغيل البطاقة الرسومية قديمًا جدًّا بحيث لا يتوافق مع إصدار CUDA المضمَّن، فإن الإصدار المدعوم بواسطة Vulkan يُعد خيارًا بديلًا موثوقًا به.

الحصول على نموذج بصيغة GGUF

يحمّل KoboldCpp ملفات GGUF مباشرةً — وهي الصيغة نفسها التي يستخدمها كلٌّ من llama.cpp وOllama. والمصدر الرئيسي لهذه الملفات هو منصة Hugging Face؛ ابحث عن اسم النموذج متبوعًا بعبارة «GGUF». وقبل التنزيل، استخدم حاسبة ذاكرة VRAM لتأكيد أن النموذج سيتّسع لوحدة معالجة الرسومات لديك عند حجم السياق المختار. ومستويات التكمين (Quantization) التي يجب معرفتها هي:

تشغيل KoboldCpp

أبسط أمر تشغيل على أي منصة هو:

./koboldcpp --model /path/to/model.gguf

وهذا يبدأ الخادم على العنوان http://localhost:5001افتح هذا الرابط في متصفحك للوصول إلى واجهة المستخدم الويب.

نظام Windows — المشغّل الرسومي

انقر نقرًا مزدوجًا على koboldcpp.exeويتيح لك نافذة المشغّل تصفح ملف النموذج وتعيين عدد الطبقات المرسلة إلى وحدة معالجة الرسومات (GPU layers) وحجم السياق ومحرك التشغيل (backend) دون اللجوء إلى سطر الأوامر. وبعد الانتهاء، انقر على زر تشغيل ؛ فتفتح نافذة طرفية تعرض سجل الخادم وتُطلق واجهة المستخدم الويب تلقائيًّا.

سطر الأوامر (على جميع الأنظمة)

أمر تشغيل نموذجي يتضمّن تفريغ الحمل على وحدة معالجة الرسومات، وحجم سياق مخصص، ومنفذ محدد صراحةً:

./koboldcpp 
  --model ./models/llama3-8b-q4_k_m.gguf 
  --gpulayers 32 
  --contextsize 8192 
  --port 5001

مرجع لأهم الأعلام:

واجهة المستخدم الويب وواجهة البرمجة المُتوافقة مع OpenAI

بعد التشغيل، يوفّر برنامج KoboldCpp واجهتين مختلفتين عبر المنفذ نفسه:

• واجهة المستخدم في المتصفح — http://localhost:5001واجهة توليد نصوص متكاملة تدعم أوضاع القصة والدردشة والتوجيه. وتتيح استخدام قوالب المُدخلات، والذاكرة، وملاحظات المؤلف، وحقول معلومات العالم الموروثة من مشروع KoboldAI.
• واجهة برمجة تطبيقات KoboldAI — http://localhost:5001/api/v1تُستخدم بواسطة واجهات أمامية مثل SillyTavern وAgnaistic.
• واجهة برمجة تطبيقات متوافقة مع OpenAI — http://localhost:5001/v1تنفّذ /v1/chat/completions و /v1/completions. ويمكن لأي عميل يقبل تحديد عنوان أساسي مخصص أن يعمل معها، بما في ذلك مكتبة LangChain ومجموعة أدوات OpenAI البرمجية لبايثون ومعظم تطبيقات الدردشة مفتوحة المصدر.

لتوجيه مجموعة أدوات OpenAI البرمجية لبايثون نحو KoboldCpp:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # لا يتطلب KoboldCpp مفتاح وصول افتراضيًا
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "مرحبًا"}]
)

تفريغ الحمل على وحدة معالجة الرسومات (GPU): تحديد القيمة المناسبة لخيار «–gpulayers»

إن نقل كل طبقة من طبقات نموذج التحويل (transformer) إلى وحدة معالجة الرسومات (GPU) يُخرج عملية المعالجة من وحدة المعالجة المركزية (CPU) ويُحسّن بشكل كبير عدد الرموز المُولَّدة في الثانية. أما المقابل فهو استهلاك ذاكرة الفيديو (VRAM). ويتحدد العدد الإجمالي لطبقات النموذج ثابتًا وفقًا لهندسته — فعلى سبيل المثال، تكون القيم الشائعة 32 طبقة للنماذج ذات الحجم 7B/8B، و40 طبقة للنماذج ذات الحجم 13B، و80 طبقة للنماذج ذات الحجم 70B. وكل طبقة تستهلك جزءًا تقريبيًا متساويًا من إجمالي ذاكرة الفيديو المخصصة للنموذج على وحدة معالجة الرسومات.

النهج العملي:

1. استخدم حاسبة ذاكرة VRAM لتقدير عدد الطبقات التي يمكن تحميلها على وحدة معالجة الرسومات عند حجم السياق المستهدف.
2. ابدأ بـ --gpulayers 999 لمحاولة التحميل الكامل على وحدة معالجة الرسومات. ويقوم برنامج KoboldCpp تلقائيًا بتقييد هذه القيمة لتتطابق مع العدد الفعلي لطبقات النموذج.
3. إذا ظهر خطأ «نفاذ الذاكرة» عند بدء التشغيل، فقلّل هذه القيمة وأعد المحاولة. كما يعرض سجل الخادم توزيع الذاكرة المُخصصة لكل طبقة لمساعدتك في ضبط القيمة بدقة.

ويدعم البرنامج التحميل الجزئي على وحدة معالجة الرسومات وهو مفيدٌ جدًّا — إذ إن تحميل نصف طبقات نموذج كبير فقط يُحقّق تحسّنًا ملحوظًا في السرعة مقارنةً بالاستنتاج الذي يعتمد كليًّا على وحدة المعالجة المركزية. وإذا كنت غير متأكد من وحدة معالجة الرسومات الأنسب لهذا النموذج، فراجع الأفضل وحدات معالجة الرسومات (GPUs) للنماذج اللغوية المحلية دليل والـ تحليل متطلبات ذاكرة الفيديو (VRAM) حسب النموذج.

حجم السياق وإعدادات الأداء

حجم السياق (--contextsize) هو العامل الأكبر الوحيد في استهلاك ذاكرة الفيديو بعد وزن النموذج. فعلى سبيل المثال، يستهلك نموذج 7B بتنسيق Q4_K_M ما يقارب 4 غيغابايت للوزن؛ بينما قد يؤدي توسيع السياق من 4096 رمزًا إلى 32768 رمزًا إلى إضافة عدة غيغابايتات إضافية إلى ذاكرة التخزين المؤقت KV. وفعّل --flashattention لتقليل استهلاك ذاكرة التخزين المؤقت KV — وهي فعّالة جدًّا جدًّا عند السياقات الطويلة جدًّا ولا تؤثر إطلاقًا على جودة المخرجات.

إعدادات أخرى تؤثر على السرعة:

• --threadsفي حالة الاستنتاج الذي يعتمد على وحدة المعالجة المركزية فقط، اضبط هذه القيمة لتكون قريبة من عدد النوى الفعلية في وحدة المعالجة المركزية، وليس عدد النوى المنطقية (المدعومة بتقنية التعدد الموازي المترابط أو Hyperthreading).
• --batchsizeالقيم الأكبر (مثل 512) تحسّن سرعة معالجة المُدخلات على حساب الذروة في استهلاك ذاكرة الفيديو أثناء مرحلة التحضير المبدئي (prefill).
• --smartcontextعند امتلاء السياق، يقوم برنامج KoboldCpp بإزاحة أقدم الرموز بدلًا من إيقاف التوليد — وهي ميزة مفيدة جدًّا في الجلسات التفاعلية الطويلة.

مقارنة بين KoboldCpp وOllama وllama.cpp

جميع هذه الأدوات الثلاثة مبنية على محرك llama.cpp نفسه وتدعم نماذج GGUF. أما الاختلافات بينها فهي في سير العمل وواجهة المستخدم.

اختر KoboldCpp إذا كنت ترغب في إعدادٍ جاهزٍ دون الحاجة إلى التثبيت، أو واجهة القصة/الدردشة المدمجة، أو التوافق مع واجهات أمامية لـ KoboldAI مثل SillyTavern.
اختر Ollama إذا كنت ترغب في مكتبة نماذج مُدارة، أو خدمة نظام، أو تكامل أوثق مع واجهة سطر الأوامر (CLI) — راجع systemd للاطّلاع على دليل تفصيلي كامل. الدليل الكامل لأولاما الدليل التفصيلي
اختر llama.cpp مباشرةً إذا كنت تقوم ببناء تكامل مخصص، أو تحتاج إلى أحدث الميزات المتاحة من النسخة الأصلية (upstream) قبل أن تصل إلى الحِزم الفرعية (downstream wrappers).

إذا كنت لا تزال تفكر في ما إذا كان يجب عليك استضافة النموذج ذاتيًا أم استخدام واجهة برمجة تطبيقات (API) مستضافة، فإن حاسبة نقطة التعادل بين الاستضافة الذاتية وواجهات برمجة التطبيقات (API) يمكن أن يساعدك في حساب نقطة التعادل التكلفيّة.

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

هل يتطلب KoboldCpp تثبيت برامج تشغيل CUDA بشكل منفصل؟

على نظام Windows، يحتوي ملف koboldcpp.exe على مكتبات وقت تشغيل CUDA المدمجة، وبالتالي فأنت بحاجة فقط إلى برنامج تشغيل عرض NVIDIA القياسي — ولا حاجة لتثبيت حزمة أدوات CUDA بشكل منفصل. أما على نظام Linux، فعادةً ما ترتبط إصدارات CUDA بالوقت التشغيلي المثبت لـ CUDA، ولذلك تكتسب توافقية إصدار برنامج التشغيل أهميةً بالغة؛ فإذا كان إصدار برنامج التشغيل قديمًا جدًّا، فإن الإصدار المبني على Vulkan يُعدّ أسهل بديلٍ يمكنك اللجوء إليه.

ماذا يعني الخيار «--gpulayers 0»؟

القيمة صفر للطبقات المُسندة للوحدة الرسومية تعني أن جميع العمليات الحسابية تُنفَّذ على وحدة المعالجة المركزية (CPU). وهذه هي القيمة الافتراضية عند عدم تحديد أي خيار متعلق بالوحدة الرسومية. وتكون عملية الاستنتاج على وحدة المعالجة المركزية أبطأ بكثير — عادةً ما تتراوح بين ٢–١٠ رموز/ثانية على وحدة معالجة مركزية حديثة، مقابل ٤٠–١٠٠+ رمز/ثانية على وحدة معالجة رسومية متوسطة الأداء — لكنها تعمل على أي جهاز بغض النظر عن توافر وحدة معالجة رسومية.

هل يمكنني استخدام KoboldCpp كاستبدال مباشر لواجهة برمجة تطبيقات OpenAI في تطبيقي؟

نعم. عيّن قيمة base_url في عميل OpenAI الخاص بك إلى http://localhost:5001/v1 وأدخل أي سلسلة نصية غير فارغة كقيمة لمعلمة api_key (ولن تتم مراجعتها افتراضيًا). ويُقبل حقل النموذج model

كيف أشغل نموذجين مختلفين في الوقت نفسه؟

يتعامل كل عملية من عمليات KoboldCpp مع نموذج واحد فقط. ولذلك، شغّل نسخة ثانية باستخدام قيمة مختلفة لمعلمة --port port

لماذا تكون عملية التوليد أبطأ مما هو متوقع حتى عند استخدام وحدة معالجة رسومية؟

السبب الأكثر شيوعًا هو التفريغ الجزئي للحسابات إلى وحدة المعالجة المركزية: فإذا كانت قيمة المعلمة --gpulayers أقل من العدد الكلي لطبقات النموذج، فإن الطبقات المتبقية ستُنفَّذ على وحدة المعالجة المركزية، ما يُشكّل عنق زجاجة. تحقّق من سجل بدء التشغيل — حيث يطبع KoboldCpp عدد الطبقات التي تم توجيهها إلى وحدة المعالجة الرسومية مقابل تلك التي نفذتها وحدة المعالجة المركزية بدقة. كما تأكّد من ظهور المحرك الصحيح (CUDA/ Metal/ Vulkan) في إخراج بدء التشغيل بدلًا من التراجع التلقائي إلى وحدة المعالجة المركزية.

هل من الآمن تعريض KoboldCpp على شبكة ما؟

بشكل افتراضي، يرتبط KoboldCpp بعنوان 127.0.0.1 localhost فقط (127.0.0.1) --host 0.0.0.0لا تحتوي KoboldCpp على آلية مصادقة مدمجة، وبالتالي لا يُوصى بتعريضها على شبكات غير موثوقة أو على الإنترنت العام دون استخدام وكيل عكسي (reverse proxy) مزوّد بميزة مصادقة أمامها.