Как использовать плагин

Это руководство охватывает весь API среды выполнения: создание экземпляра LLM, загрузку моделей, отправку сообщений, загрузку моделей во время выполнения, управление состоянием и вспомогательные функции.

Создание экземпляра LLM

Начните с создания объекта Runtime Local LLM. Сохраняйте ссылку на него (например, как переменную в Blueprints или UPROPERTY в C++), чтобы предотвратить преждевременную сборку мусора.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Загрузка модели

Перед отправкой сообщений необходимо загрузить модель. Плагин предоставляет несколько способов загрузки в зависимости от вашего рабочего процесса.

Загрузка по имени

Если вы управляете моделями через панель настроек редактора, используйте Load Model (By Name).

Blueprint

UE 5.3 and earlier

В 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 and earlier

В 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++

```cpp
LLM->UnloadModel();

Состояние запроса

Проверьте текущее состояние экземпляра LLM:

Blueprint

• Модель загружена: True, если модель готова к инференсу
• Генерируется: True, если идёт генерация
• Занят: True, если активна какая-либо операция (загрузка, генерация, скачивание)
• Загружается: True, если идёт загрузка модели
• Получить метаданные загруженной модели: Возвращает метаданные текущей модели
• Получить применённые параметры инференса: Возвращает параметры, применённые при загрузке

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

Сборка метаданных из URL

Сконструируйте метаданные модели из исходного URL (поля извлекаются из имени файла):

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 ГБ"). Полезно для отображения размеров моделей в интерфейсе.

Форматирование прогресса загрузки

Форматирует строку прогресса загрузки, например "1.23 ГБ / 4.07 ГБ (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 имеет значение null или недействителен
ModelNotFoundOnDisk	41	Файл модели не существует по ожидаемому пути
ModelURLEmpty	42	Был запрошен скачивание с пустым URL
ModelDownloadCancelled	43	Загрузка была отменена
ModelDownloadEmptyData	44	Загрузка завершена, но тело ответа пустое
ModelDownloadSaveFailed	45	Загрузка завершена, но файл не удалось сохранить на диск