שאלות נפוצות על Conversational Analytics API

בדף הזה מופיעות תשובות לשאלות נפוצות על Conversational Analytics API.

האם Conversational Analytics API יכול לשנות או למחוק את הנתונים שלי?

ממשק Conversational Analytics API תוכנן עם אמצעי הגנה כדי למנוע שינוי או מחיקה של הנתונים.

כך מתבצעת אבטחת נתונים במקורות נתונים שונים:

  • ‫BigQuery: ה-API חוסם הצהרות של שפת הגדרת נתונים (DDL) ושפת טיפול בנתונים (DML). באופן ספציפי, המערכת מבצעת הרצה של ה-SQL שנוצר ומתירה רק שאילתות מסוג SELECT.
  • ‫Looker: ה-API מתקשר עם Looker באמצעות שיטות כמו run_inline_query, שמוגבלות לפעולות קריאה כמו בחירות, מסננים והגבלות. השיטות האלה לא תומכות בפעולות DDL או DML, והן לא כוללות פעולות של מחיקה או השמטה.
  • ‫Data Studio (לקובצי CSV ו-Google Sheets): ב-Data Studio נעשה שימוש בפורמט מובנה כדי להגדיר ולאחזר נתונים לתרשימים ולדוחות. כל השאילתות שמופעלות באמצעות השיטה הזו הן לקריאה בלבד, ולא תומכות בשינויים בנתונים.
  • מסדי נתונים: המערכת מאפשרת רק שאילתות מסוג SELECT. כדי למנוע שינוי או מחיקה של נתונים, צריך לוודא שלחשבון השירות או למשתמש שמבצע אינטראקציה עם Conversational Analytics API יש הרשאות קריאה בלבד למסד הנתונים.

ה-API של Analytics בממשק שיחה מיועד לקריאה בלבד במקורות הנתונים האלה. מידע נוסף על האבטחה של Conversational Analytics API זמין בפוסט בבלוג שיחה בטוחה: פירוט האבטחה ב-Conversational Analytics של Looker.

איך מטפלים בשגיאות שקשורות לאימות ולהרשאות?

ריכזנו כאן כמה שגיאות נפוצות שקשורות לאימות ולהרשאות, שאתם עשויים להיתקל בהן במהלך השימוש ב-API של ניתוח נתונים בשיחה:

  1. שגיאה: PERMISSION_DENIED או 403 Write access to project ... was denied

    • הסיבה הסבירה: ההודעה הזו מצביעה בדרך כלל על בעיות בתפקידי IAM. Google Cloud למשתמש או לחשבון השירות שמנסים להשתמש ב-API חסרות ההרשאות הנדרשות בפרויקט Google Cloud .
    • פתרון בעיות:
      • בעל הפרויקט Google Cloud צריך לוודא שלמשתמש או לחשבון השירות מוקצים התפקידים הנכונים ב-IAM בפרויקט Google Cloud . יכול להיות שיהיה צורך בתפקידים כמו Project Editor לפעולות מסוימות, כמו הפעלת ה-API או בדיקת הפונקציות שלו.
      • אם נתקלתם בשגיאה 403 כמו Write access to project 'us-gcp-project-name' was denied כשעברתם בין אזורים, צריך לוודא שהגדרת ה-IAM של הפרויקט תקינה.

  2. שגיאה: 500 Internal Server Error כשמשתמש Looker עם תפקיד משתמש מנסה לשוחח עם סוכן נתונים.

למה מופיעות שגיאות 503 או 500 כשמזרים תגובות?

אם משתמשים בלקוח HTTP או REST בסיסי (כמו ספריית requests של Python) כדי לקרוא לנקודת הקצה של הסטרימינג :chat, יכול להיות שה-API יחזיר הודעת שגיאה כללית, כמו 503 Connection reset by peer או 500 Internal error.

השגיאות הכלליות האלה מתרחשות כי ה-API של הסטרימינג שולח כותרת HTTP 200 OK ברגע שהסטרימינג נפתח. אם סוכן הנתונים נתקל בשגיאה חמורה במהלך הסטרימינג (למשל, זמן קצוב לתפוגה לשאילתה שפועלת במשך זמן רב או דחייה פתאומית של הרשאה), הוא מפסיק את הסטרימינג וכולל את קוד השגיאה הספציפי בטריילרים של HTTP/2. לקוחות HTTP או REST רגילים לא יכולים לנתח את הכותרות האלה בסוף, ובמקום זאת מפרשים את הסיום הפתאומי כקריסת שקע.

כדי לטפל בשגיאות שמתרחשות במהלך סטרימינג, מומלץ מאוד להשתמש בספריות הלקוח (SDK) הרשמיות של Google Cloud , כמו Python SDK. ערכות ה-SDK האלה מבוססות על gRPC, הן מנתחות את הטריילרים של HTTP/2 ומחזירות את קוד השגיאה הספציפי, כמו DEADLINE_EXCEEDED או PERMISSION_DENIED, במקום שגיאה כללית ברשת.

