Devkit do Customer Experience Insights

O devkit do CX Insights é uma API de alto nível projetada para estender o cliente Python do Google para o CX Insights. Como desenvolvedor ou alguém que faz manutenção de código, você pode usar o devkit do CX Insights para escalonar uma ampla variedade de tarefas.

Casos de uso

Você pode realizar as seguintes ações:

Ingerir conversas únicas com metadados.
Ingerir muitas conversas em massa com metadados.
Transcreva arquivos de áudio mono usando a Speech-to-Text (STT) V1.
Crie reconhecedores usando a STT V2.
Configure o BigQuery Export.
Mudar as configurações globais do CX Insights.
Transformar o formato de dados de transcrição do Genesys Cloud para o CX Insights.
Transformar o formato de dados de transcrição da AWS para o CX Insights.

Primeiros passos

Para começar a usar o devkit, siga estas etapas de configuração do ambiente e autenticação.

Etapa 1: configurar um ambiente virtual

Antes de usar o devkit, siga estas etapas para configurar suas credenciais do Google Cloud e instalar as dependências necessárias.

Use o código a seguir para autenticar sua conta com a Google Cloud CLI.
```
gcloud auth login
gcloud auth application-default login
```
Defina seu projeto Google Cloud com o seguinte código. Substitua o nome do projeto pelo ID do projeto Google Cloud .
```
gcloud config set project 
```
Crie e ative um ambiente virtual Python com o seguinte código. Você precisa usar um ambiente virtual para gerenciar as dependências do projeto.
```
python3 -m venv venv
source ./venv/bin/activate
```
Instale as dependências. No diretório do projeto, verifique se há um arquivo requirements.txt com as dependências do devkit e instale-as executando o seguinte código.
```
pip install -r requirements.txt
```

Etapa 2: autenticação da conta

Os métodos de autenticação do devkit Python variam de acordo com o ambiente.

Google Colaboratory

Se você estiver usando o devkit do CX Insights em um notebook do Google Colaboratory, adicione o seguinte código à parte de cima dos notebooks gerenciados pelo usuário para fazer a autenticação:
```
project_id = ''
```
Isso inicia um comando interativo que permite a autenticação com Google Cloud em um navegador.
```
!gcloud auth application-default login --no-launch-browser
```

A autenticação define seu projeto ativo como project_id.

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

Cloud Run Functions

Ao usar o devkit do CX Insights com as funções do Cloud Run, ele coleta automaticamente as credenciais de ambiente padrão usadas por esses serviços.

Adicione o devkit ao arquivo TXT de requisitos: verifique se ele está listado no arquivo requirements.txt do serviço de funções do Cloud Run.
Papel do Identity and Access Management: verifique se a conta de serviço do Cloud Run Functions tem o papel apropriado do IAM do Dialogflow atribuído.

Ambiente local do Python

Assim como as funções do Cloud Run, esse devkit coleta suas credenciais de autenticação local se você estiver usando a CLI gcloud.

Instale a CLI gcloud. Instale o SDK Google Cloud, caso ainda não tenha feito isso. Ela inclui a CLI gcloud.
Inicialize a CLI gcloud com o seguinte código.
```
gcloud init
```
Faça login em Google Cloud com o código a seguir.
```
gcloud auth login
```
Verifique uma conta ativa com o seguinte código. Esse comando autentica sua conta principal Google Cloud com a CLI gcloud. Em seguida, o devkit do CX Insights pode buscar as credenciais da sua configuração.
```
gcloud auth list
```

Conteúdo do devkit

O devkit do CX Insights contém os seguintes recursos.

Pasta principal

A pasta "core" é sinônimo dos tipos de recursos principais encontrados na maioria das classes. Ele tem os blocos de construção de alto nível do devkit e funcionalidades gerais, como autenticação e configurações globais. Essas classes e métodos são usados para criar métodos de nível superior ou ferramentas e aplicativos personalizados.

Pasta comum

A pasta "common" contém wrappers criados com base nos métodos implementados no SDK Google Cloud. A ideia aqui é adicionar um novo nível de simplicidade às implementações atuais. É possível realizar as seguintes ações com a pasta "Common":

Manipular configurações globais do CX Insights.
Ingerir conversas (únicas e em massa) com metadados.
Criar ou listar blobs em um bucket do Cloud Storage.
Crie transcrições de áudios usando STT V1 e V2.
Transcrever arquivos de áudio mono com a STT V1.

Pasta "Workflows"

A pasta "workflows" contém classes e métodos projetados para realizar ações que o CX Insights não oferece suporte, como as seguintes:

Formatar transcrições do Genesys Cloud para o CX Insights.
Formatar transcrições da AWS para o Customer Experience Insights.
Reconhecer funções em uma transcrição usando o Gemini.

Anotar uma conversa de áudio

O script Python a seguir transcreve um arquivo de áudio, atribui papéis de falante e envia os dados enriquecidos da conversa para o CX Insights para análise.

    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.

Contribuições e solicitações de recursos

Para fazer contribuições ou pedidos de recursos, siga estas etapas:

Crie um fork do repositório no GitHub.
Crie sua ramificação de recurso com o seguinte código.
```
git checkout -b feature/AmazingFeature
```
Confirme as mudanças com o código a seguir.
```
git commit -m 'Add some AmazingFeature'
```
Envie as mudanças para a ramificação com o seguinte código.
```
git push origin feature/AmazingFeature
```
Abra e envie uma solicitação de envio da ramificação de recurso para o repositório principal.

Licença

A distribuição do devkit do CX Insights está sob a licença Apache 2.0. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.

Devkit do Customer Experience Insights Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.