- كوبولد سي بي بي هو ملف تنفيذي واحد — فقط قم بتنزيله، ثم أشر إليه ملف نموذج GGUF، وسيبدأ واجهة المستخدم عبر المتصفح بالإضافة إلى واجهة برمجة تطبيقات متوافقة مع OpenAI فورًا على المنفذ 5001.
- يتم التحكم في GPU offload عبر
--gpulayers N؛ ابدأ بـ 999 لتجربة الإفراغ الكامل وقلل القيمة إذا واجهت أخطاء نقص الذاكرة. - Use it when you want a built-in story/chat UI or need KoboldAI-compatible endpoints; use Ollama if you prefer a managed model library and CLI-first workflow.
- بدون خطوة تثبيت، بدون مدير حزم، بدون daemon — فقط ملف ثنائي واحد وملف GGUF.
KoboldCpp هو runtime بملف واحد نموذج محلي مبني فوق llama.cpp. حمّل ملف ثنائي واحد، وأشر إليه بملف نموذج GGUF، وستحصل فوراً على واجهة مستخدم دردشة تعتمد على المتصفح وواجهة برمجية REST متوافقة مع OpenAI — بدون مدير حزم، بدون daemon للتكوين، بدون خطوة تثبيت مطلوبة. يعمل على Windows و macOS و Linux مع تسريع GPU اختياري عبر CUDA أو Metal أو Vulkan أو OpenCL.
تحميل KoboldCpp
يتم نشر الإصدارات على صفحة إصدارات KoboldCpp على GitHub، وكل إصدار يتضمن ملفات تنفيذية خاصة بالنظام الأساسي؛ اختر الملف الذي يتطابق مع أجهزتك.
ويندوز
Download koboldcpp.exe لدعم GPU من NVIDIA (مكتبات CUDA مضمنة — لا تحتاج إلى تثبيت CUDA toolkit منفصل، فقط برنامج تشغيل NVIDIA العام). إذا لم يكن لديك GPU من NVIDIA، فقم بتنزيل koboldcpp_nocuda.exe بدلاً من ذلك. النقر المزدوج على ملف .exe يفتح مشغل رسومي حيث يمكنك البحث عن ملف النموذج الخاص بك وتكوين الإعدادات قبل بدء الخادم. لتخطي المشغل والبدء من سطر الأوامر، مرر --skiplauncher العلم.
macOS
قم بتنزيل ملف macOS التنفيذي من صفحة الإصدارات (عادةً باسم koboldcpp_mac أو توزيعها كملف .dmg). تسريع GPU باستخدام Metal مضمّن تلقائياً — لا توجد حاجة لأي علم إضافي؛ KoboldCpp يكتشف Apple Silicon ويستخدم Metal افتراضياً. عند الإطلاق الأول، قد يحذر macOS من أن الملف الثنائي من مطوّر غير معروّف؛ انقر بزر الماوس الأيمن → فتح لتجاوز Gatekeeper.
Linux
حمّل الملف الثنائي لنظام 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 للتأكد من أن النموذج سيتسع في GPU الخاص بك بحجم السياق المختار. مستويات الكمّ المهمة:
| Quantization | الجودة | الحجم مقابل FP16 | متى يتم الاستخدام |
|---|---|---|---|
| Q2_K | خسارة ملحوظة | ~25% | ذاكرة وصول عشوائي محدودة جداً فقط |
| Q4_K_M | جيد | ~45% | الخيار الافتراضي لمعظم الأجهزة |
| Q5_K_M | ممتاز | ~55% | عندما تكون لديك ذاكرة وصول عشوائي إضافية |
| Q8_0 | شبه خسارة-حرة | ~80% | بطاقات عالية VRAM أو ذاكرة CPU كبيرة |
تشغيل KoboldCpp
الأمر الأساسي على أي منصة:
./koboldcpp --model /path/to/model.ggufهذا يبدأ الخادم على http://localhost:5001. افتح عنوان URL هذا في متصفحك للوصول إلى واجهة الويب.
Windows — مشغل الواجهة الرسومية
انقر نقراً مزدوجاً koboldcpp.exe. تتيح لك نافذة المشغل البحث عن ملف نموذج وتعيين طبقات GPU وحجم السياق والخلفية دون لمس سطر الأوامر. انقر الإطلاق عند الانتهاء، تفتح نافذة طرفية تعرض سجل الخادم ويتم إطلاق واجهة المتصفح تلقائياً.
سطر الأوامر (جميع الأنظمة)
أمر إطلاق نموذجي مع إزاحة GPU وسياق مخصص ومنفذ صريح:
./koboldcpp
--model ./models/llama3-8b-q4_k_m.gguf
--gpulayers 32
--contextsize 8192
--port 5001مرجع العلامات الرئيسية:
| الخيار | الافتراضي | ما الذي يتحكم فيه |
|---|---|---|
--model <path> |
— | المسار إلى ملف GGUF (مطلوب) |
--gpulayers <n> |
0 | طبقات المحول المنقولة إلى GPU |
--contextsize |
4096 | حد أقصى لنافذة السياق بالرموز |
--port |
5001 | منفذ HTTP |
--host |
127.0.0.1 | عنوان الربط (استخدم 0.0.0.0 للكشف على الشبكة المحلية) |
--threads |
auto | خيوط CPU للاستدلال |
--flashattention |
مغلق | يقلل VRAM للسياقات الطويلة عبر Flash Attention |
--usecublas |
مغلق | فرض خلفية CUDA (NVIDIA) |
--usevulkan |
مغلق | خلفية Vulkan (AMD/Intel/NVIDIA) |
--skiplauncher |
مغلق | على Windows فقط: تخطي مشغل الواجهة الرسومية |
--smartcontext |
مغلق | تحول السياق بدلاً من التوقف عند الامتلاء |
واجهة الويب وAPI المتوافقة مع OpenAI
عند التشغيل، يعرض KoboldCpp واجهتين من نفس المنفذ:
- واجهة المتصفح — http://localhost:5001: واجهة توليد نصوص كاملة الميزات مع أوضاع القصة والدردشة والتعليمات. تدعم قوالب الأوامر والذاكرة وملاحظات المؤلف وحقول معلومات العالم الموروثة من مشروع KoboldAI.
- KoboldAI API — http://localhost:5001/api/v1: تستخدمها الواجهات الأمامية مثل SillyTavern و Agnaistic.
- OpenAI-compatible API — http://localhost:5001/v1: تطبق
/v1/chat/completionsو/v1/completions. أي عميل يقبل عنوان URL أساسي مخصص يعمل، بما في ذلك LangChain وحزمة OpenAI Python SDK ومعظم تطبيقات الدردشة مفتوحة المصدر.
لتوجيه حزمة OpenAI Python SDK إلى KoboldCpp:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:5001/v1",
api_key="unused" # KoboldCpp does not require an API key by default
)
response = client.chat.completions.create(
model="koboldcpp",
messages=[{"role": "user", "content": "Hello"}]GPU Offload: اختيار قيمة –gpulayers الصحيحة
كل طبقة محول تم نقلها إلى GPU تنقل المعالجة من CPU وتزيد بشكل كبير من الرموز في الثانية. المقابل هو VRAM. عدد طبقات النموذج الإجمالي ثابت حسب بنيته - القيم الشائعة هي 32 للنماذج 7B/8B، و40 للنماذج 13B، و80 للنماذج 70B. كل طبقة تستهلك حصة متساوية تقريباً من إجمالي ذاكرة GPU للنموذج.
منهج عملي:
- استخدم حاسبة VRAM لتقدير عدد الطبقات التي تتسع عند حجم السياق المستهدف.
- ابدأ بـ
--gpulayers 999لمحاولة النقل الكامل. يثبت KoboldCpp هذا تلقائياً إلى عدد الطبقات الفعلي للنموذج. - إذا حصلت على خطأ في الذاكرة عند البدء، قلل القيمة وحاول مجدداً. يطبع سجل الخادم التخصيص لكل طبقة لمساعدتك على المعايرة.
يتم دعم النقل الجزئي وهو مفيد - حتى نقل نصف طبقات نموذج كبير يعطي تحسناً كبيراً في السرعة مقارنة باستدلال CPU النقي. إذا لم تكن متأكداً من GPU المراد إقران به نموذج، انظر دليل أفضل GPUs للنماذج المحلية و تفصيل متطلبات VRAM حسب النموذج.
حجم السياق وإعدادات الأداء
حجم السياق (--contextsize) هو أكبر محرك منفرد لـ VRAM بعد أوزان النموذج. نموذج 7B عند Q4_K_M يستخدم تقريباً 4 GB للأوزان؛ توسيع السياق من 4096 إلى 32768 رمز يمكن أن يضيف عدة غيغابايتات إضافية إلى ذاكرة KV. فعّل --flashattention لتقليل بصمة ذاكرة KV - هذا فعال بشكل خاص عند السياقات الطويلة جداً ولا يكلف شيئاً في جودة المخرجات.
الإعدادات الأخرى التي تؤثر على السرعة:
--threads: للاستدلال على CPU فقط، اضبطه بالقرب من عدد النوى الفعلية، وليس العدد المنطقي (hyperthreaded).--batchsize: القيم الأكبر (مثل 512) تحسن سرعة معالجة الأوامر على حساب ذاكرة VRAM الذروة أثناء الملء المسبق.--smartcontext: عندما يمتلئ السياق، يحول KoboldCpp أقدم الرموز بدلاً من التوقف عن الإنشاء - مفيد للجلسات التفاعلية الطويلة.
KoboldCpp مقابل Ollama مقابل llama.cpp
كل الثلاثة مبنية على محرك llama.cpp نفسه وتدعم نماذج GGUF. الاختلافات في سير العمل والواجهة.
| KoboldCpp | Ollama | llama.cpp (llama-server) | |
|---|---|---|---|
| التوزيع | ملف ثنائي واحد، بدون تثبيت | المثبت + خادم خلفي | البناء من المصدر أو مبني مسبقاً |
| واجهة الويب | نعم، مدمجة (rich) | بلا (يتطلب طرف ثالث) | بسيط |
| إدارة النماذج | يدوي - أحضر GGUF الخاص بك | مدمج: ollama pull |
يدوي - أحضر GGUF الخاص بك |
| OpenAI-compatible API | نعم (/v1) | نعم | نعم |
| KoboldAI API | نعم | لا | لا |
| الأفضل لـ | الكتابة الإبداعية، لعب الأدوار، SillyTavern | أدوات التطوير، واجهة سطر الأوامر، خدمة systemd | بصمة منخفضة، بناء مخصص |
اختر KoboldCpp إذا كنت تريد إعدادًا بدون تثبيت، واجهة المحادثة والقصة المدمجة، أو التوافقية مع واجهات KoboldAI الأمامية مثل SillyTavern.
اختر Ollama إذا كنت تريد مكتبة نماذج مدارة، و systemd خدمة، أو تكامل CLI أقرب — انظر دليل Ollama الكامل للحصول على شرح كامل.
اختر llama.cpp مباشرة إذا كنت تبني تكاملًا مخصصًا أو تحتاج إلى أحدث ميزات في المصدر الأساسي قبل وصولها إلى الأغلفة اللاحقة.
إذا كنت لا تزال تقرر ما إذا كنت ستستضيف ذاتيًا مقابل استدعاء API مستضاف، فإن self-hosting vs API break-even calculator يمكن أن يساعدك في نمذجة نقطة تقاطع التكلفة.
الأسئلة المتكررة
هل يتطلب KoboldCpp تثبيت برامج تشغيل CUDA بشكل منفصل؟
على نظام Windows، يجمع koboldcpp.exe مكتبات وقت تشغيل CUDA، لذا تحتاج فقط إلى برنامج تشغيل عرض NVIDIA القياسي — لا يلزم تثبيت مجموعة CUDA منفصلة. على Linux، تربط بناءات CUDA عادةً مقابل وقت التشغيل المثبت لـ CUDA، لذا يهم توافق إصدار البرنامج التشغيل؛ إذا كان البرنامج التشغيل قديمًا جدًا، فإن بناء Vulkan هو أسهل بديل.
ماذا يعني –gpulayers 0؟
لا طبقات GPU تعني تشغيل جميع الحسابات على CPU. هذا هو الافتراضي عندما لا يتم تعيين علم GPU. الاستدلال على CPU أبطأ بكثير — عادةً 2-10 رموز/ثانية على CPU حديث مقابل 40-100+ رموز/ثانية على GPU من فئة متوسطة — لكنه يعمل على أي جهاز بغض النظر عن توفر GPU.
هل يمكنني استخدام KoboldCpp كبديل API متوافق مع OpenAI لتطبيقي؟
نعم. عيّن base_url إلى http://localhost:5001/v1 وأي سلسلة غير فارغة كـ مفتاح API (لا تتم التحقق من صحتها بشكل افتراضي). يتم قبول الحقل النموذج لكن يتم تجاهله — أيًا كان GGUF المحمل يتم استخدامه دائمًا. تعمل كمل المحادثة واستكمال النصوص؛ لا تُدعم نقاط النهاية للتضمينات والصور.
كيف أقوم بتشغيل نموذجين مختلفين في نفس الوقت؟
كل عملية KoboldCpp تتعامل مع نموذج واحد. شغّل مثيلًا ثانيًا بـ --port مختلف (مثل 5002) يشير إلى ملف GGUF مختلف. لا يوجد موازن تحميل مدمج؛ قم بالتوجيه بين الحالات على مستوى التطبيق.
لماذا يكون التوليد أبطأ من المتوقع حتى مع وجود GPU؟
السبب الأكثر شيوعًا هو إزاحة CPU جزئية: إذا --gpulayers أقل من العدد الكلي لطبقات النموذج، فإن الطبقات المتبقية ستُنفَّذ على وحدة المعالجة المركزية، ما يُشكّل عنق زجاجة. تحقّق من سجل بدء التشغيل — حيث يطبع KoboldCpp عدد الطبقات التي تم توجيهها إلى وحدة المعالجة الرسومية مقابل تلك التي نفذتها وحدة المعالجة المركزية بدقة. كما تأكّد من ظهور المحرك الصحيح (CUDA/ Metal/ Vulkan) في إخراج بدء التشغيل بدلًا من التراجع التلقائي إلى وحدة المعالجة المركزية.
هل من الآمن تعريض KoboldCpp على شبكة ما؟
بشكل افتراضي، يرتبط KoboldCpp بعنوان 127.0.0.1 localhost فقط (127.0.0.1) --host 0.0.0.0لا تحتوي KoboldCpp على آلية مصادقة مدمجة، وبالتالي لا يُوصى بتعريضها على شبكات غير موثوقة أو على الإنترنت العام دون استخدام وكيل عكسي (reverse proxy) مزوّد بميزة مصادقة أمامها.