Cách sử dụng plugin

Hướng dẫn này bao gồm toàn bộ API runtime: tạo một phiên bản LLM, tải mô hình, gửi tin nhắn, tải xuống mô hình trong runtime, quản lý trạng thái và các hàm tiện ích.

Tạo một Phiên bản LLM

Bắt đầu bằng cách tạo một đối tượng Runtime Local LLM. Duy trì một tham chiếu đến nó (ví dụ: như một biến trong Blueprints hoặc UPROPERTY trong C++) để ngăn chặn việc thu gom rác sớm.

Blueprint

C++

    UPROPERTY()
    URuntimeLocalLLM* LLM;

    LLM = URuntimeLocalLLM::CreateRuntimeLocalLLM();

Tải một Mô hình

Bạn phải tải một mô hình trước khi gửi tin nhắn. Plugin cung cấp một số phương pháp tải tùy thuộc vào quy trình làm việc của bạn.

Tải theo Tên

Nếu bạn quản lý các mô hình thông qua bảng cài đặt trình soạn thảo, hãy sử dụng Load Model (By Name).

Blueprint

UE 5.3 và các phiên bản trước

Trong UE 5.3 và các phiên bản trước, menu thả xuống không xuất hiện, vì vậy bạn cần phải truy xuất các mô hình có sẵn theo cách thủ công. Sử dụng Get All Downloaded Model Metadata, lấy phần tử tại chỉ mục 0 (hoặc bất kỳ mô hình nào bạn cần), truyền nó vào Get Model File Name để lấy chuỗi tên, sau đó truyền chuỗi đó vào Load Model (By Name).

UE 5.4+

Trong UE 5.4 trở lên, Load Model (By Name) hiển thị một menu thả xuống gồm tất cả các mô hình trên đĩa - chỉ cần chọn mô hình bạn muốn tải.

C++

Trong C++, sử dụng GetAllDownloadedModelMetadata để truy xuất các mô hình có sẵn và GetModelFileName để lấy tên để truyền vào 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);
    }

Tải từ Đường dẫn Tệp

Tải một mô hình trực tiếp từ đường dẫn tuyệt đối đến tệp .gguf:

Blueprint

C++

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

Tải từ URL (Tải xuống và Tải)

Tải một mô hình từ URL (nếu chưa có trên đĩa) và tự động tải nó. Nếu tệp đã tồn tại cục bộ, quá trình tải xuống sẽ được bỏ qua.

Blueprint

Biến thể đơn giản nhất chỉ yêu cầu một URL - siêu dữ liệu được lấy từ tên tệp:

Bạn cũng có thể sử dụng Tải Mô hình từ URL với siêu dữ liệu mô hình đầy đủ để có thông tin mô hình phong phú hơn:

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

Tải Không Đồng Bộ (Blueprint)

Để xử lý việc hoàn tất tải và lỗi thông qua các chân đầu ra thay vì tự động gắn delegate, có sẵn hai node không đồng bộ.

Load Model By Name (Async) tương tự Load Model (By Name) - trong UE 5.4+, nó hiển thị một danh sách thả xuống của tất cả các model trên đĩa:

UE 5.4+

UE 5.3 trở về trước

Trong UE 5.3 trở về trước, danh sách thả xuống không xuất hiện. Sử dụng Get All Downloaded Model Metadata, lấy phần tử tại index 0 (hoặc bất kỳ model nào bạn cần), truyền nó vào Get Model File Name, sau đó truyền kết quả đó vào Load Model By Name (Async).

Load Model From File (Async) nhận một đường dẫn tuyệt đối thay vào đó:

Gắn Sự Kiện

Gắn vào các delegate của phiên bản LLM để nhận callback. Tất cả callback đều được kích hoạt trên luồng game.

Blueprint

Các delegate có sẵn:

• On Token Generated: Kích hoạt cho mỗi token đầu ra
• On Generation Complete: Kích hoạt khi phản hồi đầy đủ đã sẵn sàng, kèm theo thời lượng, số lượng token và token mỗi giây
• On Prompt Processed: Kích hoạt sau khi lời nhắc đầu vào được xử lý, trước khi bắt đầu sinh
• On Error: Kích hoạt nếu xảy ra lỗi trong bất kỳ thao tác nào
• On Model Loaded: Kích hoạt khi một model hoàn tất tải
• On Model Unloaded: Kích hoạt khi model được dỡ bỏ
• On Download Progress: Kích hoạt định kỳ trong quá trình tải model (phần trăm tiến trình, số byte đã nhận, tổng số byte)
• On Model Downloaded: Kích hoạt khi một thao tác chỉ tải xuống hoàn tất

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

Gửi Tin nhắn

Khi một mô hình đã được tải, hãy gửi một tin nhắn người dùng để tạo phản hồi:

Blueprint

Để ghi đè lời nhắc hệ thống cho một tin nhắn cụ thể, hãy sử dụng 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.")
    );

Các token được truyền qua OnTokenGenerated khi chúng được tạo ra. Khi quá trình tạo hoàn tất, OnGenerationComplete sẽ kích hoạt với phản hồi đầy đủ, thời lượng, số lượng token và số token mỗi giây.

Gửi Tin nhắn Bất đồng bộ (Blueprint)

Node Send LLM Message (Async) cung cấp các chân đầu ra chuyên dụng cho token, hoàn tất và lỗi:

Tải xuống Mô hình trong Runtime

Ngoài luồng tải xuống và tải như đã mô tả ở trên, bạn có thể tải xuống một mô hình vào đĩa mà không cần tải nó. Điều này hữu ích cho việc lưu trữ trước các mô hình trong màn hình tải hoặc menu cài đặt.

Blueprint

