وحدة الجرانيت للغوص العميق

وحدة Granite (aurorasoc/granite/) هي التجريد الأساسي الذي يربط وكلاء AuroraSOC بنماذج IBM Granite 4. فهو يتعامل مع تكوين النموذج المدرك للواجهة الخلفية، ودقة النموذج، وإنشاء ChatModel، ومراقبة صحة النموذج.

هيكل الوحدة

aurorasoc/granite/
├── __init__.py     # GraniteModelConfig, resolve_model(), create_granite_chat_model()
└── registry.py     # Health checks, model availability, warmup

فئة البيانات `GraniteModelConfig`

كائن التكوين المركزي:

@dataclass
class GraniteModelConfig:
    backend: ServingBackend = ServingBackend.OLLAMA
    vllm_base_url: str = "http://vllm:8000/v1"
    ollama_base_url: str = "http://ollama:11434"
    use_finetuned: bool = True
    use_per_agent_models: bool = False
    finetuned_model_tag: str = "granite-soc:latest"
    vllm_specialist_model: str = "granite-soc-specialist"
    vllm_orchestrator_model: str = "granite-soc-specialist"
    ollama_specialist_model: str = "granite4:8b"
    ollama_orchestrator_model: str = "granite4:dense"
    model_overrides: dict[str, str] = field(default_factory=dict)

مجال	يكتب	تقصير	وصف
`backend`	خدمة الخلفية	`OLLAMA`	ما هي الواجهة الخلفية التي يجب استخدامها (`OLLAMA` أو `VLLM`)
`vllm_base_url`	شارع	`"http://vllm:8000/v1"`	vLLM عنوان URL API المتوافق مع Openالذكاء الاصطناعي
`ollama_base_url`	شارع	`"http://ollama:11434"`	عنوان URL لخادم Ollama
`use_finetuned`	منطقي	`True`	تمكين التراجع العام الدقيق في وضع Ollama
`use_per_agent_models`	منطقي	`False`	تمكين تحليل النموذج لكل وكيل في وضع Ollama
`finetuned_model_tag`	شارع	`"granite-soc:latest"`	علامة Ollama للنموذج العام المضبوط
`vllm_specialist_model`	شارع	`"granite-soc-specialist"`	تم تقديم معرف نموذج vLLM للوكلاء المتخصصين
`vllm_orchestrator_model`	شارع	`"granite-soc-specialist"`	تم تقديم معرف نموذج vLLM للمنسق
`ollama_specialist_model`	شارع	`"granite4:8b"`	العلامة الأساسية المتخصصة Ollama عند إيقاف الضبط الدقيق
`ollama_orchestrator_model`	شارع	`"granite4:dense"`	العلامة الأساسية للمنسق Ollama عند إيقاف الضبط الدقيق
`model_overrides`	إملاء [شارع، شارع]	`{}`	خريطة تجاوز واضحة لكل وكيل (الأولوية القصوى)

`ServingBackend` التعداد

class ServingBackend(str, Enum):
    OLLAMA = "ollama"
    VLLM = "vllm"

أولوية حل النموذج

تطبق طريقة resolve_model() إستراتيجية الأولوية المدركة للواجهة الخلفية:

def resolve_model(self, agent_name: str) -> str:
    # Tier 1: Explicit per-agent override
    if agent_name in self.model_overrides:
        return self._format_model(self.model_overrides[agent_name])

    # Tier 2: vLLM explicit served model IDs
    if self.backend == ServingBackend.VLLM:
        model = (
            self.vllm_orchestrator_model
            if agent_name == "Orchestrator"
            else self.vllm_specialist_model
        )
        return self._format_model(model)

    # Tier 3: Ollama per-agent specialists
    if self.use_per_agent_models and agent_name in AGENT_MODEL_MAP:
        return self._format_model(AGENT_MODEL_MAP[agent_name])

    # Tier 4: Ollama generic fine-tuned fallback
    if self.use_finetuned:
        return self._format_model(self.finetuned_model_tag)

    # Tier 5: Ollama base specialist/orchestrator tags
    if agent_name == "Orchestrator":
        return self._format_model(self.ollama_orchestrator_model)
    return self._format_model(self.ollama_specialist_model)

وأوضح أولوية القرار

الطبقة	عندما ينشط	حالة الاستخدام
1. تجاوز صريح	تم تعيين `model_overrides[agent_name]`	فرض وكيل واحد على نموذج محدد لتصحيح الأخطاء المستهدف
2. معرفات الطراز vLLM	`backend == VLLM`	استخدم معرفات نماذج vLLM المقدمة من إعدادات وقت التشغيل
3. لكل وكيل Ollama	`use_per_agent_models=true` + الوكيل في `AGENT_MODEL_MAP`	الإنتاج مع متخصصين Ollama لكل وكيل
4. Generic Ollama ضبط دقيق	`use_finetuned=true`	الإنتاج باستخدام طراز Ollama عام واحد مضبوط بدقة
5. العلامات الأساسية Ollama	لم يتم تحديد مسار الضبط الدقيق	التطوير أو الرجوع إلى علامات الجرانيت الأساسية

