Aller au contenu principal

Comment utiliser le plugin

Ce guide couvre l'API d'exécution complète : création d'une instance LLM, chargement de modèles, envoi de messages, téléchargement de modèles à l'exécution, gestion d'état et fonctions utilitaires.

Créez une instance LLM

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

Create Runtime Local LLM

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

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.

Load Model By Name UE 5.4+

Charger depuis le chemin de fichier

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

Load Model From File

Charger depuis une URL (Télécharger et charger)

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

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

Load Model From URL Simple

Vous pouvez également utiliser Load Model From URL avec les métadonnées complètes du modèle pour obtenir des informations plus riches sur celui-ci.

Load Model From URL

Chargement asynchrone (Blueprint)

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

Load Model By Name (Async) reflète Load Model (By Name) - dans UE 5.4+, il présente une liste déroulante de tous les modèles sur le disque :

Load Model By Name Async UE 5.4+

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

Load Model From File Async

Lier les événements

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

Bind Events

Délégués disponibles :

  • Sur jeton généré : se déclenche pour chaque jeton de sortie
  • Sur génération terminée : se déclenche lorsque la réponse complète est prête, avec la durée, le nombre de jetons et les jetons par seconde
  • Sur invite traitée : se déclenche après le traitement de l'invite d'entrée, avant le début de la génération
  • Sur erreur : se déclenche si une erreur survient pendant une opération
  • Sur modèle chargé : se déclenche lorsqu'un modèle a fini de se charger
  • Sur modèle déchargé : se déclenche lorsque le modèle est déchargé
  • Sur progression du téléchargement : se déclenche périodiquement pendant le téléchargement d'un modèle (fraction de progression, octets reçus, octets totaux)
  • Sur modèle téléchargé : se déclenche lorsqu'une opération de téléchargement uniquement est terminée
  • Sur conversation sauvegardée : se déclenche lorsqu'une conversation a été écrite dans un fichier JSON
  • Sur conversation chargée : se déclenche lorsqu'une conversation a été chargée depuis un fichier ou un instantané mémoire
  • Sur historique résumé : se déclenche lorsque l'auto-résumé compresse les messages plus anciens (rapporte le nombre de messages, les jetons économisés et le résumé)

Envoyer des messages

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

Send Message

Pour remplacer le prompt système pour un message spécifique, utilisez Send Message With System Prompt :

Send Message With System Prompt

Les jetons transitent via OnTokenGenerated au fur et à mesure de leur production. Lorsque la génération se termine, OnGenerationComplete se déclenche avec la réponse complète, la durée, le nombre de jetons et les jetons par seconde.

Envoyer un message de manière asynchrone (Blueprint)

Le nœud Envoyer un message LLM (Async) fournit des broches de sortie dédiées pour les jetons, la complétion et les erreurs :

Async Send Message

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

Outre le 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 pré-mettre en cache des modèles dans un écran de chargement ou un menu de paramètres.

Download Model

Une variante uniquement URL est également disponible :

Download Model From URL

Les nœuds Download LLM Model (Async) et Download LLM Model From URL (Async) fournissent des broches de sortie pour la progression, l'achèvement et les erreurs :

Async Download Model

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 :

Cancel Download

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 :

Stop Generation

Réinitialiser le contexte de la conversation

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

Reset Context

Enregistrer et charger les conversations

Le plugin peut conserver l'historique des conversations sur le disque au format JSON ou le garder en mémoire sous forme d'instantané. Par défaut, l'invite système est exclue des sauvegardes, de sorte que le même historique de conversation peut être chargé dans différentes instances LLM avec des règles système différentes. Ceci est utile pour les scénarios multi-PNJ, où chaque personnage a sa propre mémoire mais peut partager ou différer dans ses instructions système.

Enregistrer dans un fichier

Enregistrez la conversation actuelle dans un fichier JSON sur le disque.

Save Conversation To File

