مرجع التكوين

توثق هذه الصفحة كل خيار تكوين للتدريب وتقديم ودمج نماذج Granite 4 في AuroraSOC.

تدريب تكوين YAML

** الملف: ** training/configs/granite_soc_finetune.yaml

قسم `model`

يتحكم في النموذج الأساسي الذي سيتم تحميله وكيفية تحميله.

model:
  name: "unsloth/granite-4.0-h-tiny"
  max_seq_length: 4096
  load_in_4bit: true

مجال	يكتب	تقصير	وصف
`name`	خيط	`"unsloth/granite-4.0-h-tiny"`	معرف نموذج الوجه المعانق. يجب أن يكون إصدار Granite 4 المحسّن لـ Unsloth.
`max_seq_length`	كثافة العمليات	`4096`	الحد الأقصى لطول تسلسل الرمز المميز. تستخدم التسلسلات الأطول المزيد من VRAM. يدعم Granite 4 ما يصل إلى 128 كيلو بايت ولكن 4096 هو الأمثل للتدريب.
`load_in_4bit`	منطقي	`true`	تمكين تكميم QLoRA 4 بت. يقلل VRAM بمقدار ~4×. قم بالتعطيل فقط إذا كان لديك ذاكرة VRAM تبلغ ≥48 جيجابايت.

** الموديلات المتوفرة: **

معرف النموذج	حدود	VRAM (4 بت)	جودة
`unsloth/granite-4.0-micro`	~1 ب	~4 جيجابايت	خط الأساس
`unsloth/granite-4.0-h-micro`	~1 ب	~4 جيجابايت	أفضل (الهجين)
`unsloth/granite-4.0-h-tiny`	~2ب	~6 جيجا بايت	مُستَحسَن
`unsloth/granite-4.0-h-small`	~8ب	~12 جيجابايت	أفضل جودة

قسم `lora`

تكوين معلمات LoRA (التكيف منخفض الرتبة).

lora:
  r: 64
  lora_alpha: 64
  lora_dropout: 0
  bias: "none"
  target_modules:
    - "q_proj"
    - "k_proj"
    - "v_proj"
    - "o_proj"
    - "gate_proj"
    - "up_proj"
    - "down_proj"
    - "shared_mlp.input_linear"
    - "shared_mlp.output_linear"
  use_gradient_checkpointing: "unsloth"

مجال	يكتب	تقصير	وصف
`r`	كثافة العمليات	`64`	رتبة لورا. أعلى = المزيد من المعلمات = قدرة أفضل ولكن تدريب أبطأ. القيم: 16، 32، 64، 128.
`lora_alpha`	كثافة العمليات	`64`	عامل تحجيم LoRA عادةً ما يتم تعيينه على أنه يساوي `r`. القيم الأعلى تجعل تحديثات LoRA أقوى بالنسبة للنموذج الأساسي.
`lora_dropout`	يطفو	`0`	احتمالية التسرب لطبقات LoRA. يوصى Unsloth باستخدام `0` لتحقيق أقصى سرعة في التدريب.
`bias`	خيط	`"none"`	ما إذا كان سيتم تدريب معلمات التحيز. `"none"` يحافظ على وزن LoRA خفيفًا. الخيارات الأخرى: `"all"`، `"lora_only"`.
`target_modules`	قائمة	9 وحدات	طبقات النموذج التي تحصل على محولات LoRA. تغطي القائمة المكونة من 9 وحدات كلاً من انتباه المحولات (`q_proj`-`down_proj`) وMamba SSM (`shared_mlp.*`).
`use_gradient_checkpointing`	خيط	`"unsloth"`	تحسين الذاكرة. يستخدم `"unsloth"` التنفيذ الأمثل لـ Unsloth (ذاكرة VRAM أقل بمقدار 2 × من PyTorch الأصلي).

فهم r (الرتبة):

رتبة	المعلمات القابلة للتدريب	سرعة التدريب	جودة النموذج
16	~5M	الأسرع	جيد للمهام البسيطة
32	~10 م	سريع	توازن جيد
64	~20 مليون	معتدل	الأفضل لمهام SOC
128	~40 م	بطيء	تناقص العوائد

