Cómo usar el plugin

Esta guía cubre la API completa en tiempo de ejecución: crear una instancia de LLM, cargar modelos, enviar mensajes, descargar modelos en tiempo de ejecución, gestionar el estado y funciones de utilidad.

Crear una instancia de LLM

Comience por crear un objeto Runtime Local LLM. Mantenga una referencia a él (por ejemplo, como una variable en Blueprints o una UPROPERTY en C++) para evitar la recolección prematura de basura.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Cargar un Modelo

Debe cargar un modelo antes de enviar mensajes. El plugin ofrece varios métodos de carga según su flujo de trabajo.

Cargar por Nombre

Si gestiona los modelos a través del panel de configuración del editor, utilice Load Model (By Name).

Blueprint

UE 5.3 y versiones anteriores

En UE 5.3 y versiones anteriores, el menú desplegable no aparece, por lo que debe obtener los modelos disponibles manualmente. Utilice Get All Downloaded Model Metadata, obtenga el elemento en el índice 0 (o el modelo que necesite), páselo a Get Model File Name para recuperar la cadena de nombre y luego páselo a Load Model (By Name).

UE 5.4+

En UE 5.4 y versiones posteriores, Load Model (By Name) presenta un menú desplegable con todos los modelos en disco; simplemente seleccione el modelo que desea cargar.

C++

En C++, use GetAllDownloadedModelMetadata para recuperar los modelos disponibles y GetModelFileName para obtener el nombre que pasará a 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);
    }

Cargar desde ruta de archivo

Cargue un modelo directamente desde una ruta de archivo absoluta a un archivo .gguf:

Blueprint

C++

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

Cargar desde URL (Descargar y cargar)

Descarga un modelo desde una URL (si no se encuentra ya en el disco) y lo carga automáticamente. Si el archivo ya existe localmente, se omite la descarga.

Blueprint

La variante más simple solo requiere una URL: los metadatos se derivan del nombre del archivo:

También puedes usar Load Model From URL con metadatos completos del modelo para obtener información más rica:

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

Carga Asíncrona (Blueprint)

Para gestionar la finalización de la carga y los errores mediante pines de salida en lugar de vincular delegados manualmente, hay dos nodos asíncronos disponibles.

Load Model By Name (Async) espeja a Load Model (By Name) - en UE 5.4+ presenta un desplegable con todos los modelos en disco:

UE 5.4+

UE 5.3 and earlier

En UE 5.3 y versiones anteriores el desplegable no aparece. Usa Get All Downloaded Model Metadata, toma el elemento en el índice 0 (o el modelo que necesites), pásalo a Get Model File Name y luego pásalo a Load Model By Name (Async).

Load Model From File (Async) toma una ruta de archivo absoluta en su lugar:

Vincular Eventos

Vincula los delegados de la instancia LLM para recibir callbacks. Todos los callbacks se ejecutan en el hilo del juego.

Blueprint

Delegados disponibles:

• On Token Generated: Se dispara por cada token de salida
• On Generation Complete: Se dispara cuando la respuesta completa está lista, con duración, número de tokens y tokens por segundo
• On Prompt Processed: Se dispara después de que el prompt de entrada se procesa, antes de que comience la generación
• On Error: Se dispara si ocurre un error durante cualquier operación
• On Model Loaded: Se dispara cuando un modelo termina de cargarse
• On Model Unloaded: Se dispara cuando el modelo se descarga
• On Download Progress: Se dispara periódicamente durante la descarga de un modelo (fracción de progreso, bytes recibidos, bytes totales)
• On Model Downloaded: Se dispara cuando se completa una operación de solo descarga

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

Enviar Mensajes

Una vez cargado un modelo, envía un mensaje de usuario para generar una respuesta:

Blueprint

Para sobrescribir el prompt del sistema para un mensaje específico, usa 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.")
    );

Los tokens se transmiten a través de OnTokenGenerated a medida que se producen. Cuando la generación finaliza, OnGenerationComplete se activa con la respuesta completa, la duración, el recuento de tokens y los tokens por segundo.

Envío asincrónico de mensaje (Blueprint)

El nodo Send LLM Message (Async) proporciona pines de salida dedicados para tokens, completado y errores:

Descargar modelos en tiempo de ejecución

Además del flujo de descarga y carga descrito anteriormente, puedes descargar un modelo al disco sin cargarlo. Esto es útil para precargar modelos en una pantalla de carga o en el menú de configuración.

