Kontext für KI-Datenagenten für BigQuery-Datenquellen definieren

Auf dieser Seite wird beschrieben, wie Sie selbst erstellten Kontext für Daten-Agents bereitstellen, die BigQuery-Datenquellen verwenden.

Der selbst erstellte Kontext ist eine Anleitung, die Daten-KI-Agent-Inhaber bereitstellen können, um das Verhalten eines Daten-KI-Agenten zu beeinflussen und die Antworten der API zu optimieren. Ein effektiver selbst erstellter Kontext liefert Ihren Daten-KI-Agenten der Conversational Analytics API nützliche Informationen, um Fragen zu Ihren Datenquellen zu beantworten.

Selbst erstellter Kontext ist zwar optional, aber wenn Sie einen aussagekräftigen Kontext angeben, kann der KI-Agent genauere und relevantere Antworten liefern. Ihr Daten-Agent berücksichtigt diesen Kontext bei der Erstellung und Laufzeit, um sicherzustellen, dass seine Aktionen, Anfragen und Antworten genau, konform und geschäftsorientiert sind. Dieser Kontext wird aufgenommen, indexiert und verwendet, um das Verhalten des KI-Agenten zu beeinflussen.

Optionen zum Bereitstellen von selbst erstelltem Kontext

Für BigQuery-Datenquellen können Sie selbst erstellten Kontext über eine Kombination aus strukturiertem Kontext und Systemanweisungen bereitstellen. Stellen Sie nach Möglichkeit Kontext über strukturierte Kontextfelder bereit. Verwenden Sie dann den Parameter system_instruction für zusätzliche Anleitungen, die nicht von den strukturierten Feldern abgedeckt werden, z. B. um den Ton oder das allgemeine Verhalten eines KI-Agenten zu definieren.

Nachdem Sie die strukturierten Felder und Systemanweisungen definiert haben, aus denen Ihr selbst erstellter Kontext besteht, können Sie diesen Kontext in einem der folgenden Aufrufe an die API übergeben:

Felder für strukturierten Kontext definieren

In diesem Abschnitt wird beschrieben, wie Sie einem Daten-KI-Agenten mithilfe strukturierter Kontextfelder Kontext bereitstellen. Sie können einem KI-Agenten folgende Informationen als strukturierten Kontext zur Verfügung stellen:

  • Strukturierter Kontext auf Tabellenebene, einschließlich einer Beschreibung, Synonymen und Tags für eine Tabelle
  • Strukturierter Kontext auf Spaltenebene, einschließlich einer Beschreibung, Synonymen, Tags und Beispielwerte für die Spalten der Tabelle
  • Beispielabfragen, mit denen Sie Fragen in natürlicher Sprache und entsprechende SQL-Abfragen bereitstellen können, die der KI-Agent zum Beantworten von Fragen und zum Zitieren in seinen Antworten verwenden kann
  • Benutzerdefinierte Funktionen, mit denen Sie benutzerdefinierte BigQuery-Routinen bereitstellen können, die der Agent in seinen SQL-Abfragen verwenden kann

Strukturierter Kontext auf Tabellenebene

Verwenden Sie den Schlüssel tableReferences, um einem Agenten Details zu den spezifischen Tabellen zu geben, die zum Beantworten von Fragen zur Verfügung stehen. Für jede Tabellenreferenz können Sie die folgenden strukturierten Kontextfelder verwenden, um das Schema einer Tabelle zu definieren:

  • description: Eine Zusammenfassung des Inhalts und Zwecks der Tabelle
  • synonyms: Eine Liste alternativer Begriffe, die für die Tabelle verwendet werden können
  • tags: Eine Liste von Keywords oder Tags, die der Tabelle zugeordnet sind.

Die folgenden Beispiele zeigen, wie Sie diese Eigenschaften als strukturierten Kontext in direkten HTTP-Anfragen und mit dem Python SDK angeben.

HTTP

Bei einer direkten HTTP-Anfrage geben Sie diese Eigenschaften auf Tabellenebene im Objekt schema für die entsprechende Tabellenreferenz an. Ein vollständiges Beispiel für die Strukturierung der vollständigen Anfragenutzlast finden Sie unter Verbindung zu BigQuery-Daten herstellen.

"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

