ליצור סוכני נתונים ולנהל צ'אט עם הנתונים

מפתחים יכולים להשתמש ב-Conversational Analytics API, שאפשר לגשת אליו דרך geminidataanalytics.googleapis.com או נקודות קצה אזוריות, כדי ליצור ממשק צ'אט שמבוסס על בינה מלאכותית (AI) או סוכן לאינטראקציה עם נתונים. ה-API משתמש בשפה טבעית כדי לענות על שאלות לגבי נתונים מובְנים ב-BigQuery, ב-Looker, ב-Data Studio ובמקורות נתונים של מסדי נתונים (AlloyDB,‏ GoogleSQL ל-Spanner,‏ Cloud SQL ל-MySQL ו-Cloud SQL ל-PostgreSQL בגרסת טרום-השקה (Preview) ב-v1beta). בנוסף לשיחה עם זיכרון, אתם יכולים להשתמש ב-method QueryData כדי להריץ שאילתות ללא זיכרון.

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

איך Gemini for Google Cloud ‎ משתמש בנתונים שלכם, ובאילו מקרים.

תחילת העבודה עם Conversational Analytics API

כדי להתחיל להשתמש ב-Conversational Analytics API, קראו את המאמרים הבאים כדי להבין את גישות השילוב הזמינות ואת מושגי הליבה:

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

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

לפני שמשתמשים ב-API או בדוגמאות, צריך לבצע את השלבים הבאים:

  • הפעלת Conversational Analytics API: דרישות מוקדמות להפעלת Conversational Analytics API.
  • בקרת גישה באמצעות IAM: איך משתמשים בניהול הזהויות והרשאות הגישה כדי לשתף ולנהל את הגישה לסוכנים לאינטראקציה עם נתונים.
  • אימות והתחברות למקור נתונים: הוראות לאימות ב-API ולהגדרת חיבורים למקורות הנתונים של BigQuery,‏ Lakehouse,‏ Looker,‏ Data Studio ומסדי נתונים (AlloyDB,‏ GoogleSQL ל-Spanner,‏ Cloud SQL ל-MySQL ו-Cloud SQL ל-PostgreSQL).
  • התחברות ל-BigQuery: הסבר על התפקידים הנדרשים ואיך מחברים סוכן לאינטראקציה עם נתונים לטבלאות ולתרשימים ב-BigQuery.
  • התחברות ל-Looker: איך מחברים סוכן לאינטראקציה עם נתונים ל-Looker Explores ומאמתים את המכונה של Looker.
  • מפתחות הצפנה בניהול הלקוח (CMEK): איך משתמשים במפתחות הצפנה משלכם ב-Cloud Key Management Service כדי להגן על סוכנים לאינטראקציה עם נתונים ועל שיחות.
  • אילוצים של מדיניות הארגון: איך משתמשים באילוצים מוגדרים מראש של מדיניות הארגון כדי לשלוט במשאבים ברמת הארגון, התיקייה או הפרויקט.

איך יוצרים סוכן לאינטראקציה עם נתונים ומשתמשים בו

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

שיטות מומלצות

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

מאמרי העזרה של ה-API וספריות הלקוח

פעולות עיקריות ב-API

ה-API מספק את נקודות הקצה העיקריות הבאות לניהול סוכנים לאינטראקציה עם נתונים ושיחות. נקודות הקצה של v1 בטבלה הבאה תומכות במקורות נתונים של BigQuery,‏ Looker ו-Data Studio. מכיוון שמקורות נתונים של מסדי נתונים נמצאים בגרסת טרום-השקה (Preview) ב-v1beta, צריך לציין את הנתיבים התואמים של /v1beta/ למקורות של מסדי נתונים.

כשיוצרים את הנתיבים האלה (או את שמות המשאבים התואמים ב-SDK), מחליפים את התווים הכלליים לחיפוש (*) במזהה הפרויקט, במזהה המיקום (למשל global או us) ובמזהה המשאב (למשל מזהה הנציג או מזהה השיחה), לפי הצורך.

