הפקת תובנות באמצעות סוכן התובנות מנתונים

גרסת טרום-השקה פרטית

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. אתם יכולים לקרוא מידע נוסף בקטע תיאור שלבי ההשקה.

הסוכן 'תובנות לגבי נתונים' הוא סוכן שנוצר על ידי Google. הוא מספק תובנות מנתונים ב-BigQuery. עם הסוכן 'תובנות לגבי נתונים', לא צריך ידע מוקדם ב-SQL. כך תוכלו לקבל החלטות עסקיות מושכלות שמבוססות על נתונים, ומנתחי הנתונים יוכלו להתמקד במשימות מורכבות יותר.

בדף הזה מוסבר איך אדמין של פרויקט Google Cloud יכול להעניק הרשאה, ליצור ולפרוס את סוכן Data Insights באמצעות Google Cloud המסוף ו-API בארכיטקטורת REST. בדף הזה מוסבר גם איך משתמש קצה יכול להשתמש בסוכן.

הערה: כדי לגשת לתכונה הזו, צריך לפנות לנציג של חשבון Google.

סקירה כללית

הסוכן Data Insights נועד לבצע את הפעולות הבאות:

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

דוגמאות לשאילתות שאפשר לשאול את הסוכן Data Insights

ריכזנו כאן כמה דוגמאות לשאילתות שאפשר לשאול את נציג התובנות לגבי הנתונים:

• צבירה והצגה חזותית של נתונים:
  • "מה היו נתוני המכירות ברבעון השני באזור אמריקה הלטינית השנה בהשוואה לרבעון השני בשנה שעברה?"
  • "צור תרשים עמודות שבו מוצגת ההשוואה בין 5 המדינות המובילות באזור".
• ניתוח מגמות:
  • "מה היו השינויים בנפח השיחות היוצאות ב-6 החודשים האחרונים, בחלוקה לפי מיקום?"
  • ‫"Analyze the booking patterns for the hotels in Lisbon rated higher than 3 stars"
• כריית מידע:
  • "Which factors are correlated with the total sales value when a customer buys something?" תכין לי מפת חום שמראה את הקשר ביניהם".
• ניתוח ודיווח:
  • "תסכם את טבלת ההזדמנויות והחשבונות ותיצור דוח קצר שמדגיש מגמות מרכזיות".

לפני שמתחילים

כדי להתחיל להשתמש בסוכן Data Insights ב-Gemini Enterprise, פועלים לפי השלבים הבאים:

• פועלים לפי ההוראות כדי להתחיל להשתמש ב-Gemini Enterprise.
• פועלים לפי ההוראות לקבלת רישיונות ל-Gemini Enterprise.
• כדי לקבל גישה לסוכן Data Insights, צריך לפנות לנציג של חשבון Google.
• מכינים את הנתונים ב-BigQuery. מידע נוסף זמין במאמרי העזרה של BigQuery.
• כדי להפיק את המרב מהסוכן, חשוב להבין את הנתונים במערך הנתונים של BigQuery.

איך מעניקים גישה לנתונים ב-BigQuery

כדי לאפשר לסוכן Data Insights להציג את הנתונים ב-BigQuery ולשאול עליהם שאילתות, צריך להקצות למשתמשים של הסוכן את התפקידים הבאים בניהול הזהויות והרשאות הגישה (IAM):

• BigQuery Data Viewer (roles/bigquery.dataViewer)
• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Metadata Viewer (roles/bigquery.metadataViewer)

תהליך עבודה

זהו תהליך העבודה הכולל להגדרה ולשימוש בסוכן Data Insights:

• איך מקבלים פרטי הרשאה
• מגדירים את הסוכן באמצעות המסוף Google Cloud או באמצעות API בארכיטקטורת REST.
• הוספה או שינוי של משתמשים וההרשאות שלהם
• שינוי מצב העבודה של מופע הסוכן
• שימוש בסוכן

קבלת פרטי הרשאה

כדי להגדיר הרשאה, צריך לפעול לפי השלבים הבאים. הפרטים שתקבלו נדרשים כדי לתת לסוכן Data Insights הרשאה להתחבר לנתוני BigQuery.

1. במסוף Google Cloud , נכנסים לדף Credentials בקטע APIs & Services.

   כניסה לדף Credentials

2. בוחרים את הפרויקט Google Cloud שמכיל את מערך הנתונים ב-BigQuery שרוצים שהסוכן ישלח לגביו שאילתות.

