دليل النشر المحلي

تتناول هذه الصفحة كيفية نشر AuroraSOC مع Granite LLM على جهاز واحد - وهي أسرع طريقة للانتقال من النموذج المضبوط بدقة إلى الوكلاء قيد التشغيل. ويغطي البرنامج النصي للإعداد الآلي والخطوات اليدوية وتكامل Docker Compose والتحقق.

المتطلبات الأساسية

قبل أن تبدأ:

متطلبات	الحد الأدنى	مُستَحسَن
نظام التشغيل	أوبونتو 22.04 / macOS 14+	أوبونتو 24.04
كبش	16 جيجابايت	32 جيجابايت
وحدة معالجة الرسومات الجرافيكية	4 جيجا بايت (جي جي يو إف كيو 4)	8+ جيجابايت (GGUF q8)
القرص	20 جيجا مجانا	50 جيجا مجانا
Ollama	الإصدار 0.4+	أحدث
Docker	24.0+	27.0+
Python	3.10+	3.12

الإعداد الآلي – setup_local.sh

أسرع طريق. يقوم هذا البرنامج النصي بتثبيت كل شيء والتحقق من الإعداد:

chmod +x scripts/setup_local.sh
./scripts/setup_local.sh

ما يفعله البرنامج النصي

1. التحقق من تبعيات النظام — التحقق من برامج تشغيل Python ≥ 3.10 وDocker وDocker Compose وNVIDIA (في حالة وجود وحدة معالجة الرسومات)
2. تثبيت Ollama — تنزيل وتثبيت Ollama إذا لم يكن موجودًا
3. سحب النموذج الأساسي — ollama pull granite4:8b
4. إنشاء Python virtualenv — تثبيت AuroraSOC مع إضافات التدريب (pip install -e ".[training]")
5. نسخ .env.example → .env — الإعدادات الافتراضية لوقت تشغيل البذور (الواجهة الخلفية الافتراضية vLLM؛ قم بالتبديل إلى Ollama للوضع المحلي لوحدة المعالجة المركزية فقط)
6. ** تشغيل عمليات ترحيل قاعدة البيانات ** — alembic upgrade head
7. التحقق من استنتاج Ollama — يرسل موجه اختبار ويتحقق من وجود استجابة صالحة
8. ملخص حالة الطباعة — يعرض كافة عناوين URL الخاصة بالخدمة والخطوات التالية

متى تستخدم البرنامج النصي

• الإعداد لأول مرة على جهاز جديد
• بعد استنساخ المستودع في بيئة جديدة
• عند تأهيل مطور جديد يحتاج إلى أن يعمل كل شيء بسرعة

عندما لا تستخدم البرنامج النصي

• لديك بالفعل بيئة عمل (فقط قم بتحديث .env يدويًا)
• أنت تقوم بالنشر إلى الإنتاج (استخدم Docker Compose بدلاً من ذلك)
• أنت بحاجة إلى إعداد vLLM لوحدة معالجة الرسومات أولاً على الفور (يقوم البرنامج النصي بإعداد المسار المحلي Ollama)

الإعداد اليدوي (خطوة بخطوة)

إذا كنت تفضل التحكم في كل خطوة:

الخطوة 1: تثبيت Ollama

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &   # Start in background

الخطوة 2: سحب أو استيراد نموذج

الخيار أ — استخدم النموذج الأساسي (بدون تدريب):

ollama pull granite4:8b

الخيار ب — استيراد GGUF المضبوط لديك:

# Generate Modelfile + create Ollama model
python training/scripts/serve_model.py ollama \
  --gguf training/output/generic/unsloth.Q8_0.gguf \
  --name granite-soc:latest

الخيار ج — استيراد النماذج لكل وكيل:

# Create all agent-specific models at once
python training/scripts/serve_model.py ollama-all \
  --output-dir training/output

يؤدي هذا إلى إنشاء نماذج Ollama منفصلة لكل وكيل مدرب:

• granite-soc-security-analyst:latest
• granite-soc-threat-hunter:latest
• granite-soc-incident-responder:latest
• (إلخ.)

الخطوة 3: تكوين البيئة

cp .env.example .env

