Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הגדרת הקשר של סוכן הנתונים למקורות נתונים של BigQuery

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

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

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

אפשרויות להוספת הקשר שנכתב על ידיכם

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

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

יצירת סוכן נתונים קבוע: כדי להגדיר התנהגות של סוכן שנשמרת בכמה שיחות, צריך לכלול הקשר שנוצר על ידי מחבר באובייקט published_context בגוף הבקשה. מידע נוסף זמין במאמרים יצירת סוכן נתונים (HTTP) או הגדרת הקשר לשיחה עם שמירת סטטוס או ללא שמירת סטטוס (Python SDK).
שליחת בקשה ללא מצב: כדי להגדיר את ההתנהגות של הסוכן עבור קריאה ספציפית ל-API, צריך לספק הקשר שנוצר בתוך אובייקט inline_context בבקשה לצ'אט. מידע נוסף אפשר למצוא במאמר יצירת שיחה מרובת תפניות ללא שמירת מצב (HTTP) או במאמר שליחת בקשת צ'אט ללא שמירת מצב עם הקשר מוטבע (Python SDK).
שליחת בקשה לנתוני שאילתה: במקורות נתונים של מסד נתונים, צריך לציין את מזהה קבוצת ההקשר של ההקשר שנוצר באובייקט agent_context_reference בבקשה לנתוני שאילתה. מידע נוסף זמין במאמר הגדרת ההקשר של סוכן הנתונים למקורות נתונים של מסדי נתונים.

הגדרת שדות של הקשר מובנה

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

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

הקשר מובנה ברמת הטבלה

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

‫description: סיכום של תוכן הטבלה והמטרה שלה
synonyms: רשימה של מונחים חלופיים שאפשר להשתמש בהם כדי להתייחס לטבלה
‫tags: רשימה של מילות מפתח או תגים שמשויכים לטבלה

בדוגמאות הבאות אפשר לראות איך מספקים את המאפיינים האלה כהקשר מובנה בבקשות HTTP ישירות וב-Python SDK.

HTTP

בבקשת HTTP ישירה, מציינים את המאפיינים האלה ברמת הטבלה באובייקט schema של הפניה הרלוונטית לטבלה. דוגמה מלאה לאופן שבו צריך לבנות את מטען הייעודי (payload) של הבקשה המלאה זמינה במאמר חיבור לנתונים ב-BigQuery.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
        "description": "Data for orders in The Look, a fictitious ecommerce store.",
        "synonyms": ["sales"],
        "tags": ["sale", "order", "sales_order"]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
        "description": "Data for users in The Look, a fictitious ecommerce store.",
        "synonyms": ["customers"],
        "tags": ["user", "customer", "buyer"]
    }
  }
]

Python SDK

כשמשתמשים ב-Python SDK, אפשר להגדיר את המאפיינים האלה ברמת הטבלה במאפיין schema של אובייקט BigQueryTableReference. בדוגמה הבאה מוצג אופן יצירת אובייקטים של הפניה לטבלה שמספקים הקשר לטבלאות orders ו-users. דוגמה מלאה לאופן שבו יוצרים אובייקטים של הפניה לטבלה ומשתמשים בהם זמינה במאמר התחברות לנתונים ב-BigQuery.

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]

הקשר מובנה ברמת העמודה

המפתח fields, שמוטמע באובייקט schema של הפניה לטבלה, מקבל רשימה של אובייקטים מסוג field כדי לתאר עמודות נפרדות. לא צריך להוסיף הקשר לכל השדות, אבל בשדות הכי רווחיים, הוספת פרטים נוספים יכולה לשפר את הביצועים של הסוכן.

לכל אובייקט field, אפשר להשתמש בשדות ההקשר המובנים הבאים כדי להגדיר את המאפיינים הבסיסיים של עמודה:

‫description: תיאור קצר של תוכן העמודה והמטרה שלה
synonyms: רשימה של מונחים חלופיים שאפשר להשתמש בהם כדי להתייחס לעמודה
tags: רשימה של מילות מפתח או תגים שמשויכים לעמודה

בדוגמאות הבאות אפשר לראות איך אפשר לספק את המאפיינים האלה כהקשר מובנה לשדה status בטבלה orders ולשדה first_name בטבלה users באמצעות בקשות HTTP ישירות וערכת ה-SDK של Python.

HTTP