מהן הדרישות של Looker לשימוש ב-Conversational Analytics API?

כדי להשתמש ב-Conversational Analytics API, אתם צריכים הרשאות מתאימות ב- Google Cloud IAM וב-Looker, בהתאם למקור הנתונים ולפעולות שאתם רוצים לבצע:

  1. Google Cloud תפקידי IAM:

    • צריך תפקידי IAM מספיקים בפרויקט Google Cloud כדי לבצע אינטראקציה עם geminidataanalytics.googleapis.com API. תפקידי IAM שהוגדרו בצורה שגויה מובילים לעיתים קרובות לשגיאות PERMISSION_DENIED.
    • התפקידים הספציפיים שנדרשים תלויים בפעולות, אבל יכול להיות שיהיה צורך בתפקידים כלליים כמו עורך פרויקט כדי לבצע פעולות מסוימות.

  2. הרשאות ותפקידים ב-Looker:

    • הרשאות ברמת המודל: כדי להשתמש ב-Conversational Analytics וב-Conversational Analytics API, צריך להקצות למשתמש ב-Looker תפקיד ב-Looker שכולל את ההרשאה gemini_in_looker למודלים שהוא מבצע איתם אינטראקציה.

מידע נוסף על ההרשאות והתפקידים שנדרשים לשימוש ב-Conversational Analytics API זמין במאמר הענקת הרשאות ותפקידים ב-IAM ל-Conversational Analytics API.

בנוסף, מופע Looker שלכם צריך לעמוד בדרישות ספציפיות:

כדי להשתמש ב-Conversational Analytics API עם Data Studio Pro, המינוי ל-Pro צריך להיות מחוץ לגבולות גזרה של VPC-SC.

מהן דרישות מסד הנתונים לשימוש ב-Conversational Analytics API?

כדי להשתמש ב-Conversational Analytics API עם מסדי נתונים כמו AlloyDB ל-PostgreSQL,‏ GoogleSQL ל-Spanner,‏ Cloud SQL ל-MySQL ו-Cloud SQL ל-PostgreSQL, צריך לוודא שהאימות וההפעלה של IAM מתבצעים בצורה תקינה:

  1. Google Cloud תפקידי IAM:

    • לחשבון השירות או למשתמש צריכים להיות תפקידי ה-IAM הנדרשים כדי להתחבר למסד הנתונים הספציפי ולשאול בו שאילתות. בדרך כלל מדובר בתפקידים עם הרשאת קריאה למסד הנתונים.

  2. הפעלת API:

    • מוודאים ש-Cloud AI Companion API מופעל בפרויקט Google Cloud .

מידע נוסף על הפעלת אימות IAM זמין במסמכי התיעוד של כל מסד נתונים:

איך עוברים מ-Data QnA API ל-Conversational Analytics API?

אם השתמשתם בגרסה ניסיונית ישנה יותר של Data QnA API ‏ (dataqna.googleapis.com), תוכלו לעיין במדריך להעברה כדי ללמוד איך לעבור לנקודת הקצה הרשמית החדשה של Conversational Analytics API ‏ (geminidataanalytics.googleapis.com).

מה ההבדל בין השם של סוכן נתונים לבין המזהה שלו?

המזהה של סוכן הנתונים, שמוגדר כערך של data_agent_id, הוא המזהה הייחודי של סוכן הנתונים. השם של סוכן הנתונים, data_agent.name, נגזר אוטומטית מ-data_agent_id כשם שמוגדר במלואו (FQN), בפורמט projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

כשיוצרים סוכן נתונים, המערכת מתעלמת מכל ערך שהזנתם בשדה data_agent.name. כשמבצעים פעולות get, update או delete, ה-data_agent.name המלא נחשב למזהה הייחודי של סוכן הנתונים.

כשמשתמשים ב-Conversational Analytics API כדי ליצור סוכני נתונים, התרחישים הבאים רלוונטיים:

  • אם לא מגדירים את data_agent_id, נוצר מזהה ייחודי באופן אוטומטי.
  • אם מגדירים את data_agent_id כ-TestID, למשל, כל ערך שהזנתם עבור data_agent.name ייכתב מחדש כ-projects/<project>/locations/<location>/dataAgents/TestID.
  • אם מגדירים את data_agent_id עם FQN, מוצגת השגיאה 'שם לא תקין'.

מהו הפורמט המקובל למזהה בפעולות Create Agent או Create Conversation?

לסוכני נתונים:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

‫{data_agent} הוא מזהה המשאב. האורך המקסימלי הוא 63 תווים, והפורמט צריך להיות זה שמתואר בכתובת https://google.aip.dev/122#resource-id-segments.

