Comment utiliser le plugin

Ce guide couvre l'API d'exécution complète : créer une instance LLM, charger des modèles, envoyer des messages, télécharger des modèles au moment de l'exécution, gérer l'état et les fonctions utilitaires.

Créer une instance LLM

Commencez par créer un objet Runtime Local LLM. Conservez une référence à celui-ci (par exemple en tant que variable dans Blueprints ou un UPROPERTY en C++) pour éviter une collecte des ordures prématurée.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Charger un modèle

Vous devez charger un modèle avant d'envoyer des messages. Le plugin propose plusieurs méthodes de chargement selon votre flux de travail.

Charger par nom

Si vous gérez les modèles via le panneau des paramètres de l'éditeur, utilisez Load Model (By Name).

Blueprint

UE 5.3 et versions antérieures

Dans UE 5.3 et versions antérieures, la liste déroulante n'apparaît pas, vous devez donc récupérer les modèles disponibles manuellement. Utilisez Get All Downloaded Model Metadata, obtenez l'élément à l'index 0 (ou le modèle souhaité), passez-le à Get Model File Name pour récupérer la chaîne de nom, puis passez-la à Load Model (By Name).

UE 5.4+

Dans UE 5.4 et versions ultérieures, Load Model (By Name) présente une liste déroulante de tous les modèles sur le disque - sélectionnez simplement le modèle que vous souhaitez charger.

C++

En C++, utilisez GetAllDownloadedModelMetadata pour récupérer les modèles disponibles et GetModelFileName pour obtenir le nom à passer à 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);
    }

Charger depuis un chemin de fichier

Charger un modèle directement depuis un chemin de fichier absolu vers un fichier .gguf :

Blueprint

C++

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

Load from URL (Téléchargement et chargement)

Téléchargez un modèle depuis une URL (s'il n'est pas déjà sur le disque) et chargez-le automatiquement. Si le fichier existe déjà localement, le téléchargement est ignoré.

Blueprint

La variante la plus simple ne prend qu'une URL - les métadonnées sont dérivées du nom de fichier :

Vous pouvez également utiliser Load Model From URL avec des métadonnées complètes du modèle pour des informations plus riches :

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

Chargement asynchrone (Blueprint)

Pour gérer la fin de chargement et les erreurs via des broches de sortie plutôt que de lier manuellement des délégués, deux nœuds asynchrones sont disponibles.

Load Model By Name (Async) est l'équivalent de Load Model (By Name) - dans UE 5.4+, il affiche une liste déroulante de tous les modèles sur le disque :

UE 5.4+

UE 5.3 and earlier

Dans UE 5.3 et versions antérieures, la liste déroulante n'apparaît pas. Utilisez Get All Downloaded Model Metadata, obtenez l'élément à l'index 0 (ou le modèle dont vous avez besoin), passez-le à Get Model File Name, puis passez cela à Load Model By Name (Async).

Load Model From File (Async) prend un chemin de fichier absolu à la place :

Lier les événements

Liez-vous aux délégués de l'instance LLM pour recevoir les rappels. Tous les rappels se produisent sur le thread de jeu.

Blueprint

Délégués disponibles :

• On Token Generated: Se déclenche pour chaque token de sortie
• On Generation Complete: Se déclenche lorsque la réponse complète est prête, avec la durée, le nombre de tokens et les tokens par seconde
• On Prompt Processed: Se déclenche après le traitement de l'invite d'entrée, avant le début de la génération
• On Error: Se déclenche si une erreur se produit pendant une opération
• On Model Loaded: Se déclenche lorsqu'un modèle termine le chargement
• On Model Unloaded: Se déclenche lorsque le modèle est déchargé
• On Download Progress: Se déclenche périodiquement lors d'un téléchargement de modèle (fraction de progression, octets reçus, octets totaux)
• On Model Downloaded: Se déclenche lorsqu'une opération de téléchargement uniquement se termine

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

Envoyer des messages

Une fois qu'un modèle est chargé, envoyez un message utilisateur pour générer une réponse :

Blueprint

Pour remplacer le prompt système pour un message spécifique, utilisez 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.")
    );

Les tokens sont diffusés via OnTokenGenerated au fur et à mesure qu'ils sont produits. Lorsque la génération se termine, OnGenerationComplete est déclenché avec la réponse complète, la durée, le nombre de tokens et les tokens par seconde.

Envoi de message asynchrone (Blueprint)

Le nœud Send LLM Message (Async) fournit des broches de sortie dédiées pour les tokens, la terminaison et les erreurs :

Téléchargement des modèles à l'exécution

En plus du flux de téléchargement et chargement décrit ci-dessus, vous pouvez télécharger un modèle sur le disque sans le charger. Cela est utile pour le pré-caching de modèles dans un écran de chargement ou un menu de paramètres.

Blueprint

Une variante URL seule est également disponible :