3. לוחצים על Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).

4. ב-Application type בוחרים באפשרות אפליקציית אינטרנט.

5. בקטע Authorized redirect URIs, מוסיפים את כתובות ה-URI הבאות:

   • https://vertexaisearch.cloud.google.com/oauth-redirect
   • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

6. לוחצים על יצירה.

7. בחלונית OAuth client created (נוצר לקוח OAuth), לוחצים על Download JSON (הורדת JSON).

   קובץ ה-JSON שהורדתם כולל את הפרטים הבאים לגביGoogle Cloud הפרויקט שנבחר. תצטרכו את הפרטים האלה כדי ליצור משאב הרשאה:

   • Client ID: CLIENT_ID
   • URI של הרשאה:

   כדי לאשר את האפליקציה, צריך ליצור URI ספציפי לאישור באמצעות הפרטים מקובץ ה-JSON של פרטי הכניסה ל-OAuth. מעתיקים את התבנית הבאה ומחליפים את הערכים הזמניים לשמירת מקום בערכים הספציפיים שלכם.

   תבנית של URI להרשאה

   https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
   

   פירוט הפרמטרים

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

   פרמטר	ערך או פעולה
   client_id	מחליפים את הערך ב-client_id שמופיע בקובץ ה-JSON שהורדתם.
   redirect_uri	לא לשנות. הערך חייב להיות https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
   scope	נדרשת פעולה: רשימת היקפי הגישה של Google API שהאפליקציה שלכם צריכה, למשל, https://www.googleapis.com/auth/bigquery. אם משתמשים בכמה היקפים, צריך להפריד ביניהם באמצעות רווח, שהופך ל-%20 בכתובת ה-URL.
   include_granted_scopes	חייב להיות true.
   response_type	צריך להיות בן code ומעלה כדי לקבל קוד הרשאה.
   access_type	מגדירים את הערך offline כדי לוודא שמקבלים טוקן רענון.
   prompt	הגדרה ל-consent עוזרת לוודא שתמיד יוצג למשתמש מסך בקשת הסכמה.

   • Token URI: https://oauth2.googleapis.com/token
   • Client secret: CLIENT_SECRET

הגדרת הסוכן באמצעות Google Cloud המסוף

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

אישור ויצירה של מופע סוכן

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

1. במסוף Google Cloud , עוברים אל Gemini Enterprise.

   אל Gemini Enterprise

2. בוחרים את האפליקציה שבה רוצים ליצור את הסוכן.

3. בתפריט, לוחצים על סוכנים.

   בדף סוכנים מוצגים הסוכנים הקיימים.

   

   לוחצים על סוכן

4. לוחצים על הוספת סוכן.

   

   לוחצים על add agent (הוספת סוכן)

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

   

   בחירת סוכני Google

6. לוחצים על יצירה בכרטיס של סוכן הנתונים.

   

   יצירת סוכן הנתונים

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

   

   מזינים את פרטי החיוב לצורך אימות

8. לוחצים על סיום.

9. לוחצים על הבא.

10. מגדירים את הסוכן באופן הבא:

    1. מזינים את השם והתיאור של הסוכן.

    2. בקטע BigQuery dataset (מערך נתונים ב-BigQuery), לוחצים על Browse (עיון) ומבצעים אחת מהפעולות הבאות:

       • בוחרים מערך נתונים זמין ולוחצים על בחירה.
       • מזינים את הנתיב למערך הנתונים הנדרש ב-BigQuery, לוחצים על חיפוש, בוחרים אותו ואז בוחרים באפשרות בחירה.

    3. אופציונלי: לוחצים על הצגת אפשרויות נוספות כדי לראות אפשרויות מתקדמות.

    4. בוחרים את אפשרויות הגישה הנכונות לטבלה. אם רוצים להגדיר רשימת היתרים

       או רשימת חסימה, מציינים את הנתיבים לטבלאות המוגבלות.

    5. אופציונלי: מגדירים את השאילתה בשפה טבעית כדי להתאים אישית את התרגום של השפה הטבעית ל-SQL. כדי לשפר את איכות הפלט של הסוכן, אפשר לספק דוגמאות לשאילתות בשפה טבעית, לפלט SQL הצפוי ולתשובות הצפויות.

       • תיאור הסכימה: מחרוזת בשפה טבעית שמתארת את הסכימה של מערך הנתונים ב-BigQuery.
       • הנחיה בשפה טבעית לשאילתת SQL: שאילתה בשפה טבעית שהומרה להוראת SQL.

    6. אופציונלי: מוסיפים דוגמאות לשאילתות בשפה טבעית שהומרו לשאילתות SQL:

       • שאילתה: דוגמה לשאילתה בשפה טבעית שצריך להמיר לשאילתת SQL. לדוגמה, "מה השמות וכתובות האימייל של הלקוחות שנמצאים בקליפורניה"
       • Expected SQL: מחרוזת שמציגה דוגמה לשאילתת SQL שתואמת לשאילתה בשפה טבעית. לדוגמה, נניח שיש לכם טבלה ב-BigQuery בשם customers. אז שאילתת ה-SQL הצפויה יכולה להיות SELECT customer_name, email FROM customers WHERE state = 'California'.
       • התשובה הצפויה: מחרוזת שמספקת את התשובה הצפויה לשאילתה על ידי הפעלת שאילתת ה-SQL הצפויה.

       לדוגמה:

       Here are the names and email addresses of your customers in California: \
       * Customer name: Lara B, Email address: [e-mail] \
       * Customer name: Alex A, Email address: [e-mail] \
       * Customer name: Bola C, Email address: [e-mail] \
       

