API를 사용하여 대화 분석

대화는 해당 대화 객체가 생성된 후 고객 경험 통계에서 볼 수 있습니다. 이 방법 가이드에서는 REST API를 사용하여 대화를 분석하는 과정을 안내합니다. 원하는 경우 CX Insights 콘솔을 사용하여 이러한 작업을 수행할 수도 있습니다.

기본 요건

  1. Google Cloud 프로젝트에서 Cloud Storage 및 Insights API를 사용 설정합니다.
  2. 대화 데이터 가져오기

채팅 대화

  1. 대화의 채팅 스크립트를 Cloud Storage 버킷의 객체로 가져옵니다.

  2. gs://<bucket>/<object> 형식으로 객체 경로를 기록해 둡니다.

채팅 스크립트 파일은 CCAI 대화 데이터 형식과 일치하는 JSON 형식 파일로 제공되어야 합니다.

음성 대화

  1. Cloud Storage 버킷에서 모든 파일을 가져옵니다. 오디오 및 스크립트 파일은 Cloud Storage 버킷에 객체로 가져와야 합니다.

  2. gs://<bucket>/<object> 형식으로 두 객체 경로를 기록해 둡니다.

스크립트 파일은 Cloud Speech-to-Text API 스크립트의 반환된 결과여야 합니다. 특히 모든 Speech-to-Text API 버전에서 동기식 인식과 비동기식 인식에 동일한 오디오 인식에서 반환된 response와 일치해야 합니다. 다른 스크립트 형식은 지원되지 않으며 대화 분석 중에 오류가 발생합니다.

대화 분석하기

Conversation 객체가 CX Insights에서 생성되면 유용한 결과를 생성하기 위해 분석해야 합니다. 단일 대화는 여러 번 분석할 수 있으며, 각 별도의 분석은 새로운 Analysis 객체를 생성합니다.

분석은 대화 데이터에 대해 일련의 주석 작성자를 실행하고 응답에 결과를 반환합니다. 기본적으로 분석은 사용 가능한 모든 주석 작성기를 실행합니다. 원하는 경우 지정된 주석 작성자만 실행되도록 분석을 구성할 수 있습니다.

분석은 장기 실행 작업입니다. CreateAnalysis 메서드를 호출하면 장기 실행 프로세스를 나타내는 Operation 객체가 생성됩니다. 작업이 완료되면 Operation 객체에 결과가 포함됩니다. Operation 객체를 폴링하여 완료 여부를 확인할 수 있습니다.

새 분석 만들기

REST

자세한 내용은 conversations.analyses:create API 엔드포인트를 참조하세요.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • CONVERSATION_ID: 분석하려는 대화의 ID입니다. 이 값은 `createConversation` 응답에서 반환되었습니다.

HTTP 메서드 및 URL: 

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

CX Insights에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

CX Insights에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 


import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

CX Insights에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createAnalysis() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
createAnalysis();

(선택사항) 분석 구성

REST

자세한 내용은 conversations.analyses:create API 엔드포인트를 참조하세요. 실행할 주석 작성기를 annotatorSelector 객체에 포함하고 true로 설정합니다. 포함되지 않은 주석 작성자는 기본적으로 false로 설정됩니다. annotatorSelector 객체에 주석 작성자를 지정하지 않으면 모든 주석 작성자가 실행됩니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • PHRASE_MATCHER(s): 구문 매처 주석에 사용할 구문 매처의 정규화된 구문 매처 리소스 이름입니다. 비워 두면 활성 구문 일치 도구가 모두 실행됩니다.
  • ISSUE_MODEL(s): 문제 모델 주석에 사용할 문제 모델의 정규화된 리소스 이름입니다. run_issue_model_annotator가 true인 경우에만 작동합니다. 비워 두면 배포된 모든 문제 모델이 실행됩니다. 현재 배포된 모델은 1개로 제한됩니다.

HTTP 메서드 및 URL: 

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

JSON 요청 본문:

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

작업 폴링

분석을 만들면 장기 실행 작업이 반환됩니다. 장기 실행 메서드는 비동기적이며 메서드가 응답을 반환해도 작업이 완료되지 않았을 수 있습니다. 작업을 폴링하여 상태를 확인할 수 있습니다. 자세한 내용과 코드 샘플은 장기 실행 작업 페이지를 참고하세요.