פעולה שיטת HTTP נקודת קצה (endpoint) תיאור
יצירת סוכן POST /v1/projects/*/locations/*/dataAgents יוצר סוכן חדש לאינטראקציה עם נתונים.
יצירת סוכן באופן סינכרוני POST /v1/projects/*/locations/*/dataAgents:createSync יצירת סוכן לאינטראקציה עם נתונים חדש באופן סינכרוני.
קבלת סוכן GET /v1/projects/*/locations/*/dataAgents/* אחזור הפרטים של סוכן ספציפי לאינטראקציה עם נתונים.
קבלת מדיניות של ניהול זהויות והרשאות גישה (IAM) POST /v1/projects/*/locations/*/dataAgents/*:getIamPolicy מקבל את ההרשאות של ניהול הזהויות והרשאות הגישה (IAM) שמוקצות לכל משתמש לסוכן ספציפי לאינטראקציה עם נתונים. משתמשים עם תפקיד בעלים של סוכן נתונים יכולים לקרוא לנקודת הקצה הזו כדי לראות את מדיניות ניהול הזהויות והרשאות הגישה של סוכן הנתונים, לפני שהם משתמשים בנקודת הקצה setIAMpolicy כדי לשתף סוכן נתונים עם משתמשים אחרים.
הגדרת מדיניות של ניהול זהויות והרשאות גישה (IAM) POST /v1/projects/*/locations/*/dataAgents/*:setIamPolicy הגדרת המדיניות של ניהול הזהויות והרשאות הגישה (IAM) לסוכן ספציפי לאינטראקציה עם נתונים. משתמשים עם תפקיד Data Agent Owner צריכים לקרוא לנקודת הקצה הזו כדי לשתף סוכן לאינטראקציה עם נתונים עם משתמשים אחרים, וכך לעדכן את ההרשאות של המשתמשים האלה בניהול זהויות והרשאות גישה (IAM).
עדכון סוכן PATCH /v1/projects/*/locations/*/dataAgents/* שינוי של סוכן קיים לאינטראקציה עם נתונים.
עדכון סוכן באופן סינכרוני PATCH /v1/projects/*/locations/*/dataAgents/*:updateSync שינוי של סוכן קיים לאינטראקציה עם נתונים באופן סינכרוני.
הצגת רשימת הסוכנים GET /v1/projects/*/locations/*/dataAgents הצגת רשימה של סוכנים לאינטראקציה עם נתונים שזמינים בפרויקט.
הצגת רשימה של הסוכנים הנגישים GET /v1/projects/*/locations/*/dataAgents:listaccessible הצגת רשימה של סוכנים לאינטראקציה עם נתונים נגישים בפרויקט. סוכן לאינטראקציה עם נתונים נחשב נגיש אם למשתמש שמפעיל את ה-API הזה יש את ההרשאה get בסוכן. אתם יכולים להשתמש בשדה creator_filter כדי לקבוע אילו נציגים השיטה הזו תחזיר:
  • ‫NONE (ברירת מחדל): מחזירה את כל הסוכנים לאינטראקציה עם נתונים שלמשתמש יש גישה אליהם, בלי קשר למי שיצר אותם.
  • CREATOR_ONLY: החזרת רק הסוכנים לאינטראקציה עם נתונים שהמשתמש יכול לגשת אליהם ושהוא יצר.
  • NOT_CREATOR_ONLY: החזרת רק הסוכנים לאינטראקציה עם נתונים שנגישים למשתמש ונוצרו על ידי אחרים.
מחיקת סוכן DELETE /v1/projects/*/locations/*/dataAgents/* הסרת סוכן לאינטראקציה עם נתונים.
מחיקת נציג באופן סינכרוני DELETE /v1/projects/*/locations/*/dataAgents/*:deleteSync הסרה של סוכן לאינטראקציה עם נתונים באופן סינכרוני.
יצירת שיחה POST /v1/projects/*/locations/*/conversations מתחילה שיחה חדשה ומתמשכת.
איך משוחחים בצ'אט באמצעות הפניה לשיחה POST /v1/projects/*/locations/*:chat המשך של שיחה עם מצב על ידי שליחת הודעת צ'אט שמפנה לשיחה קיימת ולהקשר של הנציג שמשויך אליה. בשיחות עם כמה סבבים, Google Cloud שומר ומנהל את היסטוריית השיחות.
צ'אט באמצעות הפניה לסוכן לאינטראקציה עם נתונים POST /v1/projects/*/locations/*:chat שליחת הודעת צ'אט בלי שמירת מצב שמפנה לסוכן לאינטראקציה עם נתונים שמור לצורך הקשר. בשיחות עם כמה פניות, האפליקציה צריכה לנהל את היסטוריית השיחות ולספק אותה בכל בקשה.
שיחה באמצעות הקשר מוטבע POST /v1/projects/*/locations/*:chat שליחת הודעת צ'אט בלי שמירת מצב (stateless) על ידי מתן כל ההקשר ישירות בבקשה, בלי להשתמש בסוכן לאינטראקציה עם נתונים שמור. בשיחות עם כמה פניות, האפליקציה צריכה לנהל את היסטוריית השיחות ולספק אותה בכל בקשה.
איך מקבלים שיחה GET /v1/projects/*/locations/*/conversations/* אחזור הפרטים של שיחה ספציפית.
הצגת רשימת השיחות GET /v1/projects/*/locations/*/conversations הצגת רשימה של השיחות בפרויקט ספציפי.
הצגת רשימת ההודעות בשיחה GET /v1/projects/*/locations/*/conversations/*/messages מציג את ההודעות בשיחה מסוימת.
למחוק שיחה DELETE /v1/projects/*/locations/*/conversations/* מוחקת שיחה ספציפית. כדי להפעיל את נקודת הקצה הזו, נדרש תפקיד אדמין של נושא בניהול זהויות והרשאות גישה (IAM) או לפחות הרשאת cloudaicompanion.topics.delete בניהול זהויות והרשאות גישה (IAM).
נתוני שאילתות POST /v1beta/projects/*/locations/*/conversations:queryData מריץ שאילתות על נתונים ממסדי הנתונים AlloyDB,‏ GoogleSQL ל-Spanner,‏ Cloud SQL ל-MySQL ו-Cloud SQL ל-PostgreSQL באמצעות שפה טבעית.
קבלת כרטיס סוכן (A2A) GET /v1/a2a/projects/*/locations/*/agents/*/v1/card אחזור היכולות, המיומנויות והתוספים הנתמכים של סוכן נתונים מובנה או מותאם אישית באמצעות פרוטוקול A2A.
שליחת הודעה (A2A) POST /v1/a2a/projects/*/locations/*/agents/*/v1/message:send שליחת הודעה לסוכן לאינטראקציה עם נתונים באמצעות פרוטוקול A2A.
שליחת הודעת סטרימינג (A2A) POST /v1/a2a/projects/*/locations/*/agents/*/v1/message:stream שליחת הודעה בסטרימינג לסוכן לאינטראקציה עם נתונים באמצעות פרוטוקול A2A, והחזרת התקדמות החשיבה בזמן אמת ופריטי מידע מובְנים (כמו שאילתות SQL ותרשימים).

תמיכה ומשוב

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

  • כדי לקבל תמיכה ב-Conversational Analytics API עם BigQuery, ברשימה Select a product בוחרים באפשרות BigQuery, ובשדה Feature בוחרים באפשרות AI and למידת מכונה::Conversational Analytics API in BigQuery.
  • כדי לקבל תמיכה ב-Conversational Analytics API עם Looker, ברשימה Select a product בוחרים באפשרות Looker (original), ובשדה Feature בוחרים באפשרות Gemini ב-Looker::Conversational Analytics API.

אם יש לכם משוב כללי או שאלות לגבי Conversational Analytics API, שלחו אימייל לכתובת conversational-analytics-api-feedback@google.com. אנחנו לא מבטיחים שנענה לאימיילים, אבל אנחנו קוראים אותם ומתייחסים למשוב הזה כשאנחנו מתכננים את מפת הדרכים.

אתם יכולים גם להגיש בקשה להוספת תכונה חדשה ל-Conversational Analytics API.