Utilizzo delle API vocali per eseguire l'analisi vocale

Per motivi di compatibilità con le versioni precedenti, puoi utilizzare le API vocali di Amazon Chime SDK per avviare e gestire l'analisi vocale. Tuttavia, solo le API della pipeline Media Insights per l'analisi vocale offrono nuove funzionalità, quindi consigliamo vivamente di utilizzarle al loro posto.

Le sezioni seguenti spiegano le differenze tra le API della pipeline di informazioni vocali e multimediali.

Interruzione delle attività

Se utilizzi un Voice Connector per avviare le attività di analisi vocale e quindi utilizzi l'UpdateMediaInsightsPipelineStatusAPI per sospendere la pipeline, le attività continuano a essere eseguite. Per interrompere le attività, devi chiamare le API StopSpeakerSearchTaskand StopVoiceToneAnalysisTask.

Comprendere le differenze tra le notifiche

Quando utilizzi le API vocali per eseguire l'analisi vocale, le notifiche sono diverse da quelle generate dalle pipeline di Media Insights.

• Gli eventi predisposti per l'analisi vocale sono disponibili solo per le attività avviate utilizzando le API vocali.

• È necessario utilizzare i callId campi voiceConnectorIdtransactionId, o nelle notifiche per associare un'attività di analisi vocale a una chiamata. Se utilizzi le pipeline di Media Insights per eseguire l'analisi vocale, utilizzi i channelId campi mediaInsightsPipelineId and streamArn o per associare un'attività a una chiamata.

I seguenti argomenti spiegano come utilizzare le notifiche con le API vocali.

Eventi pronti per l'analisi vocale

Gli eventi predisposti per l'analisi vocale hanno il tipo di VoiceAnalyticsStatus dettaglio.

Utilizzi i connettori vocali Amazon Chime SDK per avviare attività di analisi. Quando ricevi un evento pronto per l'analisi vocale, puoi attivare un'attività di ricerca degli altoparlanti o di analisi del tono vocale per la chiamata, identificata dalle seguenti proprietà:

• voiceConnectorId

• transactionId

Nota

Questa notifica viene fornita solo quando disponi di una configurazione della pipeline di Media Insights con l'analisi vocale abilitata e associata a un Voice Connector. Questa notifica NON viene fornita quando i clienti chiamano l'CreateMediaInsightsPipelineAPI e avviano un'attività di ricerca degli altoparlanti o un'attività di analisi del tono vocale tramite Media Pipelines SDK.

Le intestazioni SIP restituite da un Voice Connector contengono il. transactionId Se non hai accesso alle intestazioni SIP, l'evento di AnalyticsReady notifica contiene anche il comando and. voiceConnectorId transactionId Ciò consente di ricevere le informazioni in modo programmatico e di chiamare le StartSpeakerSearchTaskAPI, or. StartVoiceToneAnalysisTask

Quando l'analisi vocale è pronta per l'elaborazione, Voice Connector invia un evento "detailStatus": "AnalyticsReady" alla destinazione della notifica come corpo JSON. Se utilizzi Amazon SNS o Amazon SQS, quel corpo viene visualizzato nel campo «Record» del payload Amazon SNS o Amazon SQS.

L'esempio seguente mostra un tipico body JSON.

{
    "detail-type": "VoiceAnalyticsStatus",
    "version": "0",
    "id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59",
    "source": "aws.chime",
    "account": "123456789012",
    "time": "2022-08-26T17:55:15.563441Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "detailStatus": "AnalyticsReady",
        "callDetails": {
            "isCaller": false,
            "transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
            "voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
        }
    }
}

Questa notifica consente di attivare richiami aggiuntivi all'applicazione e di gestire eventuali requisiti legali, come l'avviso e il consenso, prima di chiamare le API delle attività di analisi vocale.

Eventi di ricerca degli altoparlanti

Gli eventi di ricerca degli altoparlanti hanno il tipo di SpeakerSearchStatus dettaglio.

I connettori vocali di Amazon Chime SDK inviano i seguenti eventi di ricerca degli altoparlanti:

• L'identificazione corrisponde

• Generazione di incorporamento vocale

Gli eventi possono avere i seguenti stati:

• IdentificationSuccessful— Identificato con successo almeno un ID del profilo vocale corrispondente con un punteggio di affidabilità elevato nel dominio del profilo vocale specificato.

• IdentificationFailure— Impossibile eseguire l'identificazione. Cause: il chiamante non parla per almeno 10 secondi, qualità audio scadente.

• IdentificationNoMatchesFound— Impossibile trovare una corrispondenza ad alta confidenza nel dominio del profilo vocale specificato. Il chiamante potrebbe essere nuovo o la sua voce potrebbe essere cambiata.

• VoiceprintGenerationSuccessful— Il sistema ha generato un incorporamento vocale utilizzando 20 secondi di audio non silenzioso.