شرح الوحدات المستهدفة:

الوحدة النمطية	بنيان	غاية
`q_proj`، `k_proj`، `v_proj`، `o_proj`	انتباه المحولات	توقعات الاستعلام والمفتاح والقيمة والمخرجات - آلية الاهتمام الأساسية
`gate_proj`، `up_proj`، `down_proj`	محول FFN	بوابة شبكة التغذية الأمامية والإسقاطات
`shared_mlp.input_linear`	مامبا اس اس ام	يغطي مدخل MLP المشترك لـ Granite 4 Hybrid - طبقات نموذج مساحة الحالة
`shared_mlp.output_linear`	مامبا اس اس ام	مخرج MLP المشترك لـ Granite 4 Hybrid

قسم `training`

يتحكم في المعلمات الفائقة لحلقة التدريب.

training:
  per_device_train_batch_size: 2
  gradient_accumulation_steps: 4
  num_train_epochs: 3
  max_steps: -1
  learning_rate: 0.0002
  lr_scheduler_type: "cosine"
  warmup_ratio: 0.1
  weight_decay: 0.01
  bf16: true
  fp16: false
  optim: "adamw_8bit"
  logging_steps: 10
  save_steps: 100
  seed: 42
  output_dir: "training/output"

مجال	يكتب	تقصير	وصف
`per_device_train_batch_size`	كثافة العمليات	`2`	عينات لكل GPU في كل خطوة. أعلى = تدريب أسرع ولكن المزيد من VRAM. T4: 2، A100: 4-8.
`gradient_accumulation_steps`	كثافة العمليات	`4`	قم بتجميع التدرجات على خطوات N قبل التحديث. حجم الدفعة الفعال = `batch_size × grad_accum` = 8.
`num_train_epochs`	كثافة العمليات	`3`	عدد مرات المرور عبر مجموعة البيانات الكاملة. 3 نقطة انطلاق جيدة؛ مراقبة فقدان التقييم بسبب التجهيز الزائد.
`max_steps`	كثافة العمليات	`-1`	تجاوز العصور بعدد خطوات ثابت. `-1` = استخدم `num_train_epochs` بدلاً من ذلك. مفيد للاختبارات السريعة (على سبيل المثال، `200`).
`learning_rate`	يطفو	`2e-4`	ذروة معدل التعلم. يستخدم الضبط الدقيق لـ LoRA عادةً 1e-4 إلى 5e-4.
`lr_scheduler_type`	خيط	`"cosine"`	جدول معدلات التعلم. `"cosine"` يتحلل بسلاسة؛ `"linear"` يضمحل خطيًا. يفضل جيب التمام لـ LoRA.
`warmup_ratio`	يطفو	`0.1`	جزء من خطوات التدريب التي تم إنفاقها في عملية إحماء معدل التعلم من 0. يمنع عدم الاستقرار في التدريب المبكر.
`weight_decay`	يطفو	`0.01`	تسوية L2. يمنع الإفراط في التجهيز. القيمة القياسية لضبط LLM.
`bf16`	منطقي	`true`	استخدم الدقة المختلطة bfloat16. يقلل VRAM، ويحافظ على النطاق العددي. يتطلب أمبير + GPU.
`fp16`	منطقي	`false`	استخدم الدقة المختلطة float16. يُستخدم إذا كان `bf16` غير مدعوم (وحدات معالجة الرسومات ما قبل Ampere مثل T4).
`optim`	خيط	`"adamw_8bit"`	محسن. يستخدم `"adamw_8bit"` (bitsandbytes) ذاكرة VRAM أقل بنسبة 33% تقريبًا من AdamW القياسي.
`logging_steps`	كثافة العمليات	`10`	تسجيل خسارة التدريب في كل N خطوة.
`save_steps`	كثافة العمليات	`100`	حفظ نقطة التفتيش كل خطوات N. لتمكين `--resume` في حالة مقاطعة التدريب.
`seed`	كثافة العمليات	`42`	بذور عشوائية للتكاثر.
`output_dir`	خيط	`"training/output"`	مكان حفظ نقاط التفتيش والنماذج المصدرة.

