كيفية استخدام الإضافة

يغطي هذا الدليل واجهة برمجة التطبيقات الكاملة في وقت التشغيل: إنشاء مثيل نموذج اللغة الكبير، تحميل النماذج، إرسال الرسائل، تنزيل النماذج أثناء وقت التشغيل، إدارة الحالة، ووظائف الأدوات المساعدة.

إنشاء مثيل نموذج اللغة الكبير

ابدأ بإنشاء كائن Runtime Local LLM. احتفظ بمرجع له (على سبيل المثال، كمتغير في Blueprints أو UPROPERTY في C++) لمنع جمع القمامة المبكر.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

تحميل نموذج

يجب تحميل نموذج قبل إرسال الرسائل. يوفر المكون الإضافي عدة طرق تحميل حسب سير العمل الخاص بك.

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

إذا كنت تدير النماذج من خلال لوحة إعدادات المحرر، استخدم Load Model (By Name).

Blueprint

UE 5.3 وما قبله

في UE 5.3 وما قبله لا تظهر القائمة المنسدلة، لذا تحتاج إلى استرداد النماذج المتاحة يدويًا. استخدم Get All Downloaded Model Metadata، واحصل على العنصر في الفهرس 0 (أو أي نموذج تحتاجه)، مرره إلى Get Model File Name لاسترداد سلسلة الاسم، ثم مررها إلى Load Model (By Name).

UE 5.4+

في UE 5.4 والإصدارات الأحدث، تعرض Load Model (By Name) قائمة منسدلة بجميع النماذج الموجودة على القرص - ما عليك سوى تحديد النموذج الذي تريد تحميله.

C++

في C++، استخدم GetAllDownloadedModelMetadata لاسترداد النماذج المتاحة و GetModelFileName للحصول على الاسم لتمريره إلى LoadModelByName:

    FLLMInferenceParams Params;
    Params.MaxTokens = 512;
    Params.Temperature = 0.7f;
    Params.SystemPrompt = TEXT("You are a helpful assistant.");

    TArray<FLLMModelMetadata> DownloadedModels = URuntimeLLMLibrary::GetAllDownloadedModelMetadata();

    if (DownloadedModels.Num() > 0)
    {
        const FLLMModelMetadata& Model = DownloadedModels[0]; // Select the first available model
        FString ModelFileName = URuntimeLLMLibrary::GetModelFileName(Model);
        LLM->LoadModelByName(FName(*ModelFileName), Params);
    }

تحميل من مسار الملف

تحميل نموذج مباشرةً من مسار ملف مطلق إلى ملف .gguf:

Blueprint

C++

    FLLMInferenceParams Params;
    LLM->LoadModelFromFile(TEXT("/path/to/model.gguf"), Params);

التحميل من URL (تنزيل وتحميل)

تنزيل نموذج من عنوان URL (إذا لم يكن موجودًا بالفعل على القرص) وتحميله تلقائيًا. إذا كان الملف موجودًا بالفعل محليًا، يتم تخطي التنزيل.

Blueprint

أبسط متغير يأخذ رابط URL فقط - يتم اشتقاق البيانات الوصفية من اسم الملف:

يمكنك أيضًا استخدام Load Model From URL مع بيانات تعريف النموذج الكاملة للحصول على معلومات نموذج أكثر ثراءً:

C++

    FLLMInferenceParams Params;

    // Simple: URL only - metadata is derived from the filename
    LLM->LoadModelFromURLSimple(
        TEXT("https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf"), Params);

    // With full metadata
    FLLMModelMetadata Metadata;
    Metadata.ModelFamilyName = TEXT("Llama3_2_1B_Instruct");
    Metadata.ModelDisplayName = TEXT("Llama 3.2 1B Instruct");
    Metadata.Description = TEXT("Meta's Llama 3.2 1B parameter instruction-tuned model. Lightweight and fast, suitable for simple tasks.");
    Metadata.ParameterCount = TEXT("1B");
    Metadata.Variant.VariantName = TEXT("Q4_K_M");
    Metadata.Variant.ModelURL = TEXT("https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf");
    Metadata.Variant.ApproximateSizeBytes = 776LL * 1024 * 1024;
    Metadata.Variant.QuantizationType = ELLMQuantizationType::Q4_K_M;
    LLM->LoadModelFromURL(Metadata, Params);