تحرير .env:

# Backend selection
LLM_BACKEND=ollama
OLLAMA_BASE_URL=http://localhost:11434

# Model selection (base or fine-tuned)
OLLAMA_MODEL=granite4:8b                 # Base model name in Ollama
OLLAMA_ORCHESTRATOR_MODEL=granite4:dense # Orchestrator model in Ollama

# Optional: generic fine-tuned model tag
# OLLAMA_MODEL=granite-soc:latest

# Optional: use per-agent fine-tuned models
GRANITE_USE_FINETUNED=true

الخطوة 4: التحقق

# Confirm models are loaded
ollama list

# Test inference directly
ollama run granite-soc:latest "What is a C2 beacon?"

# Test via the Granite module
python -c "
from aurorasoc.granite import create_granite_chat_model, get_default_granite_config
config = get_default_granite_config()
print(f'Backend: {config.serving_backend}')
print(f'Model: {config.resolve_model(\"security_analyst\")}')
"

الخطوة 5: ابدأ تشغيل AuroraSOC

# Start the API server
uvicorn aurorasoc.api.main:app --host 0.0.0.0 --port 8000 --reload

# Or use the Makefile
make api

نشر Docker Compose

بالنسبة للنشر في حاوية مع كافة الخدمات:

مرساة x-granite-env YAML

يستخدم docker-compose.yml مرساة YAML لتجنب تكرار متغيرات بيئة Granite عبر الخدمات:

x-granite-env: &granite-env
  LLM_BACKEND: ${LLM_BACKEND:-vllm}
  VLLM_BASE_URL: ${VLLM_BASE_URL:-http://vllm:8000/v1}
  VLLM_MODEL: ${VLLM_MODEL:-granite-soc-specialist}
  VLLM_ORCHESTRATOR_MODEL: ${VLLM_ORCHESTRATOR_MODEL:-granite-soc-specialist}
  OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://ollama:11434}
  OLLAMA_MODEL: ${OLLAMA_MODEL:-granite4:8b}
  OLLAMA_ORCHESTRATOR_MODEL: ${OLLAMA_ORCHESTRATOR_MODEL:-granite4:dense}
  GRANITE_USE_FINETUNED: ${GRANITE_USE_FINETUNED:-false}

لماذا الارتساء؟ تحتاج الخدمات المتعددة (API، العمال، فحص الصحة) إلى نفس إعدادات Granite. يضمن المرساة بقائهم متزامنين: قم بتغييره مرة واحدة، وكل خدمة تشير إلى *granite-env تلتقط التغيير.

تقوم كل خدمة بدمج هذه المتغيرات:

services:
  api:
    environment:
      <<: *granite-env
      # ... other service-specific vars

بدء تشغيل Docker Compose

# Start all services (Ollama, API, workers, monitoring)
docker compose up -d

# Check service health
docker compose ps

# View Ollama logs
docker compose logs ollama

# View API logs
docker compose logs api

Docker Compose بنية الخدمة

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

بعد التدريب، قم باستيراد GGUF الخاص بك إلى مثيل Docker Ollama:

# Copy GGUF into the Ollama container
docker compose cp training/output/generic/unsloth.Q8_0.gguf ollama:/tmp/

# Exec into the container and create the model
docker compose exec ollama ollama create granite-soc:latest \
  -f /tmp/Modelfile

# Or use the serve script which handles this automatically
docker compose exec api python training/scripts/serve_model.py ollama \
  --gguf /models/generic/unsloth.Q8_0.gguf \
  --name granite-soc:latest

تمكين / تعطيل النماذج المضبوطة بدقة

استخدم الطراز الأساسي فقط (بدون ضبط دقيق)

# .env
LLM_BACKEND=ollama
GRANITE_USE_FINETUNED=false
OLLAMA_MODEL=granite4:8b

سيستخدم جميع الوكلاء نفس النموذج الأساسي. جيد للتطوير الأولي.

استخدم نموذجًا عامًا واحدًا تم ضبطه بدقة

# .env
LLM_BACKEND=ollama
GRANITE_USE_FINETUNED=true
OLLAMA_MODEL=granite-soc:latest

يشترك جميع الوكلاء في نموذج واحد مضبوط. جيد بعد التدريب العام.

استخدم نماذج مضبوطة بدقة لكل وكيل

# .env
LLM_BACKEND=ollama
GRANITE_USE_FINETUNED=true
OLLAMA_MODEL=granite-soc:latest  # fallback for agents without a specialist model

يقوم AGENT_MODEL_MAP في aurorasoc/granite/__init__.py بتعيين كل وكيل إلى متخصصه:

AGENT_MODEL_MAP = {
    "security_analyst": "granite-soc-security-analyst:latest",
    "threat_hunter": "granite-soc-threat-hunter:latest",
    "incident_responder": "granite-soc-incident-responder:latest",
    # ...
}

تحدد الدقة المكونة من 4 طبقات النموذج الصحيح تلقائيًا:

Override → Per-agent fine-tuned → Generic fine-tuned → Base

راجع وحدة الجرانيت للحصول على منطق الدقة الكاملة.

قائمة التحقق

قم بتشغيل قائمة التحقق هذه بعد النشر:

# 1. Ollama is running and responsive
curl -s http://localhost:11434/api/tags | jq '.models[].name'

# 2. Expected models are loaded
ollama list | grep granite

# 3. Inference works
curl -s http://localhost:11434/api/chat -d '{
  "model": "granite-soc:latest",
  "messages": [{"role": "user", "content": "What is lateral movement?"}],
  "stream": false
}' | jq '.message.content'

