خدمة الواجهات الخلفية

تدعم AuroraSOC ثلاث واجهات خلفية للخدمة لاستضافة استدلال LLM: Ollama (للنشر المحلي/الحافة)، وvLLM (للإنتاج)، وواجهات برمجة التطبيقات المتوافقة مع OpenAI (لموفري السحابة أو نقاط نهاية BYO). تشرح هذه الصفحة متى يتم استخدام كل منها، وكيفية تكوينها، وكيفية تكاملها مع إطار عمل الوكيل.

مقارنة الواجهة الخلفية

ميزة	أولاما	vLLM	متوافق مع OpenAI
شكل النموذج	GGUF (الكمية)	FP16/BF16 (الدقة الكاملة)	يديره الموفر
وحدة معالجة الرسومات مطلوبة	لا (وحدة المعالجة المركزية الاحتياطية)	نعم	لا (عن بعد)
الحد الأدنى لذاكرة الفيديو (VRAM)	4-8 جيجابايت (جيجوف)	8-16 جيجابايت (FP16)	لا يوجد
الطلبات المتزامنة	تسلسلي	دفعة (الدفعة المستمرة)	تعتمد على المزود
** الإنتاجية **	~1-5 مطلوب/ثانية	~50-500 مطلوب/ثانية	تعتمد على المزود
** الكمون (الرمز المميز الأول) **	~100-500 مللي ثانية	~50-200 مللي ثانية	شبكة + مزود
تعقيد الإعداد	بسيط (ollama create)	معتدل	الحد الأدنى (env vars فقط)
بروتوكول واجهة برمجة التطبيقات	واجهة برمجة تطبيقات Olma الأصلية	/v1/chat/completions متوافق مع OpenAI	/v1/chat/completions متوافق مع OpenAI
الأفضل ل	تطوير، حافة، مستخدم واحد	الإنتاج، متعدد المستخدمين، الإنتاجية العالية	النماذج السحابية، والنماذج الأولية السريعة، وخوادم BYO

أولاما

لماذا أولاما؟

Ollama هي الواجهة الخلفية الموصى بها للتطوير والنشر المحلي للأسباب التالية:

• إعداد التكوين الصفري - التثبيت والتشغيل
• يعمل بدون وحدة معالجة الرسومات (وحدة المعالجة المركزية الاحتياطية، أبطأ ولكن وظيفية)
• بصمة ذاكرة صغيرة مع تكميم GGUF
• إدارة النماذج المضمنة (السحب، الإنشاء، القائمة، الحذف)
• عظيم للاختبار والتكرار على المطالبات

تثبيت

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# macOS
brew install ollama

# Verify
ollama --version

سحب النموذج الأساسي

ollama pull granite4:8b

يؤدي هذا إلى تنزيل نموذج Granite 4 الأساسي من سجل Ollama (حوالي 1.5 جيجابايت).

استيراد نموذج مضبوط بدقة

بعد التدريب، قم باستيراد ملف GGUF الخاص بك:

# Using serve_model.py (recommended — handles Modelfile generation)
python training/scripts/serve_model.py ollama \
  --gguf training/output/generic/unsloth.Q8_0.gguf \
  --name granite-soc:latest

# Using the Makefile
make train-serve-ollama

يقوم البرنامج النصي بإنشاء Modelfile الذي يتضمن قالب دردشة Granite 4:

FROM /path/to/unsloth.Q8_0.gguf

TEMPLATE """{{- if .System }}<|start_of_role|>system<|end_of_role|>
{{ .System }}<|end_of_text|>
{{- end }}
<|start_of_role|>user<|end_of_role|>
{{ .Prompt }}<|end_of_text|>
<|start_of_role|>assistant<|end_of_role|>
{{ .Response }}<|end_of_text|>"""

PARAMETER temperature 0.1
PARAMETER top_p 0.95
PARAMETER stop "<|end_of_text|>"
PARAMETER stop "<|start_of_role|>"

سبب أهمية القالب: بدون هذا القالب، يستخدم Olma تنسيقًا عامًا للدردشة. يتم تدريب نماذج Granite 4 باستخدام محددات <|start_of_role|>...<|end_of_role|> - يؤدي استخدام القالب الخاطئ إلى إنتاج النموذج لمخرجات غير متماسكة.

