Customer Experience Insights 開發套件

CX Insights 開發套件是高階 API，旨在擴充 CX Insights 的 Google Python 用戶端。開發人員或程式碼維護人員可以使用 CX Insights 開發套件，大規模執行各種工作。

用途

你可以執行的動作包括：

擷取含有中繼資料的單一對話。
大量匯入附有中繼資料的對話。
使用 Speech-to-Text (STT) V1 轉錄單聲道音訊檔案。
使用 STT V2 建立辨識器。
設定 BigQuery Export。
變更 CX Insights 全域設定。
將轉錄稿資料格式從 Genesys Cloud 轉換為 CX Insights。
將轉錄稿資料格式從 AWS 轉換為 CX Insights。

開始使用

如要開始使用 devkit，請按照下列步驟設定環境及進行驗證。

步驟 1：設定虛擬環境

使用開發套件前，請按照下列步驟設定 Google Cloud 憑證，並安裝必要的依附元件。

使用下列程式碼，透過 Google Cloud CLI 驗證帳戶。
```
gcloud auth login
gcloud auth application-default login
```
使用下列程式碼設定 Google Cloud 專案。將專案名稱替換為實際的專案 ID。 Google Cloud
```
gcloud config set project 
```
使用下列程式碼建立並啟用 Python 虛擬環境。您必須使用虛擬環境管理專案依附元件。
```
python3 -m venv venv
source ./venv/bin/activate
```
安裝依附元件。在專案目錄中，檢查是否有包含開發套件依附元件的 requirements.txt 檔案，然後執行下列程式碼來安裝這些依附元件。
```
pip install -r requirements.txt
```

步驟 2：驗證帳戶

Python 開發套件的驗證方法因環境而異。

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 函式

搭配 Cloud Run functions 使用 CX Insights 開發套件時，開發套件會自動擷取這些服務使用的預設環境憑證。

將開發套件新增至 requirements TXT 檔案：確認 Cloud Run 函式服務的 requirements.txt 檔案中列有該套件。
身分與存取權管理角色：確認 Cloud Run 函式服務帳戶已指派適當的 Dialogflow 身分與存取權管理角色。

本機 Python 環境

與 Cloud Run 函式類似，如果您使用 gcloud CLI，這個開發套件會擷取本機驗證憑證。

安裝 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 開發套件包含下列資源。

核心資料夾

核心資料夾等同於大多數類別中的核心資源類型。其中包含開發套件的高階建構區塊，以及驗證和全域設定等一般功能。這些類別和方法可用於建構高階方法或自訂工具和應用程式。

通用資料夾

common 資料夾包含以 Google Cloud SDK 中實作的方法為基礎建構的包裝函式。我們的目標是為現有實作項目新增一層簡化功能。您可以在「Common」資料夾中執行下列動作。

從 CX Insights 操控全域設定。
匯入附有中繼資料的對話 (單一和大量)。
在 Cloud Storage 值區中建立或列出 Blob。
使用 STT V1 和 V2 根據音訊建立轉錄稿。
使用 STT V1 轉錄單聲道音訊檔案。

工作流程資料夾

工作流程資料夾包含的類別和方法，可執行 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
```
使用下列程式碼提交變更。
```
git commit -m 'Add some AmazingFeature'
```
使用下列程式碼將變更推送至分支。
```
git push origin feature/AmazingFeature
```
開啟提取要求，並從功能分支版本提交至主要存放區。

授權

CX Insights 開發套件的發布版本採用 Apache 2.0 授權。詳情請參閱專案存放區中的 LICENSE 檔案。

Customer Experience Insights 開發套件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

用途