Como usar o plugin

O Runtime AI Chatbot Integrator oferece duas funcionalidades principais: chat Texto-para-Texto e Texto-para-Voz (TTS). Ambos os recursos seguem um fluxo de trabalho similar:

Registrar seu token de provedor de API
Configurar definições específicas do recurso
Enviar solicitações e processar respostas

Registrar Token do Provedor

Antes de enviar qualquer solicitação, registre seu token de provedor de API usando a função RegisterProviderToken.

Blueprint
C++

Registrar Token do Provedor em Blueprint

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

Funcionalidade de Chat Texto-para-Texto

O plugin suporta dois modos de requisição de chat para cada provedor:

Requisições de Chat Não-Streaming

Recupera a resposta completa em uma única chamada.

OpenAI
DeepSeek
Claude

Blueprint
C++

Enviar Requisição de Chat OpenAI

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

Blueprint
C++

Enviar Solicitação de Chat DeepSeek

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

Blueprint
C++

Enviar Solicitação de Chat Claude

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

Solicitações de Chat em Streaming

Receba partes da resposta em tempo real para uma interação mais dinâmica.

OpenAI
DeepSeek
Claude

Blueprint
C++

Enviar Solicitação de Chat em Streaming OpenAI

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

Blueprint
C++

Enviar Solicitação de Chat em Streaming DeepSeek

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

Blueprint
C++

Enviar Solicitação de Chat em Streaming do Claude

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

Funcionalidade Text-to-Speech (TTS)

Converta texto em áudio de fala de alta qualidade usando os principais provedores de TTS. O plugin retorna dados de áudio brutos (TArray<uint8>) que você pode processar de acordo com as necessidades do seu projeto.

Enquanto os exemplos abaixo demonstram o processamento de áudio para reprodução usando o plugin Runtime Audio Importer (veja a documentação de importação de áudio), o Runtime AI Chatbot Integrator foi projetado para ser flexível. O plugin simplesmente retorna os dados de áudio brutos, dando a você total liberdade em como processá-los para seu caso de uso específico, o que pode incluir reprodução de áudio, salvamento em arquivo, processamento adicional de áudio, transmissão para outros sistemas, visualizações personalizadas e mais.

Requisições TTS Não-Streaming

Requisições TTS não-streaming retornam os dados de áudio completos em uma única resposta após todo o texto ter sido processado. Essa abordagem é adequada para textos mais curtos onde esperar pelo áudio completo não é problemático.

OpenAI TTS
ElevenLabs TTS

Blueprint
C++

Enviar Requisição OpenAI TTS

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

Blueprint
C++

Enviar Solicitação ElevenLabs TTS

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

Solicitações de TTS em Streaming

O TTS em Streaming entrega partes do áudio conforme são geradas, permitindo que você processe os dados incrementalmente em vez de esperar pela síntese completa do áudio. Isso reduz significativamente a latência percebida para textos longos e possibilita aplicações em tempo real.

OpenAI Streaming TTS
ElevenLabs Streaming TTS

Blueprint
C++

Enviar Solicitação de TTS em Streaming da OpenAI

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

Blueprint
C++

Enviar Requisição ElevenLabs Streaming TTS

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

Tratamento de Erros

Ao enviar qualquer solicitação, é crucial lidar com possíveis erros verificando o ErrorStatus em seu callback. O ErrorStatus fornece informações sobre quaisquer problemas que possam ocorrer durante a solicitação.

Blueprint
C++

Tratamento de Erros

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

Cancelando Solicitações

O plugin permite que você cancele solicitações de texto-para-texto e TTS enquanto elas estão em andamento. Isso pode ser útil quando você deseja interromper uma solicitação de longa duração ou alterar o fluxo da conversa dinamicamente.

Blueprint
C++

Cancel Request

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

Melhores Práticas

Sempre trate possíveis erros verificando o ErrorStatus em seu callback
Esteja atento aos limites de taxa e custos da API
Use o modo de streaming para conversas longas ou interativas
Considere cancelar requisições que não são mais necessárias para gerenciar recursos eficientemente
Utilize TTS com streaming para textos longos e reduzir a latência percebida
Para processamento de áudio, o plugin Runtime Audio Importer oferece uma solução conveniente, mas você pode implementar processamento personalizado conforme as necessidades do seu projeto

Solução de Problemas

Verifique se suas credenciais de API estão corretas
Verifique sua conexão com a internet
Certifique-se que quaisquer bibliotecas de processamento de áudio (como Runtime Audio Importer) estejam corretamente instaladas ao trabalhar com recursos TTS
Confirme que você está usando o formato de áudio correto ao processar dados de resposta TTS
Para TTS com streaming, garanta que você está manipulando os chunks de áudio corretamente

Registrar Token do Provedor​

Funcionalidade de Chat Texto-para-Texto​

Requisições de Chat Não-Streaming​

Solicitações de Chat em Streaming​

Funcionalidade Text-to-Speech (TTS)​

Requisições TTS Não-Streaming​

Solicitações de TTS em Streaming​

Tratamento de Erros​

Cancelando Solicitações​

Melhores Práticas​

Solução de Problemas​

Registrar Token do Provedor

Funcionalidade de Chat Texto-para-Texto

Requisições de Chat Não-Streaming

Solicitações de Chat em Streaming

Funcionalidade Text-to-Speech (TTS)

Requisições TTS Não-Streaming

Solicitações de TTS em Streaming

Tratamento de Erros

Cancelando Solicitações

Melhores Práticas

Solução de Problemas