בבקשת HTTP ישירה, אפשר להגדיר את המאפיינים האלה ברמת העמודה על ידי ציון רשימה של אובייקטים מסוג fields בתוך האובייקט schema של הפניה לטבלה.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
      "fields": [{
          "name": "status",
          "description": "The current status of the order.",
      }]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
      "fields": [{
          "name": "first_name",
          "description": "The first name of the user.",
          "tags": "person",
      }]
    }
  }
]

Python SDK

כשמשתמשים ב-Python SDK, אפשר להגדיר את המאפיינים האלה ברמת העמודה על ידי הקצאת רשימה של אובייקטים מסוג Field למאפיין fields של המאפיין schema של טבלה.

# Define column context for the 'orders' table
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    )
]

# Define column context for the 'users' table
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    )
]

שאילתות לדוגמה

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

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

שאילתות לדוגמה שמכילות פרמטרים

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

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

בשדה naturalLanguageQuestion, משתמשים בסוגריים מסולסלים בשביל ערכי placeholder, כמו {state}.
בשדה sqlQuery, משתמשים בתחביר של פרמטר בעל שם ב-BigQuery לאותו משתנה, כמו @state.
בשדה parameters, מגדירים את השם, סוג הנתונים והתיאור של כל פרמטר.

דוגמאות

בדוגמאות הבאות מוסבר איך להגדיר שאילתות לדוגמה סטטיות ועם פרמטרים עבור מערך הנתונים של שדות התעופה של FAA.

HTTP

בבקשת HTTP ישירה, מספקים רשימה של אובייקטים example_query בשדה example_queries. לכל אובייקט, צריך לספק את המפתח naturalLanguageQuestion (השאלה שמשתמש עשוי לשאול) ואת המפתח sqlQuery התואם. בשביל שאילתות עם פרמטרים, צריך לספק גם parameters רשימה שכוללת את השם, סוג הנתונים והתיאור של כל פרמטר.

"example_queries": [
  {
    "naturalLanguageQuestion": "How many airports are there?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
  },
  {
    "naturalLanguageQuestion": "How many airports are in {state} with an elevation that is greater than {elevation}?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
    "parameters": [
      {
        "name": "state",
        "dataType": "STRING",
        "description": "The state abbreviation in lowercase.",
      },
      {
        "name": "elevation",
        "dataType": "FLOAT64",
        "description": "The elevation in feet.",
      }
    ]
  }
]

Python SDK

כשמשתמשים ב-Python SDK, צריך לספק רשימה של אובייקטים מסוג ExampleQuery. לכל אובייקט, מציינים ערכים לפרמטר natural_language_question (השאלה שמשתמש עשוי לשאול) ולפרמטרים sql_query. בשביל שאילתות עם פרמטרים, צריך לספק גם רשימה של אובייקטים מסוג QueryParameter.

example_queries = [
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are there?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
    ),
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are in {state} with an elevation that is greater than {elevation}?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
        parameters=[
            geminidataanalytics.QueryParameter(
                name="state",
                data_type="STRING",
                description="The state abbreviation in lowercase.",
            ),
            geminidataanalytics.QueryParameter(
                name="elevation",
                data_type="FLOAT64",
                description="The elevation in feet.",
            ),
        ],
    )
]

פונקציות בהגדרת המשתמש

אפשר לספק פונקציות בהגדרת המשתמש (UDF) ל-BigQuery בהקשר של הסוכן באמצעות השדה user_functions. כשמספקים פרוצדורות מותאמות אישית של BigQuery, הסוכן יכול להשתמש בהן אם הוא צריך אותן כדי לענות על שאלה.

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

‫routineReference: הפניה לשגרה של BigQuery שכוללת את מזהה הפרויקט, מזהה קבוצת הנתונים ומזהה השגרה. כדי להשתמש בשגרה באזור אחר מנקודת קצה ל-API (לדוגמה, אם אתם ניגשים לטבלה באזור us-east4 מנקודת קצה ל-API מרובה האזורים us), צריך לציין את האזור הזה בשדה boundaryLocationId.
‫description: סיכום של התנהגות הפונקציה שמשמש את הסוכן כדי לקבוע מתי הפונקציה מתאימה לתשובה.

בדוגמאות הבאות מוצגות דרכים לספק פונקציות בהגדרת המשתמש באמצעות בקשות HTTP ישירות ועם Python SDK.

