客户体验分析洞见开发套件

CX Insights 开发套件是一种高级 API，旨在扩展 Google Python 客户端以用于 CX Insights。作为开发者或代码维护人员，您可以使用 CX Insights 开发工具包来大规模执行各种任务。

使用场景

您可以执行的操作包括：

提取包含元数据的单个对话。
批量提取包含元数据的多轮对话。
使用 Speech-to-Text (STT) V1 转写单声道音频文件。
使用 STT V2 创建识别器。
设置 BigQuery 导出。
更改 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 项目。将项目名称替换为您的实际 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 开发套件的身份验证方法因环境而异。

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

将 CX Insights 开发套件与 Cloud Run 函数搭配使用时，该开发套件会自动获取这些服务使用的默认环境凭据。

将 devkit 添加到 requirements TXT 文件：验证它是否列在 Cloud Run 函数服务的 requirements.txt 文件中。
Identity and Access Management 角色：验证 Cloud Run functions 服务账号是否已分配适当的 Dialogflow IAM 角色。

本地 Python 环境

与 Cloud Run 函数类似，如果您使用的是 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 Insights 开发套件包含以下资源。

核心文件夹

核心文件夹与大多数类中找到的核心资源类型同义。它具有开发套件的高级构建块和常规功能，例如身份验证和全局配置。这些类和方法用于构建更高级别的方法或自定义工具和应用。

公用文件夹

common 文件夹包含围绕 Google Cloud SDK 中实现的方法构建的封装容器。此处的想法是为现有实现添加新的简化级别。您可以对“通用”文件夹执行以下操作。

从 CX Insights 中操控全局配置。
提取包含元数据的对话（单个和批量）。
在 Cloud Storage 存储桶中创建或列出 Blob。
使用 STT V1 和 V2 根据音频创建转写内容。
使用 STT V1 转写单声道音频文件。

Workflows 文件夹

工作流文件夹包含旨在执行 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 上创建代码库 Fork。
使用以下代码创建功能分支。
```
git checkout -b feature/AmazingFeature
```
使用以下代码提交更改。
```
git commit -m 'Add some AmazingFeature'
```
使用以下代码将更改推送到相应分支。
```
git push origin feature/AmazingFeature
```
打开拉取请求，并将其从功能分支提交到主代码库。

许可

CX Insights 开发套件的分发受 Apache 2.0 许可约束。如需了解详情，请参阅项目代码库中的 LICENSE 文件。

客户体验分析洞见开发套件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。