Como usar o plugin

Este guia cobre toda a API de runtime: criação de uma instância de LLM, carregamento de modelos, envio de mensagens, download de modelos em runtime, gerenciamento de estado e funções utilitárias.

Criar uma Instância de LLM

Comece criando um objeto Runtime Local LLM. Mantenha uma referência a ele (por exemplo, como uma variável em Blueprints ou uma UPROPERTY em C++) para evitar a coleta prematura de lixo.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Carregar um Modelo

Você deve carregar um modelo antes de enviar mensagens. O plugin oferece vários métodos de carregamento, dependendo do seu fluxo de trabalho.

Carregar por Nome

Se você gerencia modelos através do painel de configurações do editor, use Load Model (By Name).

Blueprint

UE 5.3 and earlier

No UE 5.3 e versões anteriores, o menu suspenso não aparece, portanto, você precisa recuperar os modelos disponíveis manualmente. Use Get All Downloaded Model Metadata, pegue o elemento no índice 0 (ou qualquer modelo que você precise), passe-o para Get Model File Name para recuperar a string do nome e, em seguida, passe isso para Load Model (By Name).

UE 5.4+

No UE 5.4 e posterior, Load Model (By Name) apresenta um menu suspenso de todos os modelos no disco - basta selecionar o modelo que deseja carregar.

C++

Em C++, use GetAllDownloadedModelMetadata para recuperar os modelos disponíveis e GetModelFileName para obter o nome a ser passado para 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);
    }

Carregar do Caminho do Arquivo

Carregue um modelo diretamente de um caminho absoluto de arquivo para um arquivo .gguf:

Blueprint

C++

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

Carregar a partir de URL (Baixar e Carregar)

Baixe um modelo a partir de uma URL (se já não estiver no disco) e carregue-o automaticamente. Se o arquivo já existir localmente, o download é ignorado.

Blueprint

A variante mais simples recebe apenas uma URL - os metadados são derivados do nome do arquivo:

Você também pode usar Load Model From URL com metadados completos do modelo para informações mais ricas sobre o modelo:

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

Carregamento Assíncrono (Blueprint)

Para lidar com a conclusão do carregamento e erros via pinos de saída em vez de vincular delegates manualmente, dois nós assíncronos estão disponíveis.

Load Model By Name (Async) espelha Load Model (By Name) - no UE 5.4+, ele apresenta uma lista suspensa de todos os modelos no disco:

UE 5.4+

UE 5.3 e anteriores

No UE 5.3 e anteriores, a lista suspensa não aparece. Use Get All Downloaded Model Metadata, obtenha o elemento no índice 0 (ou o modelo que você precisar), passe-o para Get Model File Name e, em seguida, passe isso para Load Model By Name (Async).

Load Model From File (Async) aceita um caminho de arquivo absoluto em vez disso:

Vincular Eventos

Vincule-se aos delegates da instância LLM para receber callbacks. Todos os callbacks são executados na thread do jogo.

Blueprint

Delegates disponíveis:

• On Token Generated: Dispara para cada token de saída
• On Generation Complete: Dispara quando a resposta completa está pronta, com duração, contagem de tokens e tokens por segundo
• On Prompt Processed: Dispara após o prompt de entrada ser processado, antes de a geração começar
• On Error: Dispara se ocorrer um erro durante qualquer operação
• On Model Loaded: Dispara quando um modelo termina de carregar
• On Model Unloaded: Dispara quando o modelo é descarregado
• On Download Progress: Dispara periodicamente durante o download de um modelo (fração de progresso, bytes recebidos, total de bytes)
• On Model Downloaded: Dispara quando uma operação de apenas download é concluída

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 Mensagens

Assim que um modelo estiver carregado, envie uma mensagem de usuário para gerar uma resposta:

Blueprint

Para substituir o prompt do sistema para uma mensagem específica, use 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.")
    );

Os tokens fluem através de OnTokenGenerated conforme são produzidos. Quando a geração termina, OnGenerationComplete é disparado com a resposta completa, duração, contagem de tokens e tokens por segundo.

Envio Assíncrono de Mensagem (Blueprint)

O nó Send LLM Message (Async) fornece pinos de saída dedicados para tokens, conclusão e erros:

Baixar Modelos em Tempo de Execução

Além do fluxo de download e carregamento descrito acima, você pode baixar um modelo para o disco sem carregá-lo. Isso é útil para pré-armazenar modelos em cache durante uma tela de carregamento ou menu de configurações.

