고객 경험 인사이트 개발 키트

CX Insights devkit은 CX Insights용 Google Python 클라이언트를 확장하도록 설계된 고급 API입니다. 개발자 또는 코드를 유지관리하는 사용자는 CX 통계 개발 키트를 사용하여 다양한 작업을 확장할 수 있습니다.

사용 사례

수행할 수 있는 작업은 다음과 같습니다.

메타데이터가 포함된 단일 대화를 수집합니다.
메타데이터를 사용하여 여러 대화를 일괄적으로 수집합니다.
Speech-to-Text (STT) V1을 사용하여 모노 오디오 파일을 텍스트 변환합니다.
STT V2를 사용하여 인식기를 만듭니다.
BigQuery 내보내기를 설정합니다.
CX 인사이트 전체 설정을 변경합니다.
Genesys Cloud에서 CX Insights로 스크립트 데이터 형식을 변환합니다.
AWS에서 CX Insights로 스크립트 데이터 형식을 변환합니다.

시작하기

devkit을 시작하려면 다음 단계에 따라 환경을 설정하고 인증하세요.

1단계: 가상 환경 설정

개발 키트를 사용하기 전에 다음 단계에 따라 Google Cloud 사용자 인증 정보를 설정하고 필요한 종속 항목을 설치하세요.

다음 코드를 사용하여 Google Cloud CLI로 계정을 인증합니다.
```
gcloud auth login
gcloud auth application-default login
```
다음 코드를 사용하여 Google Cloud 프로젝트를 설정합니다. 프로젝트 이름을 실제 Google Cloud 프로젝트 ID로 바꿉니다.
```
gcloud config set project 
```
다음 코드를 사용하여 Python 가상 환경을 만들고 활성화합니다. 가상 환경을 사용하여 프로젝트 종속 항목을 관리해야 합니다.
```
python3 -m venv venv
source ./venv/bin/activate
```
종속 항목을 설치합니다. 프로젝트 디렉터리에서 개발 키트의 종속 항목이 포함된 requirements.txt 파일을 확인하고 다음 코드를 실행하여 설치합니다.
```
pip install -r requirements.txt
```

2단계: 계정 인증

Python devkit의 인증 방법은 환경에 따라 다릅니다.

Google Colaboratory

Google Colaboratory 노트북에서 CX Insights 개발 키트를 사용하는 경우 사용자 관리 노트북 상단에 다음 코드를 추가하여 인증할 수 있습니다.
```
project_id = ''
```
이렇게 하면 브라우저에서 Google Cloud 로 인증할 수 있는 대화형 프롬프트가 실행됩니다.
```
!gcloud auth application-default login --no-launch-browser
```
인증하면 활성 프로젝트가 project_id로 설정됩니다.
```
!gcloud auth application-default set-quota-project $project_id
```

Cloud Run Functions

Cloud Run Functions와 함께 CX Insights 개발 키트를 사용하면 개발 키트에서 이러한 서비스가 사용하는 기본 환경 사용자 인증 정보를 자동으로 선택합니다.

requirements TXT 파일에 devkit 추가: Cloud Run Functions 서비스의 requirements.txt 파일에 나열되어 있는지 확인합니다.
Identity and Access Management 역할: Cloud Run Functions 서비스 계정에 적절한 Dialogflow IAM 역할이 할당되어 있는지 확인합니다.

로컬 Python 환경

Cloud Run Functions와 마찬가지로 gcloud CLI를 사용하는 경우 이 개발 키트는 로컬 인증 사용자 인증 정보를 선택합니다.

gcloud CLI를 설치합니다. 아직 설치하지 않았다면 Google Cloud SDK를 설치합니다. 여기에는 gcloud CLI가 포함됩니다.
다음 코드를 사용하여 gcloud CLI를 초기화합니다.
```
gcloud init
```
다음 코드를 사용하여 Google Cloud 에 로그인합니다.
```
gcloud auth login
```
다음 코드를 사용하여 활성 계정을 확인합니다. 이 명령어는 주 구성원 Google Cloud 계정을 gcloud CLI로 인증합니다. 그러면 CX Insights 개발 키트에서 설정의 사용자 인증 정보를 가져올 수 있습니다.
```
gcloud auth list
```

개발 키트 콘텐츠

CX 통계 개발 키트에는 다음 리소스가 포함되어 있습니다.

핵심 폴더

핵심 폴더는 대부분의 클래스에서 발견되는 핵심 리소스 유형과 동의어입니다. 여기에는 개발 키트의 상위 수준 빌딩 블록과 인증, 전역 구성과 같은 일반적인 기능이 있습니다. 이러한 클래스와 메서드는 상위 수준 메서드 또는 맞춤 도구와 애플리케이션을 빌드하는 데 사용됩니다.

일반 폴더

common 폴더에는 Google Cloud SDK에 구현된 메서드를 기반으로 빌드된 래퍼가 포함되어 있습니다. 여기서 아이디어는 기존 구현에 새로운 수준의 단순성을 추가하는 것입니다. Common 폴더를 사용하여 다음 작업을 수행할 수 있습니다.

CX Insights에서 전역 구성을 조작합니다.
메타데이터를 사용하여 대화 (단일 및 일괄)를 수집합니다.
Cloud Storage 버킷에서 블롭을 만들거나 나열합니다.
STT V1 및 V2를 사용하여 오디오에서 스크립트를 만듭니다.
STT V1을 사용하여 모노 오디오 파일을 텍스트로 변환합니다.

워크플로 폴더