HTTP

בבקשת HTTP ישירה, צריך לספק אובייקט user_functions שמכיל רשימה של bqRoutines. כל אובייקט ברשימה חייב להכיל מאפיין routineReference ושדה description.

"user_functions": {
  "bqRoutines": [
    {
      "routineReference": {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "routineId": "my_custom_function"
      },
      "description": "Calculates adjusted revenue by using custom logic."
    }
  ]
}

Python SDK

כשמשתמשים ב-Python SDK, אפשר להגדיר את השגרה הזו על ידי הקצאת רשימה של אובייקטים מסוג BigQueryRoutine למאפיין bq_routines של אובייקט מסוג UserFunctions שמוסיפים להקשר של הסוכן.

# Define a BigQuery routine (UDF)
bq_routine = geminidataanalytics.BigQueryRoutine()
bq_routine.routine_reference.project_id = "bigquery-public-data"
bq_routine.routine_reference.dataset_id = "thelook_ecommerce"
bq_routine.routine_reference.routine_id = "my_custom_function"
bq_routine.description = "Calculates adjusted revenue by using custom logic."

# Add the routine to the agent's context
user_functions = geminidataanalytics.UserFunctions()
user_functions.bq_routines = [bq_routine]

# Assign to context
context.user_functions = user_functions

הגדרת הקשר נוסף בהוראות המערכת

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

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

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

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
  - table: # Details about a single table that is relevant for the agent.
    - name: str # The name of the table.
    - fields: # Details about columns (fields) within the table.
      - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.
  - relationships: # A list of join relationships between tables.
    - relationship: # Details about a single join relationship.
      - name: str # The name of this join relationship.
      - description: str # A description of the relationship.
      - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
      - join_type: str # The join type: inner, outer, left, right, or full.
      - left_table: str # The name of the left table in the join.
      - right_table: str # The name of the right table in the join.
      - relationship_columns: # A list of columns that are used for the join.
        - left_column: str # The join column from the left table.
        - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
  - glossary: # The definition for a single glossary item.
    - term: str # The term, phrase, or abbreviation to define.
    - description: str # A description or definition of the term.
    - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
  - text: str # Any additional general instructions or context not covered elsewhere.

בקטעים הבאים מופיעות דוגמאות לרכיבים מרכזיים בהוראות המערכת:

system_instruction
tables
relationships
glossaries
additional_descriptions

`system_instruction`

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

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

-   system_instruction: You are an expert sales analyst for a fictitious
    ecommerce store. You will answer questions about sales, orders, and customer
    data. Your responses should be concise and data-driven.

`tables`

כשמגדירים את המאפיינים הבסיסיים של טבלה (כמו התיאור והמילים הנרדפות שלה) כהקשר מובנה, אפשר גם להשתמש במפתח tables בהוראות המערכת כדי לספק לוגיקה עסקית משלימה. במקורות נתונים של BigQuery, זה כולל שימוש במפתח fields כדי להגדיר את ברירת המחדל aggregations לעמודות ספציפיות.

בדוגמה הבאה של בלוק קוד YAML אפשר לראות איך משתמשים במפתח tables בהוראות המערכת כדי להוסיף שדות שמספקים הנחיות נוספות לטבלה bigquery-public-data.thelook_ecommerce.orders:

-   tables:
  -   table:
    -   name: bigquery-public-data.thelook_ecommerce.orders
    -   fields:
      -   field:
        -   name: num_of_items
        -   aggregations: 'sum, avg'

`relationships`

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

לדוגמה, אפשר להגדיר קשר גומלין orders_to_user בין הטבלה bigquery-public-data.thelook_ecommerce.orders לבין הטבלה bigquery-public-data.thelook_ecommerce.users באופן הבא:

-   relationships:
  -   relationship:
    -   name: orders_to_user
    -   description: >-
        Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
    -   relationship_type: many-to-one
    -   join_type: left
    -   left_table: bigquery-public-data.thelook_ecommerce.orders
    -   right_table: bigquery-public-data.thelook_ecommerce.users
    -   relationship_columns:
      -   left_column: user_id
      -   right_column: id

`glossaries`

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

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