السلوك الاحتياطي

إذا كانت LLM_BACKEND=vllm، فإن الدقة تستخدم VLLM_MODEL / VLLM_ORCHESTRATOR_MODEL بعد التجاوزات الصريحة ولا تستخدم الطبقات الخاصة بـ Ollama. في وضع Ollama، تعود العلامات المفقودة لكل وكيل إلى finetuned_model_tag، ثم علامات Ollama الأساسية.

`AGENT_MODEL_MAP`

تعيين أسماء الوكلاء إلى علامات نموذج Ollama:

AGENT_MODEL_MAP = {
    "security_analyst":      "granite-soc-security-analyst",
    "threat_hunter":         "granite-soc-threat-hunter",
    "malware_analyst":       "granite-soc-malware-analyst",
    "incident_responder":    "granite-soc-incident-responder",
    "network_security":      "granite-soc-network-security",
    "cps_security":          "granite-soc-cps-security",
    "threat_intel":          "granite-soc-threat-intel",
    "ueba_analyst":          "granite-soc-ueba-analyst",
    "forensic_analyst":      "granite-soc-forensic-analyst",
    "endpoint_security":     "granite-soc-endpoint-security",
    "web_security":          "granite-soc-web-security",
    "cloud_security":        "granite-soc-cloud-security",
    "compliance_analyst":    "granite-soc-compliance-analyst",
    "vulnerability_manager": "granite-soc-vulnerability-manager",
    "report_generator":      "granite-soc-report-generator",
    "orchestrator":          "granite-soc-orchestrator",
}

تتوافق هذه العلامات مع نماذج Ollama التي أنشأتها serve_model.py ollama-all. يتم إلحاق العلامة :latest تلقائيًا بواسطة resolve_model().

`create_granite_chat_model()`

ينشئ مثيل Beeالذكاء الاصطناعي ChatModel استنادًا إلى النموذج الذي تم حله والواجهة الخلفية:

def create_granite_chat_model(
    agent_name: str,
    config: GraniteModelConfig | None = None,
) -> ChatModel:
    model_name = config.resolve_model(agent_name)
    provider_options = {}

    if config.backend == ServingBackend.OLLAMA:
        provider_options["base_url"] = config.ollama_base_url
    elif config.backend == ServingBackend.VLLM:
        provider_options["base_url"] = config.vllm_base_url

    return ChatModel.from_name(model_name, provider_options=provider_options)

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

الخلفية	موفر نموذج الدردشة	تنسيق عنوان URL	بروتوكول
Ollama	`ollama:<model>`	`http://host:11434`	Ollama API (أصلي)
vLLM	`openai:<model>`	`http://host:8000/v1`	API متوافق مع Openالذكاء الاصطناعي

** لماذا openai: لـ vLLM؟ ** يكشف vLLM عن نقطة نهاية /v1/chat/completions متوافقة مع Openالذكاء الاصطناعي. يقوم ChatModel.from_name("openai:...") الخاص بـ Beeالذكاء الاصطناعي بإجراء مكالمات Openالذكاء الاصطناعي API القياسية، والتي يتعامل معها vLLM بشفافية.

`get_default_granite_config()`

ينشئ التكوين من متغيرات البيئة:

def get_default_granite_config() -> GraniteModelConfig:
    settings = get_settings()
    granite = settings.granite

    return GraniteModelConfig(
        backend=ServingBackend.VLLM if settings.LLM_BACKEND == "vllm" else ServingBackend.OLLAMA,
        ollama_base_url=settings.OLLAMA_BASE_URL,
        vllm_base_url=settings.VLLM_BASE_URL,
        use_finetuned=granite.use_finetuned,
        use_per_agent_models=granite.use_per_agent_models,
        finetuned_model_tag=granite.finetuned_model_tag,
        vllm_specialist_model=settings.VLLM_MODEL,
        vllm_orchestrator_model=settings.VLLM_ORCHESTRATOR_MODEL,
        ollama_specialist_model=resolve_ollama_model_tag(settings.OLLAMA_MODEL),
        ollama_orchestrator_model=resolve_ollama_model_tag(
            settings.OLLAMA_ORCHESTRATOR_MODEL,
            orchestrator=True,
        ),
    )

ملاحظة: تتم مقارنة متغيرات البيئة المنطقية كسلاسل صغيرة بـ "true". السلاسل الفارغة والمتغيرات غير المحددة هي False بشكل افتراضي.

