如何使用插件

本指南涵蓋完整的執行時期 API：建立 LLM 實例、載入模型、傳送訊息、在執行時下載模型、管理狀態以及實用函式。

建立一個 LLM 實例

首先建立一個 Runtime Local LLM 物件。保持對它的參考（例如在 Blueprints 中作為變數或 C++ 中的 UPROPERTY）以避免過早的垃圾回收。

Blueprint

C++

```cpp
UPROPERTY()
URuntimeLocalLLM* LLM;

LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

載入模型

在發送訊息之前，您必須先載入模型。此外掛程式根據您的工作流程提供了多種載入方法。

按名稱載入

如果您透過編輯器設定面板管理模型，請使用 Load Model (By Name)。

Blueprint

UE 5.3 及更早版本

在 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 及更早版本

在 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：每個輸出 Token 時觸發
• On Generation Complete：完整回應準備好時觸發，附帶持續時間、Token 數量和每秒 Token 數
• 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.")
    );

當 token 生成時，它們會透過 OnTokenGenerated 進行串流。生成完成時，OnGenerationComplete 會觸發，並提供完整的回應、持續時間、token 數量和每秒 token 數。

非同步發送訊息 (Blueprint)

Send LLM Message (Async) 節點提供專門的輸出引腳，用於 token、完成和錯誤：

在執行時下載模型

除了前面說明的下載並載入流程之外，您還可以將模型下載到磁碟而不載入它。這對於在載入畫面或設定選單中預先快取模型很有用。

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 delegate 會在下載過程中回報進度。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++

    LLM->UnloadModel();

查詢狀態

檢查 LLM 實例的當前狀態：

Blueprint

• Is Model Loaded: 如果模型已準備好進行推理，則為 True。
• Is Generating: 如果正在進行生成，則為 True。
• Is Busy: 如果任何操作（載入、生成、下載）處於活動狀態，則為 True。
• Is Downloading: 如果正在下載模型，則為 True。
• Get Loaded Model Metadata: 返回當前模型的中繼資料。
• Get Applied Inference Params: 返回載入時套用的參數。

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

模型庫函式

提供一組靜態工具函式，用於管理磁碟上的模型檔案。這些函式有助於建構模型選擇 UI 或在執行階段檢查模型可用性。

Get Downloaded Model Names / 中繼資料

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 GB"）。適用於在 UI 中顯示模型大小。

格式化下載進度

格式化下載進度字串，如 "1.23 GB / 4.07 GB (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 實例為空或無效
ModelNotFoundOnDisk	41	模型檔案不存在於預期的路徑
ModelURLEmpty	42	嘗試下載時 URL 為空
ModelDownloadCancelled	43	下載已取消
ModelDownloadEmptyData	44	下載完成但回應本文為空
ModelDownloadSaveFailed	45	下載完成但無法將檔案儲存至磁碟