11. לוחצים על יצירה.

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

הגדרת ה-Agent באמצעות API בארכיטקטורת REST

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

אישור הסוכן

אדמינים יכולים ליצור משאב הרשאה ב-Gemini Enterprise. כך סוכן התובנות מנתונים יכול לגשת לנתוני BigQuery.

1. יוצרים את משאב ההרשאה.

   REST

   בדוגמה הבאה אפשר לראות איך יוצרים משאב הרשאה באמצעות השיטה authorizations.create.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_NUMBER" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
    -d '{
      "name": projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
      "serverSideOauth2": {
        "clientId": "CLIENT_ID",
        "clientSecret": "CLIENT_SECRET",
        "authorizationUri": "AUTHORIZATION_URI",
        "tokenUri": "https://oauth2.googleapis.com/token"
   }
   }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
   • ‫LOCATION: המיקום של Google Cloud הפרויקט.
   • ‫AUTHORIZATION_ID: מזהה שצריך לספק כדי לזהות את משאב ההרשאה.
   • ‫CLIENT_ID: מזהה הלקוח שקיבלתם בשלב הקודם.
   • CLIENT_SECRET: סוד הלקוח שקיבלתם בשלב הקודם.
   • ‫AUTHORIZATION_URI: כתובת ה-URI של ההרשאה שקיבלתם בשלב הקודם.

   תשובה

   אתם אמורים לקבל תגובת JSON שדומה לתגובה הבאה. שימו לב ל-AUTHORIZATION_RESOURCE_NAME, שבו צריך להשתמש כדי ליצור את סוכן התובנות לגבי נתונים. המזהה הייחודי בסוף AUTHORIZATION_RESOURCE_NAME הוא AUTHORIZATION_ID.

   {
    "name": "AUTHORIZATION_RESOURCE_NAME",
    "serverSideOauth2": {
      "clientId": "CLIENT_ID",
      "clientSecret": "CLIENT_SECRET",
      "tokenUri": "https://oauth2.googleapis.com/token",
      "authorizationUri": "AUTHORIZATION_URI"
    }
   }
   

יצירת מופע של סוכן

בתור אדמינים של פרויקטים ב- Google Cloud , אתם יכולים ליצור מופע של סוכן Data Insights. לשם כך צריך את מזהה הפרויקט ואת מזהה מערך הנתונים של נתוני BigQuery שרוצים לשלוח להם שאילתות באמצעות הסוכן.

REST