تحميل غير متزامن (Blueprint)

للتعامل مع إكمال التحميل والأخطاء عبر دبابيس الإخراج بدلاً من ربط المندوبين يدويًا، يتوفر عقدتين غير متزامنتين.

Load Model By Name (Async) يعكس نفس وظيفة Load Model (By Name) - في UE 5.4+ يعرض قائمة منسدلة بكل النماذج الموجودة على القرص:

UE 5.4+

UE 5.3 والإصدارات الأقدم

في UE 5.3 والإصدارات الأقدم، لا تظهر القائمة المنسدلة. استخدم Get All Downloaded Model Metadata، واحصل على العنصر في الفهرس 0 (أو أي نموذج تحتاجه)، مرره إلى Get Model File Name، ثم مرره إلى Load Model By Name (Async).

Load Model From File (Async) يأخذ مسار ملف مطلق بدلاً من ذلك:

ربط الأحداث

اربط بمندوبي نسخة LLM لتلقي ردود النداء. جميع ردود النداء تنفذ على خيط اللعبة.

Blueprint

المندوبين المتاحين:

• On Token Generated: ينطلق مع كل رمز إخراج
• On Generation Complete: ينطلق عندما تكون الاستجابة الكاملة جاهزة، مع المدة وعدد الرموز والرموز في الثانية
• On Prompt Processed: ينطلق بعد معالجة الموجه المدخل، قبل بدء التوليد
• On Error: ينطلق إذا حدث خطأ أثناء أي عملية
• On Model Loaded: ينطلق عند انتهاء تحميل النموذج
• On Model Unloaded: ينطلق عند إلغاء تحميل النموذج
• On Download Progress: ينطلق بشكل دوري أثناء تنزيل النموذج (كسر التقدم، البايتات المستلمة، إجمالي البايتات)
• On Model Downloaded: ينطلق عند اكتمال عملية التنزيل فقط

C++

LLM->OnTokenGeneratedNative.AddLambda([](const FString& Token)
{
});

LLM->OnGenerationCompleteNative.AddLambda([](const FString& FullResponse)
{
});

LLM->OnPromptProcessedNative.AddLambda([]()
{
});

LLM->OnErrorNative.AddLambda([](const FString& ErrorMessage)
{
});

LLM->OnModelLoadedNative.AddLambda([](const FString& ModelName)
{
});

LLM->OnModelUnloadedNative.AddLambda([](const FString& ModelName)
{
});

LLM->OnDownloadProgressNative.AddLambda([](const FString& ModelName, float Progress)
{
});

LLM->OnModelDownloadedNative.AddLambda([](const FString& ModelName)
{
});

إرسال الرسائل

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

Blueprint

لتجاوز موجه النظام لرسالة محددة، استخدم Send Message With System Prompt:

C++

    LLM->SendMessage(TEXT("Tell me a short story about a brave knight."));

    // With a custom system prompt override
    LLM->SendMessageWithSystemPrompt(
        TEXT("Translate this to French: Hello world"),
        TEXT("You are a professional translator.")
    );

تمر الرموز عبر OnTokenGenerated أثناء إنتاجها. عند اكتمال التوليد، يتم استدعاء OnGenerationComplete مع الاستجابة الكاملة والمدة وعدد الرموز والرموز في الثانية.

إرسال رسالة غير متزامن (Blueprint)

توفر عقدة Send LLM Message (Async) منافذ إخراج مخصصة للرموز والاكتمال والأخطاء:

تنزيل النماذج في وقت التشغيل

إلى جانب تدفق التنزيل والتحميل الموصوف أعلاه، يمكنك تنزيل نموذج إلى القرص دون تحميله. هذا مفيد للتخزين المؤقت للنماذج في شاشة التحميل أو قائمة الإعدادات.

Blueprint

يتوفر أيضًا إصدار بعنوان URL فقط:

توفر عقدة Download LLM Model (Async) و Download LLM Model From URL (Async) منافذ إخراج للتقدم والاكتمال والأخطاء:

