使用 API 匯入對話

瞭解如何使用 API 匯入音訊和轉錄稿檔案及其相關中繼資料。您可以使用 UploadConversation API 匯入單一檔案，也可以使用 IngestConversations API 從 Cloud Storage bucket 批次匯入所有檔案。

這兩個要求指令 UploadConversation 和 IngestConversations 支援下列函式：

要求指令 檔案數 Speech-to-Text 遮蓋 中繼資料擷取 自動產生分析結果
UploadConversation 1 ✔ ✔ ✔ 透過分析規則或專案 [設定](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)中的上傳對話分析百分比
IngestConversations bucket 中的所有檔案 ✔ ✔ ✔ 僅限分析規則

必要條件

  1. 在用於 Dialogflow 的 Google Cloud 專案中，啟用 Cloud Storage、Speech-to-Text、Cloud Data Loss Prevention 和 Customer Experience Insights API。
  2. 使用標準儲存空間類別，將對話資料 (雙聲道音訊和轉錄稿檔案) 儲存到 Cloud Storage bucket。
    1. 按照 Cloud Storage 快速入門操作說明建立 bucket。
    2. 將「bucket location」(儲存空間位置) 設為離您最近的位置。
    3. 提供對話資料時，請注意下列資訊：
      • 值區名稱
      • 地點 ID，格式：us-west1
      • 物件路徑，格式為 gs://<bucket>/<object>
  3. 授予 Speech-to-Text 和 Customer Experience Insights 服務代理程式 Cloud Storage bucket 中物件的存取權。如需服務帳戶方面的協助，請參閱這篇疑難排解頁面。

  4. 如果選擇匯入對話中繼資料，請確保中繼資料檔案位於專屬 bucket 中，且中繼資料檔案名稱與對應的對話檔案名稱相符。

    舉例來說，如果對話的 Cloud Storage URI 為 gs://transcript-bucket-name/conversation.mp3，則必須有對應的中繼資料檔案，例如 gs://metadata-bucket-name/conversation.json。

對話資料

對話資料包括語音或即時通訊轉錄稿和音訊。

轉錄稿

請以 JSON 格式的檔案提供對話記錄，每個檔案包含單一對話的資料。JSON 格式的文字檔包含對話資料格式。

語音轉錄稿可以採用對話資料格式，也可以是 Speech-to-Text API 轉錄作業傳回的語音辨識結果。在所有 Speech-to-Text API 版本中，同步和非同步辨識作業的回應都相同。

音訊

Customer Experience Insights 會使用 Cloud Speech-to-Text 批次辨識功能轉錄音訊。CX Insights 會使用「辨識器」資源設定 Speech-to-Text 轉錄設定。您可以在要求中建立自訂辨識器，也可以在「設定」或要求中不提供辨識器，CX Insights 會在專案中建立預設 ccai-insights-recognizer。

CX Insights 辨識器會使用電話模型轉錄英文語音，預設語言為 en-US。如需依地區、語言、模型和辨識功能列出的 Speech-to-Text 支援完整清單，請參閱 Speech-to-Text 語言支援文件。

首次將音訊匯入 CX Insights 前，請評估是否要：

  • 使用自訂的 Speech-to-Text 轉錄設定。
  • 分析 (視需要) 經過編輯的對話。

如要在每個 UploadConversation 或 IngestConversation 要求中預設執行這些動作，請在專案的「設定」資源中設定適當的欄位。您也可以在每個要求中覆寫語音和遮蓋設定。如未指定任何語音設定，CX Insights 會使用預設語音設定，且不會遮蓋轉錄稿。

遮蓋

除非您在專案設定、UploadConversationRequest 或 IngestConversationsRequest 中明確提供遮蓋設定，否則 Cloud Data Loss Prevention 不會遮蓋轉錄稿。Cloud Data Loss Prevention 支援使用檢查範本和去識別化範本遮蓋資料。

配置專案設定

如要為 UploadConversation 和 IngestConversations 要求設定遮蓋和語音功能，請設定對應的專案設定參數。您也可以為每個要求個別設定這些設定，覆寫專案設定。分析規則中設定的 analysis_percentage 會覆寫透過專案設定設定的 upload_conversation_analysis_percentage。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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"

中繼資料

以單一檔案或大量匯入的形式匯入中繼資料。

直接在要求中加入中繼資料

如果只匯入單一檔案，品質中繼資料可直接納入 UploadConversationsRequest 的 curl 指令。

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

從 Cloud Storage 檔案匯入中繼資料

以 JSON 格式的檔案提供對話中繼資料檔案。如要大量匯入，請在 IngestConversationsRequest 的 gcs_source.metadata_bucket_uri 欄位中提供指定 bucket。如要匯入單一物件，請在 UploadConversationRequest 的 data_source.metadata_uri 欄位中提供物件路徑。

CX Insights 會填入檔案中的對話品質中繼資料，但您也可以建立自訂中繼資料。

舉例來說，如要為資料集中的每則對話指定自訂對話 ID，請在 Cloud Storage 內的對話物件中指定自訂中繼資料。將索引鍵設為 ccai_insights_conversation_id。這個值是自訂對話 ID。您也可以在 metadata 檔案中提供自訂對話 ID。

如果您在 IngestConversationsRequest 的 custom_metadata_keys 欄位中提供任何自訂中繼資料，CX Insights 會將該自訂中繼資料儲存在對話標籤中。最多可支援 100 個標籤。

請參閱以下有效中繼資料檔案的範例，其中包含 Conversation.quality_metadata 資源、自訂對話 ID 和對話開始時間：

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

匯入單一音訊檔案

UploadConversation API 會建立長時間執行作業，轉錄對話內容並視需要進行編輯。如果對話只包含 audio_uri，系統會轉錄音訊檔案。DataSource否則，系統會讀取並使用提供的 transcript_uri。

JSON 要求主體：

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

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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"

大量匯入

REST

如需完整資訊，請參閱 conversations:ingest API 端點。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud Platform 專案 ID。
  • GCS_BUCKET_URI：指向含有對話轉錄稿的 bucket 的 Cloud Storage URI。可能含有前置字元。例如 gs://BUCKET_NAME 或 gs://BUCKET_NAME/PREFIX。不支援萬用字元。
  • MEDIUM：根據資料類型設為 PHONE_CALL 或 CHAT。如未指定，預設值為 PHONE_CALL。
  • AGENT_ID：選用。整個 bucket 的代理 ID。

HTTP 方法和網址：

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

JSON 要求主體：

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

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：


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

輪詢作業

UploadConversation 和 IngestConversation 要求都會傳回長時間執行的作業。長時間執行的作業是非同步作業，方法傳回回應時，作業可能尚未完成。您可以輪詢作業來查看狀態。詳情和程式碼範例請參閱長時間執行的作業頁面。

Speech-to-Text 配額

Customer Experience Insights 使用兩種不同的 Speech-to-Text API：BatchRecognize 和 GetOperation。客戶體驗洞察會發出 BatchRecognize要求，開始進行語音轉文字轉錄，並發出 GetOperation 要求，監控轉錄作業是否完成。如要啟動 BatchRecognize 作業，請發出 BatchRecognize 要求，使用每分鐘每個區域的配額。如要監控作業，請發出 GetOperation 要求，使用每個區域每分鐘的配額。

單一 UploadConversation 呼叫會消耗一個 BatchRecognize，但視工作持續時間而定，可能需要更多 GetOperation 要求。大量匯入時，顧客體驗洞察會耗用每種要求 100 個。