בדוגמה הבאה מוצג אופן יצירת מופע של סוכן Data Insights באמצעות השיטה agents.create. מידע על השדות המתקדמים שאפשר להוסיף לדוגמה הזו זמין במאמר הוספת הגדרות מתקדמות לסוכן.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
• ‫LOCATION: המיקום של אפליקציית Gemini Enterprise.
• ‫APP_ID: מזהה האפליקציה.
• ‫AGENT_DISPLAY_NAME: השם של מופע הסוכן של Data Insights.
• ‫AGENT_ICON_URI: שדה אופציונלי שבו אפשר לציין URI לסמל של הסוכן.
• ‫AGENT_DESCRIPTION: תיאור של מופע הסוכן של 'תובנות מנתונים' שמציין את המטרה של הסוכן או את פרטי מקור הנתונים שלו ב-BigQuery.
• ‫BIGQUERY_PROJECT_ID: מזהה הפרויקט של פרויקטGoogle Cloud שמכיל את מערך הנתונים ב-BigQuery.
• ‫BIGQUERY_DATASET_ID: מזהה מערך הנתונים ב-BigQuery שמכיל את הנתונים שרוצים לשלוח אליהם שאילתות.
• ‫AUTHORIZATION_RESOURCE_NAME: שם משאב ההרשאה שקיבלתם בקטע הקודם.

תשובה

אתם אמורים לקבל תגובת JSON שדומה לתגובה הבאה. שימו לב ל-AGENT_RESOURCE_NAME, שבו צריך להשתמש כדי לפרוס את סוכן התובנות לגבי נתונים. המזהה הייחודי בסוף AGENT_RESOURCE_NAME הוא AGENT_ID.

{
  "name": "AGENT_RESOURCE_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "icon": {
    "uri": "AGENT_ICON_URI"
  },
  "createTime": "CREATION_TIME",
  "managedAgentDefinition": {
    "toolSettings": {
      "toolDescription": "AGENT_DISPLAY_NAME"
    },
    "deploymentInfo": {},
    "dataScienceAgentConfig": {
      "bqProjectId": "BIGQUERY_PROJECT_ID",
      "bqDatasetId": "BIGQUERY_DATASET_ID"
    }
  },
  "authorization_config": {
    "tool_authorizations" : [
      "AUTHORIZATION_RESOURCE_NAME"
    ]
  },
  "state": "CONFIGURED"
}

הוספת הגדרות מתקדמות לסוכן

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

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2sqlExample": [{
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    }],
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

מחליפים את מה שכתוב בשדות הבאים:

• ‫NL_TO_SQL_INSTRUCTIONS: שאילתה בשפה טבעית שהומרה להוראת SQL.

• ‫EXAMPLE_NL_QUERY: דוגמה לשאילתה בשפה טבעית שצריך להמיר לשאילתת SQL. לדוגמה, "מהם השמות וכתובות האימייל של הלקוחות שנמצאים בקליפורניה"

• ‫EXPECTED_SQL_QUERY: מחרוזת שמציגה דוגמה לשאילתת SQL שמתאימה לשאילתה בשפה טבעית. לדוגמה, נניח שיש לכם טבלת BigQuery בשם customers. אז שאילתת ה-SQL הצפויה יכולה להיות: SELECT customer_name, email FROM customers WHERE state = 'California'.

• ‫EXPECTED_SQL_RESPONSE: מחרוזת שמספקת את התשובה הצפויה לשאילתה ואת שאילתת ה-SQL הצפויה. לדוגמה:

  
  Here are the names and email addresses of your customers in California: \
  * Customer name: Lara B, Email address: [e-mail] \
  * Customer name: Alex A, Email address: [e-mail] \
  * Customer name: Bola C, Email address: [e-mail] \
  
  

• ‫NL_DESCRIPTION_OF_BQ_DATASET: מחרוזת בשפה טבעית שמתארת את הסכימה של מערך הנתונים ב-BigQuery.

פריסת המופע

אחרי שיוצרים את מופע הסוכן Data Insights, האדמין יכול לפרוס אותו כדי שמשתמשי הקצה יוכלו להשתמש בו.

REST

1. פורסים את הסוכן. בדוגמה הבאה אפשר לראות איך פורסים את הסוכן שנוצר באמצעות השיטה agents.deploy. פריסת הסוכן היא פעולה ממושכת (LRO).

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_NUMBER" \
    "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
    -d '{
      "name":"AGENT_RESOURCE_NAME"
    }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
   • ‫AGENT_RESOURCE_NAME: שם המשאב של הסוכן שקיבלתם בקטע הקודם כשנוצר הסוכן.

   תשובה

   אתם אמורים לקבל תגובת JSON שדומה לתגובה הבאה. שימו לב ל-DEPLOY_OPERATION_NAME, שבו צריך להשתמש כדי לקבל את הסטטוס של ה-LRO.

   {
    "name": "DEPLOY_OPERATION_NAME",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.DeployAgentMetadata"
    }
   }

