API bidirezionale

L'API BiDiStreamingAnalyzeContent è l'API principale per le esperienze audio e multimodali di nuova generazione sia negli agenti conversazionali sia in Agent Assist. Questa API facilita lo streaming dei dati audio e ti restituisce trascrizioni o suggerimenti di agenti umani.

A differenza delle API precedenti, la configurazione audio semplificata ha un supporto ottimizzato per le conversazioni tra persone e un limite di scadenza esteso di 15 minuti. Ad eccezione della traduzione in tempo reale, questa API supporta anche tutte le funzionalità di Agent Assist supportate da StreamingAnalyzeContent.

Nozioni di base sullo streaming

Il seguente diagramma illustra il funzionamento dello stream.

Avvia uno stream inviando una configurazione audio al server. Poi invii i file audio e il server ti invia una trascrizione o suggerimenti per un agente umano. Invia altri dati audio per altre trascrizioni e suggerimenti. Questo scambio continua finché non lo interrompi chiudendo parzialmente lo stream.

Guida allo streaming

Per utilizzare l'API BiDiStreamingAnalyzeContent durante il runtime della conversazione, segui queste linee guida.

  1. Chiama il metodo BiDiStreamingAnalyzeContent e imposta i seguenti campi:
    • BiDiStreamingAnalyzeContentRequest.participant
    • (Facoltativo) BiDiStreamingAnalyzeContentRequest.voice_session_config.input_audio_sample_rate_hertz (se specificato, sostituisce la configurazione di ConversationProfile.stt_config.sample_rate_hertz)
    • (Facoltativo) BiDiStreamingAnalyzeContentRequest.voice_session_config.input_audio_encoding (se specificato, sostituisce la configurazione di ConversationProfile.stt_config.audio_encoding)
  2. Prepara lo stream e imposta la configurazione audio con la prima richiesta BiDiStreamingAnalyzeContent.
  3. Nelle richieste successive, invia i byte audio allo stream tramite BiDiStreamingAnalyzeContentRequest.audio.
  4. Dopo aver inviato la seconda richiesta con un payload audio, dovresti ricevere alcune BidiStreamingAnalyzeContentResponses dallo stream.
    • I risultati della trascrizione intermedi e finali sono disponibili con il seguente comando: BiDiStreamingAnalyzeContentResponse.recognition_result.
    • Puoi accedere ai suggerimenti degli agenti umani e ai messaggi di conversazione elaborati con il seguente comando: BiDiStreamingAnalyzeContentResponse.analyze_content_response.
  5. Puoi chiudere parzialmente lo stream in qualsiasi momento. Dopo aver chiuso parzialmente lo stream, il server restituisce la risposta contenente i risultati di riconoscimento rimanenti, insieme ai potenziali suggerimenti di Agent Assist.
  6. Avvia o riavvia un nuovo stream nei seguenti casi:
    • Lo stream è interrotto. Ad esempio, lo stream si è interrotto quando non avrebbe dovuto.
    • La conversazione si sta avvicinando al massimo di 15 minuti per la richiesta.
  7. Per una qualità ottimale, quando avvii uno stream, invia a BidiStreamingAnalyzeContent i dati audio generati dopo l'ultimo speech_end_offset di BiDiStreamingAnalyzeContentResponse.recognition_result con is_final=true.

Utilizzare l'API tramite la libreria client Python

Le librerie client ti aiutano ad accedere alle API di Google da un determinato linguaggio di codice. Puoi utilizzare la libreria client Python per Agent Assist con BidiStreamingAnalyzeContent come segue.

from google.cloud import dialogflow_v2beta1
from google.api_core.client_options import ClientOptions
from google.cloud import storage

import time
import google.auth
import participant_management
import conversation_management


PROJECT_ID="your-project-id"
CONVERSATION_PROFILE_ID="your-conversation-profile-id"
BUCKET_NAME="your-audio-bucket-name"

SAMPLE_RATE =48000
# Calculate the bytes with Sample_rate_hertz * bit Depth / 8 -> bytes
# 48000(sample/second) * 16(bits/sample) / 8 = 96000 byte per second,
# 96000 / 10 = 9600 we send 0.1 second to the stream API
POINT_ONE_SECOND_IN_BYTES = 9600
FOLDER_PTAH_FOR_CUSTOMER_AUDIO="your-customer-audios-files-path" 
FOLDER_PTAH_FOR_AGENT_AUDIO="your-agent-audios-file-path"
client_options = ClientOptions(api_endpoint="dialogflow.googleapis.com")
credentials, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform",
                                             "https://www.googleapis.com/auth/dialogflow"])

storage_client = storage.Client(credentials = credentials, project=PROJECT_ID)

participant_client = dialogflow_v2beta1.ParticipantsClient(client_options=client_options,
                                                           credentials=credentials)

def download_blob(bucket_name, folder_path, audio_array : list):
    """Uploads a file to the bucket."""
    bucket = storage_client.bucket(bucket_name, user_project=PROJECT_ID)
    blobs = bucket.list_blobs(prefix=folder_path)
    for blob in blobs:
      if not blob.name.endswith('/'):
          audio_array.append(blob.download_as_string())

