Conversational Analytics API: פיתוח סוכני נתונים וצ'אט עם הנתונים

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

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

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

כדי להתחיל להשתמש ב-Conversational Analytics API, מומלץ קודם לעיין במסמכי התיעוד בנושא ארכיטקטורה ומושגי מפתח כדי להבין איך סוכנים מעבדים בקשות, מהם תהליכי העבודה של יוצרי סוכנים ומשתמשים, מהם מצבי שיחה ומהם תפקידים ב-Identity and Access Management ‏ (IAM). תוכלו גם לצפות בסרטון ההיכרות הזה עם Conversational Analytics API כדי לקבל סקירה כללית של ה-API והיכולות העיקריות שלו.

כדי להתחיל ליצור סוכני נתונים, אפשר לבחור בין חוויה מודרכת עם מדריכים להתחלה מהירה, סדנאות קוד, מחברות, ערכת פיתוח סוכנים (ADK) וארגז כלים של MCP, או גישה עצמאית על ידי ביצוע השלבים שמפורטים במאמר הגדרה ותנאים מוקדמים.

מדריכים למתחילים

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

מומלץ לעיין בהדגמות ובכלים של Conversational Analytics כדי להכיר את היכולות של Conversational Analytics API ולראות דוגמאות מעשיות לשילוב.

Codelabs

ב-Conversational Analytics API Codelab יש מדריך מפורט שמסביר איך להשתמש ב-Python SDK עם נתוני BigQuery.

מחשבים ניידים

כדי להתחיל להשתמש ב-Conversational Analytics API, תוכלו להיעזר במחברות Colaboratory הבאות של Conversational Analytics API, שמספקות הדרכה מפורטת:

  • ‫HTTP Colaboratory notebook: מדריך אינטראקטיבי מפורט להגדרת הסביבה, ליצירת סוכן נתונים ולביצוע קריאות ל-API באמצעות בקשות HTTP.
  • מחברת Colaboratory של Python SDK: מדריך אינטראקטיבי מפורט להגדרת הסביבה, ליצירת סוכן נתונים ולביצוע קריאות ל-API באמצעות Python SDK.

ערכת כלים לפיתוח סוכנים (ADK) וארגז כלים של MCP

כאן מוסבר איך משתמשים בפונקציה ask_data_insights בערכת פיתוח הסוכנים (ADK) כדי לענות על שאלות לגבי הנתונים בשפה טבעית.

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

ספריות לקוח

הוראות התקנה ומסמכי עזר זמינים לספריות הלקוח הבאות של Conversational Analytics API:

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

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

איך יוצרים סוכן נתונים ואיך מתקשרים איתו

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

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

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

פעולות מרכזיות ב-API

ה-API מספק את נקודות הקצה הבאות לניהול סוכני נתונים ושיחות:

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

שליחת משוב

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

מקורות מידע נוספים

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