Customer Experience Insights 開発キット

CX Insights devkit は、CX Insights 用の Google Python クライアントを拡張するように設計された高レベルの API です。デベロッパーやコードの保守担当者は、CX Insights デベロッパーキットを使用して、さまざまなタスクをスケーリングできます。

ユースケース

実行できる操作は次のとおりです。

メタデータを含む単一の会話を取り込みます。
メタデータを使用して、複数の会話を一括で取り込みます。
Speech-to-Text（STT）V1 を使用してモノラル音声ファイルを文字起こしします。
STT V2 を使用して認識ツールを作成します。
BigQuery Export を設定します。
CX Insights のグローバル設定を変更します。
文字起こしデータの形式を Genesys Cloud から CX Insights に変換します。
文字起こしデータの形式を AWS から CX Insights に変換します。

使ってみる

devkit を使用するには、次の手順に沿って環境設定と認証を行います。

ステップ 1: 仮想環境を設定する

devkit を使用する前に、次の手順に沿って 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
```
依存関係をインストールします。プロジェクトディレクトリで、devkit の依存関係を含む 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 devkit を使用すると、これらのサービスが使用するデフォルトの環境認証情報が devkit によって自動的に取得されます。

requirements TXT ファイルに devkit を追加する: Cloud Run functions サービスの requirements.txt ファイルに記載されていることを確認します。
Identity and Access Management ロール: Cloud Run functions サービスアカウントに適切な Dialogflow IAM ロールが割り当てられていることを確認します。

ローカルの Python 環境

Cloud Run functions と同様に、gcloud CLI を使用している場合、この devkit はローカル認証情報を取得します。

gcloud CLI をインストールします。まだインストールしていない場合は、Google Cloud SDK をインストールします。これには gcloud CLI が含まれます。
次のコードを使用して gcloud CLI を初期化します。
```
gcloud init
```
次のコードを使用して Google Cloud にログインします。
```
gcloud auth login
```
次のコードを使用して、アクティブなアカウントを確認します。このコマンドは、gcloud CLI でプリンシパルアカウントを認証します。 Google Cloud CX Insights デベロッパーキットは、設定から認証情報を取得できます。
```
gcloud auth list
```

デベロッパーキットの内容

CX Insights 開発キットには次のリソースが含まれています。

コアフォルダ

コアフォルダは、ほとんどのクラスで見られるコアリソースタイプと同義です。これには、devkit の高レベルのビルディングブロックと、認証やグローバル構成などの一般的な機能が含まれています。これらのクラスとメソッドは、高レベルのメソッドやカスタムツール、アプリケーションを構築するために使用されます。

共通フォルダ

common フォルダには、Google Cloud SDK で実装されたメソッドを基に構築されたラッパーが含まれています。ここで目指すのは、既存の実装に新たなレベルのシンプルさを加えることです。Common フォルダでは、次の操作を行うことができます。

CX Insights からグローバル構成を操作する。
メタデータを含む会話（単一および一括）を取り込みます。
Cloud Storage バケット内の BLOB を作成または一覧表示します。
STT V1 と V2 を使用して音声から文字起こしを作成します。
STT V1 でモノラル音声ファイルを文字起こしします。

Workflows フォルダ

workflows フォルダには、次のような CX Insights でサポートされていないアクションを実行するように設計されたクラスとメソッドが含まれています。

Genesys Cloud から CX Insights への文字起こしをフォーマットします。
AWS から Customer Experience Insights への文字起こしをフォーマットします。
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
```
次のコードを使用して変更を commit します。
```
git commit -m 'Add some AmazingFeature'
```
次のコードを使用して、変更をブランチに push します。
```
git push origin feature/AmazingFeature
```
pull リクエストを開き、機能ブランチからメインリポジトリに送信します。

ライセンス

CX Insights デベロッパーキットの配布は Apache 2.0 ライセンスに基づきます。詳細については、プロジェクトリポジトリの LICENSE ファイルをご覧ください。

Customer Experience Insights 開発キット コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。