שאלות נפוצות על 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 של ניתוח נתונים בממשק שיחה מיועד לקריאה בלבד במקורות הנתונים האלה. מידע נוסף על האבטחה של Conversational Analytics API זמין בפוסט בבלוג שיחה בטוחה: פירוט האבטחה ב-Conversational Analytics של Looker.

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

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

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

    • הסיבה הסבירה: ההודעה הזו מצביעה בדרך כלל על בעיות ב Google Cloud תפקידי IAM. למשתמש או לחשבון השירות שמנסים להשתמש ב-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 רגילים לא יכולים לנתח את הכותרות האלה בסוף, ובמקום זאת מפרשים את הסיום הפתאומי כקריסת שקע.

כדי לטפל בשגיאות שמתרחשות במהלך סטרימינג, מומלץ מאוד להשתמש ב Google Cloud ספריות הלקוח (SDK) הרשמיות, כמו Python SDK. ערכות ה-SDK האלה מבוססות על gRPC, הן מנתחות את ה-trailers של 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 Enablement:

    • מוודאים ש-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}.

איך משתמשים ב-updateMask?

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

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

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

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

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

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

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

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

האם סוכן נתונים של 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 (כולל טבלאות וגרפים עם BigQuery Graph)
  • מידע נוסף ב-Looker
  • Data Studio
  • ‫AlloyDB ל-PostgreSQL
  • ‫GoogleSQL ל-Spanner
  • ‫Cloud SQL ל-MySQL ו-Cloud SQL ל-PostgreSQL

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

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

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

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

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

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

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

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

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