2. קבלת הסטטוס של פעולת הפריסה. בדוגמה הבאה אפשר לראות איך מקבלים את הסטטוס של פעולת הפריסה באמצעות השיטה operations.get.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"
   

   מחליפים את DEPLOY_OPERATION_NAME בשם הפעולה הממושכת שהתקבל בשלב הקודם כשפרסתם את הסוכן.

   בתשובה, אם הערך של השדה done הוא true, הפריסה הושלמה. אם הערך של השדה done הוא false, הפריסה מתבצעת.

קבלת מפרטים של סוכנים

אפשר לאחזר את ההגדרות והמפרטים של סוכן Data Insights, כמו רשימות ההיתרים ורשימות החסימות של טבלאות ב-BigQuery, באמצעות ה-API. כדי לקבל את המפרט של סוכן, שולחים בקשת GET:

REST

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫APP_ID: מזהה האפליקציה.
• ‫LOCATION: המיקום של אפליקציית Gemini Enterprise.
• ‫AGENT_ID: מזהה הסוכן.

דוגמה לתשובה

בקשה שמושלמת בהצלחה מחזירה תגובת JSON שדומה לזו:

{
  "name": "projects/12345/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/my-agent",
  "displayName": "Data Science Agent",
  "description": "An agent that helps query BigQuery data.",
  "managedAgentDefinition": {
    "dataScienceAgentConfig": {
      "bqProjectId": "my-bq-project",
      "bqDatasetId": "my-bq-dataset",
      "allowlistTables": [
        "sales_data_2024",
        "inventory_levels"
      ],
      "blocklistTables": [
        "employee_salaries",
        "pii_users"
      ]
    }
  },
  "authorizationConfig": {
    "toolAuthorizations": [
      "projects/12345/locations/global/authorizations/test-authorization"
    ]
  },
  "state": "ENABLED",
  "createTime": "2024-05-20T10:00:00Z",
  "updateTime": "2024-05-20T10:05:00Z"
}

הוספה או שינוי של משתמשים וההרשאות שלהם

כדי להוסיף או לשנות ישויות במופע של הסוכן Data Insights ולהקצות להן תפקידים ספציפיים בממשק לניהול זהויות והרשאות גישה (IAM), פועלים לפי השלבים הבאים:

המסוף

1. במסוף Google Cloud , עוברים אל Gemini Enterprise.

   אל Gemini Enterprise

2. בוחרים אפליקציה שמכילה את מופע הסוכן של Data Insights.

3. בתפריט, לוחצים על סוכנים.

   בדף סוכנים מוצגים הסוכנים הקיימים.

4. לוחצים על הסוכן שרוצים להוסיף או לשנות את המשתמשים שלו. לדוגמה, לוחצים על המופע Data insights agent.

   כברירת מחדל, לסוכן חדש שנוצר אין משתמשים.

   

   לוחצים על מופע הסוכן 'תובנות מהנתונים'

5. לוחצים על הרשאות משתמש.

6. בטבלה משתמשים עם הרשאה, לוחצים על הוספת משתמש.

   

   איך מוסיפים משתמש

7. בוחרים סוג חבר מהרשימה הזמינה:

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

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

   • בקטע All users (כל המשתמשים), בוחרים תפקיד.

   

   בחירת סוג חברות

8. לוחצים על Save.

   מדיניות IAM מתעדכנת והמשתמש מתווסף לרשימת המשתמשים עם הרשאות.

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

   

   הסרת תפקיד

שינוי מצב הפעולה של המופע

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

המסוף

1. במסוף Google Cloud , עוברים אל Gemini Enterprise.

   אל Gemini Enterprise

2. בוחרים אפליקציה שמכילה את מופע הסוכן של Data Insights.

3. בתפריט, לוחצים על סוכנים.

   בדף סוכנים מוצגים הסוכנים הקיימים.

   

   איך מוסיפים משתמש

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

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

   

   בוחרים אחת מהפעולות לסוכן.

שימוש בסוכן

בקטע הזה מוסבר איך משתמשי קצה יכולים ליצור אינטראקציה עם הסוכן 'תובנות מנתונים' כדי לקבל תובנות מהנתונים שלהם ב-BigQuery. אפשר להשתמש בסוכן דרך אפליקציית Gemini Enterprise או באופן פרוגרמטי באמצעות ה-API.

שימוש בסוכן מתוך האפליקציה