قسم `dataset`

يتحكم في تحميل مجموعة البيانات والمعالجة المسبقة.

dataset:
  train_file: "training/data/soc_train.jsonl"
  eval_file: "training/data/soc_eval.jsonl"
  train_on_completions: true

مجال	يكتب	تقصير	وصف
`train_file`	خيط	`"training/data/soc_train.jsonl"`	المسار إلى ملف JSONL للتدريب. تم إنشاؤها بواسطة `prepare_datasets.py`.
`eval_file`	خيط	`"training/data/soc_eval.jsonl"`	المسار إلى ملف JSONL للتقييم. يستخدم لخسارة التقييم أثناء التدريب (منفصل عن التقييم المعياري).
`train_on_completions`	منطقي	`true`	تمكين إخفاء الاستجابة. حساب الخسارة فقط في استجابات المساعد، وليس الرموز المميزة للنظام/المستخدم. مهم للجودة.

قسم `agent_profiles`

يحدد تكوينات التدريب المتخصص لكل وكيل.

agent_profiles:
  security_analyst:
    system_prompt: "You are the AuroraSOC Security Analyst..."
    dataset_filter: "alert_triage"
    model_override: null
    output_dir: "training/output/security_analyst"

  threat_hunter:
    system_prompt: "You are the AuroraSOC Threat Hunter..."
    dataset_filter: "threat_hunting"
    model_override: null
    output_dir: "training/output/threat_hunter"

مجال	يكتب	تقصير	وصف
`system_prompt`	خيط	(يختلف)	تم إدخال موجه النظام في كل مثال تدريبي. يعلم النموذج شخصيته.
`dataset_filter`	خيط	(يختلف)	تصفية بيانات التدريب حسب المجال. يتم استخدام العينات ذات الحقل `domain` المطابق فقط.
`model_override`	خيط	`null`	استخدم نموذجًا أساسيًا مختلفًا لهذا الوكيل. `null` = استخدم `model.name` العام.
`output_dir`	خيط	(يختلف)	مكان حفظ النموذج المدرب لهذا الوكيل. النمط: `training/output/<agent_name>/`.

قسم `export`

يتحكم في تصدير النموذج بعد التدريب.

export:
  save_lora: true
  save_merged_16bit: false
  save_gguf: true
  gguf_quantization_methods:
    - "q8_0"
  push_to_hub: false
  hub_model_name: ""

مجال	يكتب	تقصير	وصف
`save_lora`	منطقي	`true`	حفظ أوزان محول LoRA. خفيف الوزن (~50-200 ميجابايت). مطلوب لـ `--resume` و`--export-only`.
`save_merged_16bit`	منطقي	`false`	قم بدمج LoRA في النموذج الأساسي واحفظ أوزان FP16 الكاملة. يتطلب نموذج VRAM الكامل. مطلوب لخدمة vLLM.
`save_gguf`	منطقي	`true`	تصدير إلى تنسيق GGUF. مطلوب لنشر Olma.
`gguf_quantization_methods`	قائمة	`["q8_0"]`	طرق التكميم GGUF. الخيارات: `"q8_0"`، `"q4_k_m"`، `"q5_k_m"`، `"f16"`.
`push_to_hub`	منطقي	`false`	ادفع إلى HuggingFace Hub بعد التدريب. يتطلب `HF_TOKEN` env var.
`hub_model_name`	خيط	`""`	اسم الريبو HuggingFace (على سبيل المثال، `"yourname/granite-soc-finetuned"`).

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

تكوين وقت التشغيل (`.env`)

تتحكم هذه المتغيرات في كيفية حل AuroraSOC لنماذج Granite واستخدامها في وقت التشغيل:

# Runtime Backend Selection
LLM_BACKEND=vllm
VLLM_BASE_URL=http://vllm:8000/v1
VLLM_MODEL=granite-soc-specialist
VLLM_ORCHESTRATOR_MODEL=granite-soc-specialist
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=granite4:8b
OLLAMA_ORCHESTRATOR_MODEL=granite4:dense