Blueprint

Uma variante somente de URL também está disponível:

O nó Download LLM Model (Async) e Download LLM Model From URL (Async) fornece pinos de saída para progresso, conclusão e erros:

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

O delegado OnDownloadProgress informa o progresso durante o download. OnModelDownloaded é acionado quando o arquivo é salvo no disco.

Para cancelar um download em andamento:

Blueprint

C++

    LLM->CancelDownload();

O plugin previne downloads duplicados automaticamente - se um download já estiver em andamento para o mesmo modelo, chamadas subsequentes são ignoradas.

Interromper Geração

Para interromper uma geração em andamento:

Blueprint

C++

    LLM->StopGeneration();

Redefinir Contexto da Conversa

Limpe o histórico da conversa para iniciar uma nova conversa:

Blueprint

C++

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

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

Descarregar um Modelo

Libere recursos quando um modelo não for mais necessário:

Blueprint

C++

    LLM->UnloadModel();

Estado da Consulta

Verifique o estado atual da instância LLM:

Blueprint

• Is Model Loaded: Verdadeiro se um modelo estiver pronto para inferência
• Is Generating: Verdadeiro se a geração estiver em andamento
• Is Busy: Verdadeiro se qualquer operação (carregamento, geração, download) estiver ativa
• Is Downloading: Verdadeiro se um download do modelo estiver em andamento
• Get Loaded Model Metadata: Retorna os metadados do modelo atual
• Get Applied Inference Params: Retorna os parâmetros aplicados durante o carregamento

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

Funções da Biblioteca de Modelos

Um conjunto de funções utilitárias estáticas é fornecido para gerenciar arquivos de modelo no disco. Elas são úteis para criar uma interface de seleção de modelo ou verificar a disponibilidade do modelo em tempo de execução.

Obter Nomes de Modelos Baixados / Metadados

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 se um modelo está no disco

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

Get Model File Path

Blueprint

C++

    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

Excluir Arquivos de Modelo

Blueprint

C++

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

Obter modelos pré-definidos e disponíveis

Blueprint

C++

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

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

Construir Metadados a partir de uma URL

Construa metadados do modelo a partir de uma URL bruta (os campos são derivados do nome do arquivo):

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

Funções Utilitárias

Um conjunto de funções auxiliares é fornecido para formatação e exibição de erros.

Bytes para String Legível

Converte uma quantidade de bytes em uma string legível por humanos (ex: "4.07 GB"). Útil para exibir tamanhos de modelo na interface.

Formatar Progresso de Download

Formata uma string de progresso de download como "1.23 GB / 4.07 GB (30.2%)". Se o tamanho total for desconhecido, retorna apenas o valor recebido.

Obter Descrição de Erro / String de Código de Erro

Get LLM Error Description retorna uma descrição de texto legível para um código de erro. Get LLM Error Code String retorna o nome do valor enum como uma string (útil para logging).

Referência de Códigos de Erro

Código	Valor	Descrição
Unknown	0	Um erro não especificado
ModelLoadFailed	10	Falha ao carregar o arquivo GGUF (arquivo corrompido, formato incompatível, etc.)
ContextCreateFailed	11	Falha ao criar o contexto de inferência
ModelNotLoaded	20	A inferência foi tentada sem um modelo carregado
ChatTemplateFailed	21	O template de chat do modelo falhou ao ser aplicado
TokenizationFailed	22	O texto de entrada não pôde ser tokenizado
ContextOverflow	23	O prompt + contexto excede o tamanho do contexto configurado
PromptDecodeFailed	24	Os tokens do prompt falharam ao serem decodificados
ContextTooFullToGenerate	25	Espaço de contexto restante insuficiente para gerar a saída
GenerationDecodeFailed	30	Um token falhou ao ser decodificado durante a geração
GenerationTruncated	31	A geração parou porque o limite máximo de tokens foi atingido
LLMInstanceNull	40	A instância do LLM é nula ou inválida
ModelNotFoundOnDisk	41	O arquivo do modelo não existe no caminho esperado
ModelURLEmpty	42	Uma tentativa de download foi feita com uma URL vazia
ModelDownloadCancelled	43	O download foi cancelado
ModelDownloadEmptyData	44	O download foi concluído mas o corpo da resposta estava vazio
ModelDownloadSaveFailed	45	O download foi concluído mas o arquivo não pôde ser salvo em disco