Wenn Sie das Python SDK verwenden, können Sie diese Eigenschaften auf Tabellenebene für die schema-Eigenschaft eines BigQueryTableReference-Objekts definieren. Das folgende Beispiel zeigt, wie Sie Tabellenreferenzobjekte erstellen, die Kontext für die Tabellen orders und users liefern. Ein vollständiges Beispiel für das Erstellen und Verwenden von Tabellenreferenzobjekten finden Sie unter Verbindung zu BigQuery-Daten herstellen.

# 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"]

Strukturierter Kontext auf Spaltenebene

Der Schlüssel fields, der im schema-Objekt einer Tabellenreferenz verschachtelt ist, enthält eine Liste von field-Objekten zur Beschreibung einzelner Spalten. Nicht für alle Felder ist zusätzlicher Kontext erforderlich. Bei häufig verwendeten Feldern kann es jedoch hilfreich sein, zusätzliche Details anzugeben, um die Leistung des KI-Agenten zu verbessern.

Für jedes field-Objekt können Sie die folgenden strukturierten Kontextfelder verwenden, um die grundlegenden Eigenschaften einer Spalte zu definieren:

  • description: Eine kurze Beschreibung des Inhalts und Zwecks der Spalte
  • synonyms: Eine Liste alternativer Begriffe, die verwendet werden können, um sich auf die Spalte zu beziehen
  • tags: Eine Liste von Keywords oder Tags, die der Spalte zugeordnet sind

Die folgenden Beispiele zeigen, wie Sie diese Eigenschaften als strukturierten Kontext für das Feld status in der Tabelle orders und für das Feld first_name in der Tabelle users mit direkten HTTP-Anfragen und mit dem Python SDK bereitstellen können.

HTTP

In einer direkten HTTP-Anfrage können Sie diese Eigenschaften auf Spaltenebene definieren, indem Sie eine Liste von fields-Objekten im schema-Objekt einer Tabellenreferenz angeben.

"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

Wenn Sie das Python SDK verwenden, können Sie diese Eigenschaften auf Spaltenebene definieren, indem Sie der fields-Eigenschaft der schema-Eigenschaft einer Tabelle eine Liste von Field-Objekten zuweisen.

# 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"],
    )
]

Beispielabfragen

Der Schlüssel example_queries akzeptiert eine Liste von example_query-Objekten, um Abfragen in natürlicher Sprache zu definieren, die dem KI-Agenten helfen, genauere und relevantere Antworten zu geben. Wenn Sie dem KI-Agenten sowohl eine Frage in natürlicher Sprache als auch die entsprechende SQL-Abfrage zur Verfügung stellen, können Sie ihn anleiten, qualitativ hochwertige und konsistente Ergebnisse zu liefern.

Wenn die Frage eines Nutzers semantisch mit einer definierten Beispielanfrage übereinstimmt, führt der Agent diese Anfrage möglicherweise direkt aus, anstatt eine neue zu generieren. Wenn ein Agent eine vorhandene Abfrage ausführt, enthält die API-Antwort ein matched_query-Objekt, das angibt, dass eine bestätigte Abfrage verwendet wurde. Der Agent kann diese Abfrage auch in seiner Antwort zitieren.

Beispielabfragen mit Parametern

Zusätzlich zu statischen Anfragen können Sie parametrisierte Beispielanfragen definieren, mit denen der Agent dynamische Werte in eine bestätigte Anfragevorlage einfügen kann. Wenn Sie Parameter in Ihre Beispielabfragen einfügen, können Sie flexible Vorlagen erstellen, die ein breiteres Spektrum von Nutzeranfragen abdecken als statische Beispiele. Wenn die Frage eines Nutzers mit einer Vorlage übereinstimmt, führt der Agent die entsprechende Anfrage aus, um eine bestätigte Antwort zu geben.

So definieren Sie eine parametrisierte Abfrage:

  1. Verwenden Sie im Feld naturalLanguageQuestion geschweifte Klammern für Platzhalter, z. B. {state}.
  2. Verwenden Sie im Feld sqlQuery die BigQuery-Syntax für benannte Parameter für dieselbe Variable, z. B. @state.
  3. Definieren Sie im Feld parameters den Namen, den Datentyp und die Beschreibung der einzelnen Parameter.

Beispiele

Die folgenden Beispiele zeigen, wie Sie sowohl statische als auch parametrisierte Beispielabfragen für das FAA-Flughafen-Dataset definieren.

