API zum Importieren von Unterhaltungen verwenden

Hier erfahren Sie, wie Sie Audio- und Transkriptdateien mit ihren Metadaten über die API importieren. Sie können eine einzelne Datei mit der UploadConversation API importieren oder alle Dateien aus einem Cloud Storage-Bucket im Bulk mit der IngestConversations API importieren.

Die beiden Anforderungsbefehle UploadConversation und IngestConversations unterstützen die folgenden Funktionen:

Anforderungsbefehl Anzahl der Dateien Speech-to-Text Entfernen Metadatenaufnahme Automatische Analyse
UploadConversation 1 ✔ ✔ ✔ Mit Analyseregeln oder dem Prozentsatz für die Analyse von Unterhaltungen beim Hochladen in den Projekteinstellungen [Einstellungen](/gemini-enterprise-cx/insights/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations Alle Dateien in einem Bucket ✔ ✔ ✔ Nur mit Analyseregeln

Vorbereitung

  1. Aktivieren Sie die Cloud Storage API, die Speech-to-Text API, die Sensitive Data Protection API und die Customer Experience Insights API für das Google Cloud Projekt, das Sie für Dialogflow verwenden.
  2. Speichern Sie Ihre Unterhaltungsdaten (Audio- und Transkriptdateien mit zwei Kanälen) in einem Cloud Storage-Bucket mit der Standardspeicherklasse.
    1. Folgen Sie der Cloud Storage-Kurzanleitung, um einen Bucket zu erstellen.
    2. Legen Sie den Bucket-Speicherort auf einen Standort fest, der Ihrem Standort am nächsten ist.
    3. Beachten Sie die folgenden Informationen, die Sie beim Bereitstellen von Unterhaltungsdaten benötigen:
      • Bucket-Name
      • Standort-ID, Format: us-west1
      • Objektpfad, Format: gs://<bucket>/<object>
  3. Gewähren Sie den Dienstkonten von Speech-to-Text und Customer Experience Insights Zugriff auf die Objekte in Ihrem Cloud Storage-Bucket. Auf dieser Seite zur Fehlerbehebung finden Sie weitere Informationen zu Dienstkonten.

  4. Wenn Sie Unterhaltungsmetadaten importieren möchten, müssen sich die Metadatendateien in einem eigenen Bucket befinden und die Namen der Metadatendateien müssen mit den Namen der entsprechenden Unterhaltungsdateien übereinstimmen.

    Eine Unterhaltung mit dem Cloud Storage-URI gs://transcript-bucket-name/conversation.mp3 muss beispielsweise eine entsprechende Metadatendatei wie gs://metadata-bucket-name/conversation.json haben.

Unterhaltungsdaten

Unterhaltungsdaten bestehen aus Sprach- oder Chattranskripten und Audio.

Transkripte

Chattranskripte müssen in JSON-formatierten Dateien bereitgestellt werden, wobei jede Datei Daten für eine einzelne Unterhaltung enthält. Ihre JSON-formatierten Textdateien enthalten das Datenformat für Unterhaltungen.

Sprachtranskripte können im Datenformat der Unterhaltungsdaten oder als zurückgegebenes Spracherkennungsergebnis einer Speech-to-Text API-Transkription bereitgestellt werden. Die Antwort ist für synchrone und asynchrone Erkennung in allen Speech-to-Text API-Versionen identisch.

Audio

Customer Experience Insights verwendet die Batcherkennung von Cloud Speech-to-Text, um Audio zu transkribieren. CX Insights konfiguriert die Speech-to-Text-Transkriptionseinstellungen mit Erkennungsressourcen. Sie können in der Anfrage eine benutzerdefinierte Erkennung erstellen. Wenn Sie keine Erkennung in den Einstellungen oder in der Anfrage angeben, erstellt CX Insights eine Standarderkennung ccai-insights-recognizer in Ihrem Projekt.

Die CX Insights-Erkennung transkribiert englische Sprache mit dem Telefonmodell. Die Standardsprache ist „en-US“. Eine vollständige Liste der Speech-to-Text-Unterstützung nach Region, Sprache, Modell und Erkennungsfunktion finden Sie in der Dokumentation zur Sprachunterstützung für Speech-to-Text language support docs.

Bevor Sie Audio zum ersten Mal in CX Insights importieren, sollten Sie sich überlegen, ob Sie Folgendes tun möchten:

  • Eine benutzerdefinierte Speech-to-Text-Transkriptionskonfiguration verwenden.
  • Die (optional) entfernten Unterhaltungen analysieren.

Sie können diese Aktionen so konfigurieren, dass sie standardmäßig in jeder UploadConversation oder IngestConversation Anfrage ausgeführt werden, indem Sie die entsprechenden Felder in der Ressource für die Projekt-Einstellungen festlegen. Die Einstellungen für Sprache und Entfernen können auch pro Anfrage überschrieben werden. Wenn Sie keine Spracheinstellungen angeben, verwendet CX Insights die Standardeinstellungen für die Sprache und entfernt die Transkripte nicht.

Entfernen

Sensitive Data Protection entfernt Transkripte nur, wenn Sie explizit Konfigurationen zum Entfernen in den Projekt-Einstellungen, in der UploadConversationRequest oder in der IngestConversationsRequest angeben. Sensitive Data Protection unterstützt sowohl Inspektionsvorlagen als auch De-Identifikationsvorlagen zum Entfernen.

Projekteinstellungen konfigurieren

Das Entfernen und die Sprache können für UploadConversation- und IngestConversations-Anfragen konfiguriert werden, indem Sie die entsprechenden Parameter für die Projekteinstellungen festlegen. Diese Konfigurationen können auch einzeln pro Anfrage festgelegt werden, wodurch die Projekteinstellungen überschrieben werden. Der analysis_percentage in einer Analyseregel überschreibt den upload_conversation_analysis_percentage, der über die Projekt-einstellungen konfiguriert wurde.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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"

Metadaten

Importieren Sie Metadaten in einer einzelnen Datei oder als Bulk-Import.

Metadaten direkt in die Anfrage einfügen

Nur für Importe mit einer einzelnen Datei können Ihre Qualitätsmetadaten direkt in den curl-Befehl für UploadConversationsRequest eingefügt werden.

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"}}}
          }'