سجل النموذج (`registry.py`)

توفر وحدة التسجيل فحص السلامة وإدارة النماذج:

`check_ollama_models()`

استعلامات Ollama للنماذج المتاحة:

async def check_ollama_models(ollama_host: str) -> list[str]:
    """Returns list of model tags available in Ollama."""

يستخدم أثناء بدء التشغيل للتحقق من سحب النماذج المطلوبة وإتاحتها.

`check_vllm_models()`

التحقق من نقطة نهاية vLLM الخاصة بـ /v1/models:

async def check_vllm_models(vllm_base: str) -> list[str]:
    """Returns list of models loaded in vLLM."""

`pull_ollama_model()`

يسحب نموذجًا من سجل Ollama:

async def pull_ollama_model(ollama_host: str, model: str) -> bool:
    """Pulls a model if not already available. Returns success."""

`warmup_model()`

يرسل مطالبة صغيرة لتسخين النموذج في الواجهة الخلفية للعرض:

async def warmup_model(config: GraniteModelConfig, agent_name: str | None = None) -> bool:
    """Sends a warmup prompt to ensure the model is loaded in memory."""

لماذا الاحماء؟ طلب الاستدلال الأول إلى Ollama/vLLM بطيء لأنه يجب تحميل وزن النموذج من القرص إلى ذاكرة وحدة معالجة الرسومات. يرسل Warmup الحد الأدنى من المطالبة أثناء بدء التشغيل بحيث يكون النموذج ساخنًا بالفعل عند وصول تنبيهات حقيقية.

نقاط التكامل

مع المصنع

# aurorasoc/agents/factory.py
class AuroraAgentFactory:
    def __init__(self, granite_config=None):
        self.granite_config = granite_config or get_default_granite_config()

    def _llm_for(self, agent_name: str) -> ChatModel:
        return create_granite_chat_model(self.granite_config, agent_name)

مع الإعدادات

# aurorasoc/config/settings.py
class Settings(BaseSettings):
    LLM_BACKEND: str = "vllm"
    VLLM_BASE_URL: str = "http://vllm:8000/v1"
    VLLM_MODEL: str = "granite-soc-specialist"
    VLLM_ORCHESTRATOR_MODEL: str = "granite-soc-specialist"
    OLLAMA_BASE_URL: str = "http://ollama:11434"
    OLLAMA_MODEL: str = "granite4:8b"
    OLLAMA_ORCHESTRATOR_MODEL: str = "granite4:dense"
    # plus granite.* toggles for Ollama finetuned/per-agent behavior

مع Docker Compose

# docker-compose.yml
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}
  GRANITE_USE_FINETUNED: ${GRANITE_USE_FINETUNED:-false}
  GRANITE_USE_PER_AGENT_MODELS: ${GRANITE_USE_PER_AGENT_MODELS:-false}
    OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://ollama:11434}
  # ... injected into all agent services

إضافة نموذج جديد

لإضافة متغير نموذج جديد:

أضف إلى AGENT_MODEL_MAP (إذا كان لكل وكيل):

AGENT_MODEL_MAP["my_new_agent"] = "granite-soc-my-new-agent"

تدريب النموذج باستخدام finetune_granite.py --agent my_new_agent
الاستيراد إلى Ollama باستخدام serve_model.py ollama
الحل تلقائيًا — سوف يجده resolve_model("my_new_agent")

لاستخدام عائلة نماذج مختلفة تمامًا (وليس Granite)، قم بتعيين معرفات نماذج الواجهة الخلفية مباشرةً:

مسار vLLM: اضبط VLLM_MODEL وVLLM_ORCHESTRATOR_MODEL
مسار Ollama: اضبط OLLAMA_MODEL وOLLAMA_ORCHESTRATOR_MODEL
بالنسبة لتجاوزات الوكيل لمرة واحدة في التعليمات البرمجية/الاختبارات، قم بتوفير model_overrides في GraniteModelConfig

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

دليل تبديل النماذج — التبديل بسرعة بين تكوينات النماذج
واجهات العرض الخلفية — Ollama مقابل vLLM بالتفصيل

هيكل الوحدة​

فئة البيانات GraniteModelConfig​

ServingBackend التعداد​

أولوية حل النموذج​

وأوضح أولوية القرار​

السلوك الاحتياطي​

AGENT_MODEL_MAP​

create_granite_chat_model()​

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

get_default_granite_config()​

سجل النموذج (registry.py)​

check_ollama_models()​

check_vllm_models()​

pull_ollama_model()​

warmup_model()​

نقاط التكامل​

مع المصنع​

مع الإعدادات​

مع Docker Compose​

إضافة نموذج جديد​

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