HTTP

Geben Sie bei einer direkten HTTP-Anfrage eine Liste von example_query-Objekten im Feld example_queries an. Geben Sie für jedes Objekt den naturalLanguageQuestion-Schlüssel (die Frage, die ein Nutzer stellen könnte) und den entsprechenden sqlQuery-Schlüssel an. Bei parametrisierten Abfragen müssen Sie auch eine parameters-Liste mit dem Namen, dem Datentyp und der Beschreibung jedes Parameters angeben.

"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

Wenn Sie das Python SDK verwenden, geben Sie eine Liste von ExampleQuery-Objekten an. Geben Sie für jedes Objekt Werte für den Parameter natural_language_question (die Frage, die ein Nutzer stellen könnte) und die Parameter sql_query an. Bei parametrisierten Abfragen müssen Sie auch eine Liste von QueryParameter-Objekten angeben.

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.",
            ),
        ],
    )
]

Benutzerdefinierte Funktionen

Sie können benutzerdefinierte Funktionen (UDFs) für BigQuery im Agent-Kontext über das Feld user_functions bereitstellen. Wenn Sie benutzerdefinierte BigQuery-Routinen bereitstellen, kann der Agent sie verwenden, wenn sie zur Beantwortung einer Frage erforderlich sind.

Für jede benutzerdefinierte Funktion können Sie die folgenden Attribute angeben:

  • routineReference: Eine Referenz zur BigQuery-Routine, die die Projekt-ID, die Dataset-ID und die Routine-ID enthält. Wenn Sie eine Routine in einer anderen Region als Ihrem API-Endpunkt verwenden möchten (z. B. wenn Sie über den multiregionalen API-Endpunkt us auf eine Tabelle in der Region us-east4 zugreifen), geben Sie diese Region im Feld boundaryLocationId an.
  • description: Eine Zusammenfassung des Verhaltens der Funktion, die vom KI-Agenten verwendet wird, um zu bestimmen, wann die Funktion für eine Antwort geeignet ist.

Die folgenden Beispiele zeigen, wie Sie benutzerdefinierte Funktionen mit direkten HTTP-Anfragen und mit dem Python SDK bereitstellen.

HTTP

Geben Sie bei einer direkten HTTP-Anfrage ein user_functions-Objekt an, das eine bqRoutines-Liste enthält. Jedes Objekt in der Liste muss ein routineReference-Attribut und ein description-Feld enthalten.

"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

Wenn Sie das Python SDK verwenden, können Sie diese Routinen definieren, indem Sie der bq_routines-Eigenschaft eines UserFunctions-Objekts, das dem Kontext Ihres Agenten hinzugefügt wird, eine Liste von BigQueryRoutine-Objekten zuweisen.

# 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

Zusätzlichen Kontext in Systemanweisungen definieren

Mit dem Parameter system_instruction können Sie zusätzliche Anleitungen für Kontext bereitstellen, der nicht von strukturierten Kontextfeldern unterstützt wird. Wenn Sie zusätzliche Anleitungen angeben, kann der KI-Agent den Kontext Ihrer Daten und Ihres Anwendungsfalls besser verstehen.

Systemanweisungen bestehen aus einer Reihe von Schlüsselkomponenten und ‑objekten, die dem Daten-KI-Agenten Details zur Datenquelle und Anleitungen zur Rolle des KI-Agenten beim Beantworten von Fragen liefern. Sie können dem Daten-KI-Agenten Systemanweisungen als YAML-formatierte Zeichenfolge über den Parameter system_instruction bereitstellen.

Die folgende Vorlage zeigt eine vorgeschlagene YAML-Struktur für den String, den Sie für den Parameter system_instruction für eine BigQuery-Datenquelle angeben können, einschließlich der verfügbaren Schlüssel und erwarteten Datentypen. Diese Vorlage bietet eine vorgeschlagene Struktur mit wichtigen Komponenten zum Definieren von Systemanweisungen. Sie enthält jedoch nicht alle möglichen Formate für Systemanweisungen.

- 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.

Die folgenden Abschnitte enthalten Beispiele für wichtige Komponenten von Systemanweisungen:

system_instruction

Verwenden Sie den Schlüssel system_instruction, um die Rolle und Persona des KI-Agenten zu definieren. Mit dieser ersten Anweisung werden Ton und Stil für die Antworten der API festgelegt und dem KI-Agenten wird sein Hauptzweck verdeutlicht.

