Utilizzare l'API per importare le conversazioni

Scopri come importare file audio e di trascrizione con i relativi metadati utilizzando l'API. Puoi importare un singolo file utilizzando l'API UploadConversation oppure importare collettivamente tutti i file da un bucket Cloud Storage utilizzando l'API IngestConversations.

I due comandi di richiesta UploadConversation e IngestConversations supportano le seguenti funzioni:

Comando di richiesta Numero di file Speech-to-Text Oscuramento Importazione dei metadati Analisi automatica
UploadConversation 1 ✔ ✔ ✔ Con regole di analisi o la percentuale di analisi delle conversazioni di caricamento nelle [impostazioni](/gemini-enterprise-cx/insights/reference/rest/v1alpha1/Settings#analysisconfig) del progetto
IngestConversations Tutti i file in un bucket ✔ ✔ ✔ Solo con regole di analisi

Prerequisiti

  1. Abilita le API Cloud Storage, Speech-to-Text, Sensitive Data Protection e Customer Experience Insights nel Google Cloud progetto che utilizzi per Dialogflow.
  2. Salva i dati delle conversazioni (file audio e di trascrizione a doppio canale) in un bucket Cloud Storage utilizzando la classe di archiviazione standard.
    1. Segui le ist0}ruzioni della guida di avvio rapido di Cloud Storage per creare un bucket.
    2. Imposta la località del bucket su una località più vicina alla tua.
    3. Prendi nota delle seguenti informazioni necessarie quando fornisci i dati delle conversazioni:
      • Nome bucket
      • ID località, formato: us-west1
      • Percorso oggetto, formato: gs://<bucket>/<object>
  3. Concedi agli agenti di servizio Speech-to-Text e Customer Experience Insights l'accesso agli oggetti nel bucket Cloud Storage. Per assistenza con gli account di servizio, consulta questa pagina per la risoluzione dei problemi.

  4. Se scegli di importare i metadati delle conversazioni, assicurati che i file di metadati si trovino nel proprio bucket e che i nomi dei file di metadati corrispondano ai nomi dei file di conversazione corrispondenti.

    Ad esempio, una conversazione con l'URI Cloud Storage gs://transcript-bucket-name/conversation.mp3 deve avere un file di metadati corrispondente, ad esempio gs://metadata-bucket-name/conversation.json.

Dati relativi alle conversazioni

I dati delle conversazioni sono costituiti da trascrizioni vocali o di chat e audio.

Trascrizioni

Le trascrizioni delle chat devono essere fornite in file in formato JSON, in cui ogni file contiene i dati di una singola conversazione. I file di testo in formato JSON includono il formato dei dati delle conversazioni.

Le trascrizioni vocali possono essere fornite nel formato dei dati delle conversazioni o come risultato del riconoscimento vocale restituito da una trascrizione dell'API Speech-to-Text. La risposta è identica per il riconoscimento sincrono e asincrono in tutte le versioni dell'API Speech-to-Text.

Audio

Customer Experience Insights utilizza il riconoscimento batch di Cloud Speech-to-Text per trascrivere l'audio. CX Insights configura le impostazioni di trascrizione di Speech-to-Text con le risorse Recognizer. Puoi creare un riconoscitore personalizzato nella richiesta oppure, se non fornisci un riconoscitore nelle Impostazioni o nella richiesta, CX Insights crea un ccai-insights-recognizer predefinito nel tuo progetto.

Il riconoscitore CX Insights trascrive il parlato in inglese utilizzando il modello di telefonia e la lingua predefinita è en-US. Per un elenco completo del supporto di Speech-to-Text per regione, lingua, modello e funzionalità di riconoscimento, consulta la documentazione sul supporto linguistico di Speech-to-Text language support docs.

Prima della prima importazione audio in CX Insights, valuta se vuoi:

  • Utilizzare una configurazione di trascrizione di Speech-to-Text personalizzata.
  • Analizzare le conversazioni (facoltativamente) oscurate.

Puoi configurare l'esecuzione predefinita di queste azioni in ogni richiesta UploadConversation o IngestConversation impostando i campi appropriati nella risorsa Settings del progetto. Le impostazioni di parlato e oscuramento possono anche essere sostituite per ogni richiesta. Se non specifichi alcuna impostazione di parlato, CX Insights utilizzerà le impostazioni di parlato predefinite e non oscurerà le trascrizioni.

Oscuramento

Sensitive Data Protection non oscura le trascrizioni a meno che tu non fornisca esplicitamente le configurazioni di oscuramento nelle impostazioni del progetto Settings, in UploadConversationRequest o in IngestConversationsRequest. Sensitive Data Protection supporta sia i modelli di ispezione sia i modelli di anonimizzazione per l'oscuramento.

