API를 사용하여 대화 가져오기

API를 사용하여 메타데이터와 함께 오디오 및 스크립트 파일을 가져오는 방법을 알아봅니다. UploadConversation API를 사용하여 단일 파일을 가져오거나 IngestConversations API를 사용하여 Cloud Storage 버킷의 모든 파일을 일괄적으로 가져올 수 있습니다.

두 요청 명령어 UploadConversation 및 IngestConversations는 다음 함수를 지원합니다.

요청 명령어 파일 수 Speech-to-Text 수정 메타데이터 수집 자동 분석
UploadConversation 1 ✔ ✔ ✔ 프로젝트 [설정](/gemini-enterprise-cx/insights/reference/rest/v1alpha1/Settings#analysisconfig)의 분석 규칙 또는 대화 분석 비율 업로드
IngestConversations 버킷의 모든 파일 ✔ ✔ ✔ 분석 규칙만

기본 요건

  1. Dialogflow에 사용하는 Google Cloud 프로젝트에서 Cloud Storage, Speech-to-Text, Sensitive Data Protection, 고객 경험 인사이트 API를 사용 설정합니다.
  2. 표준 스토리지 클래스를 사용하여 Cloud Storage 버킷에 대화 데이터 (듀얼 채널 오디오 및 스크립트 파일)를 저장합니다.
    1. Cloud Storage 빠른 시작 안내에 따라 버킷을 만듭니다.
    2. 버킷 위치를 자신과 가장 가까운 위치로 설정합니다.
    3. 대화 데이터를 제공할 때 필요한 다음 정보를 기록해 둡니다.
      • 버킷 이름
      • 위치 ID, 형식: us-west1
      • 객체 경로, 형식: gs://<bucket>/<object>
  3. Speech-to-Text 및 고객 경험 인사이트 서비스 에이전트에게 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 버전에서 동기식 및 비동기식 인식에 동일합니다.

오디오

고객 경험 인사이트는 Cloud Speech-to-Text 일괄 인식 기능을 사용하여 오디오를 텍스트로 변환합니다. CX 인사이트는 인식기 리소스로 Speech-to-Text 스크립트 작성 설정을 구성합니다. 요청에서 커스텀 인식기를 만들거나 설정 또는 요청에서 인식기를 제공하지 않으면 CX 인사이트가 프로젝트에 기본 ccai-insights-recognizer를 만듭니다.

CX 인사이트 인식기는 전화 모델을 사용하여 영어 음성을 텍스트로 변환하며 기본 언어는 en-US입니다. 리전, 언어, 모델, 인식 기능별 Speech-to-Text 지원의 전체 목록은 Speech-to-Text 언어 지원 문서를 참고하세요.

CX 인사이트로 첫 번째 오디오를 가져오기 전에 다음을 수행할지 평가합니다.

  • 커스텀 Speech-to-Text 스크립트 작성 구성을 사용합니다.
  • 수정된 대화 (선택사항)를 분석합니다.

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

수정

프로젝트 설정, UploadConversationRequest 또는 IngestConversationsRequest에서 수정 구성을 명시적으로 제공하지 않는 한 Sensitive Data Protection은 스크립트를 수정하지 않습니다. Sensitive Data Protection은 수정을 위한 검사 템플릿과 익명화 템플릿을 모두 지원합니다.

프로젝트 설정 구성

수정 및 음성은 상응하는 프로젝트 설정 매개변수를 설정하여 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 인사이트는 파일에서 찾은 대화 품질 메타데이터를 채우지만 커스텀 메타데이터를 만들 수도 있습니다.

예를 들어 데이터 세트의 각 대화에 커스텀 대화 ID를 지정하려면 Cloud Storage 내의 대화 객체에 커스텀 메타데이터를 지정합니다. 키를 ccai_insights_conversation_id로 설정합니다. 값은 커스텀 대화 ID입니다. 메타데이터 파일 내에서 커스텀 대화 ID를 제공할 수도 있습니다.

IngestConversationsRequest의 custom_metadata_keys 필드에 커스텀 메타데이터를 제공하면 CX 인사이트는 해당 커스텀 메타데이터를 대화 라벨에 저장합니다. 최대 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 할당량

고객 경험 인사이트는 두 가지 Speech-to-Text API(BatchRecognize 및 GetOperation)를 사용합니다. 고객 경험 인사이트는 Speech-to-Text 스크립트 작성을 시작하기 위해 BatchRecognize 요청을 하고 스크립트 작성이 완료되었는지 모니터링하기 위해 GetOperation 요청을 합니다. BatchRecognize 작업을 시작하려면 분당, 리전별 할당량을 사용하기 위해 BatchRecognize 요청을 합니다. 작업을 모니터링하려면 분당, 리전별 할당량을 사용하기 위해 GetOperation 요청을 합니다.

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