# 4. API server starts without errors
curl -s http://localhost:8000/health | jq

# 5. Granite module resolves models correctly
python -c "
from aurorasoc.granite import get_default_granite_config
cfg = get_default_granite_config()
for agent in ['security_analyst', 'threat_hunter', 'incident_responder']:
    print(f'{agent}: {cfg.resolve_model(agent)}')
"

استكشاف الأخطاء وإصلاحها

أعراض	سبب	يصلح
connection refused :11434	Ollama لا يعمل	ollama serve أو systemctl start ollama
model not found	النموذج غير مستورد	ollama list → ثم ollama create أو ollama pull
out of memory	GGUF كبير جدًا بالنسبة لوحدة معالجة الرسومات	استخدم كمية أصغر (Q4_K_M) أو قم بتعيين OLLAMA_GPU_LAYERS=0 لوحدة المعالجة المركزية
يتم تحميل النماذج ببطء	بداية باردة	اضبط OLLAMA_KEEP_ALIVE=30m للحفاظ على دفء النموذج
تنسيق الإخراج خاطئ	قالب الدردشة مفقود	أعد الاستيراد باستخدام serve_model.py الذي يقوم بإنشاء ملف Modelfile الصحيح
CUDA error	عدم تطابق السائق	تحقق من توافق إصدار nvidia-smi وollama CUDA
تقوم API بإرجاع مخرجات النموذج الأساسي	GRANITE_USE_FINETUNED=false	اضبط على true في .env وأعد التشغيل

اعتبارات الإنتاج

بالنسبة لعمليات نشر الإنتاج خارج جهاز واحد:

• استخدم vLLM — قم بتبديل الواجهة الخلفية للإنتاجية. راجع الواجهات الخلفية للعرض.
• عقدة GPU منفصلة — قم بتشغيل خادم LLM على جهاز GPU مخصص، وقم بتوجيه OLLAMA_BASE_URL أو VLLM_BASE_URL إلى عنوان IP الخاص به.
• إصدار النموذج — وضع علامة على النماذج بالتواريخ (granite-soc:2025-01-15) لتمكين التراجع.
• مراقبة الصحة — قم بدمج check_ollama_models() / check_vllm_models() في مجموعة المراقبة الخاصة بك.
• مقاييس وحدة معالجة الرسومات — تصدير مقاييس nvidia-smi إلى Prometheus عبر dcgm-exporter.

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

• الواجهات الخلفية للعرض — نظرة عميقة على Ollama مقابل vLLM
• تبديل النماذج وتجاوزها — تبديل النماذج دون إعادة النشر
• التدريب: نظرة عامة — الرجوع إلى النموذج وتدريبه