ערכת פיתוח של Customer Experience Insights

ערכת הכלים למפתחים של CX Insights היא API ברמה גבוהה שנועד להרחיב את לקוח Python של Google עבור CX Insights. מפתחים או אנשים שמנהלים קוד יכולים להשתמש בערכת הכלים למפתחים של CX Insights כדי להרחיב מגוון רחב של משימות.

תרחישים לדוגמה

דוגמאות לפעולות שאפשר לבצע:

  • הטמעה של שיחות בודדות עם מטא-נתונים.
  • העברה של הרבה שיחות בבת אחת עם מטא-נתונים.
  • תמלול של קובצי אודיו מונו באמצעות Speech-to-Text‏ (STT) גרסה 1.
  • יצירת רכיבי זיהוי באמצעות STT V2.
  • מגדירים את BigQuery Export.
  • שינוי ההגדרות הגלובליות של CX Insights.
  • המרת פורמט נתוני התמליל מ-Genesys Cloud ל-CX Insights.
  • המרת פורמט נתוני התמליל מ-AWS ל-CX Insights.

קדימה, מתחילים

כדי להתחיל להשתמש בערכת הפיתוח, צריך לפעול לפי השלבים הבאים להגדרת הסביבה ולאימות.

שלב 1: הגדרת סביבה וירטואלית

לפני שמשתמשים בערכת הפיתוח, צריך לבצע את השלבים הבאים כדי להגדיר את Google Cloud פרטי הכניסה ולהתקין את יחסי התלות הנדרשים.

  1. משתמשים בקוד הבא כדי לאמת את החשבון באמצעות Google Cloud CLI. 
    gcloud auth login
gcloud auth application-default login
  2. מגדירים את הפרויקט Google Cloud באמצעות הקוד הבא. מחליפים את project name במזהה הפרויקט בפועל. Google Cloud 
    gcloud config set project
  3. יוצרים ומפעילים סביבה וירטואלית של Python באמצעות הקוד הבא. חובה להשתמש בסביבה וירטואלית כדי לנהל את התלות של הפרויקט. 
    python3 -m venv venv
source ./venv/bin/activate
  4. מתקינים את יחסי התלות. בתיקיית הפרויקט, מחפשים קובץ requirements.txt שמכיל את התלויות של ערכת הפיתוח, ומתקינים אותן על ידי הפעלת הקוד הבא. 
    pip install -r requirements.txt

שלב 2: אימות החשבון

שיטות האימות בערכת הכלים למפתחים של Python משתנות בהתאם לסביבה.

Google Colaboratory

  • אם אתם משתמשים בערכת הכלים לפיתוח CX Insights במחברת Google Colaboratory, אתם יכולים לבצע אימות על ידי הוספת הקוד הבא לחלק העליון של המחברות שמנוהלות על ידי המשתמש: 

    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

כשמשתמשים בערכת הכלים למפתחים של CX Insights עם פונקציות Cloud Run, ערכת הכלים למפתחים מאחזרת באופן אוטומטי את פרטי הכניסה של סביבת ברירת המחדל שבהם משתמשים השירותים האלה.

  • מוסיפים את ערכת הפיתוח לקובץ requirements.txt: מוודאים שהיא מופיעה בקובץ requirements.txt של שירות Cloud Run functions.
  • תפקיד בניהול זהויות והרשאות גישה (IAM): מוודאים שלחשבון השירות של פונקציות Cloud Run מוקצה תפקיד ה-IAM המתאים ב-Dialogflow.

סביבת Python מקומית

בדומה לפונקציות של Cloud Run, ערכת כלי הפיתוח הזו מאחזרת את פרטי הכניסה המקומיים שלכם אם אתם משתמשים ב-CLI של gcloud.

  1. מתקינים את ה-CLI של gcloud. אם עוד לא עשיתם זאת, מתקינים את Google Cloud SDK. היא כוללת את ה-CLI של gcloud.
  2. מאתחלים את ה-CLI של gcloud באמצעות הקוד הבא. 
    gcloud init
  3. כדי להיכנס אל Google Cloud , צריך להזין את הקוד הבא. 
    gcloud auth login
  4. עליך לאמת חשבון פעיל באמצעות הקוד הבא. הפקודה הזו מאמתת את חשבון הישות הראשית Google Cloud שלכם ב-CLI של gcloud. לאחר מכן, ערכת הכלים למפתחים של CX Insights יכולה לאחזר את פרטי הכניסה מההגדרה שלכם. 
    gcloud auth list

תוכן ערכת הפיתוח

ערכת הכלים למפתחים של CX Insights מכילה את המשאבים הבאים.

תיקיית ליבה

תיקיית הליבה היא שם נרדף לסוגי משאבי הליבה שנמצאים ברוב הכיתות. הוא כולל את אבני הבניין ברמה הגבוהה של ערכת הפיתוח ופונקציות כלליות כמו אימות והגדרות גלובליות. השיעורים והשיטות האלה משמשים לבניית שיטות ברמה גבוהה יותר או כלים ואפליקציות בהתאמה אישית.

תיקייה משותפת

התיקייה common מכילה עטיפות שנבנו סביב השיטות שהוטמעו ב-Google Cloud SDK. המטרה היא להוסיף רמה חדשה של פשטות להטמעות קיימות. אפשר לבצע את הפעולות הבאות בתיקייה Common.

  • שינוי הגדרות גלובליות מ-CX Insights.
  • הטמעה של שיחות (בודדות ובתפזורת) עם מטא-נתונים.
  • יצירה או הצגה של רשימת בלובים בקטגוריה של Cloud Storage.
  • יצירת תמלילים מאודיו באמצעות 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.

הוספת תוכן ובקשות להוספת תכונות

כדי לשלוח תרומות או בקשות לתכונות:

  1. יוצרים הסתעפות של מאגר ב-GitHub.
  2. יוצרים ענף תכונות באמצעות הקוד הבא. 
    git checkout -b feature/AmazingFeature
  3. מבצעים Commit של השינויים באמצעות הקוד הבא. 
    git commit -m 'Add some AmazingFeature'
  4. מבצעים Push של השינויים אל ההסתעפות באמצעות הקוד הבא. 
    git push origin feature/AmazingFeature
  5. פותחים בקשת מיזוג ושולחים אותה מענף התכונות למאגר הראשי.

רישיון

הפצת ערכת הכלים למפתחים של CX Insights מתבצעת במסגרת רישיון Apache 2.0. פרטים נוספים זמינים בקובץ LICENSE במאגר הפרויקט.