C++

    // With full metadata
    FLLMModelMetadata Metadata;
    Metadata.ModelFamilyName = TEXT("Llama3_2_1B_Instruct");
    Metadata.ModelDisplayName = TEXT("Llama 3.2 1B Instruct");
    Metadata.Description = TEXT("Meta's Llama 3.2 1B parameter instruction-tuned model. Lightweight and fast, suitable for simple tasks.");
    Metadata.ParameterCount = TEXT("1B");
    Metadata.Variant.VariantName = TEXT("Q4_K_M");
    Metadata.Variant.ModelURL = TEXT("https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf");
    Metadata.Variant.ApproximateSizeBytes = 776LL * 1024 * 1024;
    Metadata.Variant.QuantizationType = ELLMQuantizationType::Q4_K_M;
    LLM->DownloadModel(Metadata);

    // URL only
    LLM->DownloadModelFromURL(
        TEXT("https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf"));

يقوم المفوّض OnDownloadProgress بالإبلاغ عن التقدم أثناء التنزيل. يتم تنشيط OnModelDownloaded عند حفظ الملف على القرص.

لإلغاء تنزيل جارٍ:

Blueprint

C++

    LLM->CancelDownload();

يمنع المكون الإضافي التنزيلات المكررة تلقائيًا - إذا كان التنزيل قيد التقدم بالفعل لنفس النموذج، فسيتم تجاهل الاستدعاءات اللاحقة.

إيقاف التوليد

لمقاطعة عملية التوليد الجارية:

Blueprint

C++

    LLM->StopGeneration();

إعادة تعيين سياق المحادثة

امسح سجل المحادثة لبدء محادثة جديدة:

Blueprint

C++

    // Keep the system prompt
    LLM->ResetContext(true);

    // Clear everything including the system prompt
    LLM->ResetContext(false);

إلغاء تحميل نموذج

تحرير الموارد عندما لا يعد النموذج مطلوبًا:

Blueprint

C++

    LLM->UnloadModel();

حالة الاستعلام

تحقق من الحالة الحالية لمثيل LLM:

Blueprint

• Is Model Loaded: صحيح إذا كان النموذج جاهزًا للاستدلال
• Is Generating: صحيح إذا كان التوليد قيد التقدم
• Is Busy: صحيح إذا كانت أي عملية (تحميل، توليد، تنزيل) نشطة
• Is Downloading: صحيح إذا كان تنزيل النموذج قيد التقدم
• Get Loaded Model Metadata: يعيد البيانات الوصفية للنموذج الحالي
• Get Applied Inference Params: يعيد المعلمات المطبقة عند التحميل

C++

  // Is Model Loaded - true if a model is ready for inference
  if (LLM->IsModelLoaded())
  {
      FLLMModelMetadata Metadata = LLM->GetLoadedModelMetadata();
      UE_LOG(LogTemp, Log, TEXT("Model: %s"), *Metadata.ModelDisplayName);
  
      FLLMInferenceParams Params = LLM->GetAppliedInferenceParams();
      UE_LOG(LogTemp, Log, TEXT("Context size: %d"), Params.ContextSize);
  }
  
  // Is Generating - true if token generation is currently active
  if (LLM->IsGenerating())
  {
      UE_LOG(LogTemp, Log, TEXT("Generation in progress..."));
  }
  
  // Is Busy - true if any operation (loading, generating, downloading) is active
  if (LLM->IsBusy())
  {
      UE_LOG(LogTemp, Log, TEXT("LLM is busy, deferring request"));
  }
  
  // Is Downloading - true if a model download is currently in progress
  if (LLM->IsDownloading())
  {
      UE_LOG(LogTemp, Log, TEXT("Model download in progress..."));
  }
  
  // Safe to send a new message or load a different model
  if (!LLM->IsGenerating() && !LLM->IsBusy())
  {
      UE_LOG(LogTemp, Log, TEXT("LLM is idle and ready"));
  }

وظائف مكتبة النماذج