לדוגמה: projects/1234567890/locations/us-central1/dataAgents/my-agent

מומלץ לדלג על הגדרת השדה הזה במהלך יצירת הסוכן, כי הוא יוסק באופן אוטומטי ויוחלף ב-{parent}/dataAgents/{data_agent_id}.

לשיחות:

projects/{project}/locations/{location}/conversations/{conversation_id}

‫{conversation_id} הוא מזהה המשאב, והוא צריך לכלול עד 63 תווים ולהיות בפורמט שמתואר בכתובת https://google.aip.dev/122#resource-id-segments.

דוגמה: projects/1234567890/locations/us-central1/conversations/my-conversation

מומלץ לא להגדיר את השדה הזה במהלך יצירת השיחה, כי המודל של ניתוח נתוני השיחות יזהה אותו אוטומטית ואז יחליף אותו ב-{parent}/conversations/{conversation_id}.

איך משתמשים ב-Update Mask?

בתהליך העבודה של סוכן עדכון הנתונים, הפרמטר updateMask מקבל מחרוזת בפורמט FieldMask שמציינת אילו שדות dataAgent ישוכתבו במשאב dataAgent על ידי העדכון. הפרמטר updateMask הוא שדה חובה והוא עובר אימות באופן הבא:

  • אם updateMask ריק, תופעל שגיאת BadRequestException ולא יתעדכנו שדות.
  • אם כל השדות ב-updateMask הם שדות תקינים dataAgent, רק השדות האלה יעודכנו.
  • אם תספקו שילוב של שדות תקינים ולא תקינים, המערכת תתעלם מהשדות הלא תקינים ותעדכן רק את השדות התקינים.

איך משתמשים ב-getIAMPolicy וב-setIAMPolicy כדי להגדיר את מדיניות IAM לסוכן נתונים?

אתם יכולים להשתמש בשיטה getIamPolicy ובשיטה setIamPolicy כדי להקצות תפקידי IAM למשתמשים עבור סוכן ספציפי.

בדוגמאות הקוד הבאות אפשר לראות איך מאחזרים את מדיניות IAM של סוכן נתונים:

בדוגמאות הקוד הבאות אפשר לראות איך להקצות IAM לסוכן נתונים:

מהן יכולות הזיכרון של סוכן הנתונים של Conversational Analytics API?

  • בתוך סשן יחיד: Conversational Analytics API תומך בשיחות מרובות תפניות, כלומר הוא יכול להתייחס לחלקים קודמים בשיחה הנוכחית.
  • בסשנים מרובים: ה-API של ניתוח שיחות כולל תכונות לניהול היסטוריית שיחות, שמאפשרות למשתמשים לשוחח בצ'אט בסשנים מרובים. הוא תומך גם בסוכנים עם מצב (stateful) עם שיחות מרובות שלבים שמנוהלות על ידי Google.
  • זיכרון לטווח ארוך: סוכני נתונים של Conversational Analytics API לא תומכים ביכולות מפורשות של זיכרון לטווח ארוך.

האם סוכן נתונים של Conversational Analytics API ייתן לי את אותה תשובה בכל פעם שאשאל את אותה שאלה?

  • התשובות בשפה טבעית של סוכן הנתונים של Conversational Analytics API לא נקבעות מראש, ולכן התשובה בשפה טבעית שסוכן הנתונים מספק עשויה להשתנות גם אם השאלה זהה.
  • תשובות לשאילתות נתונים: עם זאת, כשמדובר בשאלה ספציפית שמטרתה לחפש נתונים, השאילתה הבסיסית שנוצרת (שאילתת SQL או Looker) צפויה להיות דטרמיניסטית. הנתונים שמאוחזרים צריכים להיות זהים, בהנחה שנתוני הבסיס לא השתנו.