# Fine-tuned Model Settings (primarily used in Ollama model resolution paths)
GRANITE_USE_FINETUNED=false
GRANITE_USE_PER_AGENT_MODELS=false
GRANITE_FINETUNED_MODEL_TAG=granite-soc:latest

# Optional training metadata
GRANITE_SERVING_BACKEND=vllm

عامل	قيم	وصف
`LLM_BACKEND`	`vllm` / `ollama`	الواجهة الخلفية للاستدلال النشط التي يستخدمها الوكلاء ومسارات العمل ودردشة واجهة برمجة التطبيقات (API).
`VLLM_BASE_URL`	عنوان URL	نقطة النهاية المتوافقة مع vLLM OpenAI (عادةً `.../v1`)
`VLLM_MODEL`	معرف النموذج المقدم	معرف نموذج vLLM المستخدم للمكالمات المتخصصة
`VLLM_ORCHESTRATOR_MODEL`	معرف النموذج المقدم	معرف نموذج vLLM المستخدم لاستدعاءات المنسق
`OLLAMA_BASE_URL`	عنوان URL	نقطة نهاية خادم Olma
`OLLAMA_MODEL`	علامة أولاما	علامة نموذجية متخصصة لوضع Ollama
`OLLAMA_ORCHESTRATOR_MODEL`	علامة أولاما	علامة نموذج المنسق لوضع Ollama
`GRANITE_USE_FINETUNED`	`true` / `false`	قم بتمكين النموذج المضبوط بدقة كبديل عندما لا يكون النموذج لكل وكيل متاحًا
`GRANITE_USE_PER_AGENT_MODELS`	`true` / `false`	تمكين البحث عن نموذج لكل وكيل عبر `AGENT_MODEL_MAP`
`GRANITE_FINETUNED_MODEL_TAG`	علامة أولاما	العلامة المستخدمة للنموذج العام (غير الخاص بكل وكيل) الذي تم ضبطه بدقة
`GRANITE_SERVING_BACKEND`	`ollama` / `vllm`	البيانات التعريفية الاختيارية المستخدمة من قبل مساعدي التدريب/الخدمة

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

يتم استخدام هذه المتغيرات أثناء عملية التدريب:

عامل	تقصير	وصف
`AGENT_NAME`	(لا أحد)	اسم الملف التعريفي للوكيل للتدريب لكل وكيل على أساس Docker
`HF_TOKEN`	(لا أحد)	رمز HuggingFace لتنزيلات `push_to_hub` والنماذج المسورة
`WANDB_API_KEY`	(لا أحد)	مفتاح API للأوزان والتحيزات لتتبع التجربة
`CUDA_VISIBLE_DEVICES`	`0`	ما هي وحدات معالجة الرسومات (GPU) التي يجب استخدامها. `0,1` لوحدة معالجة الرسومات المتعددة.

مرجع أهداف Makefile

أهداف التدريب

هدف	يأمر	وصف
`make train-install`	`pip install -e .[training]`	تثبيت تبعيات التدريب
`make train-data`	`python training/scripts/prepare_datasets.py --output-dir training/data`	تنزيل وإعداد مجموعات بيانات التدريب
`make train`	`python training/scripts/finetune_granite.py`	تدريب نموذج SOC العام
`make train-agent AGENT=X`	`finetune_granite.py --agent X`	تدريب متخصص لكل وكيل
`python training/scripts/train_all_agents.py`	`python training/scripts/train_all_agents.py`	تدريب جميع ملفات تعريف الوكيل بالتسلسل
`make train-eval`	`python training/scripts/evaluate_model.py`	تقييم النموذج المدرب
`make train-serve-ollama`	`serve_model.py ollama`	استيراد GGUF إلى Olma
`make train-serve-vllm`	`serve_model.py vllm`	بدء تشغيل خادم vLLM

أهداف تدريب عامل الميناء