Configurare le impostazioni del progetto

L'oscuramento e il parlato possono essere configurati per le richieste UploadConversation e IngestConversations impostando i parametri delle impostazioni progetto corrispondenti. Queste configurazioni possono essere impostate anche singolarmente per ogni richiesta, sostituendo le impostazioni progetto. La analysis_percentage configurata in una regola di analisi sostituisce la upload_conversation_analysis_percentage configurata tramite le impostazioni del progetto .

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

Metadati

Importa i metadati in un singolo file o come importazione collettiva.

Includere i metadati direttamente nella richiesta

Solo per le importazioni di un singolo file, i metadati di qualità possono essere inclusi direttamente nel comando curl per UploadConversationsRequest.

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'

Importare i metadati dai file di Cloud Storage

Fornisci i file di metadati delle conversazioni come file in formato JSON. Per le importazioni collettive, fornisci un bucket specificato nel campo gcs_source.metadata_bucket_uri di IngestConversationsRequest. Per le importazioni singole, fornisci un percorso oggetto nel campo data_source.metadata_uri di UploadConversationRequest.

CX Insights popola i metadati di qualità delle conversazioni trovati nel file, ma puoi anche creare metadati personalizzati.

Ad esempio, per specificare un ID conversazione personalizzato per ogni conversazione nel set di dati, specifica i metadati personalizzati nell'oggetto di conversazione all'interno di Cloud Storage. Imposta la chiave su ccai_insights_conversation_id. Il valore è l'ID conversazione personalizzato. Gli ID conversazione personalizzati possono essere forniti anche all'interno del file di metadati.

Se fornisci metadati personalizzati nel campo custom_metadata_keys di un IngestConversationsRequest, CX Insights li memorizza nelle etichette delle conversazioni. Supporta fino a 100 etichette.

Consulta l'esempio seguente di un file di metadati valido contenente la Conversation.quality_metadata risorsa, nonché un ID conversazione personalizzato e l'ora di inizio della conversazione:

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

Importare un singolo file audio

L'UploadConversation API crea un'operazione a lunga esecuzione che trascrive e, facoltativamente, oscura le conversazioni. Un file audio verrà trascritto se la conversazione contiene solo un audio_uri in DataSource. In caso contrario, verrà letto e utilizzato il transcript_uri fornito.

Corpo JSON della richiesta:

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations:upload"

Importazione collettiva

REST

Per informazioni dettagliate, consulta l' conversations:ingest endpoint API.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto del tuo progetto Google Cloud Platform.
  • GCS_BUCKET_URI: l'URI Cloud Storage che rimanda al bucket contenente le trascrizioni delle conversazioni. Può contenere un prefisso. Ad esempio gs://BUCKET_NAME o gs://BUCKET_NAME/PREFIX. I caratteri jolly non sono supportati.
  • MEDIUM: imposta su PHONE_CALL o CHAT a seconda del tipo di dati. Se non specificato, il valore predefinito è PHONE_CALL.
  • AGENT_ID: (facoltativo) ID agente per l'intero bucket.

Metodo HTTP e URL: 

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest

Corpo JSON della richiesta: 

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:


{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

Eseguire il polling dell'operazione

Le richieste UploadConversation e IngestConversation restituiscono un'operazione a lunga esecuzione. I metodi a lunga esecuzione sono asincroni e l'operazione potrebbe non essere ancora completata quando il metodo restituisce una risposta. Puoi eseguire il polling dell'operazione per verificarne lo stato. Per dettagli ed esempi di codice, consulta la pagina relativa alle operazioni a lunga esecuzione.

Quote di Speech-to-Text

Customer Experience Insights utilizza due diverse API Speech-to-Text: BatchRecognize e GetOperation. Customer Experience Insights effettua una richiesta BatchRecognize per avviare la trascrizione di Speech-to-Text e una richiesta GetOperation per monitorare se la trascrizione è terminata o meno. Per avviare le operazioni BatchRecognize, viene effettuata una richiesta BatchRecognize per utilizzare una quota al minuto per regione. Per monitorare le operazioni, viene effettuata una richiesta GetOperation per utilizzare una quota al minuto per regione.

Per una singola chiamata UploadConversation, Customer Experience Insights utilizza una richiesta BatchRecognize, ma possibilmente più richieste GetOperation, a seconda della durata dell'attività. Per un'importazione collettiva, Customer Experience Insights utilizza 100 richieste di ogni tipo.