يتم توفير مجموعة من وظائف الأدوات الثابتة لإدارة ملفات النماذج على القرص. هذه الوظائف مفيدة لبناء واجهة مستخدم اختيار النموذج أو التحقق من توفر النموذج في وقت التشغيل.

الحصول على أسماء النماذج التي تم تنزيلها / البيانات الوصفية

Blueprint

C++

    TArray<FName> ModelNames = URuntimeLLMLibrary::GetDownloadedModelNames();

    TArray<FLLMModelMetadata> AllModels = URuntimeLLMLibrary::GetAllDownloadedModelMetadata();
    for (const FLLMModelMetadata& Model : AllModels)
    {
        UE_LOG(LogTemp, Log, TEXT("Model: %s (%s)"), *Model.ModelDisplayName, *Model.Variant.VariantName);
    }

التحقق من وجود نموذج على القرص

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

الحصول على مسار ملف النموذج

Blueprint

C++

    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

حذف ملفات النموذج

Blueprint

C++

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

احصل على النماذج المحددة مسبقًا والمتاحة

Blueprint

C++

    // Built-in catalog only
    TArray<FLLMModelFamily> Predefined = URuntimeLLMLibrary::GetPredefinedModels();

    // Catalog + custom imports
    TArray<FLLMModelFamily> All = URuntimeLLMLibrary::GetAllAvailableModels();

إنشاء بيانات وصفية من رابط

إنشاء بيانات وصفية لنموذج من رابط خام (يتم اشتقاق الحقول من اسم الملف):

Blueprint

C++

    FLLMModelMetadata Metadata = URuntimeLocalLLM::MakeMetadataFromURL(
        TEXT("https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf")
    );

دوال مساعدة

يتم توفير مجموعة من الدوال المساعدة للتنسيق وعرض الأخطاء.

تحويل البايتات إلى سلسلة قابلة للقراءة

يحول عدد البايتات إلى سلسلة نصية قابلة للقراءة (مثل "4.07 GB"). مفيد لعرض أحجام النماذج في واجهة المستخدم.

تنسيق تقدم التحميل

تنسيق سلسلة تقدم التحميل مثل "1.23 GB / 4.07 GB (30.2%)". إذا كان الحجم الإجمالي غير معروف، يتم إرجاع الكمية المستلمة فقط.

الحصول على وصف الخطأ / سلسلة رمز الخطأ

تعيد Get LLM Error Description وصفًا نصيًا قابلاً للقراءة لرمز الخطأ. تعيد Get LLM Error Code String اسم قيمة التعداد كسلسلة نصية (مفيدة للتسجيل).

مرجع رموز الأخطاء

الكود	القيمة	الوصف
Unknown	0	خطأ غير محدد
ModelLoadFailed	10	فشل تحميل ملف GGUF (ملف تالف، تنسيق غير متوافق، إلخ)
ContextCreateFailed	11	فشل إنشاء سياق الاستدلال
ModelNotLoaded	20	تمت محاولة الاستدلال دون تحميل نموذج
ChatTemplateFailed	21	فشل تطبيق قالب الدردشة الخاص بالنموذج
TokenizationFailed	22	تعذر تجزئة النص المُدخل إلى رموز
ContextOverflow	23	تجاوز الموجه + السياق حجم السياق المكون
PromptDecodeFailed	24	فشلت الرموز الموجهة في فك التشفير
ContextTooFullToGenerate	25	لا توجد مساحة سياق كافية متبقية لإنتاج الناتج
GenerationDecodeFailed	30	فشل رمز في فك التشفير أثناء التوليد
GenerationTruncated	31	توقف التوليد بسبب بلوغ الحد الأقصى للرموز
LLMInstanceNull	40	مثيل LLM فارغ أو غير صالح
ModelNotFoundOnDisk	41	ملف النموذج غير موجود في المسار المتوقع
ModelURLEmpty	42	تم طلب تحميل بعنوان URL فارغ
ModelDownloadCancelled	43	تم إلغاء التحميل
ModelDownloadEmptyData	44	اكتمل التحميل لكن جسم الاستجابة كان فارغًا
ModelDownloadSaveFailed	45	اكتمل التحميل لكن تعذر حفظ الملف على القرص