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

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

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

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

אפשרויות להוספת הקשר שנוצר על ידי משתמשים

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

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

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

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

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

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

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

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

HTTP

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

"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 ישירות ובאמצעות Python SDK.

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 שמציין שנעשה שימוש בשאילתה מאומתת. יכול להיות שהסוכן גם יצטט את השאילתה הזו בתשובה שלו.

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

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

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

  1. בשדה naturalLanguageQuestion, משתמשים בסוגריים מסולסלים לפלייסהולדרים, כמו {state}.
  2. בשדה sqlQuery, משתמשים בתחביר של הפרמטר בעל השם ב-BigQuery לאותו משתנה, למשל @state.
  3. בשדה 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)

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

לכל UDF, אפשר לספק את המאפיינים הבאים:

  • ‫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

משתמשים במפתח 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.