Le nœud Download LLM Model (Async) et le nœud Download LLM Model From URL (Async) fournissent des broches de sortie pour la progression, la terminaison et les erreurs :

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

Le délégué OnDownloadProgress signale la progression pendant le téléchargement. OnModelDownloaded se déclenche lorsque le fichier est enregistré sur le disque.

Pour annuler un téléchargement en cours :

Blueprint

C++

    LLM->CancelDownload();

Le plugin empêche automatiquement les téléchargements en double : si un téléchargement est déjà en cours pour le même modèle, les appels suivants sont ignorés.

Arrêter la génération

Pour interrompre une génération en cours :

Blueprint

C++

    LLM->StopGeneration();

Réinitialiser le contexte de conversation

Effacer l'historique de la conversation pour en démarrer une nouvelle :

Blueprint

C++

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

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

Décharger un modèle

Libérer les ressources lorsqu'un modèle n'est plus nécessaire:

Blueprint

C++

    LLM->UnloadModel();

État de la requête

Vérifiez l'état actuel de l'instance LLM :

Blueprint

• Is Model Loaded: Vrai si un modèle est prêt pour l'inférence
• Is Generating: Vrai si la génération est en cours
• Is Busy: Vrai si une opération quelconque (chargement, génération, téléchargement) est active
• Is Downloading: Vrai si un téléchargement de modèle est en cours
• Get Loaded Model Metadata: Renvoie les métadonnées du modèle actuel
• Get Applied Inference Params: Renvoie les paramètres appliqués lors du chargement

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

Fonctions de la bibliothèque de modèles

Un ensemble de fonctions utilitaires statiques est fourni pour gérer les fichiers de modèles sur le disque. Elles s'avèrent utiles pour construire une interface de sélection de modèles ou pour vérifier la disponibilité des modèles en cours d'exécution.

Obtenir les noms / métadonnées des modèles téléchargés

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

Vérifier si un modèle est sur le disque

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

Obtenir le chemin du fichier de modèle

Blueprint

C++

```cpp
    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

  </TabItem>
</Tabs>

### Supprimer les fichiers de modèle {/* #delete-model-files */}

<Tabs groupId="languages">
  <TabItem value="blueprint" label="Blueprint">
    ![Supprimer les fichiers de modèle](/img/runtime-local-llm/bp-delete-model-files.png)
  </TabItem>
  <TabItem value="c++" label="C++">

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

Obtenir les modèles prédéfinis et disponibles

Blueprint

C++

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

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

Construire les métadonnées à partir d'une URL

Construire les métadonnées d'un modèle à partir d'une URL brute (les champs sont dérivés du nom de fichier) :

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

Fonctions utilitaires

Un ensemble de fonctions d'assistance est fourni pour le formatage et l'affichage des erreurs.

Octets vers chaîne lisible

Convertit un nombre d'octets en chaîne lisible par l'humain (par ex. "4.07 Go"). Utile pour afficher les tailles de modèles dans l'interface utilisateur.

Formater la progression du téléchargement

Formate une chaîne de progression de téléchargement comme "1.23 Go / 4.07 Go (30.2%)". Si la taille totale est inconnue, retourne uniquement la quantité reçue.

Obtenir la description de l'erreur / Chaîne du code d'erreur

Get LLM Error Description retourne une description textuelle lisible pour un code d'erreur. Get LLM Error Code String retourne le nom de la valeur enum en tant que chaîne (utile pour la journalisation).

Référence des codes d'erreur

Code	Valeur	Description
Unknown	0	Une erreur non spécifiée
ModelLoadFailed	10	Le fichier GGUF n'a pas pu être chargé (fichier corrompu, format incompatible, etc.)
ContextCreateFailed	11	Échec de la création du contexte d'inférence
ModelNotLoaded	20	Une inférence a été tentée sans modèle chargé
ChatTemplateFailed	21	Le modèle de chat n'a pas pu être appliqué
TokenizationFailed	22	Le texte d'entrée n'a pas pu être tokenisé
ContextOverflow	23	Le prompt + le contexte dépasse la taille de contexte configurée
PromptDecodeFailed	24	Les tokens du prompt n'ont pas pu être décodés
ContextTooFullToGenerate	25	Pas assez d'espace de contexte restant pour générer la sortie
GenerationDecodeFailed	30	Un token n'a pas pu être décodé pendant la génération
GenerationTruncated	31	La génération s'est arrêtée car la limite maximale de tokens a été atteinte
LLMInstanceNull	40	L'instance LLM est null ou invalide
ModelNotFoundOnDisk	41	Le fichier modèle n'existe pas à l'emplacement attendu
ModelURLEmpty	42	Un téléchargement a été demandé avec une URL vide
ModelDownloadCancelled	43	Le téléchargement a été annulé
ModelDownloadEmptyData	44	Le téléchargement s'est terminé mais le corps de la réponse était vide
ModelDownloadSaveFailed	45	Le téléchargement s'est terminé mais le fichier n'a pas pu être sauvegardé sur le disque