كيفية استخدام المكون الإضافي

يوفر Runtime AI Chatbot Integrator وظيفتين رئيسيتين: الدردشة من نص إلى نص (Text-to-Text chat) والصوت من نص إلى كلام (Text-to-Speech - TTS). تتبع كلتا الميزتين سير عمل متشابه:

1. تسجيل رمز موفر API الخاص بك
2. تكوين الإعدادات الخاصة بالميزة
3. إرسال الطلبات ومعالجة الردود

تسجيل رمز الموفر

قبل إرسال أي طلبات، قم بتسجيل رمز موفر API الخاص بك باستخدام الدالة RegisterProviderToken.

Blueprint

C++

// Register an OpenAI provider token, as an example
UAIChatbotCredentialsManager::RegisterProviderToken(
    EAIChatbotIntegratorOrgs::OpenAI, 
    TEXT("sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
);

وظيفة الدردشة النصية إلى النصية

يدعم البرنامج المساعد وضعين لطلبات الدردشة لكل مزود:

طلبات الدردشة غير المتدفقة

استرجع الرد الكامل في مكالمة واحدة.

OpenAI

Blueprint

C++

// Example of sending a non-streaming chat request to OpenAI
FChatbotIntegrator_OpenAISettings Settings;
Settings.Messages.Add(FChatbotIntegrator_OpenAIMessage(
    EChatbotIntegrator_OpenAIRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_OpenAIMessage(
    EChatbotIntegrator_OpenAIRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorOpenAI::SendChatRequestNative(
    Settings, 
    FOnOpenAIChatCompletionResponseNative::CreateWeakLambda(
        this, 
        [this](const FString& Response, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Chat completion response: %s, Error: %d: %s"), 
                *Response, ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

DeepSeek

بلوپرينت

++C

// Example of sending a non-streaming chat request to DeepSeek
FChatbotIntegrator_DeepSeekSettings Settings;
Settings.Messages.Add(FChatbotIntegrator_DeepSeekMessage(
    EChatbotIntegrator_DeepSeekRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_DeepSeekMessage(
    EChatbotIntegrator_DeepSeekRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorDeepSeek::SendChatRequestNative(
    Settings, 
    FOnDeepSeekChatCompletionResponseNative::CreateWeakLambda(
        this, 
        [this](const FString& Reasoning, const FString& Content, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Chat completion reasoning: %s, Content: %s, Error: %d: %s"), 
                *Reasoning, *Content, ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

Claude

Blueprint

C++

// Example of sending a non-streaming chat request to Claude
FChatbotIntegrator_ClaudeSettings Settings;
Settings.Messages.Add(FChatbotIntegrator_ClaudeMessage(
    EChatbotIntegrator_ClaudeRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_ClaudeMessage(
    EChatbotIntegrator_ClaudeRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorClaudeStream::SendStreamingChatRequestNative(
    Settings, 
    FOnClaudeChatCompletionStreamNative::CreateWeakLambda(
        this, 
        [this](const FString& Response, bool IsFinalChunk, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Streaming chat completion response: %s, IsFinalChunk: %d, Error: %d: %s"), 
                *Response, IsFinalChunk, ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

طلبات الدردشة المتدفقة

تلقي أجزاء الرد في الوقت الفعلي لتفاعل أكثر ديناميكية.

OpenAI

Blueprint

C++

// Example of sending a streaming chat request to OpenAI
FChatbotIntegrator_OpenAISettings Settings;
Settings.Messages.Add(FChatbotIntegrator_OpenAIMessage(
    EChatbotIntegrator_OpenAIRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_OpenAIMessage(
    EChatbotIntegrator_OpenAIRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorOpenAIStream::SendStreamingChatRequestNative(
    Settings, 
    FOnOpenAIChatCompletionStreamNative::CreateWeakLambda(
        this, 
        [this](const FString& Response, bool IsFinalChunk, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Streaming chat completion response: %s, IsFinalChunk: %d, Error: %d: %s"), 
                *Response, IsFinalChunk, ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

DeepSeek

Blueprint

C++

// Example of sending a streaming chat request to DeepSeek
FChatbotIntegrator_DeepSeekSettings Settings;
Settings.Messages.Add(FChatbotIntegrator_DeepSeekMessage(
    EChatbotIntegrator_DeepSeekRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_DeepSeekMessage(
    EChatbotIntegrator_DeepSeekRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorDeepSeekStream::SendStreamingChatRequestNative(
    Settings, 
    FOnDeepSeekChatCompletionStreamNative::CreateWeakLambda(
        this, 
        [this](const FString& ReasoningChunk, const FString& ContentChunk, 
               bool IsReasoningFinalChunk, bool IsContentFinalChunk, 
               const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Streaming chat completion reasoning chunk: %s, Content chunk: %s, IsReasoningFinalChunk: %d, IsContentFinalChunk: %d, Error: %d: %s"), 
                *ReasoningChunk, *ContentChunk, IsReasoningFinalChunk, IsContentFinalChunk, 
                ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

Claude

Blueprint

C++

// Example of sending a streaming chat request to Claude
FChatbotIntegrator_ClaudeSettings Settings;
Settings.Messages.Add(FChatbotIntegrator_ClaudeMessage(
    EChatbotIntegrator_ClaudeRole::SYSTEM, 
    TEXT("You are a helpful assistant.")
));
Settings.Messages.Add(FChatbotIntegrator_ClaudeMessage(
    EChatbotIntegrator_ClaudeRole::USER, 
    TEXT("What is the capital of France?")
));

UAIChatbotIntegratorClaudeStream::SendStreamingChatRequestNative(
    Settings, 
    FOnClaudeChatCompletionStreamNative::CreateWeakLambda(
        this, 
        [this](const FString& Response, bool IsFinalChunk, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            UE_LOG(LogTemp, Log, TEXT("Streaming chat completion response: %s, IsFinalChunk: %d, Error: %d: %s"), 
                *Response, IsFinalChunk, ErrorStatus.bIsError, *ErrorStatus.ErrorMessage);
        }
    )
);

وظيفة تحويل النص إلى كلام (TTS)

قم بتحويل النص إلى صوت عالي الجودة باستخدام مزودي خدمة TTS الرائدين. تُرجع الإضافة بيانات الصوت الخام (TArray<uint8>) والتي يمكنك معالجتها وفقًا لاحتياجات مشروعك.

بينما توضح الأمثلة أدناه معالجة الصوت للتشغيل باستخدام إضافة Runtime Audio Importer (انظر توثيق استيراد الصوت)، فإن إضافة Runtime AI Chatbot Integrator مصممة لتكون مرنة. تُرجع الإضافة ببساطة بيانات الصوت الخام، مما يمنحك الحرية الكاملة في كيفية معالجتها لحالة الاستخدام الخاصة بك، والتي قد تشمل تشغيل الصوت، الحفظ في ملف، معالجة صوتية إضافية، إرسال إلى أنظمة أخرى، تصورات مخصصة، والمزيد.

طلبات TTS غير المتدفقة

تُرجع طلبات TTS غير المتدفقة بيانات الصوت الكاملة في استجابة واحدة بعد معالجة النص بالكامل. هذا الأسلوب مناسب للنصوص القصيرة حيث لا يمثل انتظار الصوت الكامل مشكلة.

OpenAI TTS

Blueprint

C++

// Example of sending a TTS request to OpenAI
FChatbotIntegrator_OpenAITTSSettings TTSSettings;
TTSSettings.Input = TEXT("Hello, this is a test of text-to-speech functionality.");
TTSSettings.Voice = EChatbotIntegrator_OpenAITTSVoice::NOVA;
TTSSettings.Speed = 1.0f;
TTSSettings.ResponseFormat = EChatbotIntegrator_OpenAITTSFormat::MP3;

UAIChatbotIntegratorOpenAITTS::SendTTSRequestNative(
	TTSSettings, 
	FOnElevenLabsTTSResponseNative::CreateWeakLambda(
		this, 
		[this](const TArray<uint8>& AudioData, const FChatbotIntegratorErrorStatus& ErrorStatus)
		{
			if (!ErrorStatus.bIsError)
			{
				// Process the audio data using Runtime Audio Importer plugin
				// Example: Import the audio data as a sound wave
				UE_LOG(LogTemp, Log, TEXT("Received TTS audio data: %d bytes"), AudioData.Num());

				// Audio data can be imported using Runtime Audio Importer plugin
				URuntimeAudioImporterLibrary* RuntimeAudioImporter = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();
				RuntimeAudioImporter->AddToRoot();
				RuntimeAudioImporter->OnResultNative.AddWeakLambda(this, [this](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
				{
					if (Status == ERuntimeImportStatus::SuccessfulImport)
					{
						UE_LOG(LogTemp, Warning, TEXT("Successfully imported audio with sound wave %s"), *ImportedSoundWave->GetName());
						// Here you can handle ImportedSoundWave playback, like "UGameplayStatics::PlaySound2D(GetWorld(), ImportedSoundWave);"
					}
					else
					{
						UE_LOG(LogTemp, Error, TEXT("Failed to import audio"));
					}

					Importer->RemoveFromRoot();
				});
				RuntimeAudioImporter->ImportAudioFromBuffer(AudioData, ERuntimeAudioFormat::Mp3);
			}
			else
			{
				UE_LOG(LogTemp, Error, TEXT("TTS request failed: %s"), *ErrorStatus.ErrorMessage);
			}
		}
	)
);

ElevenLabs TTS

Blueprint

C++

// Example of sending a TTS request to ElevenLabs
FChatbotIntegrator_ElevenLabsTTSSettings TTSSettings;
TTSSettings.Text = TEXT("Hello, this is a test of text-to-speech functionality.");
TTSSettings.VoiceID = TEXT("your-voice-id"); // Replace with actual voice ID
TTSSettings.Model = EChatbotIntegrator_ElevenLabsTTSModel::ELEVEN_TURBO_V2;
TTSSettings.OutputFormat = EChatbotIntegrator_ElevenLabsTTSFormat::MP3_44100_128;

UAIChatbotIntegratorElevenLabsTTS::SendTTSRequestNative(
	TTSSettings, 
	FOnElevenLabsTTSResponseNative::CreateWeakLambda(
		this, 
		[this](const TArray<uint8>& AudioData, const FChatbotIntegratorErrorStatus& ErrorStatus)
		{
			if (!ErrorStatus.bIsError)
			{
				// Process the audio data using Runtime Audio Importer plugin
				// Example: Import the audio data as a sound wave
				UE_LOG(LogTemp, Log, TEXT("Received TTS audio data: %d bytes"), AudioData.Num());

				// Audio data can be imported using Runtime Audio Importer plugin
				URuntimeAudioImporterLibrary* RuntimeAudioImporter = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();
				RuntimeAudioImporter->AddToRoot();
				RuntimeAudioImporter->OnResultNative.AddWeakLambda(this, [this](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
				{
					if (Status == ERuntimeImportStatus::SuccessfulImport)
					{
						UE_LOG(LogTemp, Warning, TEXT("Successfully imported audio with sound wave %s"), *ImportedSoundWave->GetName());
						// Here you can handle ImportedSoundWave playback, like "UGameplayStatics::PlaySound2D(GetWorld(), ImportedSoundWave);"
					}
					else
					{
						UE_LOG(LogTemp, Error, TEXT("Failed to import audio"));
					}

					Importer->RemoveFromRoot();
				});
				RuntimeAudioImporter->ImportAudioFromBuffer(AudioData, ERuntimeAudioFormat::Mp3);
			}
			else
			{
				UE_LOG(LogTemp, Error, TEXT("TTS request failed: %s"), *ErrorStatus.ErrorMessage);
			}
		}
	)
);

طلبات TTS المتدفقة

يوفر TTS المتدفق مقاطع صوتية أثناء توليدها، مما يسمح لك بمعالجة البيانات تدريجياً بدلاً من انتظار انتهاء توليد الصوت بالكامل. هذا يقلل بشكل كبير من زمن الوضع الملحوظ للنصوص الطويلة ويمكّن التطبيقات في الوقت الفعلي.

OpenAI Streaming TTS

Blueprint

C++

UPROPERTY()
UStreamingSoundWave* StreamingSoundWave;

UPROPERTY()
bool bIsPlaying = false;

UFUNCTION(BlueprintCallable)
void StartStreamingTTS()
{
    // Create a sound wave for streaming if not already created
    if (!StreamingSoundWave)
    {
        StreamingSoundWave = UStreamingSoundWave::CreateStreamingSoundWave();
        StreamingSoundWave->OnPopulateAudioStateNative.AddWeakLambda(this, [this]()
        {
            if (!bIsPlaying)
            {
                bIsPlaying = true;
                UGameplayStatics::PlaySound2D(GetWorld(), StreamingSoundWave);
            }
        });
    }

    FChatbotIntegrator_OpenAIStreamingTTSSettings TTSSettings;
    TTSSettings.Text = TEXT("Streaming synthesis output begins with a steady flow of data. This data is processed in real-time to ensure consistency. As the process continues, information is streamed without interruption. The output adapts seamlessly to changing inputs. Each piece of data is instantly integrated into the stream. Real-time processing allows for immediate adjustments. This constant flow ensures that the synthesis output is dynamic. As new data comes in, the output evolves accordingly. The system is designed to maintain a continuous output stream. This uninterrupted flow is what drives the efficiency of streaming synthesis.");
    TTSSettings.Voice = EChatbotIntegrator_OpenAIStreamingTTSVoice::ALLOY;
    
    UAIChatbotIntegratorOpenAIStreamTTS::SendStreamingTTSRequestNative(TTSSettings, FOnOpenAIStreamingTTSNative::CreateWeakLambda(this, [this](const TArray<uint8>& AudioData, bool IsFinalChunk, const FChatbotIntegratorErrorStatus& ErrorStatus)
    {
        if (!ErrorStatus.bIsError)
        {
            // Process the audio data using Runtime Audio Importer plugin
            // Example: Stream audio data into a sound wave
            UE_LOG(LogTemp, Log, TEXT("Received TTS audio data: %d bytes"), AudioData.Num());
            StreamingSoundWave->AppendAudioDataFromRAW(AudioData, ERuntimeRAWAudioFormat::Int16, 24000, 1);
        }
        else
        {
            UE_LOG(LogTemp, Error, TEXT("TTS request failed: %s"), *ErrorStatus.ErrorMessage);
        }
    }));
}

ElevenLabs Streaming TTS

Blueprint

C++

UPROPERTY()
UStreamingSoundWave* StreamingSoundWave;

UPROPERTY()
bool bIsPlaying = false;

UFUNCTION(BlueprintCallable)
void StartStreamingTTS()
{
    // Create a sound wave for streaming if not already created
    if (!StreamingSoundWave)
    {
        StreamingSoundWave = UStreamingSoundWave::CreateStreamingSoundWave();
        StreamingSoundWave->OnPopulateAudioStateNative.AddWeakLambda(this, [this]()
        {
            if (!bIsPlaying)
            {
                bIsPlaying = true;
                UGameplayStatics::PlaySound2D(GetWorld(), StreamingSoundWave);
            }
        });
    }

    FChatbotIntegrator_ElevenLabsStreamingTTSSettings TTSSettings;
    TTSSettings.Text = TEXT("Streaming synthesis output begins with a steady flow of data. This data is processed in real-time to ensure consistency. As the process continues, information is streamed without interruption. The output adapts seamlessly to changing inputs. Each piece of data is instantly integrated into the stream. Real-time processing allows for immediate adjustments. This constant flow ensures that the synthesis output is dynamic. As new data comes in, the output evolves accordingly. The system is designed to maintain a continuous output stream. This uninterrupted flow is what drives the efficiency of streaming synthesis.");
    TTSSettings.Model = EChatbotIntegrator_ElevenLabsTTSModel::ELEVEN_TURBO_V2_5;
    TTSSettings.OutputFormat = EChatbotIntegrator_ElevenLabsTTSFormat::MP3_22050_32;
    TTSSettings.VoiceID = TEXT("YOUR_VOICE_ID");
    
    UAIChatbotIntegratorElevenLabsStreamTTS::SendStreamingTTSRequestNative(GetWorld(), TTSSettings, FOnElevenLabsStreamingTTSNative::CreateWeakLambda(this, [this](const TArray<uint8>& AudioData, bool IsFinalChunk, const FChatbotIntegratorErrorStatus& ErrorStatus)
    {
        if (!ErrorStatus.bIsError)
        {
            // Process the audio data using Runtime Audio Importer plugin
            // Example: Stream audio data into a sound wave
            UE_LOG(LogTemp, Log, TEXT("Received TTS audio data: %d bytes"), AudioData.Num());
            StreamingSoundWave->AppendAudioDataFromEncoded(AudioData, ERuntimeAudioFormat::Mp3);
        }
        else
        {
            UE_LOG(LogTemp, Error, TEXT("TTS request failed: %s"), *ErrorStatus.ErrorMessage);
        }
    }));
}

معالجة الأخطاء

عند إرسال أي طلبات، من الضروري معالجة الأخطاء المحتملة عن طريق التحقق من ErrorStatus في رد النداء الخاص بك. يوفر ErrorStatus معلومات حول أي مشكلات قد تحدث أثناء الطلب.

Blueprint

C++

// Example of error handling in a request
UAIChatbotIntegratorOpenAI::SendChatRequestNative(
    Settings, 
    FOnOpenAIChatCompletionResponseNative::CreateWeakLambda(
        this, 
        [this](const FString& Response, const FChatbotIntegratorErrorStatus& ErrorStatus)
        {
            if (ErrorStatus.bIsError)
            {
                // Handle the error
                UE_LOG(LogTemp, Error, TEXT("Chat request failed: %s"), *ErrorStatus.ErrorMessage);
            }
            else 
            {
                // Process the successful response
                UE_LOG(LogTemp, Log, TEXT("Received response: %s"), *Response);
            }
        }
    )
);

إلغاء الطلبات

يسمح لك البرنامج المساعد بإلغاء كل من طلبات النص إلى النص وطلبات تحويل النص إلى كلام (TTS) أثناء تنفيذها. يمكن أن يكون هذا مفيدًا عندما تريد مقاطعة طلب يستغرق وقتًا طويلاً أو تغيير تدفق المحادثة ديناميكيًا.

Blueprint

C++

// Example of cancelling requests
UAIChatbotIntegratorOpenAI* ChatRequest = UAIChatbotIntegratorOpenAI::SendChatRequestNative(
    ChatSettings, 
    ChatResponseCallback
);

// Cancel the chat request at any time
ChatRequest->Cancel();

// TTS requests can be cancelled similarly
UAIChatbotIntegratorOpenAITTS* TTSRequest = UAIChatbotIntegratorOpenAITTS::SendTTSRequestNative(
    TTSSettings, 
    TTSResponseCallback
);

// Cancel the TTS request
TTSRequest->Cancel();

أفضل الممارسات

1. تعامل دائمًا مع الأخطاء المحتملة عن طريق التحقق من ErrorStatus في رد النداء الخاص بك
2. كن حذرًا من حدود معدل API والتكاليف
3. استخدم وضع البث للدردشات الطويلة أو التفاعلية
4. فكر في إلغاء الطلبات التي لم تعد مطلوبة لإدارة الموارد بكفاءة
5. استخدم TTS البث للنصوص الطويلة لتقليل زمن الوصول الملحوظ
6. لمعالجة الصوت، يقدم مكون Runtime Audio Importer plugin حلاً مناسبًا، ولكن يمكنك تنفيذ معالجة مخصصة بناءً على احتياجات مشروعك

استكشاف الأخطاء وإصلاحها

• تحقق من صحة بيانات اعتماد API الخاصة بك
• تحقق من اتصالك بالإنترنت
• تأكد من تثبيت أي مكتبات معالجة صوتية تستخدمها (مثل Runtime Audio Importer) بشكل صحيح عند العمل مع ميزات TTS
• تحقق من أنك تستخدم تنسيق الصوت الصحيح عند معالجة بيانات استجابة TTS
• بالنسبة لـ TTS البث، تأكد من أنك تتعامل مع مقاطع الصوت بشكل صحيح