Metadaten aus Cloud Storage-Dateien importieren

Stellen Sie Unterhaltungsmetadatendateien als JSON-formatierte Dateien bereit. Für Bulk-Importe geben Sie einen Bucket an, der im Feld gcs_source.metadata_bucket_uri der IngestConversationsRequest angegeben ist. Geben Sie für einzelne Importe einen Objektpfad im Feld data_source.metadata_uri der UploadConversationRequest an.

CX Insights füllt die in der Datei gefundenen Metadaten zur Unterhaltungsqualität aus. Sie können aber auch benutzerdefinierte Metadaten erstellen.

Wenn Sie beispielsweise eine benutzerdefinierte Unterhaltungs-ID für jede Unterhaltung in Ihrem Dataset angeben möchten, geben Sie benutzerdefinierte Metadaten für das Unterhaltungsobjekt in Cloud Storage an. Legen Sie den Schlüssel auf ccai_insights_conversation_id fest. Der Wert ist Ihre benutzerdefinierte Unterhaltungs-ID. Benutzerdefinierte Unterhaltungs-IDs können auch in der Metadatendatei angegeben werden.

Wenn Sie im Feld custom_metadata_keys einer IngestConversationsRequest benutzerdefinierte Metadaten angeben, speichert CX Insights diese benutzerdefinierten Metadaten in den Unterhaltungslabels. Es werden bis zu 100 Labels unterstützt.

Im folgenden Beispiel sehen Sie eine gültige Metadatendatei, die die Ressource Conversation.quality_metadata sowie eine benutzerdefinierte Unterhaltungs-ID und die Startzeit der Unterhaltung enthält:

{
  "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"
}

Einzelne Audiodatei importieren

Die UploadConversation API erstellt einen Vorgang mit langer Ausführungszeit, der Ihre Unterhaltungen transkribiert und optional entfernt. Eine Audiodatei wird transkribiert, wenn die Unterhaltung nur einen audio_uri in der DataSource enthält. Andernfalls wird der bereitgestellte transcript_uri gelesen und verwendet.

JSON-Text der Anfrage:

{ 
  "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
  }
}

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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"

Bulk-Import

REST

Ausführliche Informationen finden Sie unter dem conversations:ingest API-Endpunkt.

Ersetzen Sie folgende Werte in den Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Platform-Projekt-ID.
  • GCS_BUCKET_URI: Der Cloud Storage-URI, der auf den Bucket mit den Unterhaltungstranskripten verweist. Kann ein Präfix enthalten. Beispiel: gs://BUCKET_NAME oder gs://BUCKET_NAME/PREFIX. Platzhalter werden nicht unterstützt.
  • MEDIUM: Je nach Datentyp auf PHONE_CALL oder CHAT festlegen. Wenn nicht angegeben, ist der Standardwert PHONE_CALL.
  • AGENT_ID: Optional. Agent-ID für den gesamten Bucket.

HTTP-Methode und URL: 

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

JSON-Text der Anfrage: 

{
  "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"}
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:


{
  "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"
      }
    }
  }
}

Vorgang abfragen

Sowohl die UploadConversation- als auch die IngestConversation-Anfrage geben einen Vorgang mit langer Ausführungszeit zurück. Methoden mit langer Ausführungszeit sind asynchron und der Vorgang ist möglicherweise noch nicht abgeschlossen, wenn die Methode eine Antwort zurückgibt. Sie können den Vorgang abfragen, um seinen Status zu prüfen. Weitere Informationen und Codebeispiele finden Sie auf der Seite zu Vorgängen mit langer Ausführungszeit.

Speech-to-Text-Kontingente

Customer Experience Insights verwendet zwei verschiedene Speech-to-Text APIs: BatchRecognize und GetOperation. Customer Experience Insights sendet eine BatchRecognize-Anfrage, um die Speech-to-Text-Transkription zu starten, und eine GetOperation-Anfrage, um zu prüfen, ob die Transkription abgeschlossen ist. Zum Starten von BatchRecognize-Vorgängen wird eine BatchRecognize-Anfrage gesendet, um ein Kontingent pro Minute und Region zu verwenden. Zum Überwachen der Vorgänge wird eine GetOperation-Anfrage gesendet, um ein Kontingent pro Minute und Region zu verwenden.

Bei einem einzelnen UploadConversation-Aufruf verbraucht Customer Experience Insights eine BatchRecognize-Anfrage, aber je nach Dauer der Aufgabe möglicherweise mehr GetOperation-Anfragen. Bei einem Bulk-Import verbraucht Customer Experience Insights 100 Anfragen jedes Typs.