כדי לקבל תובנות לגבי הנתונים באמצעות הסוכן:

אפליקציה

1. בתפריט הניווט של האפליקציה, לוחצים על Agents (סוכנים).

2. לוחצים על הצגת כל הסוכנים.

   

   הצגת כל הסוכנים

3. בוחרים את הנציג מהרשימה של הנציגים שמוצגת או מהפעילות האחרונה.

   

   בחירת מופע של סוכן

4. אם הסוכן שלכם דורש הרשאה נוספת, לוחצים על אישור ומזינים את פרטי ההרשאה.

5. בתיבת החיפוש, מבצעים את הפעולות הבאות:

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

   • כדי לנהל את הנתונים, לוחצים על סמל .

6. מזינים את השאלות או ההנחיות ומקישים על Enter.

אפשר גם לקיים אינטראקציה עם סוכן התובנות לגבי נתונים באופן פרוגרמטי באמצעות ה-API.

שימוש בסוכן 'תובנות לגבי נתונים' באמצעות API

הסוכן Data Insights זמין למשתמשים מורשים באמצעות API. כדי ליצור אינטראקציה עם הסוכן באופן פרוגרמטי, שולחים בקשת POST לשיטה streamAssist.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "QUERY"
    },
    "agentsSpec": {
      "agentSpecs": {
        "agentId": "AGENT_ID"
      }
    }
  }'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫LOCATION: המיקום של אפליקציית Gemini Enterprise (לדוגמה, global).
• ‫APP_ID: מזהה האפליקציה.
• ‫QUERY: השאילתה בשפה טבעית (לדוגמה, 'צור רשימה של 10 הלקוחות המובילים לפי הוצאות וצור תרשים עם הפריטים שהם הכי אוהבים לקנות').
• ‫AGENT_ID: מזהה הסוכן.

דוגמה לתשובה

השיטה streamAssist מחזירה רשימה של אובייקטים מסוג AssistAnswer. בדוגמה הבאה מוצג זרם תגובות, שכולל את החשיבה הרציונלית הפנימית של ה-Agent ואת התשובה הסופית. אם הבקשה מצליחה, מקבלים תגובת JSON שדומה לתגובה הבאה (התגובה קוצרה).

  [
    {
      "answer": {
        "state": "IN_PROGRESS",
        "replies": [
          {
            "groundedContent": {
              "content": {
                "role": "model",
                "text": "",
                "thought": true
              }
            }
          }
        ]
      },
      "assistToken": "M8gKCwiBkYrMBhDUqLFcEiQ2OTgyNWVlMS0wMDAwLTJjMzUtYjVmOS1mNDAzMDQzYmFjNmM"
    },
    {
      "answer": {
        "state": "IN_PROGRESS",
        "replies": [
          {
            "groundedContent": {
              "content": {
                "role": "model",
                "text": "I am an expert data analyst with access to the `spark-assistant-test.bikestores` dataset...",
                "thought": true
              }
            }
          }
        ]
      },
      "assistToken": "M8gKCwiBkYrMBhDUqLFcEiQ2OTgyNWVlMS0wMDAwLTJjMzUtYjVmOS1mNDAzMDQzYmFjNmM"
    },
    {
      "answer": {
        "name": "projects/12345/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID/assistAnswers/ANSWER_ID",
        "state": "SUCCEEDED",
            "groundedContent": {
              "content": {
                "role": "model",
                "text": "I am an expert data analyst with access to the `spark-assistant-test.bikestores` dataset..."
              }
            }
          }
        ]
      },
      "sessionInfo": {
        "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID"
      }
    }
  ]

הגדרות של שדה תשובה

שדה	תיאור
answer.state	הסטטוס של יצירת התשובה. הפונקציה מחזירה IN_PROGRESS בזמן שהסוכן יוצר את התשובה ו-SUCCEEDED כשהיא מוכנה.
answer.replies	רשימה שמכילה את רכיבי התוכן שנוצרו.
replies.groundedContent.content.text	תוכן הטקסט שנוצר על ידי הסוכן.
replies.groundedContent.content.thought	אם true, הטקסט הוא תהליך החשיבה הרציונלית הפנימית של ה-Agent (כמו ניסוח SQL) ולא התגובה הסופית.
sessionInfo.session	המזהה הייחודי של הסשן. אפשר להשתמש בשם המשאב הזה בקריאות API הבאות כדי לשמור את היסטוריית השיחות.