def request_iterator(participant : dialogflow_v2beta1.Participant, audios):
    """Iterate the request for bidi streaming analyze content
    """

    yield dialogflow_v2beta1.BidiStreamingAnalyzeContentRequest(
        config={
            "participant": participant.name,
            "voice_session_config": {
                "input_audio_encoding": dialogflow_v2beta1.AudioEncoding.AUDIO_ENCODING_LINEAR_16,
                "input_audio_sample_rate_hertz": SAMPLE_RATE,
            },
        }
    )
    print(f"participant {participant}")

    for i in range(0, len(audios)):
      audios_array = audio_request_iterator(audios[i])
      for chunk in audios_array:
        if not chunk:
            break
        yield dialogflow_v2beta1.BidiStreamingAnalyzeContentRequest(
        input={
            "audio":chunk
            },
        )
        time.sleep(0.1)
    time.sleep(0.1)

def participant_bidi_streaming_analyze_content(participant, audios):
    """call bidi streaming analyze content API
    """
    bidi_responses = participant_client.bidi_streaming_analyze_content(
        requests=request_iterator(participant, audios)
    )

    for response in bidi_responses:
        bidi_streaming_analyze_content_response_handler(response)

def bidi_streaming_analyze_content_response_handler(response: dialogflow_v2beta1.BidiStreamingAnalyzeContentResponse):
    """Call Bidi Streaming Analyze Content
    """
    if  response.recognition_result:
         print(f"Recognition result: { response.recognition_result.transcript}", )

def audio_request_iterator(audio):
    """Iterate the request for bidi streaming analyze content
    """
    total_audio_length = len(audio)
    print(f"total audio length {total_audio_length}")
    array = []
    for i in range(0, total_audio_length, POINT_ONE_SECOND_IN_BYTES):
        chunk = audio[i : i + POINT_ONE_SECOND_IN_BYTES]
        array.append(chunk)
        if not chunk:
            break
    return array

def python_client_handler():
    """Downloads audios from the google cloud storage bucket and stream to
    the Bidi streaming AnalyzeContent site.
    """
    print("Start streaming")
    conversation = conversation_management.create_conversation(
        project_id=PROJECT_ID, conversation_profile_id=CONVERSATION_PROFILE_ID_STAGING
    )
    conversation_id = conversation.name.split("conversations/")[1].rstrip()
    human_agent = human_agent = participant_management.create_participant(
        project_id=PROJECT_ID, conversation_id=conversation_id, role="HUMAN_AGENT"
    )

    end_user =    end_user = participant_management.create_participant(
        project_id=PROJECT_ID, conversation_id=conversation_id, role="END_USER"
    )

    end_user_requests = []
    agent_request= []
    download_blob(BUCKET_NAME, FOLDER_PTAH_FOR_CUSTOMER_AUDIO, end_user_requests)
    download_blob(BUCKET_NAME, FOLDER_PTAH_FOR_AGENT_AUDIO, agent_request)

    participant_bidi_streaming_analyze_content( human_agent, agent_request)
    participant_bidi_streaming_analyze_content( end_user, end_user_requests)

    conversation_management.complete_conversation(PROJECT_ID, conversation_id)

Abilitare l'integrazione di SipRec per la telefonia

Puoi abilitare l'integrazione di SipRec per la telefonia per utilizzare BidiStreamingAnalyzeContent per l'elaborazione audio. Configura l'elaborazione audio con la console di Agent Assist o con una richiesta API diretta.

Console

Per configurare l'elaborazione audio in modo da utilizzare BidiStreamingAnalyzeContent:

  1. Vai alla console di Agent Assist e seleziona il tuo progetto.

    Console di Agent Assist

  2. Fai clic su Profili di conversazione > il nome di un profilo.

  3. Vai a Impostazioni di telefonia.

  4. Fai clic per attivare Utilizza l'API di streaming bidirezionale> Salva.

API

Puoi chiamare direttamente l'API per creare o aggiornare un profilo di conversazione configurando il flag in ConversationProfile.use_bidi_streaming.

Esempio di configurazione:

{
"name": "projects/PROJECT_ID/locations/global/conversationProfiles/CONVERSATION_PROFILE_ID",f
"displayName": "CONVERSATION_PROFILE_NAME",
"automatedAgentConfig": {
},
"humanAgentAssistantConfig": {
  "notificationConfig": {
    "topic": "projects/PROJECT_ID/topics/FEATURE_SUGGESTION_TOPIC_ID",
    "messageFormat": "JSON"
      },
  },
"useBidiStreaming": true,
"languageCode": "en-US"
}

Quote

Il numero di richieste BidiStreamingAnalyzeContent simultanee è limitato da una nuova quota ConcurrentBidiStreamingSessionsPerProjectPerRegion. Consulta la Google Cloud guida alle quote per informazioni sull'utilizzo delle quote e su come richiedere un aumento del limite di quota.

Per le quote, l'utilizzo delle richieste BidiStreamingAnalyzeContent agli endpoint Dialogflow globali e multiregionali degli Stati Uniti si trova nella regione us-central1.