Come usare il plugin

Il Runtime AI Chatbot Integrator fornisce due funzionalità principali: chat Testo-a-Testo e Testo-a-Voce (TTS). Entrambe le funzionalità seguono un flusso di lavoro simile:

Registra il token del tuo provider API
Configura le impostazioni specifiche per la funzionalità
Invia richieste e processa le risposte

Registrare il Token del Provider

Prima di inviare qualsiasi richiesta, registra il token del tuo provider API utilizzando la funzione RegisterProviderToken.

Blueprint
C++

Registrare il Token del Provider in Blueprint

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

Funzionalità di Chat da Testo a Testo

Il plugin supporta due modalità di richiesta di chat per ogni provider:

Richieste di Chat Non in Streaming

Recupera la risposta completa in una singola chiamata.

OpenAI
DeepSeek
Claude

Blueprint
C++

Send OpenAI Chat Request

// 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++

Invia Richiesta 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++

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

Richieste di Chat in Streaming

Ricevi porzioni di risposta in tempo reale per un'interazione più dinamica.

OpenAI
DeepSeek
Claude

Blueprint
C++

Invia Richiesta di Chat in 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++

Invia Richiesta Chat in 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++

Invia Richiesta Chat in Streaming 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);
        }
    )
);

Funzionalità Text-to-Speech (TTS)

Converti il testo in audio vocale di alta qualità utilizzando i principali provider TTS. Il plugin restituisce dati audio grezzi (TArray<uint8>) che puoi elaborare in base alle esigenze del tuo progetto.

Mentre gli esempi seguenti dimostrano l'elaborazione audio per la riproduzione utilizzando il plugin Runtime Audio Importer (vedi documentazione di importazione audio), il Runtime AI Chatbot Integrator è progettato per essere flessibile. Il plugin restituisce semplicemente i dati audio grezzi, dandoti completa libertà su come elaborarli per il tuo caso d'uso specifico, che potrebbe includere riproduzione audio, salvataggio su file, ulteriore elaborazione audio, trasmissione ad altri sistemi, visualizzazioni personalizzate e altro ancora.

Richieste TTS Non in Streaming

Le richieste TTS non in streaming restituiscono i dati audio completi in una singola risposta dopo che l'intero testo è stato elaborato. Questo approccio è adatto per testi più brevi dove attendere l'audio completo non è problematico.

OpenAI TTS
ElevenLabs TTS

Blueprint
C++

Send OpenAI TTS Request

// 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++

Invia Richiesta TTS ElevenLabs

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

Richieste TTS in Streaming

Il TTS in streaming fornisce porzioni di audio man mano che vengono generate, permettendoti di elaborare i dati in modo incrementale invece di attendere che l'intero audio sia sintetizzato. Questo riduce significativamente la latenza percepita per testi più lunghi e abilita applicazioni in tempo reale.

OpenAI Streaming TTS
ElevenLabs Streaming TTS

Blueprint
C++

Invia Richiesta OpenAI 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_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++

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

Gestione degli Errori

Quando si inviano richieste, è cruciale gestire potenziali errori controllando l'ErrorStatus nella tua callback. L'ErrorStatus fornisce informazioni su eventuali problemi che potrebbero verificarsi durante la richiesta.

Blueprint
C++

Gestione degli Errori

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

Annullamento delle Richieste

Il plugin ti consente di annullare sia le richieste testo-a-testo che TTS mentre sono in corso. Questo può essere utile quando vuoi interrompere una richiesta di lunga durata o cambiare dinamicamente il flusso della conversazione.

Blueprint
C++

Annulla Richiesta

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

Best Practices

Gestisci sempre i potenziali errori controllando lo ErrorStatus nella tua callback
Sii consapevole dei limiti di frequenza e dei costi delle API
Utilizza la modalità streaming per conversazioni lunghe o interattive
Considera di annullare le richieste non più necessarie per gestire le risorse in modo efficiente
Utilizza il TTS in streaming per testi più lunghi per ridurre la latenza percepita
Per l'elaborazione audio, il plugin Runtime Audio Importer offre una soluzione conveniente, ma puoi implementare un'elaborazione personalizzata in base alle esigenze del tuo progetto

Troubleshooting

Verifica che le tue credenziali API siano corrette
Controlla la tua connessione internet
Assicurati che eventuali librerie di elaborazione audio che utilizzi (come Runtime Audio Importer) siano installate correttamente quando lavori con le funzionalità TTS
Verifica di utilizzare il formato audio corretto durante l'elaborazione dei dati di risposta TTS
Per il TTS in streaming, assicurati di gestire correttamente i chunk audio

Registrare il Token del Provider​

Funzionalità di Chat da Testo a Testo​

Richieste di Chat Non in Streaming​

Richieste di Chat in Streaming​

Funzionalità Text-to-Speech (TTS)​

Richieste TTS Non in Streaming​

Richieste TTS in Streaming​

Gestione degli Errori​

Annullamento delle Richieste​

Best Practices​

Troubleshooting​

Registrare il Token del Provider

Funzionalità di Chat da Testo a Testo

Richieste di Chat Non in Streaming

Richieste di Chat in Streaming

Funzionalità Text-to-Speech (TTS)

Richieste TTS Non in Streaming

Richieste TTS in Streaming

Gestione degli Errori

Annullamento delle Richieste

Best Practices

Troubleshooting