プラグインの使用方法

このガイドでは、LLM インスタンスの作成、モデルの読み込み、メッセージの送信、ランタイムでのモデルのダウンロード、状態管理、ユーティリティ関数など、完全なランタイム API について説明します。

LLM インスタンスを作成する

最初に Runtime Local LLM オブジェクトを作成します。Blueprint 内の変数や C++ の UPROPERTY として参照を保持し、ガベージコレクションによる早期破棄を防ぎます。

Blueprint

C++

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

Async Load (Blueprint)

手動でデリゲートをバインドする代わりに、出力ピンを介してロードの完了とエラーを処理するために、2つの非同期ノードが利用可能です。

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 が完全な応答、所要時間、トークン数、1秒あたりのトークン数とともに発火します。

非同期メッセージ送信 (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++

    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の構築や、ランタイムでのモデルの利用可能性チェックに役立ちます。

ダウンロードされたモデル名 / メタデータの取得

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

Utility Functions

書式設定とエラー表示のための一連のヘルパー関数が提供されています。

Bytes to Readable String

バイト数を人間が読みやすい文字列（例: "4.07 GB"）に変換します。UIでモデルサイズを表示するのに便利です。

Format Download Progress

ダウンロードの進捗文字列を "1.23 GB / 4.07 GB (30.2%)" のように整形します。合計サイズが不明な場合は、受信済みの量だけを返します。

エラー説明の取得 / エラーコード文字列

Get LLM Error Description はエラーコードに対応する人間が読めるテキスト説明を返します。Get LLM Error Code String は列挙値の名前を文字列として返します（ログ出力に便利です）。

エラーコードリファレンス

Code	Value	Description
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	ダウンロードは完了しましたが、ファイルをディスクに保存できませんでした