- glossaries:
  - glossary:
    - term: complete
    - description: Represents an order status where the order has been completed.
    - synonyms: 'finish, done, fulfilled'
  - glossary:
    - term: shipped
    - description: Represents an order status where the order has been shipped to the customer.
  - glossary:
    - term: returned
    - description: Represents an order status where the customer has returned the order.
  - glossary:
    - term: OMPF
    - description: Order Management and Product Fulfillment

`additional_descriptions`

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

לדוגמה, אפשר להשתמש במפתח additional_descriptions כדי לספק מידע על הארגון באופן הבא:

-   additional_descriptions:
  -   text: All the sales data pertains to The Look, a fictitious ecommerce store.
  -   text: 'Orders can be of three categories: food, clothes, and electronics.'

דוגמה: הקשר שנוצר לסוכן מכירות

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

דוגמה: הקשר מובנה

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

HTTP

בדוגמה הבאה מוצג אופן ההגדרה של הקשר מובנה בבקשת HTTP:

{
  "bq": {
    "tableReferences": [
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "orders",
        "schema": {
          "description": "Data for orders in The Look, a fictitious ecommerce store.",
          "synonyms": ["sales"],
          "tags": ["sale", "order", "sales_order"],
          "fields": [
            {
              "name": "status",
              "description": "The current status of the order."
            },
            {
              "name": "num_of_items",
              "description": "The number of items in the order."
            }
          ]
        }
      },
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "users",
        "schema": {
          "description": "Data for users in The Look, a fictitious ecommerce store.",
          "synonyms": ["customers"],
          "tags": ["user", "customer", "buyer"],
          "fields": [
            {
              "name": "first_name",
              "description": "The first name of the user.",
              "tags": ["person"]
            },
            {
              "name": "last_name",
              "description": "The last name of the user.",
              "tags": ["person"]
            },
            {
              "name": "age_group",
              "description": "The age demographic group of the user."
            },
            {
              "name": "email",
              "description": "The email address of the user.",
              "tags": ["contact"]
            }
          ]
        }
      }
    ]
  },
  "example_queries": [
    {
      "naturalLanguageQuestion": "How many orders are there?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`"
    },
    {
      "naturalLanguageQuestion": "How many orders were shipped?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'"
    },
    {
      "naturalLanguageQuestion": "How many unique customers are there?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`"
    },
    {
      "naturalLanguageQuestion": "How many users in the 25-34 age group have a cymbalgroup email address?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'"
    }
  ]
}

Python SDK

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

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    ),
    geminidataanalytics.Field(
        name="num_of_items",
        description="The number of items in the order."
    )
]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="last_name",
        description="The last name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="age_group",
        description="The age demographic group of the user.",
    ),
    geminidataanalytics.Field(
        name="email",
        description="The email address of the user.",
        tags=["contact"],
    )
]

# Define example queries
example_queries = [
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders are there?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders were shipped?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many unique customers are there?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many users in the 25-34 age group have a cymbalgroup email address?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'",
  )
]

דוגמה: הוראות מערכת

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

-   system_instruction: >-
    You are an expert sales analyst for a fictitious ecommerce store. You will answer questions about sales, orders, and customer data. Your responses should be concise and data-driven.
-   tables:
    -   table:
        -   name: bigquery-public-data.thelook_ecommerce.orders
        -   fields:
            -   field:
                -   name: num_of_items
                -   aggregations: 'sum, avg'
-   relationships:
    -   relationship:
        -   name: orders_to_user
        -   description: >-
            Connects customer order data to user information with the user_id and id fields.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.

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

אפשרויות להוספת הקשר שנכתב על ידיכם

הגדרת שדות של הקשר מובנה

הקשר מובנה ברמת הטבלה

HTTP

Python SDK

הקשר מובנה ברמת העמודה

HTTP

Python SDK

שאילתות לדוגמה

שאילתות לדוגמה שמכילות פרמטרים

דוגמאות

HTTP

Python SDK

פונקציות בהגדרת המשתמש

HTTP

Python SDK

הגדרת הקשר נוסף בהוראות המערכת

system_instruction

tables

relationships

glossaries

additional_descriptions

דוגמה: הקשר שנוצר לסוכן מכירות

דוגמה: הקשר מובנה

HTTP

Python SDK

דוגמה: הוראות מערכת

הגדרת הקשר של סוכן הנתונים למקורות נתונים של BigQuery

`system_instruction`

`tables`

`relationships`

`glossaries`

`additional_descriptions`