Một biến thể chỉ có URL cũng có sẵn:

Node Download LLM Model (Async) và Download LLM Model From URL (Async) cung cấp các chân đầu ra cho tiến trình, hoàn tất và lỗi:

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 ủy quyền báo cáo tiến trình trong quá trình tải xuống. OnModelDownloaded kích hoạt khi tệp được lưu vào đĩa.

Để hủy quá trình tải xuống đang diễn ra:

Blueprint

C++

    LLM->CancelDownload();

Plugin tự động ngăn chặn tải xuống trùng lặp - nếu một quá trình tải xuống cho cùng một mô hình đã đang diễn ra, các lệnh gọi tiếp theo sẽ bị bỏ qua.

Dừng Tạo Sinh

Để ngắt một quá trình tạo sinh đang diễn ra:

Blueprint

C++

    LLM->StopGeneration();

Đặt lại Ngữ cảnh Hội thoại

Xóa lịch sử hội thoại để bắt đầu một cuộc trò chuyện mới:

Blueprint

C++

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

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

Giải phóng một Mô hình

Giải phóng tài nguyên khi một mô hình không còn cần thiết nữa:

Blueprint

C++

    LLM->UnloadModel();

Trạng thái Truy vấn

Kiểm tra trạng thái hiện tại của phiên bản LLM:

Blueprint

• Is Model Loaded: True nếu một mô hình đã sẵn sàng để suy luận
• Is Generating: True nếu quá trình sinh đang diễn ra
• Is Busy: True nếu bất kỳ thao tác nào (tải, sinh, tải xuống) đang hoạt động
• Is Downloading: True nếu quá trình tải xuống mô hình đang diễn ra
• Get Loaded Model Metadata: Trả về siêu dữ liệu của mô hình hiện tại
• Get Applied Inference Params: Trả về các tham số đã được áp dụng khi tải

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

Hàm Thư viện Mô hình

Một tập hợp các hàm tiện ích tĩnh được cung cấp để quản lý các tệp mô hình trên đĩa. Các hàm này hữu ích cho việc xây dựng giao diện người dùng chọn mô hình hoặc kiểm tra tính khả dụng của mô hình trong thời gian chạy.

Lấy Tên / Siêu dữ liệu Mô hình đã Tải xuống

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

Kiểm Tra Xem Mô Hình Có Trên Ổ Đĩa Không

Blueprint

C++

    bool bExists = URuntimeLLMLibrary::IsModelOnDisk(Metadata);

Lấy Đường Dẫn Tệp Mô Hình

Blueprint

C++

    FString FilePath = URuntimeLLMLibrary::GetModelFilePath(Metadata);

Xóa Tệp Mô Hình

Blueprint

C++

    bool bDeleted = URuntimeLLMLibrary::DeleteModelFiles(Metadata);

Lấy các Mô Hình Đã Định Nghĩa Sẵn và Khả Dụng

Blueprint

C++

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

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

Xây dựng Metadata từ URL

Xây dựng metadata mô hình từ một URL thô (các trường được suy ra từ tên tệp):

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

Hàm Tiện Ích

Một tập hợp các hàm trợ giúp được cung cấp để định dạng và hiển thị lỗi.

Bytes sang Chuỗi Có Thể Đọc

Chuyển đổi số lượng byte thành một chuỗi có thể đọc được (ví dụ: "4.07 GB"). Hữu ích để hiển thị kích thước mô hình trong giao diện người dùng.

Định Dạng Tiến Trình Tải Xuống

Định dạng một chuỗi tiến trình tải xuống như "1.23 GB / 4.07 GB (30.2%)". Nếu tổng kích thước không xác định, chỉ trả về lượng đã nhận được.

Lấy Mô Tả Lỗi / Chuỗi Mã Lỗi

Get LLM Error Description trả về mô tả văn bản có thể đọc được cho một mã lỗi. Get LLM Error Code String trả về tên giá trị enum dưới dạng chuỗi (hữu ích cho việc ghi log).

Tham Chiếu Mã Lỗi

Mã	Giá Trị	Mô Tả
Unknown	0	Một lỗi không xác định
ModelLoadFailed	10	Tệp GGUF không tải được (tệp hỏng, định dạng không tương thích, v.v.)
ContextCreateFailed	11	Không tạo được ngữ cảnh suy luận
ModelNotLoaded	20	Đã cố gắng suy luận khi chưa tải mô hình
ChatTemplateFailed	21	Mẫu trò chuyện của mô hình không áp dụng được
TokenizationFailed	22	Văn bản đầu vào không thể được token hóa
ContextOverflow	23	Lời nhắc + ngữ cảnh vượt quá kích thước ngữ cảnh đã cấu hình
PromptDecodeFailed	24	Các token lời nhắc không giải mã được
ContextTooFullToGenerate	25	Không đủ không gian ngữ cảnh còn lại để tạo đầu ra
GenerationDecodeFailed	30	Một token không giải mã được trong quá trình tạo
GenerationTruncated	31	Quá trình tạo bị dừng vì đã đạt đến giới hạn token tối đa
LLMInstanceNull	40	Phiên bản LLM là null hoặc không hợp lệ
ModelNotFoundOnDisk	41	Tệp mô hình không tồn tại tại đường dẫn dự kiến
ModelURLEmpty	42	Một yêu cầu tải xuống được thực hiện với URL trống
ModelDownloadCancelled	43	Quá trình tải xuống đã bị hủy
ModelDownloadEmptyData	44	Quá trình tải xuống hoàn tất nhưng nội dung phản hồi trống
ModelDownloadSaveFailed	45	Quá trình tải xuống hoàn tất nhưng không thể lưu tệp vào đĩa