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

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

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

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

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

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

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

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

הגדרה ותנאים מוקדמים

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

  • הפעלת Conversational Analytics API: מאמר שמתאר את הדרישות המוקדמות להפעלת Conversational Analytics API.
  • בקרת גישה באמצעות IAM: במאמר הזה מוסבר איך משתמשים בניהול זהויות והרשאות גישה כדי לשתף ולנהל את הגישה לסוכני נתונים.
  • אימות וחיבור למקור נתונים: הוראות לאימות ל-API ולהגדרת חיבורים למקורות נתונים של BigQuery,‏ Lakehouse,‏ Looker,‏ Data Studio ומסדי נתונים (AlloyDB,‏ GoogleSQL for Spanner,‏ Cloud SQL ל-MySQL, ו-Cloud SQL ל-PostgreSQL).
  • מפתחות הצפנה בניהול הלקוח (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/* מאחזר את הפרטים של סוכן נתונים ספציפי.
טעינת המדיניות של ניהול הזהויות והרשאות הגישה POST /v1/projects/*/locations/*/dataAgents/*:getIamPolicy מקבל את ההרשאות לניהול הזהויות והרשאות הגישה שהוקצו לכל משתמש עבור סוכן נתונים ספציפי. משתמשים עם תפקיד Data Agent Owner יכולים להתקשר לנקודת הקצה הזו כדי לראות את מדיניות ניהול זהויות והרשאות גישה (IAM) של סוכן הנתונים לפני השימוש בנקודת הקצה setIAMpolicy כדי לשתף סוכן נתונים עם משתמשים אחרים.
הגדרת מדיניות לניהול זהויות והרשאות גישה 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 שליחת הודעת צ'אט ללא סטטוס על ידי ציון כל ההקשר ישירות בבקשה, בלי להשתמש בסוכן נתונים שמור. בשיחות מרובות תורות, האפליקציה צריכה לנהל את היסטוריית השיחות ולספק אותה עם כל בקשה.
קבלת שיחה GET /v1/projects/*/locations/*/conversations/* אחזור הפרטים של שיחה ספציפית.
רשימת השיחות GET /v1/projects/*/locations/*/conversations הצגת רשימה של השיחות בפרויקט ספציפי.
הצגת רשימת ההודעות בשיחה GET /v1/projects/*/locations/*/conversations/*/messages רשימת ההודעות בשיחה מסוימת.
למחוק שיחה DELETE /v1/projects/*/locations/*/conversations/* מחיקת שיחה ספציפית. כדי להתקשר לנקודת הקצה הזו, צריך להיות לכם תפקיד Topic Admin בניהול הזהויות והרשאות הגישה (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 Machine Learning::Conversational Analytics API in BigQuery (AI ולמידת מכונה::Conversational Analytics API ב-BigQuery).
  • כדי לקבל תמיכה ב-Conversational Analytics API עם Looker, ברשימה Select a product (בחירת מוצר), בוחרים באפשרות Looker (original) (Looker (מקורי)), ובשדה Feature (תכונה), בוחרים באפשרות Gemini in Looker::Conversational Analytics API (Gemini ב-Looker::Conversational Analytics API).

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

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