Le paramètre Include System Prompt contrôle si le message système (s'il est présent) est écrit dans le fichier. La valeur par défaut est false pour la portabilité entre les PNJ.

On Conversation Saved se déclenche lorsque le fichier est écrit.

Charger depuis un fichier

Charger une conversation à partir d’un fichier JSON :

Load Conversation From File

Le paramètre Conserver l'invite système actuelle (par défaut true) maintient l'invite système actuellement chargée intacte tout en échangeant l'historique de conversation sauvegardé. Il s'agit du paramètre recommandé pour l'échange de mémoire des PNJ.

Sur Conversation Chargée se déclenche avec l'instantané chargé.

Captures instantanées en mémoire (Workflow Multi-PNJ)

Pour un échange rapide de PNJ pendant le jeu, enregistrez la conversation en cours en mémoire plutôt que de l'écrire sur le disque. Ce modèle est la méthode recommandée pour gérer de nombreux PNJ partageant un seul modèle chargé :

Le modèle multi-PNJ typique utilise une Map de Nom → Instantané de Conversation LLM sur votre gestionnaire de PNJ ou état de jeu :

  1. Lorsque vous quittez un PNJ : appelez Save Conversation To Memory, puis dans On Conversation Loaded (qui se déclenche également pour la livraison d’instantané), stockez l’instantané dans votre carte indexée par le nom du PNJ.
  2. Lorsque vous passez à un autre PNJ : lisez l’instantané depuis votre carte et appelez Load Conversation From Memory avec l’option Preserve Current System Prompt activée.

Multi NPC Pattern

Puisque le prompt système reste chargé lors des changements, la « personnalité » de chaque PNJ peut être soit encodée dans un prompt système par PNJ (appelez Send Message With System Prompt une fois après un changement pour le mettre à jour), soit partagée entre tous les PNJ.

astuce

Les instantanés sont indépendants du modèle : ils stockent les messages, pas l'état du cache KV. Un même instantané peut être chargé dans un modèle différent (bien que le style conversationnel puisse changer). Le champ OriginModelFamilyName sur l'instantané vous permet de vérifier quel modèle l'a produit, si vous souhaitez imposer une compatibilité.

Résumé automatique du contexte

Les conversations longues finissent par dépasser la fenêtre de contexte du modèle, ce qui normalement tronquerait l'historique ou provoquerait des erreurs. La fonction de résumé automatique du plugin surveille l'utilisation du contexte et, lorsqu'un seuil configuré est dépassé, résume les messages plus anciens en un seul message de « mémoire » avant que la réponse suivante ne soit générée. Cela maintient les coûts de tokens et la latence stables pour des conversations d'une durée indéfinie.

La synthèse est effectuée par le même modèle chargé, donc aucun second modèle ni appel API n'est nécessaire.

Activer la synthèse automatique

Enable Auto Summarization

Utilisez Get Default Summarization Config pour obtenir des valeurs par défaut raisonnables, puis ajustez selon vos besoins :

Get Default Summarization Config

Une fois activé, le résumé s'exécute automatiquement avant chaque appel SendMessage lorsque nécessaire, sans action supplémentaire requise.

astuce

Par défaut, le résumé automatique s'exécute avant le traitement d'un nouveau message, car il doit reconstruire le contexte, ce qui ne peut pas se faire en toute sécurité en même temps que la génération d'une réponse. Si vous préférez qu'il s'exécute après la réponse, pendant que le joueur lit et tape, désactivez le résumé automatique et pilotez-le manuellement : liez-vous à On Generation Complete, vérifiez Get Used Context Length par rapport à votre seuil, et appelez Summarize Now si celui-ci est dépassé. Comme Summarize Now se met en file d'attente sur la même file de tâches en arrière-plan, il s'exécutera juste après la fin de la réponse et avant le traitement du message suivant.

Référence de configuration

ParamètreTypeDéfautDescription
Seuil de déclenchement du jetonint321500La synthèse s'exécute lorsque les jetons de contexte utilisés dépassent cette valeur. Définissez-la par rapport à votre Context Size ; environ 60 à 75 % est une bonne règle empirique.
Conserver le nombre de messages récentsint324Les N messages les plus récents ne sont jamais résumés, préservant ainsi la cohérence immédiate de la conversation.
Messages Minimum à Résumerint326Ignorer la synthèse si moins de ce nombre d'anciens messages sont éligibles (évite des résumés inutilement minuscules)
Nombre maximal de jetons de résuméint32256Longueur maximale du résumé généré en tokens
Préserver l'invite systèmebooltrueToujours garder le message système (index 0) intact.
Instruction de résuméFString(see default)L'instruction envoyée au modèle pour produire le résumé
Préfixe du message de résuméFString« [Résumé de la mémoire à long terme de la conversation précédente] : »Préfixé au résumé généré lorsqu'il est inséré dans la conversation en tant que message de mémoire avec le rôle d'assistant.

Déclenchement manuel et écoute des résumés

Vous pouvez déclencher la synthèse manuellement à tout moment, indépendamment du seuil.

Summarize Now

Lie à On History Summarized pour être notifié lorsqu'un passage de résumé est terminé. L'événement indique combien de messages ont été supprimés, combien de jetons ont été économisés et le texte du résumé généré, utile pour afficher un indicateur subtil dans l'interface de discussion.

On History Summarized

Interrogation de la longueur de contexte utilisée

Utilisez Get Used Context Length pour vérifier combien de tokens sont actuellement occupés dans la fenêtre de contexte du modèle. Cette valeur est la même que celle que le déclencheur de résumé automatique intégré vérifie par rapport au Trigger Token Threshold.

Get Used Context Length

Désactiver le résumé automatique

Disable Auto Summarization

La désactivation n'annule pas les résumés déjà appliqués à la conversation.

remarque

La synthèse prend un moment pour s'exécuter sur le thread d'arrière-plan (le modèle génère le résumé). Les rappels de flux de jetons sont supprimés pendant cette génération interne afin qu'ils n'apparaissent pas dans votre interface de chat. On History Summarized se déclenche une fois la jonction terminée.

Décharger un modèle

Libération des ressources lorsqu'un modèle n'est plus nécessaire :

Unload Model

État de la requête

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

Query State

  • Modèle chargé : Vrai si un modèle est prêt pour l'inférence
  • En cours de génération : Vrai si la génération est en cours
  • Occupé : Vrai si une opération (chargement, génération, téléchargement) est active
  • En cours de téléchargement : Vrai si un téléchargement de modèle est en cours
  • Obtenir les métadonnées du modèle chargé : Renvoie les métadonnées du modèle actuel
  • Obtenir les paramètres d'inférence appliqués : Renvoie les paramètres appliqués lors du chargement

Fonctions de la bibliothèque de modèles

Un ensemble de fonctions utilitaires statiques est fourni pour gérer les fichiers de modèle sur le disque. Celles-ci sont utiles pour créer une interface utilisateur de sélection de modèle ou vérifier la disponibilité d'un modèle au moment de l'exécution.

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

Get Downloaded Model Names

Get All Downloaded Model Metadata

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

Is Model On Disk

Obtenir le chemin du fichier du modèle

Get Model File Path

Supprimer les fichiers du modèle

Delete Model Files

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

Get Predefined Models

Get All Available Models

Générer des métadonnées à partir d'une URL

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

Make Metadata From URL

Fonctions utilitaires

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

Octets en chaîne lisible

Convertit un nombre d'octets en une chaîne lisible par un humain (par exemple "4.07 Go"). Utile pour afficher la taille des modèles dans l'interface utilisateur.

Bytes to Readable String

Format de 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.

Format Download Progress

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

Get LLM Error Description renvoie une description textuelle lisible pour un code d'erreur. Get LLM Error Code String renvoie le nom de la valeur de l'énumération sous forme de chaîne (utile pour la journalisation).

Get Error Description

Référence des codes d'erreur

CodeValeurDescription
Inconnu0Une erreur non spécifiée
ModelLoadFailed10Le fichier GGUF n'a pas pu être chargé (fichier corrompu, format incompatible, etc.)
ContextCreateFailed11Échec de la création du contexte d'inférence
ModèleNonChargé20Une tentative d'inférence a été effectuée sans modèle chargé.
ChatTemplateFailed21Le modèle de chat du modèle n'a pas pu être appliqué.
TokenizationFailed22Le texte d'entrée n'a pas pu être tokenisé.
ContextOverflow23Le prompt + le contexte dépasse la taille de contexte configurée.
PromptDecodeFailed24Les jetons de l'invite n'ont pas pu être décodés.
ContextTooFullToGenerate25Espace de contexte insuffisant pour générer la sortie.
GenerationDecodeFailed30Un jeton n’a pas pu être décodé lors de la génération.
GenerationTruncated31Génération arrêtée car la limite maximale de jetons a été atteinte.
LLMInstanceNull40L'instance LLM est nulle ou invalide
ModelNotFoundOnDisk41Le fichier modèle n'existe pas au chemin attendu.
ModelURLEmpty42Un téléchargement a été demandé avec une URL vide.
Téléchargement du modèle annulé43Le téléchargement a été annulé.
ModelDownloadEmptyData44Le téléchargement est terminé mais le corps de la réponse était vide.
ÉchecDeSauvegardeDuTéléchargementDuModèle45Le téléchargement est terminé mais le fichier n'a pas pu être enregistré sur le disque.