• VoiceprintGenerationFailure— Il sistema non è riuscito a generare un incorporamento vocale. Cause: il chiamante non parla per almeno 20 secondi, qualità audio scadente.

L'identificazione corrisponde

Dopo una determinata chiamata all'StartSpeakerSearchTaskAPItransactionId, il servizio Voice Connector restituisce una notifica di corrispondenza dell'identificazione dopo 10 secondi di conversazione non silenziosa. Il servizio restituisce le prime 10 corrispondenze, insieme a un ID del profilo vocale e a un punteggio di affidabilità compreso tra [0, 1]. Più alto è il punteggio di confidenza, più è probabile che l'oratore della chiamata corrisponda all'ID del profilo vocale. Se il modello di machine learning non trova alcuna corrispondenza, il detailStatus campo della notifica contieneIdentificationNoMatchesFound.

L'esempio seguente mostra la notifica di un abbinamento riuscito.

{    
    "version": "0",
    "id": "12345678-1234-1234-1234-111122223333",
    "detail-type": "SpeakerSearchStatus",
    "service-type": "VoiceAnalytics",
    "source": "aws.chime",
    "account": "111122223333",
    "time": "yyyy-mm-ddThh:mm:ssZ",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "taskId": "uuid",
        "detailStatus": "IdentificationSuccessful",
        "speakerSearchDetails" : {
            "results": [
                {
                    "voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
                    "confidenceScore": "0.94567856",
                },
                {
                    "voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
                    "confidenceScore": "0.82783350",
                },
                {
                    "voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
                    "confidenceScore": "0.77136436",
                }
            ]
        },
        "isCaller": false,
        "voiceConnectorId": "abcdef1ghij2klmno3pqr4",
        "transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436"
    }
} 

Generazione di incorporamento vocale

Dopo altri 10 secondi di conversazione non silenziosa, Voice Connector invia una notifica di generazione di incorporamento vocale ai destinatari della notifica. È possibile registrare nuovi incorporamenti vocali in un profilo vocale o aggiornare una stampa già presente in un profilo vocale.

L'esempio seguente mostra la notifica di un abbinamento riuscito, il che significa che puoi aggiornare il profilo vocale associato.

{
    "version": "0",
    "id": "12345678-1234-1234-1234-111122223333",
    "detail-type": "SpeakerSearchStatus",
    "service-type": "VoiceAnalytics",
    "source": "aws.chime",
    "account": "111122223333",
    "time": "yyyy-mm-ddThh:mm:ssZ",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "taskId": "guid",
        "detailStatus": "VoiceprintGenerationSuccess",
        "isCaller": false,
        "transactionId": "12345678-1234-1234",
        "voiceConnectorId": "abcdef1ghij2klmno3pqr"
    }
}

Eventi di analisi del tono vocale

Gli eventi di analisi del tono vocale hanno il tipo di VoiceToneAnalysisStatus dettaglio. Le analisi possono restituire questi stati:

• VoiceToneAnalysisSuccessful— Ha analizzato con successo le voci del chiamante e dell'agente in base alle probabilità di sentimento: positivo, negativo o neutro.

• VoiceToneAnalysisFailure— Impossibile eseguire l'analisi del tono. Ciò può accadere se il chiamante si blocca senza parlare per 10 secondi o se la qualità dell'audio diventa troppo scarsa.

• VoiceToneAnalysisCompleted— Ha analizzato con successo le voci degli utenti e degli agenti in base alle probabilità di sentimento per l'intera chiamata. Questo è l'evento finale, inviato al termine dell'analisi del tono vocale.

L'esempio seguente mostra un tipico evento di analisi del tono vocale.

{
  "detail-type": "VoiceToneAnalysisStatus",
  "service-type": "VoiceAnalytics",
  "source": "aws.chime",
  "account": "216539279014",
  "time": "2022-08-26T17:55:15.563441Z",
  "region": "us-east-1",
  "detail": {
    "taskId": "uuid",
    "detailStatus": "VoiceToneAnalysisSuccessful",
    "voiceToneAnalysisDetails": {
      "currentAverageVoiceTone": {
          "startTime": "2022-08-26T17:55:15.563Z",
          "endTime": "2022-08-26T17:55:45.720Z",
          "voiceToneLabel": "neutral",
          "voiceToneScore": {    
            "neutral": "0.83",    
            "positive": "0.13",    
            "negative": "0.04"
          }
      },
      "overallAverageVoiceTone": {
          "startTime": "2022-08-26T16:23:13.344Z",
          "endTime": "2022-08-26T17:55:45.720Z",
          "voiceToneLabel": "positive",
          "voiceToneScore": {    
            "neutral": "0.25",    
            "positive": "0.65",    
            "negative": "0.1"
          }
      }
    },
    "isCaller": true,
    "transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
    "voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
  },
  "version": "0",
  "id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}