שימוש ב-API לייבוא שיחות

כאן מוסבר איך אפשר לייבא קובצי אודיו ותמלילים עם המטא-נתונים שלהם באמצעות ה-API. אפשר לייבא קובץ יחיד באמצעות UploadConversation API, או לייבא את כל הקבצים מקטגוריה של Cloud Storage באמצעות IngestConversations API.

שתי פקודות הבקשה UploadConversation ו-IngestConversations תומכות בפונקציות הבאות:

פקודת בקשה	מספר קבצים	המרת דיבור לטקסט (STT)	צנזורה	הטמעה של מטא-נתונים	ניתוח אוטומטי
UploadConversation	1	✔	✔	✔	עם כללי ניתוח או עם העלאת אחוז ניתוח השיחות בפרויקט [הגדרות](/gemini-enterprise-cx/insights/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations	כל הקבצים בדלי	✔	✔	✔	רק עם כללי ניתוח

דרישות מוקדמות

1. מפעילים את ממשקי ה-API של Cloud Storage,‏ Speech-to-Text,‏ Sensitive Data Protection ו-Customer Experience Insights בפרויקט Google Cloud שבו אתם משתמשים ב-Dialogflow.
2. שמירת נתוני השיחות (קבצי אודיו וקבצי תמליל דו-ערוציים) בקטגוריה ב-Cloud Storage באמצעות סוג האחסון הרגיל.
   1. פועלים לפי ההוראות שבמדריך למתחילים בנושא Cloud Storage כדי ליצור קטגוריה.
   2. מגדירים את מיקום הקטגוריה למיקום הקרוב ביותר למיקום שלכם.
   3. כשמספקים נתוני שיחות, חשוב לשים לב לפרטים הבאים:
      • שם הקטגוריה
      • מזהה מיקום, פורמט: us-west1
      • נתיב האובייקט, פורמט: gs://<bucket>/<object>
3. נותנים לסוכני השירות של Speech-to-Text ושל Customer Experience Insights גישה לאובייקטים בקטגוריה של Cloud Storage. בדף הזה לפתרון בעיות מפורטת עזרה בנושא חשבונות שירות.

4. אם בוחרים לייבא מטא-נתונים של שיחות, צריך לוודא שקבצי המטא-נתונים נמצאים בקטגוריה משלהם וששמות קובצי המטא-נתונים זהים לשמות קובצי השיחות התואמים.

   לדוגמה, לשיחה עם ה-URI של Cloud Storage‏ gs://transcript-bucket-name/conversation.mp3, צריך להיות קובץ מטא-נתונים תואם כמו gs://metadata-bucket-name/conversation.json.

הערה: בניגוד ל-UploadConversation API, ‏ IngestConversations API לא תומך בייבוא תמלילים יחד עם אודיו או בקישור אודיו לתמלילים. אם יש לכם גם אודיו של שיחות וגם תמלילים, הקפידו לשמור אותם בדליים נפרדים.

נתוני שיחות

נתוני השיחה כוללים תמלילים של שיחות קוליות או צ'אט ואודיו.

תמלילים

תמלילי הצ'אט צריכים להיות בקבצים בפורמט JSON, כאשר כל קובץ מכיל נתונים של שיחה אחת. קבצי הטקסט בפורמט JSON כוללים את פורמט נתוני השיחות.

אפשר לספק תמלילי קול בפורמט נתוני השיחה או כתוצאת זיהוי הדיבור שמוחזרת מתמלול של Speech-to-Text API. התשובה זהה לזיהוי סינכרוני ואסינכרוני בכל הגרסאות של Speech-to-Text API.

אודיו

כדי לתמלל אודיו, Customer Experience Insights משתמשת בזיהוי אצווה של Cloud Speech-to-Text. ב-CX Insights, הגדרות התמלול של Speech-to-Text נקבעות באמצעות משאבי מזהה. אפשר ליצור כלי זיהוי בהתאמה אישית בבקשה, או שאם לא מספקים כלי זיהוי בהגדרות או בבקשה, CX Insights יוצר כלי זיהוי ccai-insights-recognizer שמוגדר כברירת מחדל בפרויקט.

הכלי לזיהוי ב-CX Insights מתמלל דיבור באנגלית באמצעות מודל הטלפוניה, ושפת ברירת המחדל היא en-US. רשימה מלאה של התמיכה בהמרת דיבור לטקסט לפי אזור, שפה, מודל ותכונת זיהוי מופיעה במסמכי התמיכה בשפות של Speech-to-Text.

הערה: כדי להשתמש ב-CX Insights, צריך להפעיל את התכונה 'הזזת מילים בזמן', שהיא סוג של תכונת זיהוי של דיבור לטקסט.

לפני שמייבאים אודיו בפעם הראשונה ל-CX Insights, צריך להחליט אם רוצים:

• שימוש בהגדרת תמלול מותאמת אישית של דיבור לטקסט.
• לנתח את השיחות (אפשרות) שהוסרו מהן פרטים מזהים.

אפשר להגדיר את הפעולות האלה כך שיפעלו כברירת מחדל בכל בקשת UploadConversation או IngestConversation, על ידי הגדרת השדות המתאימים במשאב Settings של הפרויקט. אפשר גם לשנות את הגדרות הדיבור והצנזורה לכל בקשה בנפרד. אם לא תציינו הגדרות דיבור, CX Insights ישתמש בהגדרות הדיבור שמוגדרות כברירת מחדל ולא יצנזר את התמלילים.

הערה: פעולות הטמעת הנתונים של אודיו ידלגו על כל קובץ JSON בקטגוריה של Cloud Storage שציינתם.

צנזורה

Sensitive Data Protection לא מצנזרת תמלילים אלא אם מספקים במפורש הגדרות צנזורה בהגדרות הפרויקט, ב-UploadConversationRequest או ב-IngestConversationsRequest. השירות Sensitive Data Protection תומך בתבניות בדיקה ובתבניות להסרת פרטי הזיהוי לצורך צנזור.

הערה: כדי לוודא שלא תייבאו פרטים אישיים מזהים ל-CX Insights, עליכם לנקות את הנתונים בעצמכם לפני הייבוא.

הגדרת הגדרות הפרויקט

ההרשאות שנדרשות למשימה הזו

כדי לבצע את המשימה הזו נדרשות ההרשאות הבאות:

• contactcenterinsights.settings.update

אפשר להגדיר צנזורה ודיבור לבקשות UploadConversation ו-IngestConversations על ידי הגדרת הפרמטרים המתאימים בהגדרות הפרויקט. אפשר גם להגדיר את ההגדרות האלה בנפרד לכל בקשה, וכך לבטל את הגדרות הפרויקט. הערך של analysis_percentage שמוגדר בכלל ניתוח מבטל את הערך של upload_conversation_analysis_percentage שמוגדר דרך הגדרות הפרויקט.

שומרים את תוכן הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

הערה: אם הגדרתם שדות אחרים, אתם יכולים להחליף את updateMask ב-redaction_config, ב-speech_config או ב-analysis_config upload_conversation_analysis_percentage כדי לשנות רק את השדות האלה.

מטא-נתונים

ייבוא מטא-נתונים בקובץ יחיד או ייבוא בכמות גדולה.

הוספת מטא-נתונים ישירות לבקשה

בייבוא של קובץ יחיד בלבד, אפשר לכלול את המטא-נתונים של האיכות ישירות בפקודת curl עבור UploadConversationsRequest.

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'
  

ייבוא מטא-נתונים מקבצים ב-Cloud Storage

צריך לספק קבצים של מטא-נתוני שיחות בפורמט JSON. לייבוא בכמות גדולה, צריך לספק קטגוריה שצוינה בשדה gcs_source.metadata_bucket_uri של IngestConversationsRequest. בייבוא יחיד, צריך לספק נתיב אובייקט בשדה data_source.metadata_uri של UploadConversationRequest.

הערה: השמות של קובצי המטא-נתונים שמופיעים בקטגוריה לייבוא בכמות גדולה צריכים להיות זהים לשמות של אובייקטי השיחה התואמים. לדוגמה, gs://conversations/conversation.mp3 יותאם ל-gs://metadata/conversation.json.

הכלי CX Insights מאכלס את המטא-נתונים של איכות השיחה שנמצאים בקובץ, אבל אפשר גם ליצור מטא-נתונים בהתאמה אישית.

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

אם תספקו מטא-נתונים מותאמים אישית בשדה custom_metadata_keys של IngestConversationsRequest, מערכת CX Insights תשמור את המטא-נתונים המותאמים אישית האלה בתוויות של השיחה. אפשר להוסיף עד 100 תוויות.

בדוגמה הבאה אפשר לראות קובץ מטא-נתונים תקין שמכיל את המשאב Conversation.quality_metadata, מזהה שיחה בהתאמה אישית ואת שעת תחילת השיחה:

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

ייבוא של קובץ אודיו יחיד

ההרשאות שנדרשות למשימה הזו

כדי לבצע את המשימה הזו נדרשות ההרשאות הבאות:

• contactcenterinsights.conversations.upload

‫UploadConversation API יוצר פעולה ארוכת טווח שמתמללת את השיחות שלכם, ויש אפשרות גם לצנזר אותן. קובץ אודיו יתומלל אם השיחה מכילה רק audio_uri בDataSource. אחרת, המערכת תקרא את הערך שצוין ב-transcript_uri ותשתמש בו.

תוכן בקשת JSON:

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

שומרים את תוכן הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations:upload"

ייבוא בכמות גדולה

ההרשאות שנדרשות למשימה הזו

כדי לבצע את המשימה הזו נדרשות ההרשאות הבאות:

• contactcenterinsights.conversations.create

הערה: שיחות שכבר נבלעו ב-CX Insights יידלגו בניסיונות הבאים של ייבוא בכמות גדולה. תוכן הקובץ לא נסרק לצורך השוואה של כפילויות.

הערה: ב-CX Insights אפשר לבצע רק פעולת ייבוא אחת בכמות גדולה.

REST

פרטים מלאים מופיעים בנקודת קצה ל-API‏ conversations:ingest.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שלכם ב-Google Cloud Platform.
• ‫GCS_BUCKET_URI: ה-URI של Cloud Storage שמפנה אל הקטגוריה שמכילה את תמלילי השיחות. יכולה להכיל תחילית. לדוגמה, gs://BUCKET_NAME או gs://BUCKET_NAME/PREFIX. אין תמיכה בתווים כלליים לחיפוש.
• ‫MEDIUM: הערך צריך להיות PHONE_CALL או CHAT בהתאם לסוג הנתונים. אם לא מציינים ערך, ערך ברירת המחדל הוא PHONE_CALL.
• ‫AGENT_ID: אופציונלי. מזהה הסוכן של כל הקטגוריה.

הערה: כל הדוגמאות מתייחסות למופע הגלובלי של Customer Experience Insights. הוראות לשימוש במופעים אזוריים מופיעות במאמר בנושא התאמה לאזור.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest

תוכן בקשת JSON:

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

דגימה של הפעולה

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

מכסות של המרת דיבור לטקסט (STT)

ב-Customer Experience Insights נעשה שימוש בשני ממשקי Speech-to-Text API שונים: BatchRecognize ו-GetOperation. הכלי Customer Experience Insights שולח BatchRecognizeבקשה להתחיל את התמלול של הדיבור לטקסט וGetOperationבקשה לעקוב אחרי התמלול כדי לראות אם הוא הסתיים. כדי להתחיל פעולות של BatchRecognize, נשלחת בקשה של BatchRecognize לשימוש במכסה לדקה לכל אזור. כדי לעקוב אחרי הפעולות, נשלחת בקשת GetOperation לשימוש במכסה לפי דקה ולפי אזור.

בכל קריאה של UploadConversation, הכלי Customer Experience Insights צורך BatchRecognize אחד, אבל יכול להיות שהוא יצרוך יותר בקשות של GetOperation, בהתאם למשך המשימה. בייבוא בכמות גדולה, הכלי Customer Experience Insights צורך 100 בקשות מכל סוג.