C++ 篇 - 工具集
本文件介紹AIChatPlus所提供的工具類別,包含JSON操作、圖片處理及音訊處理等功能。
準備工作
在專案的 .Build.cs 檔案中加入模組依賴:
包含必要的標頭檔:
#include "Common/AIChatPlus_Util.h"
#include "Common/Json/AIChatPlus_JsonObject.h"
#include "Common/Json/AIChatPlus_JsonArray.h"
JSON 操作
AIChatPlus 提供了 Blueprint 友好的 JSON 操作類,支持鏈式調用和類型安全操作。
UAIChatPlus_JsonObject - JSON 物件
建立與解析
#include "Common/Json/AIChatPlus_JsonObject.h"
void UMyClass::JsonObjectBasics()
{
// 創建空 JSON 物件
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();
// 從字串解析
FString JsonString = TEXT(R"({"name": "John", "age": 30, "active": true})");
bool bSuccess;
FString ErrorMessage;
UAIChatPlus_JsonObject* ParsedObj = UAIChatPlus_JsonObject::Parse(JsonString, bSuccess, ErrorMessage);
if (bSuccess)
{
UE_LOG(LogTemp, Display, TEXT("Parsed successfully"));
}
else
{
UE_LOG(LogTemp, Error, TEXT("Parse error: %s"), *ErrorMessage);
}
}
設定欄位(鏈式調用)
void UMyClass::SetJsonFields()
{
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();
// 鏈式設置字段
JsonObj->SetStringField(TEXT("name"), TEXT("John"))
->SetIntegerField(TEXT("age"), 30)
->SetBooleanField(TEXT("active"), true)
->SetNumberField(TEXT("score"), 95.5f)
->SetNullField(TEXT("extra"));
// 設定巢狀物件
UAIChatPlus_JsonObject* AddressObj = UAIChatPlus_JsonObject::Create();
AddressObj->SetStringField(TEXT("city"), TEXT("Tokyo"))
->SetStringField(TEXT("country"), TEXT("Japan"));
JsonObj->SetObjectField(TEXT("address"), AddressObj);
// 輸出
FString Result = JsonObj->ToString(true); // true = 格式化輸出
UE_LOG(LogTemp, Display, TEXT("%s"), *Result);
}
取得欄位
void UMyClass::GetJsonFields()
{
FString JsonString = TEXT(R"({"name": "John", "age": 30, "scores": [85, 90, 95]})");
bool bParseSuccess;
FString ErrorMessage;
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Parse(JsonString, bParseSuccess, ErrorMessage);
if (!bParseSuccess) return;
bool bSuccess;
// 取得字串欄位
FString Name = JsonObj->GetStringField(TEXT("name"), TEXT("Unknown"), bSuccess);
if (bSuccess)
{
UE_LOG(LogTemp, Display, TEXT("Name: %s"), *Name);
}
// 取得整數字段
int32 Age = JsonObj->GetIntegerField(TEXT("age"), 0, bSuccess);
// 取得布林欄位
bool bActive = JsonObj->GetBooleanField(TEXT("active"), false, bSuccess);
// 獲取數組欄位
UAIChatPlus_JsonArray* Scores = JsonObj->GetArrayField(TEXT("scores"), bSuccess);
if (bSuccess && Scores)
{
for (int32 i = 0; i < Scores->Length(); ++i)
{
int32 Score = Scores->GetInteger(i, 0, bSuccess);
UE_LOG(LogTemp, Display, TEXT("Score[%d]: %d"), i, Score);
}
}
// 取得巢狀物件欄位
UAIChatPlus_JsonObject* AddressObj = JsonObj->GetObjectField(TEXT("address"), bSuccess);
if (bSuccess && AddressObj)
{
FString City = AddressObj->GetStringField(TEXT("city"), TEXT(""), bSuccess);
}
}
欄位檢查和管理
void UMyClass::ManageJsonFields()
{
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();
JsonObj->SetStringField(TEXT("name"), TEXT("John"))
->SetIntegerField(TEXT("age"), 30);
// 檢查欄位是否存在
if (JsonObj->HasField(TEXT("name")))
{
UE_LOG(LogTemp, Display, TEXT("Field 'name' exists"));
}
// 取得欄位類型
EAIChatPlus_JsonValueType FieldType = JsonObj->GetFieldType(TEXT("age"));
// FieldType == EAIChatPlus_JsonValueType::Number
// 取得所有欄位名稱
TArray<FString> FieldNames = JsonObj->GetFieldNames();
for (const FString& Name : FieldNames)
{
UE_LOG(LogTemp, Display, TEXT("Field: %s"), *Name);
}
// 刪除欄位
JsonObj->RemoveField(TEXT("age"));
// 清空所有欄位
JsonObj->Clear();
}
路徑查詢(巢狀訪問)
void UMyClass::PathQuery()
{
FString JsonString = TEXT(R"({
"player": {
"inventory": {
"gold": 1000,
"items": ["sword", "shield"]
}
}
})");
bool bParseSuccess;
FString ErrorMessage;
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Parse(JsonString, bParseSuccess, ErrorMessage);
// 透過路徑取得數值
FAIChatPlus_JsonQueryResult Result;
FString Gold = JsonObj->GetStringByPath(TEXT("player.inventory.gold"), TEXT("0"), Result);
// Gold = "1000"
// 透過路徑設定值
FAIChatPlus_JsonPathOptions PathOptions;
JsonObj->SetStringByPath(TEXT("player.inventory.gold"), TEXT("2000"), PathOptions);
}
合併與複製
void UMyClass::MergeAndDuplicate()
{
UAIChatPlus_JsonObject* Obj1 = UAIChatPlus_JsonObject::Create();
Obj1->SetStringField(TEXT("name"), TEXT("John"));
UAIChatPlus_JsonObject* Obj2 = UAIChatPlus_JsonObject::Create();
Obj2->SetIntegerField(TEXT("age"), 30)
->SetStringField(TEXT("name"), TEXT("Jane")); // 覆蓋 name
// 合併(當 bOverwrite = true 時覆蓋已存在的欄位)
Obj1->Merge(Obj2, true);
// Obj1 現在包含 {"name": "Jane", "age": 30}
// 深拷貝
UAIChatPlus_JsonObject* Copy = Obj1->Duplicate();
}
與 UStruct 互轉
USTRUCT(BlueprintType)
struct FMyData
{
GENERATED_BODY()
UPROPERTY()
FString Name;
UPROPERTY()
int32 Age;
};
void UMyClass::StructConversion()
{
// 將 UStruct 轉換為 JsonObject
FMyData Data;
Data.Name = TEXT("John");
Data.Age = 30;
UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::FromStruct(Data);
// JsonObject 轉換為 UStruct
FMyData OutData;
bool bSuccess = JsonObj->ToStruct(OutData);
if (bSuccess)
{
UE_LOG(LogTemp, Display, TEXT("Name: %s, Age: %d"), *OutData.Name, OutData.Age);
}
}
UAIChatPlus_JsonArray - JSON 陣列
創建與操作
#include "Common/Json/AIChatPlus_JsonArray.h"
void UMyClass::JsonArrayBasics()
{
// 建立空陣列
UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Create();
// 添加元素(鏈式調用)
JsonArray->AddString(TEXT("apple"))
->AddString(TEXT("banana"))
->AddInteger(42)
->AddBoolean(true)
->AddNull();
// 添加物件元素
UAIChatPlus_JsonObject* ItemObj = UAIChatPlus_JsonObject::Create();
ItemObj->SetStringField(TEXT("name"), TEXT("sword"));
JsonArray->AddObject(ItemObj);
// 加入巢狀陣列
UAIChatPlus_JsonArray* NestedArray = UAIChatPlus_JsonArray::Create();
NestedArray->AddInteger(1)->AddInteger(2)->AddInteger(3);
JsonArray->AddArray(NestedArray);
// 輸出
FString Result = JsonArray->ToString(true);
UE_LOG(LogTemp, Display, TEXT("%s"), *Result);
}
取得元素
void UMyClass::GetArrayElements()
{
FString JsonString = TEXT(R"(["apple", "banana", 42, true, {"name": "item"}])");
bool bParseSuccess;
FString ErrorMessage;
UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Parse(JsonString, bParseSuccess, ErrorMessage);
if (!bParseSuccess) return;
bool bSuccess;
// 獲取字串元素
FString Fruit = JsonArray->GetString(0, TEXT(""), bSuccess); // "apple"
// 取得整數元素
int32 Number = JsonArray->GetInteger(2, 0, bSuccess); // 42
// 取得布林元素
bool bValue = JsonArray->GetBoolean(3, false, bSuccess); // true
// 獲取對象元素
UAIChatPlus_JsonObject* Obj = JsonArray->GetObject(4, bSuccess);
if (bSuccess && Obj)
{
FString Name = Obj->GetStringField(TEXT("name"), TEXT(""), bSuccess);
}
// 遍歷數組
for (int32 i = 0; i < JsonArray->Length(); ++i)
{
EAIChatPlus_JsonValueType Type = JsonArray->GetElementType(i);
UE_LOG(LogTemp, Display, TEXT("Element[%d] type: %d"), i, static_cast<int32>(Type));
}
}
陣列操作
void UMyClass::ArrayOperations()
{
UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Create();
JsonArray->AddString(TEXT("a"))
->AddString(TEXT("b"))
->AddString(TEXT("c"));
// 取得長度
int32 Len = JsonArray->Length(); // 3
// 檢查索引是否有效
bool bValid = JsonArray->IsValidIndex(1); // true
// 設定元素
bool bSuccess;
JsonArray->SetString(1, TEXT("B"), bSuccess);
// 刪除元素
JsonArray->RemoveAt(0, bSuccess);
// 清空陣列
JsonArray->Clear();
// 深拷貝
UAIChatPlus_JsonArray* Copy = JsonArray->Duplicate();
}
批量轉換
void UMyClass::BatchConversion()
{
// 從字串陣列建立
TArray<FString> StringArray = {TEXT("a"), TEXT("b"), TEXT("c")};
UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::FromStringArray(StringArray);
// 轉回字元串陣列
bool bSuccess;
TArray<FString> OutArray = JsonArray->ToStringArray(bSuccess);
// 從整數陣列創建
TArray<int32> IntArray = {1, 2, 3, 4, 5};
UAIChatPlus_JsonArray* IntJsonArray = UAIChatPlus_JsonArray::FromIntegerArray(IntArray);
// 轉回整數陣列
TArray<int32> OutIntArray = IntJsonArray->ToIntegerArray(bSuccess);
}
UAIChatPlus_Util - JSON 輔助函數
void UMyClass::JsonUtilFunctions()
{
// 合併兩個 JSON 字串
FString Json1 = TEXT(R"({"name": "John"})");
FString Json2 = TEXT(R"({"age": 30, "name": "Jane"})");
FString Merged = UAIChatPlus_Util::MergeJsonObjects(Json1, Json2);
// Merged = {"name": "Jane", "age": 30}
// 載入 JSON 字串為物件
TSharedPtr<FJsonObject> JsonObj = UAIChatPlus_Util::LoadJsonString(Json1);
// 物件轉字串
FString JsonString = UAIChatPlus_Util::ToJsonString(JsonObj);
}
圖片工具
載入與儲存圖片
#include "Common/AIChatPlus_Util.h"
void UMyClass::ImageLoadSave()
{
// 從文件載入圖片
FString ImagePath = FPaths::ProjectContentDir() / TEXT("Images/sample.png");
UTexture2D* Texture = UAIChatPlus_Util::LoadImage(ImagePath, true); // true = 完成編譯
if (Texture)
{
UE_LOG(LogTemp, Display, TEXT("Image loaded: %dx%d"),
Texture->GetSizeX(), Texture->GetSizeY());
}
// 將圖片保存到文件
FString SavePath = FPaths::ProjectSavedDir() / TEXT("output.png");
bool bSaved = UAIChatPlus_Util::SaveImage(Texture, SavePath);
if (bSaved)
{
UE_LOG(LogTemp, Display, TEXT("Image saved to: %s"), *SavePath);
}
}
圖片轉 Base64
void UMyClass::ImageToBase64()
{
UTexture2D* Texture = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));
// 轉換為 Base64 字串
// InQuality: 0 = PNG, 1-100 = JPEG 品質
FString B64String = UAIChatPlus_Util::ImageToB64(Texture, 0); // PNG 格式
UE_LOG(LogTemp, Display, TEXT("Base64 length: %d"), B64String.Len());
}
複製圖片
void UMyClass::CopyTexture()
{
UTexture2D* Original = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));
// 複製紋理
UTexture2D* Copy = UAIChatPlus_Util::CopyTexture2D(
Original,
nullptr, // 外部(nullptr = 取得暫存套件)
名稱, // 名稱
RF_無標誌 // 標誌
);
// 藍圖版本(帶預設標誌)
UTexture2D* BPCopy = UAIChatPlus_Util::CopyTexture2DInBlueprint(Original);
}
從網址取得圖片
void UMyClass::GetImageFromUrl()
{
FString ImageUrl = TEXT("https://example.com/image.png");
UAIChatPlus_Util::GetImageFromUrl(ImageUrl,
UAIChatPlus_Util::OnImageCreated::CreateLambda([](UTexture2D* Texture, const FString& Error)
{
if (Texture)
{
UE_LOG(LogTemp, Display, TEXT("Image downloaded: %dx%d"),
Texture->GetSizeX(), Texture->GetSizeY());
}
else
{
UE_LOG(LogTemp, Error, TEXT("Download failed: %s"), *Error);
}
}));
}
從 Base64 取得圖片
void UMyClass::GetImageFromBase64()
{
FString B64String = TEXT("iVBORw0KGgoAAAANSUhEUg..."); // Base64 資料
UAIChatPlus_Util::GetImageFromB64(B64String,
UAIChatPlus_Util::OnImageCreated::CreateLambda([](UTexture2D* Texture, const FString& Error)
{
if (Texture)
{
UE_LOG(LogTemp, Display, TEXT("Image decoded successfully"));
}
else
{
UE_LOG(LogTemp, Error, TEXT("Decode failed: %s"), *Error);
}
}));
}
複製圖片到剪貼簿
void UMyClass::CopyToClipboard()
{
UTexture2D* Texture = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));
// 檢查是否支援
if (UAIChatPlus_Util::IsCanCopyTexture2DToClipboard())
{
UAIChatPlus_Util::CopyTexture2DToClipboard(Texture);
UE_LOG(LogTemp, Display, TEXT("Image copied to clipboard"));
}
}
音頻工具
載入 WAV 檔案
void UMyClass::LoadWavFile()
{
FString WavPath = FPaths::ProjectContentDir() / TEXT("Audio/sample.wav");
USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(WavPath);
if (Sound)
{
UE_LOG(LogTemp, Display, TEXT("Sound loaded: Duration=%.2f, Channels=%d, SampleRate=%d"),
Sound->Duration,
Sound->NumChannels,
Sound->GetSampleRateForCurrentPlatform());
}
}
將音頻保存為WAV檔案
void UMyClass::SaveWavFile()
{
// 假設 Sound 是已有的 USoundWave
USoundWave* 音效 = /* 取得音訊 */;
FString SavePath = FPaths::ProjectSavedDir() / TEXT("output.wav");
bool bSaved = UAIChatPlus_Util::SaveSoundWav(Sound, SavePath);
if (bSaved)
{
UE_LOG(LogTemp, Display, TEXT("Sound saved to: %s"), *SavePath);
}
}
音頻轉 Base64
void UMyClass::SoundToBase64()
{
USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));
// 轉換為 Base64 字串
FString B64String = UAIChatPlus_Util::SoundToB64(Sound);
UE_LOG(LogTemp, Display, TEXT("Audio Base64 length: %d"), B64String.Len());
}
WAV 資料轉 SoundWave
void UMyClass::WavDataToSound()
{
// 從文件讀取原始數據
TArray<uint8> RawData;
FFileHelper::LoadFileToArray(RawData, TEXT("D:/audio.wav"));
// 轉換為 SoundWave
USoundWave* Sound = UAIChatPlus_Util::WavDataToSoundWave(
RawData,
false, // bIsAmbiX
false // bIsFuMa
);
if (Sound)
{
UE_LOG(LogTemp, Display, TEXT("Sound created from data"));
}
}
複製 SoundWave
void UMyClass::CopySoundWave()
{
USoundWave* Original = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));
// 複製音訊
USoundWave* Copy = UAIChatPlus_Util::CopySoundWave(
Original,
nullptr, // Outer
名稱
);
}
取得原始 PCM 數據
void UMyClass::GetPCMData()
{
USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));
// 獲取原始 PCM 數據
TArray<uint8> PCMData = UAIChatPlus_Util::GetSoundWavePCMData(Sound);
UE_LOG(LogTemp, Display, TEXT("PCM data size: %d bytes"), PCMData.Num());
}
從錄音數據創建SoundWave
void UMyClass::RecorderDataToSound()
{
// 假設從 Audio Capture 獲取的錄音數據
TArray<float> RecorderData; // 音訊採樣數據
int32 NumChannels = 1; // 單聲道
int32 SampleRate = 16000; // 取樣率
USoundWave* Sound = UAIChatPlus_Util::RecorderDataToSoundWave(
RecorderData,
NumChannels,
SampleRate
);
if (Sound)
{
UE_LOG(LogTemp, Display, TEXT("Sound created from recorder data"));
}
}
日誌控制
void UMyClass::ControlLogging()
{
// 設定內部日誌級別
UAIChatPlus_Util::SetInternalLogVerbosity(EAIChatPlus_LogVerbosityType::Verbose);
// 可用級別:
// - NoLogging
// - Fatal
// - Error
// - Warning
// - Display
// - Log
// - Verbose
// - VeryVerbose
}
回應包裝器輔助函數
在回調中處理響應時,需要將 FAIChatPlus_PointerWrapper 轉換為具體類型:
void UMyClass::HandleCallbackResponse()
{
// 在 OnFinished 回呼中
Request->OnFinishedListeners.AddLambda([](const FAIChatPlus_PointerWrapper& ResponseWrapper)
{
// 取得回應訊息
FString Message = UAIChatPlus_Util::GetResponseWrapperMessage(ResponseWrapper);
UE_LOG(LogTemp, Display, TEXT("Message: %s"), *Message);
// 或者轉換為基礎響應類型
FAIChatPlus_ChatResponseBodyBase& Response = UAIChatPlus_Util::CastWrapperToResponse(ResponseWrapper);
});
// 在 OnFailed 回調中
Request->OnFailedListeners.AddLambda([](const FAIChatPlus_PointerWrapper& ErrorWrapper)
{
// 取得錯誤描述
FString ErrorDesc = UAIChatPlus_Util::GetErrorWrapperDescription(ErrorWrapper);
UE_LOG(LogTemp, Error, TEXT("Error: %s"), *ErrorDesc);
// 或者轉換為錯誤類型
FAIChatPlus_ResponseErrorBase& Error = UAIChatPlus_Util::CastWrapperToError(ErrorWrapper);
});
}
模型資訊查詢
void UMyClass::QueryModelInfo()
{
// 獲取 OpenAI 預設模型清單
const TArray<FName>& OpenAIModels = UAIChatPlus_Util::GetOpenAIChatDefaultModels();
// 獲取特定模型資訊
FAIChatPlus_ChatModelInfo ModelInfo = UAIChatPlus_Util::GetOpenAIChatModelInfo(TEXT("gpt-4o"));
UE_LOG(LogTemp, Display, TEXT("Model: %s, MaxTokens: %d, SupportImage: %s"),
*ModelInfo.Name.ToString(),
ModelInfo.MaxTokens,
ModelInfo.IsSupportSendImage ? TEXT("Yes") : TEXT("No"));
// Claude 模型
const TArray<FName>& ClaudeModels = UAIChatPlus_Util::GetClaudeChatDefaultModels();
FAIChatPlus_ChatModelInfo ClaudeInfo = UAIChatPlus_Util::GetClaudeChatModelInfo(TEXT("claude-3-5-sonnet"));
// 雙子座模型
const TArray<FName>& GeminiModels = UAIChatPlus_Util::GetGeminiChatDefaultModels();
FAIChatPlus_ChatModelInfo GeminiInfo = UAIChatPlus_Util::GetGeminiChatModelInfo(TEXT("gemini-1.5-pro"));
}
Cllama 輔助函數
void UMyClass::CllamaUtilities()
{
// 檢查 Cllama 是否可用
if (UAIChatPlus_Util::Cllama_IsValid())
{
UE_LOG(LogTemp, Display, TEXT("Cllama is available"));
}
// 檢查 GPU 支援
if (UAIChatPlus_Util::Cllama_IsSupportGpu())
{
UE_LOG(LogTemp, Display, TEXT("GPU acceleration supported"));
}
// 取得支援的後端
TArray<FString> Backends = UAIChatPlus_Util::Cllama_GetSupportBackends();
for (const FString& Backend : Backends)
{
UE_LOG(LogTemp, Display, TEXT("Backend: %s"), *Backend);
}
// 準備 Pak 中的模型路徑
FString ModelPath = TEXT("Models/my_model.gguf");
FString ActualPath = UAIChatPlus_Util::Cllama_PrepareModelPathFromPak(ModelPath);
// 如果模型在 Pak 中,會解壓到臨時目錄並返回新路徑
}
文件輔助函數
void UMyClass::FileUtilities()
{
// 取得插件基礎目錄
FString PluginDir = UAIChatPlus_Util::GetPluginBaseDir(TEXT("AIChatPlus"));
UE_LOG(LogTemp, Display, TEXT("Plugin dir: %s"), *PluginDir);
// 複製目錄
FString SourceDir = FPaths::ProjectContentDir() / TEXT("Source");
FString DestDir = FPaths::ProjectSavedDir() / TEXT("Backup");
bool bCopied = UAIChatPlus_Util::CopyDirectory(SourceDir, DestDir, true); // true = 覆蓋
}
提示 模板
void UMyClass::PromptTemplates()
{
// 取得 Prompt 範本 JSON 檔案清單
TArray<FDirectoryPath> ExtraDirs; // 額外搜尋目錄(可選)
TArray<FFilePath> TemplateFiles = UAIChatPlus_Util::GetPromptTemplateJsonFiles(ExtraDirs);
// 載入 Prompt 範本
TArray<FAIChatPlus_PromptTemplate> Templates = UAIChatPlus_Util::GetPromptTemplates(TemplateFiles);
for (const FAIChatPlus_PromptTemplate& Template : Templates)
{
UE_LOG(LogTemp, Display, TEXT("Template: %s"), *Template.Name);
}
}
Original: https://wiki.disenone.site/tc
This post is protected by CC BY-NC-SA 4.0 agreement, should be reproduced with attribution.
Visitors. Total Visits. Page Visits.
此帖子是使用 ChatGPT 翻譯的,請在意見回饋中指出任何遺漏之處。