워크플로 폴더에는 다음과 같이 CX Insights에서 지원하지 않는 작업을 실행하도록 설계된 클래스와 메서드가 포함되어 있습니다.

Genesys Cloud의 스크립트를 CX Insights로 포맷합니다.
AWS의 스크립트를 고객 경험 인사이트로 변환합니다.
Gemini를 사용하여 스크립트에서 역할을 인식합니다.

오디오 대화에 주석 달기

다음 Python 스크립트는 오디오 파일을 텍스트로 변환하고, 화자 역할을 할당한 다음, 분석을 위해 CX Insights에 풍부한 대화 데이터를 전송합니다.

    def audio_with_role_recognition():
      # 1. Reset Insights Settings
      reset_insights_settings()
      # Verifies a clean state for CX Insights settings before starting the test.
      # This function is assumed to be defined elsewhere and handles resetting global configurations.

      # 2. Initialize Speech-to-Text V2 Client
      sp = speech.V2(
          project_id = _PROBER_PROJECT_ID
      )
      # Initializes a client for interacting with the Google Cloud Speech-to-Text API (V2).
      # _PROBER_PROJECT_ID: The Google Cloud Project ID where the STT recognizer resides.

      # 3. Create Transcription
      transcript = sp.create_transcription(
          audio_file_path = _MONO_SHORT_AUDIO_LOCATION,
          recognizer_path = 'projects/<project_id>/locations/<region>/recognizers/<recognizer_id>'
      )
      # Sends an audio file for transcription using a specific STT V2 recognizer.
      # audio_file_path: Local path to the mono audio file to be transcribed.
      # recognizer_path: Full resource path to the STT V2 recognizer to be used for transcription.
      #                  Example: 'projects/YOUR_PROJECT_NUMBER/locations/global/recognizers/YOUR_RECOGNIZER_ID'


      # Verifies that the returned 'transcript' object is of the expected type from the Speech-to-Text V2 API.

      # 4. Format Transcription
      ft = format.Speech()
      # Initializes a formatting utility for speech-related data.

      transcript = ft.v2_recognizer_to_dict(transcript)
      # Transforms the STT V2 `RecognizeResponse` object into a more manageable Python dictionary format,
      # which is often easier to work with for subsequent processing steps like role recognition.

      # 5. Initialize Google Cloud Storage Client
      gcs = storage.Gcs(
        project_name = _PROBER_PROJECT_ID,
        bucket_name = _TMP_PROBER_BUCKET
      )
      # Initializes a Google Cloud Storage client.
      # project_name: The Google Cloud Project ID.
      # bucket_name: The name of the Google Cloud Storage bucket where the processed transcript will be temporarily stored.

      # 6. Generate Unique File Name
      file_name = f'{uuid.uuid4()}.json'
      # Creates a unique file name for the JSON transcript using a UUID (Universally Unique Identifier).
      # This prevents naming conflicts when uploading multiple transcripts to the same Google Cloud Storage bucket.

      # 7. Perform Role Recognition
      role_recognizer = rr.RoleRecognizer()
      # Initializes the RoleRecognizer component, likely part of the Customer Experience Insights DevKit,
      # responsible for identifying speaker roles (e.g., agent, customer) within a conversation.

      roles = role_recognizer.predict_roles(conversation=transcript)
      # Predicts the roles of speakers in the transcribed conversation.
      # conversation: The transcribed conversation in a dictionary format.

      transcript = role_recognizer.combine(transcript, roles)
      # Integrates the recognized roles back into the original transcript data structure.
      # This step enriches the transcript with speaker role metadata.

      # 9. Upload Processed Transcript to Google Cloud Storage
      gcs.upload_blob(
        file_name = file_name,
        data = transcript
      )
      # Uploads the enriched transcript (as JSON data) to the specified Google Cloud Storage bucket with the generated unique file name.
      # This Google Cloud Storage path will be used as the source for Customer Experience Insights ingestion.

      # 10. Construct Google Cloud Storage Path
      gcs_path = f"gs://{_TMP_PROBER_BUCKET}/{file_name}"
      # Forms the full Google Cloud Storage URI for the uploaded transcript, which is required by the Customer Experience Insights Ingestion API.

      # 11. Initialize CX Insights Ingestion
      ingestion = insights.Ingestion(
          parent = _PARENT,
          transcript_path = gcs_path
      )
      # Initializes an Ingestion client for CX Insights.
      # parent: The parent resource path for CX Insights, typically in the format:
      #         'projects/YOUR_PROJECT_NUMBER/locations/YOUR_LOCATION'
      # transcript_path: The Google Cloud Storage URI where the conversation transcript is stored.

      # 12. Ingest Single Conversation
      operation = ingestion.single()
      # Initiates the ingestion of the single conversation into CX Insights.
      # This returns an operation object, which can be used to monitor the status of the ingestion.

기여 및 기능 요청

기여 또는 기능 요청을 하려면 다음 단계를 따르세요.

GitHub에서 저장소 포크를 만듭니다.
다음 코드를 사용하여 기능 브랜치를 만듭니다.
```
git checkout -b feature/AmazingFeature
```
다음 코드를 사용하여 변경사항을 커밋합니다.
```
git commit -m 'Add some AmazingFeature'
```
다음 코드를 사용하여 변경사항을 브랜치에 푸시합니다.
```
git push origin feature/AmazingFeature
```
pull 요청을 열고 기능 브랜치에서 기본 저장소로 제출합니다.

라이선스

CX Insights 개발 키트의 배포는 Apache 2.0 라이선스에 따라 이루어집니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참고하세요.

고객 경험 인사이트 개발 키트 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.