Sie können einen KI-Agenten beispielsweise als Vertriebsanalyst für ein fiktives E-Commerce-Unternehmen definieren:

-   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

Die grundlegenden Eigenschaften einer Tabelle, z. B. die Beschreibung und die Synonyme, definieren Sie als strukturierten Kontext. Sie können den Schlüssel tablesaber auch in Systemanweisungen verwenden, um zusätzliche Geschäftslogik anzugeben. Bei BigQuery-Datenquellen können Sie mit dem Schlüssel fields Standardwerte für aggregations für bestimmte Spalten definieren.

Der folgende YAML-Beispielcodeblock zeigt, wie Sie den Schlüssel tables in Ihren Systemanweisungen verwenden können, um Felder zu verschachteln, die zusätzliche Anleitungen für die Tabelle bigquery-public-data.thelook_ecommerce.orders enthalten:

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

relationships

Der Schlüssel relationships in Ihren Systemanweisungen enthält eine Liste von Join-Beziehungen zwischen Tabellen. Wenn Sie Join-Beziehungen definieren, können Sie dem KI-Agenten helfen, zu verstehen, wie Daten aus mehreren Tabellen zusammengeführt werden müssen, um Fragen zu beantworten.

Sie können beispielsweise eine orders_to_user-Beziehung zwischen der Tabelle bigquery-public-data.thelook_ecommerce.orders und der Tabelle bigquery-public-data.thelook_ecommerce.users so definieren:

-   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

Unter glossaries in Ihren Systemanweisungen finden Sie Definitionen für geschäftliche Begriffe, Fachsprache und Abkürzungen, die für Ihre Daten und Ihren Anwendungsfall relevant sind. Wenn Sie Glossardefinitionen angeben, können Sie dem KI-Agenten helfen, Fragen mit spezifischer Geschäftssprache richtig zu interpretieren und zu beantworten. Wenn ein Agent einen Glossarbegriff verwendet, um auf eine Frage zu antworten, wird dieser Begriff möglicherweise in der Antwort zitiert.

So können Sie beispielsweise Begriffe wie allgemeine Unternehmensstatus und „OMPF“ (Order Management and Product Fulfillment) entsprechend Ihrem spezifischen geschäftlichen Kontext so definieren:

- 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

Verwenden Sie den Schlüssel additional_descriptions, um allgemeine Anweisungen oder Kontexte anzugeben, die nicht in andere Felder für strukturierten Kontext oder Systemanweisungen passen. Wenn Sie zusätzliche Beschreibungen in Ihren Systemanweisungen angeben, kann der KI-Agent den Kontext Ihrer Daten und Ihres Anwendungsfalls besser verstehen.

Mit dem Schlüssel additional_descriptions können Sie beispielsweise Informationen zu Ihrer Organisation angeben:

-   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.'

Beispiel: Selbst erstellter Kontext für einen Vertriebsmitarbeiter

Das folgende Beispiel eines fiktiven Vertriebsanalysten zeigt, wie Sie mithilfe einer Kombination aus strukturiertem Kontext und Systemanweisungen einen selbst erstellten Kontext bereitstellen.

Beispiel: Strukturierter Kontext

Sie können strukturierten Kontext mit Details zu Tabellen, Spalten und Beispielabfragen bereitstellen, um den KI-Agenten zu unterstützen. Entsprechende Beispiele finden Sie nachfolgend für HTTP und Python SDK.

HTTP

Das folgende Beispiel zeigt, wie strukturierter Kontext in einer HTTP-Anfrage definiert wird:

{
  "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

Das folgende Beispiel zeigt, wie Sie mit dem Python SDK strukturierten Kontext definieren:

# 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'",
  )
]

Beispiel: Systemanweisungen

Die folgenden Systemanweisungen ergänzen den strukturierten Kontext, indem sie die Persona des KI-Agenten definieren und Anleitungen geben, die nicht durch strukturierte Felder unterstützt werden, z. B. Beziehungsdefinitionen, Glossarbegriffe, zusätzliche Beschreibungen und zusätzliche orders-Tabellendetails. Da die Tabelle users in diesem Beispiel vollständig mit strukturiertem Kontext definiert ist, muss sie in den Systemanweisungen nicht neu definiert werden.

-   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.