איך אפשר לשפר את הדיוק של התשובות מסוכן נתונים של API לניתוח נתונים בשיחה?

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

  • בשכבה הסמנטית של Looker, אפשר לספק הקשר בהגדרות של LookML. מידע נוסף ודוגמאות זמינים בדף התיעוד הנחיית התנהגות הסוכן באמצעות הקשר שנוצר ב-Looker.
  • במקורות נתונים של BigQuery, אתם יכולים לספק הקשר שנוצר באמצעות שדות הקשר המובְנים – כמו תיאורים ברמת הטבלה והעמודה, מילים נרדפות, תגים ושאילתאות לדוגמה – וגם באמצעות הוראות מערכת. ההקשר הזה גם עוזר לשפר את הדיוק של התשובות, ויכול לאפשר לסוכנים לצטט מקורות בתשובות שלהם. מידע נוסף זמין במאמר בנושא הגדרת ההקשר של סוכן הנתונים למקורות נתונים של BigQuery.
  • במקורות נתונים של AlloyDB ל-PostgreSQL,‏ Cloud SQL ל-MySQL,‏ Cloud SQL ל-PostgreSQL ו-Spanner, אתם יכולים לספק הקשר על ידי הוספה של טבלה, עמודה, תיאורי סכימה ואילוצים כהנחיות לנתונים ולאופן הפרשנות של הנתונים.

  • כשיוצרים סוכן נתונים, אפשר לספק הוראות למערכת, שאילתות מאומתות והקשר מתקדם:

    • הוראות מערכת, שהן הנחיות שמוגדרות על ידי המשתמש ויכולות לעצב את ההתנהגות של סוכן נתונים. ההנחיות האלה כוללות לוגיקה ספציפית לעסק, פרמוט של התשובה או הצגת נתונים.
    • אתם יכולים לספק שאילתות מאומתות (שנקראות גם שאילתות מוזהבות, בהתאם למקור הנתונים), שהן דוגמאות לשאלות בשפה טבעית שמשויכות לשאילתות SQL או Looker הנכונות.
    • במקורות נתונים של AlloyDB,‏ Cloud SQL ל-MySQL,‏ Cloud SQL ל-PostgreSQL ו-Spanner, אפשר לספק הקשר מתקדם שיעזור לכם לשפר את ההבנה של הנתונים והדיוק של הסוכנים.

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

במאמר איך שואלים שאלות יעילות יש הנחיות לשאילת שאלות כדי לקבל תשובות יעילות ומדויקות יותר.

איך אפשר לבדוק קוד Python שנוצר על ידי סוכן ולטפל בו בצורה בטוחה?

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

כדי לבדוק ולטפל בקוד Python שנוצר על ידי סוכן בצורה בטוחה, צריך לפעול לפי ההנחיות הבאות:

  • לבדוק ידנית את הקוד שנוצר לפני שמריצים אותו. מחפשים דפוסים חשודים כמו בקשות רשת לא צפויות (לדוגמה, socket,‏ requests או urllib), פקודות ברמת המערכת (לדוגמה, os.system או subprocess) או משתנים ומחרוזות מילוליות שעברו הסתרה מורכבת.
  • לעולם אל תריצו קוד לא מאומת ישירות במחשב מקומי או בסביבת ייצור. משתמשים בארגז חול מאובטח ומבודד – כמו מחברת Colaboratory, קונטיינר Docker זמני או מכונה וירטואלית – שאין לו גישה לפרטי כניסה רגישים, לרשתות פנימיות או למערכות קבצים מקומיות.
  • אם אפשר, לפני שמריצים את הקוד, כדאי להריץ על הקוד כלי ניתוח סטטי או כלי לינט כדי לסמן פעולות שעלולות להיות לא בטוחות או דפוסים זדוניים מוכרים.

האם אפשר לשלב את Conversational Analytics API עם אפליקציות של צד שלישי?

שילוב של Conversational Analytics API עם אפליקציות של צד שלישי מאפשר למשתמשים ליצור אינטראקציה עם הנתונים שלהם ישירות בכלים שבהם הם משתמשים מדי יום.

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

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

מה העלות של Conversational Analytics API?

ה-Conversational Analytics API זמין לכלל המשתמשים (GA). מידע נוסף על תמחור מפורט במדריך התמחור.

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

אילו מקורות נתונים נתמכים ב-Conversational Analytics API?

‫Conversational Analytics API תומך במקורות הנתונים הבאים:

  • ‫BigQuery (כולל טבלאות או גרף)
  • מידע נוסף ב-Looker
  • Data Studio
  • ‫AlloyDB ל-PostgreSQL
  • ‫GoogleSQL ל-Spanner
  • ‫Cloud SQL ו-Cloud SQL ל-PostgreSQL

אפשר גם להתחבר למקורות כמו SAP ו-Salesforce דרך BigQuery, ולקבצי CSV ול-Google Sheets דרך Data Studio.

מהן המגבלות הידועות של Conversational Analytics API?

מידע נוסף על המגבלות הידועות של Conversational Analytics API זמין בדף התיעוד מגבלות ידועות של Conversational Analytics API.

אילו מכסות חשוב להכיר לגבי Google Cloud פרויקטים?

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

האם Conversational Analytics API תומך במיקום הנתונים?

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

האם Conversational Analytics API תומך בשפות אחרות חוץ מאנגלית?

השפה היחידה שנתמכת רשמית ב-Conversational Analytics API היא אנגלית. למרות שמודלי Gemini הבסיסיים תומכים בשפות רבות, וחלק מהמשתמשים דיווחו על הצלחה נקודתית עם שאילתות בשפות שאינן אנגלית, ממשק ה-API של ניתוח נתונים בשיחה לא תומך רשמית בשפות שאינן אנגלית.