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과 같은 해당 메타데이터 파일이 있어야 합니다.

대화 데이터

대화 데이터는 음성 또는 채팅 스크립트와 오디오로 구성됩니다.

스크립트

채팅 스크립트는 각 파일마다 단일 대화의 데이터가 포함된 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 통계 인식기는 전화 통신 모델을 사용하여 영어 음성을 스크립트로 변환하며 기본 언어는 en-US입니다. 지역, 언어, 모델, 인식 기능별 Speech-to-Text 지원의 전체 목록은 Speech-to-Text 언어 지원 문서를 참고하세요.

CX 통계로 오디오를 처음 가져오기 전에 다음 작업을 수행할지 평가하세요.

  • 맞춤 Speech-to-Text 텍스트 변환 구성을 사용합니다.
  • 선택적으로 수정된 대화를 분석합니다.

프로젝트 설정 리소스에서 적절한 필드를 설정하여 각 UploadConversation 또는 IngestConversation 요청에서 기본적으로 실행되도록 이러한 작업을 구성할 수 있습니다. 음성 및 수정 설정은 요청별로 재정의할 수도 있습니다. 음성 설정을 지정하지 않으면 CX Insights에서 기본 음성 설정을 사용하며 스크립트가 수정되지 않습니다.

수정

Cloud Data Loss Prevention은 프로젝트 설정, UploadConversationRequest 또는 IngestConversationsRequest에서 수정 구성을 명시적으로 제공하지 않는 한 스크립트를 수정하지 않습니다. 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를 제공할 수도 있습니다.

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는 대화를 텍스트로 변환하고 선택적으로 수정하는 장기 실행 작업을 만듭니다. 대화에 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 메서드 및 URL: 

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는 BatchRecognize 및 GetOperation의 두 가지 Speech-to-Text API를 사용합니다. Customer Experience Insights는 BatchRecognize 요청을 통해 텍스트 변환을 시작하고 GetOperation 요청을 통해 텍스트 변환이 완료되었는지 모니터링합니다. BatchRecognize 작업을 시작하려면 분당 리전별 할당량을 사용하도록 BatchRecognize 요청이 이루어집니다. 작업을 모니터링하기 위해 분당 리전별 할당량을 사용하도록 GetOperation 요청이 이루어집니다.

단일 UploadConversation 호출의 경우 Customer Experience Insights에서 하나의 BatchRecognize를 사용하지만 작업의 지속 시간에 따라 더 많은 GetOperation 요청이 있을 수 있습니다. 일괄 가져오기의 경우 고객 경험 통계는 각 유형의 요청 100개를 사용합니다.