Blueprint

También está disponible una variante solo con URL:

El nodo Download LLM Model (Async) y Download LLM Model From URL (Async) proporciona pines de salida para progreso, completado y errores:

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

El delegado OnDownloadProgress informa del progreso durante la descarga. OnModelDownloaded se activa cuando el archivo se guarda en el disco.

Para cancelar una descarga en curso:

Blueprint

C++

    LLM->CancelDownload();

El complemento evita descargas duplicadas automáticamente: si ya hay una descarga en curso para el mismo modelo, las llamadas posteriores se ignoran.

Detener Generación

Para interrumpir una generación en curso:

Blueprint

C++

    LLM->StopGeneration();

Restablecer contexto de conversación

Borrar el historial de la conversación para iniciar una nueva conversación:

Blueprint

C++

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

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

Descargar un modelo

Libere recursos cuando un modelo ya no sea necesario:

Blueprint

C++

    LLM->UnloadModel();

Estado de Consulta

Consultar el estado actual de la instancia del LLM:

Blueprint

• Is Model Loaded: True si un modelo está listo para la inferencia
• Is Generating: True si la generación está en progreso
• Is Busy: True si cualquier operación (carga, generación, descarga) está activa
• Is Downloading: True si una descarga de modelo está en progreso
• Get Loaded Model Metadata: Devuelve los metadatos del modelo actual
• Get Applied Inference Params: Devuelve los parámetros aplicados durante la carga

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

Funciones de la biblioteca de modelos

Se proporciona un conjunto de funciones de utilidad estáticas para administrar los archivos de modelo en el disco. Estas son útiles para construir una IU de selección de modelo o verificar la disponibilidad del modelo en tiempo de ejecución.

Obtener nombres de modelos descargados / Metadatos

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

Verificar si un modelo está en el disco

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

Obtener ruta de archivo del modelo

Blueprint

C++

    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

Eliminar archivos de modelo

Blueprint

C++

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

Obtener modelos predefinidos y disponibles

Blueprint

C++

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

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

Generar metadatos a partir de una URL

Construir metadatos del modelo a partir de una URL sin procesar (los campos se derivan del nombre del archivo):

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

Funciones de utilidad

Se proporciona un conjunto de funciones auxiliares para formatear y mostrar errores.

Bytes a cadena legible

Convierte un número de bytes en una cadena legible por humanos (ej. "4.07 GB"). Útil para mostrar tamaños de modelo en la interfaz.

Formatear progreso de descarga

Formatea una cadena de progreso de descarga como "1.23 GB / 4.07 GB (30.2%)". Si el tamaño total es desconocido, devuelve solo la cantidad recibida.

Obtener descripción de error / Cadena de código de error

Get LLM Error Description devuelve una descripción de texto legible para un código de error. Get LLM Error Code String devuelve el nombre del valor de enumeración como una cadena (útil para registro).

Referencia de códigos de error

Código	Valor	Descripción
Unknown	0	Un error no especificado
ModelLoadFailed	10	El archivo GGUF no se pudo cargar (archivo corrupto, formato incompatible, etc.)
ContextCreateFailed	11	Falló la creación del contexto de inferencia
ModelNotLoaded	20	Se intentó inferencia sin modelo cargado
ChatTemplateFailed	21	La plantilla de chat del modelo no se pudo aplicar
TokenizationFailed	22	El texto de entrada no se pudo tokenizar
ContextOverflow	23	El prompt + contexto supera el tamaño de contexto configurado
PromptDecodeFailed	24	Los tokens del prompt no se pudieron decodificar
ContextTooFullToGenerate	25	No queda suficiente espacio de contexto para generar salida
GenerationDecodeFailed	30	Un token no se pudo decodificar durante la generación
GenerationTruncated	31	Generación detenida porque se alcanzó el límite máximo de tokens
LLMInstanceNull	40	La instancia LLM es nula o inválida
ModelNotFoundOnDisk	41	El archivo del modelo no existe en la ruta esperada
ModelURLEmpty	42	Se solicitó una descarga con una URL vacía
ModelDownloadCancelled	43	La descarga fue cancelada
ModelDownloadEmptyData	44	La descarga se completó pero el cuerpo de la respuesta estaba vacío
ModelDownloadSaveFailed	45	La descarga se completó pero no se pudo guardar el archivo en disco