使用 API 导入对话

了解如何使用 API 导入音频和转录文件及其元数据。您可以使用 UploadConversation API 导入单个文件，也可以使用 IngestConversations API 从 Cloud Storage 存储桶批量导入所有文件。

两个请求命令 UploadConversation 和 IngestConversations 支持以下功能：

请求命令 文件数 Speech-to-Text 隐去 元数据注入 自动分析
UploadConversation 1 ✔ ✔ ✔ 使用分析规则或项目 [设置](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)中的上传对话分析百分比
IngestConversations 存储桶中的所有文件 ✔ ✔ ✔ 仅使用分析规则

前提条件

  1. 在您用于 Dialogflow 的 Google Cloud 项目上启用Cloud Storage、Speech-to-Text、Cloud Data Loss Prevention 和 Customer Experience Insights API。
  2. 使用 标准存储类别 将对话数据（双声道音频和转录文件）保存在 Cloud Storage 存储桶 中。
    1. 按照 Cloud Storage 快速入门 中的说明创建存储桶。
    2. 将存储桶位置设置为离您最近的位置。
    3. 请注意，在提供对话数据时，您需要以下信息：
      • 存储分区名称
      • 位置 ID，格式：us-west1
      • 对象路径，格式：gs://<bucket>/<object>
  3. 向 Speech-to-Text 和 Customer Experience Insights 服务代理授予对 Cloud Storage 存储桶中对象的访问权限。如需有关服务账号的帮助，请参阅此问题排查页面。

  4. 如果您选择导入对话元数据，请确保元数据文件位于自己的存储桶中，并且元数据文件名与其对应的对话文件名相匹配。

    例如，Cloud Storage URI 为 gs://transcript-bucket-name/conversation.mp3 的对话必须具有相应的元数据文件，例如 gs://metadata-bucket-name/conversation.json。

对话数据

对话数据包括语音或聊天转录内容和音频。

转录内容

Chat 转录内容必须以 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 转录配置。
  • 分析（可选）隐去的对话。

您可以通过在项目 Settings 资源中设置适当的字段，将这些操作配置为在每个 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 字段中提供指定的存储桶。对于单次导入，请在 UploadConversationRequest 的 data_source.metadata_uri 字段中提供对象路径。

CX Insights 会填充文件中找到的对话质量元数据，但您也可以创建 自定义元数据。

例如，如需为数据集中的每个对话指定自定义对话 ID，请在 Cloud Storage 中的对话对象上指定自定义元数据。将键设置为 ccai_insights_conversation_id。该值是您的自定义对话 ID。您还可以在元数据文件中提供自定义对话 ID。

如果您在 custom_metadata_keys 字段的 IngestConversationsRequest 中提供任何自定义元数据，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 会创建一个长时间运行的操作，用于转录对话并选择性地隐去对话。如果对话在 DataSource 中仅包含 audio_uri，则系统会转录音频文件。否则，系统会读取并使用提供的 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：指向包含 对话转录内容的存储桶的 Cloud Storage URI。可能包含前缀。例如 gs://BUCKET_NAME 或 gs://BUCKET_NAME/PREFIX。不支持通配符。
  • MEDIUM：设置为 PHONE_CALL 或 CHAT，具体取决于 数据类型。如果未指定，则默认值为 PHONE_CALL。
  • AGENT_ID：可选。整个存储桶的代理 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。Customer Experience Insights 会发出 BatchRecognize 请求以启动 Speech-to-Text 转录，并发出 GetOperation 请求以监控转录是否完成。如需启动 BatchRecognize 操作，系统会发出 BatchRecognize 请求以使用每分钟每个区域的配额。如需监控操作，系统会发出 GetOperation 请求以使用每分钟每个区域的配额。

对于单个 UploadConversation 调用，Customer Experience Insights 会使用一个 BatchRecognize，但可能会使用更多 GetOperation 请求，具体取决于任务的持续时间。对于批量导入，Customer Experience Insights 会使用每种类型的 100 个请求。