Kit de développement Insights sur l'expérience client

Le kit de développement CX Insights est une API de haut niveau conçue pour étendre le client Python Google pour CX Insights. En tant que développeur ou responsable de la maintenance du code, vous pouvez utiliser le kit de développement CX Insights pour mettre à l'échelle un large éventail de tâches.

Cas d'utilisation

Voici quelques exemples d'actions que vous pouvez effectuer :

Ingérez des conversations individuelles avec des métadonnées.
Ingérez de nombreuses conversations de manière groupée avec des métadonnées.
Transcrivez des fichiers audio mono à l'aide de Speech-to-Text (STT) V1.
Créez des outils de reconnaissance à l'aide de STT V2.
Configurez l'exportation BigQuery.
Modifier les paramètres généraux de CX Insights
Transformer le format des données de transcription de Genesys Cloud en données CX Insights
Transformer le format des données de transcription d'AWS en données CX Insights

Commencer

Pour commencer à utiliser le devkit, suivez ces étapes pour configurer l'environnement et l'authentification.

Étape 1 : Configurer un environnement virtuel

Avant d'utiliser le kit de développement, suivez ces étapes pour configurer vos identifiants Google Cloud et installer les dépendances nécessaires.

Utilisez le code suivant pour authentifier votre compte avec la Google Cloud CLI.
```
gcloud auth login
gcloud auth application-default login
```
Définissez votre projet Google Cloud avec le code suivant. Remplacez le nom du projet par votre ID de projet Google Cloud .
```
gcloud config set project 
```
Créez et activez un environnement virtuel Python avec le code suivant. Vous devez utiliser un environnement virtuel pour gérer les dépendances de votre projet.
```
python3 -m venv venv
source ./venv/bin/activate
```
Installez vos dépendances. Dans le répertoire de votre projet, recherchez un fichier requirements.txt contenant les dépendances du kit de développement, puis installez-les en exécutant le code suivant.
```
pip install -r requirements.txt
```

Étape 2 : Authentification du compte

Les méthodes d'authentification pour le kit de développement Python varient en fonction de votre environnement.

Google Colaboratory

Si vous utilisez le kit de développement CX Insights dans un notebook Google Colaboratory, vous pouvez vous authentifier en ajoutant le code suivant en haut de vos notebooks gérés par l'utilisateur :
```
project_id = ''
```
Cela lance une invite interactive vous permettant de vous authentifier avec Google Cloud dans un navigateur.
```
!gcloud auth application-default login --no-launch-browser
```

L'authentification définit votre projet actif sur project_id.

!gcloud auth application-default set-quota-project $project_id

Cloud Run Functions

Lorsque vous utilisez le kit de développement CX Insights avec les fonctions Cloud Run, il récupère automatiquement les identifiants d'environnement par défaut utilisés par ces services.

Ajoutez le kit de développement au fichier TXT des exigences : vérifiez qu'il figure dans le fichier requirements.txt du service Cloud Run Functions.
Rôle Identity and Access Management : vérifiez que le rôle IAM Dialogflow approprié est attribué au compte de service Cloud Run Functions.

Environnement Python local

Comme pour les fonctions Cloud Run, ce kit de développement récupère vos identifiants d'authentification locaux si vous utilisez gcloud CLI.

Installez gcloud CLI. Si ce n'est pas déjà fait, installez Google Cloud SDK. Elle inclut la gcloud CLI.
Initialisez gcloud CLI avec le code suivant.
```
gcloud init
```
Connectez-vous à Google Cloud avec le code suivant.
```
gcloud auth login
```
Vérifiez un compte actif avec le code suivant. Cette commande authentifie votre compte principal Google Cloud avec gcloud CLI. Le kit de développement CX Insights peut ensuite récupérer les identifiants de votre configuration.
```
gcloud auth list
```

Contenu du kit de développement

Le kit de développement CX Insights contient les ressources suivantes.

Dossier principal

Le dossier "core" est synonyme des types de ressources de base que l'on trouve dans la plupart des classes. Il contient les blocs de construction de haut niveau du kit de développement et les fonctionnalités générales telles que l'authentification et les configurations globales. Ces classes et méthodes sont utilisées pour créer des méthodes de niveau supérieur ou des outils et applications personnalisés.

Dossier commun

Le dossier "common" contient des wrappers créés autour des méthodes implémentées dans Google Cloud SDK. L'idée est d'ajouter un nouveau niveau de simplicité aux implémentations existantes. Vous pouvez effectuer les actions suivantes avec le dossier "Common" (Commun).

manipuler les configurations globales à partir de CX Insights ;
Ingérez des conversations (individuelles et groupées) avec des métadonnées.
Créez ou listez des blobs dans un bucket Cloud Storage.
Créez des transcriptions à partir de contenus audio à l'aide de STT V1 et V2.
Transcrivez des fichiers audio mono avec STT V1.

Dossier "Workflows"

Le dossier "workflows" contient des classes et des méthodes conçues pour effectuer des actions que CX Insights ne prend pas en charge, comme les suivantes.

Mettez en forme les transcriptions de Genesys Cloud pour CX Insights.
Mettre en forme les transcriptions d'AWS pour les insights sur l'expérience client
Identifier les rôles dans une transcription à l'aide de Gemini

Annoter une conversation audio

Le script Python suivant transcrit un fichier audio, attribue des rôles aux locuteurs, puis envoie les données de conversation enrichies à CX Insights pour analyse.

    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.

Contributions et demandes de fonctionnalités

Pour envoyer des contributions ou des demandes de fonctionnalités, procédez comme suit :

Créez un fork du dépôt sur GitHub.
Créez votre branche de fonctionnalité avec le code suivant.
```
git checkout -b feature/AmazingFeature
```
Validez vos modifications avec le code suivant.
```
git commit -m 'Add some AmazingFeature'
```
Transférez les modifications vers la branche avec le code suivant.
```
git push origin feature/AmazingFeature
```
Ouvrez une demande d'extraction et envoyez-la depuis votre branche de fonctionnalité vers le dépôt principal.

Licence

Le kit de développement CX Insights est distribué sous licence Apache 2.0. Pour en savoir plus, consultez le fichier LICENSE dans le dépôt du projet.

Kit de développement Insights sur l'expérience client Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.