דף זה תורגם על ידי Cloud Translation API.

פיתוח סוכן נתונים באמצעות HTTP ו-Python

בדף הזה נסביר איך משתמשים ב-Python כדי לשלוח בקשות HTTP ל-Conversational Analytics API (הגישה אליו מתבצעת דרך geminidataanalytics.googleapis.com).

קוד Python לדוגמה שבדף הזה מראה איך לבצע את הפעולות הבאות:

הגדרת ההגדרות הראשוניות והאימות
חיבור למקור נתונים של Looker,‏ BigQuery או Looker Studio
יצירת סוכן נתונים
יצירת שיחה
שימוש ב-API לשאילתות

אפשר גם להריץ את דוגמאות הקוד שבדף הזה במחברות של Colaboratory בנושא HTTP של Conversational Analytics API.

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

הגדרת ההגדרות הראשוניות והאימות

הקוד לדוגמה ב-Python מבצע את המשימות הבאות:

ייבוא הספריות הנדרשות של Python
הגדרת משתנים לפרויקט החיוב, הוראות למערכת ושאלה לסוכנות הנתונים
הצגת אסימון גישה לאימות HTTP באמצעות ה-CLI של Google Cloud

from pygments import highlight, lexers, formatters
import pandas as pd
import json as json_lib
import requests
import json
import altair as alt
import IPython
from IPython.display import display, HTML
import google.auth
from google.auth.transport.requests import Request

from google.colab import auth
auth.authenticate_user()

billing_project = 'YOUR-BILLING-PROJECT'
system_description = 'YOUR-SYSTEM-INSTRUCTIONS'
question = 'YOUR-QUESTION-HERE'

access_token = !gcloud auth application-default print-access-token
headers = {
    "Authorization": f"Bearer {access_token[0]}",
    "Content-Type": "application/json",
}

מחליפים את ערכי הדוגמה באופן הבא:

YOUR-BILLING-PROJECT: המזהה של פרויקט החיוב שבו הפעלתם את ממשקי ה-API הנדרשים.
YOUR-SYSTEM-INSTRUCTIONS: הוראות מערכת שמנחות את ההתנהגות של הסוכן ומאפשרות לכם להתאים אישית את הסוכן לצרכים שלכם. לדוגמה, אפשר להשתמש בהוראות המערכת כדי להגדיר מונחים עסקיים (למשל, מהו 'לקוח נאמן'), לשלוט באורך התשובה ('סיכום בפחות מ-20 מילים') או להגדיר את עיצוב הנתונים ('התאמה לסטנדרטים של החברה'). מחליפים את הטקסט של placeholder בהוראות שרלוונטיות לנתונים ולתרחיש לדוגמה.
YOUR-QUESTION-HERE: שאלה בשפה טבעית ששולחים לסוכנות הנתונים.

אימות מול Looker

אם אתם מתכננים להתחבר למקור נתונים של Looker, תצטרכו לבצע אימות למכונה של Looker.

שימוש במפתחות API

דוגמת הקוד הבאה ב-Python מראה איך לאמת את הסוכן במכונה של Looker באמצעות מפתחות API.

looker_credentials = {
    "oauth": {
        "secret": {
          "client_id": "YOUR-LOOKER-CLIENT-ID",
          "client_secret": "YOUR-LOOKER-CLIENT-SECRET",
        }
    }
}

מחליפים את ערכי הדוגמה באופן הבא:

YOUR-LOOKER-CLIENT-ID: מזהה הלקוח של מפתח Looker API שנוצר.
YOUR-LOOKER-CLIENT-SECRET: סוד הלקוח של מפתח Looker API שנוצר.

שימוש באסימוני גישה

דוגמת הקוד הבאה ב-Python מראה איך לאמת את הסוכן במכונה של Looker באמצעות אסימוני גישה.

looker_credentials = {
   "oauth": {
       "token": {
         "access_token": "YOUR-TOKEN",
       }
   }
}

מחליפים את ערכי הדוגמה באופן הבא:

YOUR-TOKEN: הערך של access_token שיוצרים כדי לבצע אימות ב-Looker.

התחברות למקור נתונים

דוגמאות הקוד הבאות ב-Python מדגימות איך להגדיר את מקור הנתונים של Looker, BigQuery או Looker Studio לשימוש של הסוכן.

חיבור לנתונים של Looker

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

looker_data_source = {
    "looker": {
      "explore_references": {
          "looker_instance_uri": "https://your_company.looker.com",
          "lookml_model": "your_model",
          "explore": "your_explore",
      },
    }
}

מחליפים את ערכי הדוגמה באופן הבא:

https://your_company.looker.com: כתובת ה-URL המלאה של מכונה של Looker.
your_model: השם של מודל ה-LookML שכולל את ה-Explore שאליו רוצים להתחבר.
your_explore: השם של Looker Explore שרוצים שסוכן הנתונים ישלח אליו שאילתה.

התחברות לנתוני BigQuery