هدف	يأمر	وصف
`make train-docker-data`	`docker compose ... run prepare-data`	تحضير البيانات في Docker
`make train-docker`	`docker compose ... run training`	تدريب في دوكر
`make train-docker-agent AGENT=X`	`docker compose ... run training-agent`	التدريب لكل وكيل في Docker
`make train-docker-eval`	`docker compose ... run eval`	تقييم في دوكر

أهداف الإعداد المحلية

هدف	يأمر	وصف
`make setup-local`	`./scripts/setup_local.sh`	إعداد البيئة المحلية الكاملة
`make enable-finetuned`	يضبط vars `.env`	تمكين النماذج المضبوطة بدقة في AuroraSOC
`make disable-finetuned`	يقوم بإلغاء تعيين `.env` vars	العودة إلى نماذج الجرانيت الأساسية
`make ollama-pull-granite`	`ollama pull granite4:8b`	سحب النموذج الأساسي من Olma

خدمات إنشاء عامل الميناء

`docker-compose.training.yml`

خدمة	غاية	مطلوب وحدة معالجة الرسومات	مجلدات
`prepare-data`	تنزيل + مجموعة بيانات العملية	لا	`./training/data:/app/training/data`
`training`	التدريب النموذجي العام	نعم	`./training:/app/training`، ذاكرة التخزين المؤقت HF
`training-agent`	التدريب لكل وكيل	نعم	نفس `training`
`eval`	تقييم النموذج	نعم	`./training:/app/training`
`vllm`	خدمة الإنتاج (FP16)	نعم	`./training/output:/models`
`ollama-import`	GGUF → أولاما	يعتمد على	`./training/output:/models`، بيانات أولاما

`docker-compose.yml` (مرساة x-granite-env)

يستخدم ملف الإنشاء الرئيسي مرساة YAML لإدخال متغيرات بيئة Granite في جميع خدمات الوكيل:

x-granite-env: &granite-env
  GRANITE_USE_FINETUNED: ${GRANITE_USE_FINETUNED:-false}
  GRANITE_USE_PER_AGENT_MODELS: ${GRANITE_USE_PER_AGENT_MODELS:-false}
  GRANITE_FINETUNED_MODEL_TAG: ${GRANITE_FINETUNED_MODEL_TAG:-granite-soc:latest}
  GRANITE_SERVING_BACKEND: ${GRANITE_SERVING_BACKEND:-vllm}
  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}

مثال التكوين الكامل

ملف .env كامل لنشر الإنتاج باستخدام نماذج مضبوطة بدقة لكل وكيل:

# --- Granite Model Configuration ---
LLM_BACKEND=vllm
VLLM_BASE_URL=http://vllm:8000/v1
VLLM_MODEL=granite-soc-specialist
VLLM_ORCHESTRATOR_MODEL=granite-soc-specialist
OLLAMA_MODEL=granite4:8b
OLLAMA_ORCHESTRATOR_MODEL=granite4:dense
GRANITE_USE_FINETUNED=true
GRANITE_USE_PER_AGENT_MODELS=true
GRANITE_FINETUNED_MODEL_TAG=granite-soc:latest
GRANITE_SERVING_BACKEND=vllm
OLLAMA_BASE_URL=http://ollama:11434

# --- Application Configuration ---
SECRET_KEY=your-secret-key-here
DATABASE_URL=postgresql+asyncpg://aurora:aurora@postgres:5432/aurorasoc
NATS_URL=nats://nats:4222
MQTT_BROKER=mosquitto

# --- Monitoring ---
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

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

تكامل LLM: الهندسة المعمارية — كيفية اتصال النماذج بإطار عمل الوكيل
تكامل LLM: تبديل النماذج — التبديل بين النماذج الأساسية والنماذج المضبوطة بدقة

تدريب تكوين YAML​

قسم model​

قسم lora​

قسم training​

قسم dataset​

قسم agent_profiles​

قسم export​

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

تكوين وقت التشغيل (.env)​

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

مرجع أهداف Makefile​

أهداف التدريب​

أهداف تدريب عامل الميناء​

أهداف الإعداد المحلية​

خدمات إنشاء عامل الميناء​

docker-compose.training.yml​

docker-compose.yml (مرساة x-granite-env)​

مثال التكوين الكامل​

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