أولاما في دوكر يؤلف

يتضمن docker-compose.yml الرئيسي خدمة Ollama:

ollama:
  image: ollama/ollama:latest
  ports:
    - "11434:11434"
  volumes:
    - ollama_data:/root/.ollama
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]

تشير الخدمات الأخرى إليه عبر OLLAMA_BASE_URL=http://ollama:11434.

إعدادات

# .env
LLM_BACKEND=ollama
OLLAMA_BASE_URL=http://localhost:11434   # or http://ollama:11434 in Docker
OLLAMA_MODEL=granite4:8b
OLLAMA_ORCHESTRATOR_MODEL=granite4:dense

التحقق من أولاما

# Check running models
ollama list

# Test inference
ollama run granite-soc:latest "Analyze this alert: ET TROJAN Cobalt Strike"

# Check model details
ollama show granite-soc:latest

ضبط أداء أولاما

المعلمة	تقصير	ضبط
OLLAMA_NUM_PARALLEL	1	زيادة الطلبات المتزامنة (يستخدم المزيد من VRAM)
OLLAMA_MAX_LOADED_MODELS	1	زيادة في حالة تشغيل النماذج لكل وكيل (يبقى كل منها في VRAM)
OLLAMA_KEEP_ALIVE	5 م	كم من الوقت يجب الاحتفاظ بالنموذج في الذاكرة بعد الطلب الأخير
OLLAMA_GPU_LAYERS	آلي	عدد الطبقات التي تم تحميلها على وحدة معالجة الرسومات. أقل = استخدام أقل لـ VRAM

بالنسبة للنماذج لكل وكيل، قم بتعيين OLLAMA_MAX_LOADED_MODELS على عدد النماذج المميزة التي تتوقع أن تكون نشطة في وقت واحد:

# Allow up to 4 models in VRAM simultaneously
export OLLAMA_MAX_LOADED_MODELS=4

vLLM

لماذا vLLM؟

vLLM هي الواجهة الخلفية الموصى بها للإنتاج للأسباب التالية:

• التجميع المستمر — يخدم طلبات متعددة في وقت واحد دون الانتظار
• PagedAttention — إدارة فعالة لذاكرة وحدة معالجة الرسومات، وإنتاجية أعلى بمقدار 24× من عمليات التجميع البسيطة
• واجهة برمجة التطبيقات المتوافقة مع OpenAI — بديل سهل الاستخدام لأي عميل OpenAI
• توازي الموتر — تقسيم النماذج الكبيرة عبر وحدات معالجة الرسومات المتعددة
• فك التشفير التخميني — إنشاء أسرع باستخدام نماذج مسودة

متطلبات

• وحدة معالجة الرسومات: وحدة معالجة الرسومات NVIDIA مع ذاكرة فيديو بسعة ≥16 جيجابايت (لجهاز Granite 4 Tiny FP16)
• كودا: 12.0+
• بايثون: 3.10+

تثبيت

pip install vllm

بدء تشغيل vLLM

# Serve a fine-tuned model
python training/scripts/serve_model.py vllm \
  --model training/output/generic/merged_fp16 \
  --served-model-name granite-soc-specialist

# Or start vLLM directly
python -m vllm.entrypoints.openai.api_server \
  --model training/output/generic/merged_fp16 \
  --host 0.0.0.0 \
  --port 8000 \
  --max-model-len 4096

vLLM في Docker Compose

يتضمن ملف إنشاء التدريب خدمة vLLM:

vllm:
  image: vllm/vllm-openai:latest
  ports:
    - "8000:8000"
  volumes:
    - ./training/output:/models
  command: >
    --model /models/generic/merged_fp16
    --host 0.0.0.0
    --port 8000
    --max-model-len 4096
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]

إعدادات

# .env
LLM_BACKEND=vllm
VLLM_BASE_URL=http://localhost:8000/v1   # or http://vllm:8000/v1 in Docker
VLLM_MODEL=granite-soc-specialist
VLLM_ORCHESTRATOR_MODEL=granite-soc-specialist

