API bidirezionale

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

A differenza delle API precedenti, la configurazione audio semplificata offre un supporto ottimizzato per le conversazioni tra persone e un limite di scadenza esteso di 30 minuti. 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 dei suggerimenti per un agente umano. Invia più dati audio per ottenere più trascrizioni e suggerimenti. Questo scambio continua finché non lo termini chiudendo parzialmente lo stream.

Guida allo streaming

Per utilizzare l'API BiDiStreamingAnalyzeContent in fase di esecuzione 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, esegue l'override della configurazione da ConversationProfile.stt_config.sample_rate_hertz).
    • (Facoltativo) BiDiStreamingAnalyzeContentRequest.voice_session_config.input_audio_encoding (se specificato, esegue l'override della configurazione da 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 alcuni BidiStreamingAnalyzeContentResponses dallo stream.
    • I risultati della trascrizione intermedi e finali sono disponibili con il seguente comando: BiDiStreamingAnalyzeContentResponse.recognition_result.
    • Puoi accedere ai suggerimenti per gli 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 invia la risposta contenente i risultati del 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 tua conversazione sta per raggiungere il limite massimo di 30 minuti.
  7. Per una qualità ottimale, quando avvii uno stream, invia i dati audio generati dopo l'ultimo speech_end_offset di BiDiStreamingAnalyzeContentResponse.recognition_result con is_final=true a BidiStreamingAnalyzeContent.

Utilizza l'API tramite la libreria client Python

Le librerie client ti aiutano ad accedere alle API di Google da un linguaggio di codice specifico. 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)

Abilita per l'integrazione SIPREC della telefonia

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

Console

Segui questi passaggi per configurare l'elaborazione audio in modo da utilizzare BidiStreamingAnalyzeContent.

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

    Console 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 Bidirectional Streaming > Salva.

API

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

Configurazione di esempio:

{
"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 in parallelo è 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 è nella regione us-central1.