كيفية استضافة ‫LocalAI‬ على خادم ‫VPS‬

حيث يركّز ‫Ollama‬ على النص، يستهدف ‫LocalAI‬ توافقًا واسعًا مع واجهة ‫OpenAI API‬: فهو يكشف ‫/v1/chat/completions‬ و‫/v1/embeddings‬ و‫/v1/images/generations‬ وحتى نسخ الصوت، على واجهة واحدة. بالنسبة إلى فريق لديه بالفعل شيفرة مكتوبة مقابل ‫OpenAI SDK‬، يُعدّ ‫LocalAI‬ بديلاً شبه شفاف: تغيّر عنوان ‫URL‬ الأساسي والمفتاح، والباقي يعمل. على خادم ‫VPS‬، تحصل على هذا التنوّع دون اعتماد خارجي أو تكلفة لكل استدعاء. وهذا وثيق الصلة بشكل خاص عندما تحتاج في آنٍ واحد إلى توليد النصوص، والمتجهات لأغراض ‫RAG‬، وأحيانًا الصور، دون تكثير المزوّدين والمفاتيح.

بما أن ‫LocalAI‬ متعدّد الاستخدامات، فإن احتياجاته تعتمد على الوظائف المُفعَّلة. الأرقام أدناه هي حدود دنيا مقيسة — خادم ‫VPS‬ أقوى يقلل أوقات الاستجابة دون أن يغير الجدوى.

نص فقط، ‫CPU‬، نموذج ‫7B‬ (مثل ‫Mistral-7B-GGUF‬): 8 ‫GB‬ من ‫RAM‬، 4 ‫vCPU‬، 30 ‫GB‬ من القرص. بهذا الحجم، يستغرق استدعاء ‫/v1/chat/completions‬ من 5 إلى 15 ثانية حسب التكميم (‫Q4‬ هو التوازن المعياري). يناسب نموذج ‫3B‬ ذاكرة بسعة 4 ‫GB‬.

نص + صور (‫7B‬ + ‫Stable Diffusion‬): 16 ‫GB‬ من ‫RAM‬، يُوصى بـ‫GPU‬، 50 ‫GB‬ من القرص. بدون ‫GPU‬، يستغرق توليد صورة واحدة عدة دقائق على ‫CPU‬ — فضّل خادم ‫VPS‬ بـ‫GPU‬ للاستخدام المنتظم وخيار ‫SINGLE_ACTIVE_BACKEND=true‬ لتفادي التشبع عند مزج المحادثة والصور على نفس المضيف بـ‫CPU‬.

البرمجيات المطلوبة: ‫Docker 24+‬ و‫Docker Compose v2‬ (‫docker compose‬ بدون شرطة)، نطاق فرعي مخصص (مثل ‫ia.your-domain.com‬)، المنفذ 443 مفتوح، سجل ‫DNS‬ يشير إلى عنوان ‫IP‬ الخادم.

يدعم ‫LocalAI‬ صيغًا عدة، لكن صيغة ‫GGUF‬ (التي ينتجها ‫llama.cpp‬) هي المعيار الموصى به لـ‫CPU‬: إنها مكمَّمة (تقلل استخدام ‫RAM‬)، ومحمولة، ومدعومة جيدًا من قِبل المعرض.

‫GGUF‬ مقابل صيغ أخرى: صيغ ‫GGUF‬ هي الوحيدة القابلة للتحميل مباشرةً عبر ‫llama.cpp‬ دون تحويل مسبق. نماذج ‫Diffusers‬ (الصور) و‫ONNX‬ (التضمينات الخفيفة) لها واجهاتها الخلفية الخاصة وليست قابلة للتبادل مع ‫GGUF‬.

المعرض مقابل التنزيل اليدوي: المعرض هو الخيار الأبسط — فهو ينزّل ‫GGUF‬ ويولّد ‫YAML‬ الإعداد تلقائيًا. بالنسبة لنموذج غير مدرج في المعرض (نموذج مضبوط الدقة، أو ‫GGUF‬ مخصص)، ضع الملف في ‫./models/‬ وأنشئ ‫YAML‬ يدويًا:

name: my-model
backend: llama
parameters:
  model: my-model.Q4_K_M.gguf
context_size: 4096

سرد النماذج المحمّلة:

curl https://ia.your-domain.com/v1/models \
  -H 'Authorization: Bearer your-secret-key'

تظهر في القائمة النماذج التي يوجد لها ‫YAML‬ في ‫./config/‬، حتى لو لم يُنزَّل ‫GGUF‬ بعد — في هذه الحالة يُطلق الاستدعاء الأول التنزيل.

بما أن ‫LocalAI‬ متوافق مع ‫OpenAI API‬، فإن ترحيل تطبيق قائم يتلخص في تغييرين: عنوان ‫URL‬ الأساسي والمفتاح.

‫Python‬ (‫openai SDK‬):

import openai

client = openai.OpenAI(
    base_url="https://ia.your-domain.com/v1",
    api_key="your-secret-key"
)

response = client.chat.completions.create(
    model="mistral-7b-instruct-v0.2.Q4_K_M",
    messages=[{"role": "user", "content": "Summarize this text: ..."}]
)
print(response.choices[0].message.content)

‫Node.js‬ (‫openai SDK‬):

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ia.your-domain.com/v1',
  apiKey: 'your-secret-key'
});

const completion = await client.chat.completions.create({
  model: 'mistral-7b-instruct-v0.2.Q4_K_M',
  messages: [{ role: 'user', content: 'Hello' }]
});
console.log(completion.choices[0].message.content);

‫curl‬ مباشر:

curl https://ia.your-domain.com/v1/embeddings \
  -H 'Authorization: Bearer your-secret-key' \
  -H 'Content-Type: application/json' \
  -d '{"model": "all-minilm", "input": "Text to vectorize"}'

تقبل مكتبات ‫LangChain‬ و‫LlamaIndex‬ ومعظم أطر ‫RAG‬ معاملًا ‫openai_api_base‬ أو ‫base_url‬ — التغيير مطابق.

‫404 model not found‬ أو ‫model not loaded‬: اسم النموذج الممرَّر في ‫model:‬ لا يطابق أي ملف ‫YAML‬ في ‫./config/‬. تحقق بـ‫GET /v1/models‬: الاسم المعروض يجب استخدامه كما هو بالضبط. إذا لم يظهر النموذج، تحقق من وجود ‫YAML‬ في المجلد المثبَّت وأعد تشغيل الحاوية.

استنتاج بطيء جدًا أو ‫killed‬ (‫OOM‬): النموذج يتجاوز ‫RAM‬ المتاحة. يتطلب نموذج ‫7B Q4‬ تقريبًا 6 ‫GB‬ من ‫RAM‬ الحرة وقت التحميل. تحقق بـ‫docker stats localai‬ خلال استنتاج. الحلول: الانتقال إلى تكميم أخف (‫Q3_K_S‬ أو ‫Q2_K‬)، تقليل ‫context_size‬ في ‫YAML‬، أو ترقية خادم ‫VPS‬.

‫SINGLE_ACTIVE_BACKEND error‬: ‫LocalAI‬ مُهيَّأ بـ‫SINGLE_ACTIVE_BACKEND=true‬ وطلب يحاول تحميل نموذج ثانٍ بينما الأول نشط. هذا هو السلوك المتوقع على ‫CPU‬. انتظر انتهاء الاستنتاج الأول، أو عطّل الخيار إذا كان خادم ‫VPS‬ لديك يمتلك ‫RAM‬ كافية لنماذج متعددة في آنٍ واحد.

‫GPU‬ غير مكتشف (‫CUDA device not found‬): تحقق من استخدام صورة ‫latest-gpu-nvidia-cuda-12‬، ومن تثبيت برنامج تشغيل ‫NVIDIA‬ على المضيف (‫nvidia-smi‬)، ومن حصول الحاوية على وصول ‫GPU‬ (‫gpus: all‬ في ‫docker-compose.yaml‬ تحت مفتاح ‫deploy:‬). بدون هذه الشروط الثلاثة، يعود ‫LocalAI‬ بصمت إلى ‫CPU‬.

‫401 Unauthorized‬: المتغير ‫API_KEY‬ مُعيَّن في ‫docker-compose.yaml‬ لكن ترويسة ‫Authorization: Bearer <key>‬ غائبة أو خاطئة في الاستدعاء. تتطلب جميع نقاط النهاية، بما فيها ‫/v1/models‬، الترويسة فور تعيين ‫API_KEY‬.