ضبط أداء vLLM

المعلمة	تقصير	وصف
--max-model-len	الحد الأقصى للنموذج	الحد الأقصى لطول التسلسل. أقل = أقل VRAM.
--tensor-parallel-size	1	عدد وحدات معالجة الرسومات لتوازي النموذج.
--gpu-memory-utilization	0.9	جزء من ذاكرة وحدة معالجة الرسومات (GPU) المراد استخدامه. أقل بالنسبة لوحدات معالجة الرسومات المشتركة.
--max-num-batched-tokens	آلي	الحد الأقصى من الرموز في دفعة واحدة.
--quantization	لا أحد	تكميم وقت التشغيل: awq، gptq، squeezellm.

وحدة معالجة رسومات متعددة مع vLLM

بالنسبة للنماذج الأكبر أو الإنتاجية الأعلى:

# Spread across 2 GPUs
python -m vllm.entrypoints.openai.api_server \
  --model training/output/generic/merged_fp16 \
  --tensor-parallel-size 2

التحقق من vLLM

# Check loaded models
curl http://localhost:8000/v1/models | jq

# Test inference
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "granite-soc-specialist",
    "messages": [
      {"role": "system", "content": "You are a security analyst."},
      {"role": "user", "content": "Analyze: ET TROJAN Cobalt Strike Beacon"}
    ],
    "temperature": 0.1,
    "max_tokens": 512
  }'

واجهات برمجة التطبيقات المتوافقة مع OpenAI

يمكن استخدام أي نقطة نهاية تنفذ عقد OpenAI /v1/chat/completions. يتضمن ذلك موفري الخدمات السحابية (Together AI وGroq وFireworks AI وOpenAI) والخوادم المحلية (llama.cpp وLM Studio وJan AI وLocalAI) وخوادم الاستدلال المشتركة على شبكة المؤسسة.

الموفرون المدعومون (غير شامل)

الموفر	مثال على عنوان URL الأساسي	ملاحظات
Together AI	https://api.together.xyz/v1	كتالوج نماذج واسع
Groq	https://api.groq.com/openai/v1	زمن استجابة منخفض للغاية
Fireworks AI	https://api.fireworks.ai/inference/v1	استضافة نماذج مفتوحة سريعة
OpenAI	https://api.openai.com/v1	GPT-4o وo3-mini وما إلى ذلك
llama.cpp	http://localhost:8080/v1	استدلال CPU/GPU محلي
LM Studio	http://localhost:1234/v1	تطبيق سطح مكتب للنماذج المحلية
Jan AI	http://localhost:1337/v1	تطبيق سطح مكتب مع تركيز على الخصوصية
vLLM عن بُعد	http://192.168.1.10:8000/v1	خادم GPU مشترك للفريق أو المؤسسة

حالات الاستخدام

• الوصول إلى النماذج السحابية دون تشغيل بنية تحتية GPU خاصة.
• النماذج التي لا تتوفر كعلامات Ollama أو تصديرات vLLM.
• النمذجة الأولية والوصول السريع لنماذج حدودية قبل ضبط Granite محليًا.
• خادم استدلال GPU مشترك: يتيح لمحللين متعددين تشغيل AuroraSOC على محطات عملهم بينما يجري الاستدلال مركزيًا على خادم مخصص.

متغيرات البيئة