בקוד לדוגמה הבא מוגדר חיבור לטבלה ב-BigQuery.

bigquery_data_sources = {
   "bq" :  {
        "tableReferences": [
        {
            "projectId": "bigquery-public-data",
            "datasetId": "san_francisco",
            "tableId": "street_trees",
        }
        ]
    }
}

מחליפים את ערכי הדוגמה באופן הבא:

bigquery-public-data: המזהה של Google Cloud הפרויקט שמכיל את מערך הנתונים והטבלה ב-BigQuery שאליהם רוצים להתחבר. כדי להתחבר למערך נתונים ציבורי, מציינים bigquery-public-data.
san_francisco: המזהה של מערך הנתונים ב-BigQuery.
street_trees: המזהה של טבלת BigQuery.

חיבור לנתונים של Looker Studio

הקוד לדוגמה הבא מגדיר חיבור למקור נתונים ב-Looker Studio.

looker_studio_data_source = {
    "studio":{
        "studio_references":
         [
            {
              "studio_datasource_id": "studio_datasource_id"
            }
         ]
    }
}

מחליפים את studio_datasource_id במזהה של מקור הנתונים.

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

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

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

אפשר גם להפעיל ניתוח מתקדם באמצעות Python על ידי הכללת הפרמטר options בתוכן של הבקשה.

data_agent_url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}/locations/{location}/dataAgents"

data_agent_id = "data_agent_1"

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}", # Optional
      "description": "This is the description of data_agent_1.", # Optional

      "data_analytics_agent": {
          "published_context": {
              "datasource_references": bigquery_data_sources,
              "system_instruction": system_instruction,
              # Optional: To enable advanced analysis with Python, include the following options block:
              "options": {
                  "analysis": {
                      "python": {
                          "enabled": True
                      }
                  }
              }
          }
      }
  }

params = {"data_agent_id": data_agent_id} # Optional

data_agent_response = requests.post(
    data_agent_url, params=params, json=data_agent_payload, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent created successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error creating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

מחליפים את ערכי הדוגמה באופן הבא:

data_agent_1: מזהה ייחודי של סוכן הנתונים. הערך הזה משמש בשם המשאב של הסוכן וכפרמטר השאילתה של כתובת ה-URL data_agent_id.
This is the description of data_agent_1.: תיאור של סוכן הנתונים.

יצירת שיחה

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

conversation_url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}/locations/{location}/conversations"

data_agent_id = "data_agent_1"
conversation_id = "conversation_1"

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}"
}
params = {
    "conversation_id": conversation_id
}

conversation_response = requests.post(conversation_url, headers=headers, params=params, json=conversation_payload)

if conversation_response.status_code == 200:
    print("Conversation created successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error creating Conversation: {conversation_response.status_code}")
    print(conversation_response.text)

מחליפים את ערכי הדוגמה באופן הבא:

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

שימוש ב-API לשאילת שאלות

אחרי שיוצרים סוכן נתונים ושיחה, אפשר לשאול שאלות לגבי הנתונים באמצעות אחת מהשיטות הבאות:

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

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

צ'אט עם שמירת מצב

שליחת בקשת צ'אט עם שמירת מצב עם הפניה לשיחה

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

chat_url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}/locations/{location}:chat"

data_agent_id = "data_agent_1"
conversation_id = "conversation_1"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/global",
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "conversation_reference": {
        "conversation": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
        "data_agent_context": {
            "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
            # "credentials": looker_credentials
        }
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

מחליפים את ערכי הדוגמה באופן הבא:

data_agent_1: המזהה של סוכן הנתונים, כפי שמוגדר בבלוק הקוד לדוגמה בקטע יצירת סוכן נתונים.
conversation_1: מזהה ייחודי של השיחה.
Make a bar graph for the top 5 states by the total number of airports שימשה כהנחיה לדוגמה.

צ'אט ללא שמירת מצב

שליחת בקשת צ'אט ללא מצב עם הפניה לסוכנות נתונים

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

chat_url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}/locations/{location}:chat"

data_agent_id = "data_agent_1"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/global",
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "data_agent_context": {
        "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
        # "credentials": looker_credentials
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

מחליפים את ערכי הדוגמה באופן הבא:

data_agent_1: המזהה של סוכן הנתונים, כפי שמוגדר בבלוק הקוד לדוגמה בקטע יצירת סוכן נתונים.
Make a bar graph for the top 5 states by the total number of airports שימשה כהנחיה לדוגמה.

שליחת בקשת צ'אט ללא שמירת מצב עם הקשר בשורה

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

אפשר גם להפעיל ניתוח מתקדם באמצעות Python על ידי הכללת הפרמטר options בתוכן של הבקשה.

chat_url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}/locations/global:chat"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/global",
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "inline_context": {
        "datasource_references": bigquery_data_sources,
          # Optional: To enable advanced analysis with Python, include the following options block:
          "options": {
              "analysis": {
                  "python": {
                      "enabled": True
                  }
              }
          }
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

דוגמת קוד מקצה לקצה

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