Eklenti Nasıl Kullanılır

Bu kılavuz, tüm çalışma zamanı API'sini kapsar: LLM örneği oluşturma, modelleri yükleme, mesaj gönderme, çalışma zamanında modelleri indirme, durum yönetimi ve yardımcı işlevler.

Bir LLM Örneği Oluşturun

Bir Runtime Local LLM nesnesi oluşturarak başlayın. Erken çöp toplama işlemine takılmasını önlemek için ona bir referans tutun (örneğin, Blueprint'lerde bir değişken veya C++'da bir UPROPERTY olarak).

Blueprint

C++

```cpp
    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Bir Model Yükle

Mesajları göndermeden önce bir model yüklemeniz gerekir. Eklenti, iş akışınıza bağlı olarak çeşitli yükleme yöntemleri sunar.

İsme Göre Yükle

Modelleri düzenleyici ayarları paneli aracılığıyla yönetiyorsanız, Load Model (By Name) kullanın.

Blueprint

UE 5.3 and earlier

UE 5.3 ve öncesinde açılır menü görünmez, bu nedenle mevcut modelleri manuel olarak almanız gerekir. Get All Downloaded Model Metadata kullanın, 0. indeksteki öğeyi (veya ihtiyacınız olan modeli) alın, ad dizesini almak için Get Model File Name işlevine iletin, ardından bunu Load Model (By Name) işlevine iletin.

UE 5.4+

UE 5.4 ve sonrasında, Load Model (By Name) diskteki tüm modellerin bir açılır menüsünü sunar - yüklemek istediğiniz modeli seçmeniz yeterlidir.

C++

C++ dilinde, mevcut modelleri almak için GetAllDownloadedModelMetadata ve adı LoadModelByName işlevine iletmek için GetModelFileName kullanın:

    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);
    }

Dosya Yolundan Yükle

Bir modeli doğrudan bir .gguf dosyasının mutlak dosya yolundan yükleyin:

Blueprint

C++

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

  </TabItem>
</Tabs>

### URL'den Yükle (İndir ve Yükle) {/* #load-from-url */}

Bir modeli bir URL'den indirin (eğer diskte zaten yoksa) ve otomatik olarak yükleyin. Dosya yerel olarak zaten mevcutsa, indirme atlanır.

<Tabs groupId="languages">
  <TabItem value="blueprint" label="Blueprint">
    En basit varyant yalnızca bir URL alır - meta veriler dosya adından elde edilir:

    ![Load Model From URL Simple](/img/runtime-local-llm/bp-load-model-from-url-simple.png)

    Daha zengin model bilgisi için tam model meta verileriyle `Load Model From URL`'i de kullanabilirsiniz:

    ![Load Model From URL](/img/runtime-local-llm/bp-load-model-from-url-metadata.png)
  </TabItem>
  <TabItem value="c++" label="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);

Eşzamansız Yükleme (Blueprint)

Çıktı pin'leri aracılığıyla yükleme tamamlanma ve hataları, delegate'leri manuel olarak bağlamak yerine ele almak için iki eşzamansız düğüm mevcuttur.

Load Model By Name (Async), Load Model (By Name) yöntemini yansıtır - UE 5.4+ sürümünde diskteki tüm modellerin bir açılır listesini sunar:

UE 5.4+

UE 5.3 ve öncesi

UE 5.3 ve öncesinde açılır liste görünmez. Get All Downloaded Model Metadata kullanın, 0 dizinindeki öğeyi (veya ihtiyacınız olan modeli) alın, Get Model File Namee iletin, ardından bunu Load Model By Name (Async)e iletin.

Load Model From File (Async) bunun yerine mutlak bir dosya yolu alır:

Olaylara Bağlanma

Geri çağrıları almak için LLM örneğinin delegate'lerine bağlanın. Tüm geri çağrılar oyun iş parçacığında tetiklenir.

Blueprint

Kullanılabilir delegate'ler:

• On Token Generated: Her çıkış belirteci için tetiklenir
• On Generation Complete: Tam yanıt hazır olduğunda, süre, belirteç sayısı ve saniyede belirteç ile tetiklenir
• On Prompt Processed: Giriş istemi işlendikten sonra, üretim başlamadan önce tetiklenir
• On Error: Herhangi bir işlem sırasında hata oluşursa tetiklenir
• On Model Loaded: Bir model yüklemeyi tamamladığında tetiklenir
• On Model Unloaded: Model bellekten kaldırıldığında tetiklenir
• On Download Progress: Bir model indirme sırasında periyodik olarak tetiklenir (ilerleme oranı, alınan bayt, toplam bayt)
• On Model Downloaded: Yalnızca indirme işlemi tamamlandığında tetiklenir

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)
{
});

Mesaj Gönder

Bir model yüklendiğinde, yanıt oluşturmak için bir kullanıcı mesajı gönderin:

Blueprint

Belirli bir mesaj için sistem istemini geçersiz kılmak için Send Message With System Prompt kullanın:

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.")
    );

Tokenler üretildikçe OnTokenGenerated üzerinden akar. Üretim tamamlandığında, OnGenerationComplete tüm yanıt, süre, token sayısı ve saniye başına token bilgisiyle tetiklenir.

Asenkron Mesaj Gönderme (Blueprint)

Send LLM Message (Async) düğümü, tokenler, tamamlanma ve hatalar için özel çıkış pinleri sağlar:

Çalışma Zamanında Modelleri İndir

Yukarıda açıklanan indir ve yükle akışına ek olarak, bir modeli yüklemeden diske indirebilirsiniz. Bu, bir yükleme ekranında veya ayarlar menüsünde modelleri ön belleğe almak için kullanışlıdır.

Blueprint

Yalnızca URL ile çalışan bir varyant da mevcuttur:

Download LLM Model (Async) ve Download LLM Model From URL (Async) düğümleri, ilerleme, tamamlanma ve hatalar için çıkış pinleri sağlar:

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 delegesi indirme sırasında ilerlemeyi bildirir. OnModelDownloaded, dosya diske kaydedildiğinde tetiklenir.

Devam eden bir indirmeyi iptal etmek için:

Blueprint

C++

    LLM->CancelDownload();

Eklenti, aynı model için bir indirme zaten devam ediyorsa, sonraki çağrıları yok sayarak, yinelenen indirmeleri otomatik olarak önler.

Oluşturmayı Durdur

Devam eden bir oluşturmayı yarıda kesmek için:

Blueprint

C++

    LLM->StopGeneration();

Konuşma Bağlamını Sıfırla

Yeni bir konuşma başlatmak için konuşma geçmişini temizleyin:

Blueprint

C++

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

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

Bir Modeli Kaldırma

Bir model artık gerekmediğinde kaynakları serbest bırakın:

Blueprint

C++

    LLM->UnloadModel();

Sorgulama Durumu

LLM örneğinin mevcut durumunu kontrol edin:

Blueprint

• Is Model Loaded: Bir model çıkarım için hazırsa True
• Is Generating: Oluşturma işlemi devam ediyorsa True
• Is Busy: Herhangi bir işlem (yükleme, oluşturma, indirme) etkinse True
• Is Downloading: Bir model indirme işlemi devam ediyorsa True
• Get Loaded Model Metadata: Mevcut modelin meta verilerini döndürür
• Get Applied Inference Params: Yükleme sırasında uygulanan parametreleri döndürür

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"));
  }

Model Kütüphanesi İşlevleri

Diskteki model dosyalarını yönetmek için bir dizi statik yardımcı işlev sağlanır. Bunlar, model seçim kullanıcı arayüzü oluşturmak veya çalışma zamanında model kullanılabilirliğini kontrol etmek için kullanışlıdır.

Get Downloaded Model Names / Metadata

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);
    }

Disk Üzerindeki Bir Modeli Kontrol Et

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

Model Dosya Yolunu Al

Blueprint

C++

    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

Model Dosyalarını Sil

Blueprint

C++

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

Önceden Tanımlanmış ve Mevcut Modelleri Al

Blueprint

C++

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

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

Bir URL'den Meta Veri Oluşturma

Ham bir URL'den bir model meta verisi oluşturma (alanlar dosya adından türetilir):

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")
    );

Yardımcı Fonksiyonlar

Biçimlendirme ve hata gösterimi için bir dizi yardımcı fonksiyon sunulmaktadır.

Baytları Okunabilir Dizeye Dönüştür

Bayt sayısını insan tarafından okunabilir bir dizeye dönüştürür (örn. "4.07 GB"). Model boyutlarını kullanıcı arayüzünde görüntülemek için kullanışlıdır.

İndirme İlerlemesini Biçimlendir

İndirme ilerlemesini "1.23 GB / 4.07 GB (%30.2)" gibi bir dize olarak biçimlendirir. Toplam boyut bilinmiyorsa yalnızca alınan miktarı döndürür.

Hata Açıklaması Al / Hata Kodu Dizesi

Get LLM Error Description bir hata kodu için insan tarafından okunabilir bir metin açıklaması döndürür. Get LLM Error Code String enum değer adını bir dize olarak döndürür (günlük kaydı için kullanışlıdır).

Hata Kodları Referansı

Kod	Değer	Açıklama
Unknown	0	Belirtilmemiş bir hata
ModelLoadFailed	10	GGUF dosyası yüklenemedi (bozuk dosya, uyumsuz format vb.)
ContextCreateFailed	11	Çıkarım bağlamı oluşturulamadı
ModelNotLoaded	20	Yüklü bir model olmadan çıkarım denendi
ChatTemplateFailed	21	Modelin sohbet şablonu uygulanamadı
TokenizationFailed	22	Giriş metni tokenleştirilemedi
ContextOverflow	23	İstem + bağlam yapılandırılan bağlam boyutunu aşıyor
PromptDecodeFailed	24	İstem tokenleri çözülemedi
ContextTooFullToGenerate	25	Çıktı üretmek için yeterli bağlam alanı kalmadı
GenerationDecodeFailed	30	Oluşturma sırasında bir token çözülemedi
GenerationTruncated	31	Maksimum token sınırına ulaşıldığı için oluşturma durduruldu
LLMInstanceNull	40	LLM örneği null veya geçersiz
ModelNotFoundOnDisk	41	Model dosyası beklenen yolda mevcut değil
ModelURLEmpty	42	Boş bir URL ile indirme talep edildi
ModelDownloadCancelled	43	İndirme iptal edildi
ModelDownloadEmptyData	44	İndirme tamamlandı ancak yanıt gövdesi boştu
ModelDownloadSaveFailed	45	İndirme tamamlandı ancak dosya diske kaydedilemedi