عامل	غاية
LLM_BACKEND=openai	حدد الواجهة الخلفية العامة لـ OpenAI
OPENAI_COMPATIBLE_BASE_URL	عنوان URL الأساسي الكامل (مثل https://api.together.xyz/v1)
OPENAI_COMPATIBLE_MODEL	اسم النموذج الأساسي كما هو مدرج من قبل الموفر
OPENAI_COMPATIBLE_ORCHESTRATOR_MODEL	نموذج منسق منفصل اختياري (يعود إلى الأعلى)
OPENAI_COMPATIBLE_API_KEY	الرمز المميز للمصادقة (إذا لزم الأمر)

docker-compose.yml

services:
  aurorasoc:
    environment:
      LLM_BACKEND: "openai"
      OPENAI_COMPATIBLE_BASE_URL: "https://api.groq.com/openai/v1"
      OPENAI_COMPATIBLE_MODEL: "llama-3.3-70b-versatile"
      OPENAI_COMPATIBLE_API_KEY: "${GROQ_API_KEY}"

استخدام ملف الإضافات docker-compose.llm-api.yml

للتبديل إلى أي خادم استدلال خارجي دون تعديل الملف الرئيسي:

# خادم vLLM مشترك على الشبكة المحلية
export OPENAI_COMPATIBLE_BASE_URL=http://192.168.1.10:8000/v1
export OPENAI_COMPATIBLE_MODEL=granite4:8b
export OPENAI_COMPATIBLE_API_KEY=        # فارغ للخوادم غير المصادقة
make compose-llm-api

# أو بشكل مباشر:
docker compose -f docker-compose.yml -f docker-compose.llm-api.yml up -d

# إيقاف التشغيل:
make compose-llm-api-down

تشغيل شبكة الوكلاء المحلية مقابل واجهة برمجة تطبيقات خارجية

يمكن تشغيل الوكلاء الـ 14 على جهازك المحلي بينما يعمل الاستدلال على خادم بعيد:

# Jan AI (نفس الجهاز، بدون مفتاح)
python scripts/run_local_agents.py \
  --llm-backend openai \
  --llm-base-url http://localhost:1337/v1 \
  --llm-model granite4:8b

# LM Studio (نفس الجهاز، بدون مفتاح)
python scripts/run_local_agents.py \
  --llm-backend openai \
  --llm-base-url http://localhost:1234/v1 \
  --llm-model granite4:8b

# خادم vLLM مشترك على الشبكة المحلية
python scripts/run_local_agents.py \
  --llm-backend openai \
  --llm-base-url http://192.168.1.10:8000/v1 \
  --llm-model granite-soc-specialist

# Groq API السحابي
python scripts/run_local_agents.py \
  --llm-backend openai \
  --llm-base-url https://api.groq.com/openai/v1 \
  --llm-model llama-3.1-70b-versatile \
  --llm-api-key $GROQ_API_KEY

# اختصار Makefile
make agents-local-api \
  LLM_API_BASE_URL=http://192.168.1.10:8000/v1 \
  LLM_API_MODEL=granite-soc-specialist

التحقق من الاتصال

# Confirm the endpoint is reachable and lists models
curl -s "$OPENAI_COMPATIBLE_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_COMPATIBLE_API_KEY" | head -c 500

كيف تتصل الخلفيات بـ BeeAI

تقوم وحدة Granite بترجمة اختيار الواجهة الخلفية إلى مُنشئ ChatModel الصحيح:

لا يعرف الوكيل أو يهتم بالواجهة الخلفية التي تقف خلف ChatModel. يسمح هذا التجريد بالتبديل السلس للواجهة الخلفية دون تغيير أي رمز وكيل.

نموذج التحقق من صحة السجل

تتحقق الوحدة registry.py من توفر الواجهة الخلفية:

# Check which models are available in Ollama
available = await check_ollama_models(ollama_host)
# Returns: list[ModelStatus]

# Check vLLM models
available = await check_vllm_models(vllm_base)
# Returns: list[ModelStatus]

# Check OpenAI-compatible endpoint models
available = await check_openai_compatible_models(base_url, api_key)
# Returns: list[ModelStatus]

# Warmup a model (pre-load into GPU memory)
await warmup_model(config, agent_name="security_analyst")

يتم استخدام هذه الفحوصات أثناء:

• بدء التشغيل — التحقق من توفر النماذج المطلوبة قبل قبول الطلبات
• نقاط النهاية الصحية — الإبلاغ عن حالة النموذج في استجابات /health API
• الاسترداد التلقائي — اكتشف متى تتعطل الواجهة الخلفية وتفشل بأمان

اختيار الواجهة الخلفية: شجرة القرار

الخطوات التالية

• النشر المحلي — الإعداد الشامل الكامل
• تدريب: التقييم والتصدير — نماذج التصدير لكل واجهة خلفية