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

Erstellter Kontext ist eine Anleitung, die Eigentümer von Daten-Agents bereitstellen können, um das Verhalten eines Daten-Agents zu beeinflussen und die Antworten der API zu optimieren. Ein effektiver Kontext, den Sie selbst erstellen, liefert Ihren Daten-KI-Agenten der Conversational Analytics API nützliche Informationen, um Fragen zu Ihren Datenquellen zu beantworten.

Auf dieser Seite wird beschrieben, wie Sie selbst erstellten Kontext für BigQuery-Datenquellen bereitstellen. 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. Sie können dann den Parameter system_instruction für zusätzliche Anleitungen verwenden, die nicht von den strukturierten Feldern abgedeckt werden.

Sowohl strukturierte Kontextfelder als auch Systemanweisungen sind optional. Wenn Sie jedoch einen aussagekräftigen Kontext angeben, kann der Agent genauere und relevantere Antworten liefern.

Nachdem Sie die strukturierten Felder und Systemanweisungen definiert haben, aus denen Ihr 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-Agent mithilfe strukturierter Kontextfelder Kontext bereitstellen. Sie können einem Kundenservicemitarbeiter die folgenden Informationen als strukturierten Kontext zur Verfügung stellen:

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.

In den folgenden Beispielen wird gezeigt, 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 den entsprechenden Tabellenverweis an. Ein vollständiges Beispiel für die Strukturierung der vollständigen Anfrage-Payload 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. Im folgenden Beispiel wird gezeigt, 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 Mit BigQuery-Daten verbinden.

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

In den folgenden Beispielen wird gezeigt, 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 eines Tabellenverweises 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 Anfragen in natürlicher Sprache zu definieren, die dem Agenten helfen, genauere und relevantere Antworten auf häufige oder wichtige Fragen zu geben. Wenn Sie dem 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.

Für jedes example_query-Objekt können Sie die folgenden Felder angeben, um eine Frage in natürlicher Sprache und die entsprechende SQL-Abfrage zu definieren:

  • natural_language_question: Die Frage in natürlicher Sprache, die ein Nutzer stellen könnte
  • sql_query: Die SQL-Abfrage, die der Frage in natürlicher Sprache entspricht

Die folgenden Beispiele zeigen, wie Sie Beispielanfragen für die Tabelle orders sowohl mit direkten HTTP-Anfragen als auch mit dem Python SDK bereitstellen.

HTTP

Geben Sie bei einer direkten HTTP-Anfrage eine Liste von example_query-Objekten im Feld example_queries an. Jedes Objekt muss einen naturalLanguageQuestion-Schlüssel und einen entsprechenden sqlQuery-Schlüssel enthalten.

"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'"
  }
]

Python SDK

Wenn Sie das Python SDK verwenden, können Sie eine Liste von ExampleQuery-Objekten angeben. Geben Sie für jedes Objekt Werte für die Parameter natural_language_question und sql_query an.

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

Zusätzlichen Kontext in Systemanweisungen definieren

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

Systemanweisungen bestehen aus einer Reihe von Schlüsselkomponenten und ‑objekten, die dem KI-Datenagenten Details zur Datenquelle und Anleitungen zur Rolle des Agenten beim Beantworten von Fragen liefern. Sie können dem Daten-Agent 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, 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.

In den folgenden Abschnitten finden Sie Beispiele für wichtige Komponenten von Systemanweisungen:

system_instruction

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

Sie können einen 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 aber auch den Schlüssel tables 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 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 Agenten helfen, Fragen mit spezifischer Geschäftssprache richtig zu interpretieren und zu beantworten.

Sie können 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 Kontext anzugeben, die nicht in andere Felder für strukturierten Kontext oder Systemanweisungen passen. Wenn Sie zusätzliche Beschreibungen in Ihren Systemanweisungen angeben, kann der 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: Kontext für einen Vertriebsmitarbeiter

Das folgende Beispiel für einen fiktiven Agent für die Vertriebsanalyse zeigt, wie Sie mithilfe einer Kombination aus strukturiertem Kontext und Systemanweisungen einen vom Nutzer erstellten Kontext bereitstellen.

Beispiel: Strukturierter Kontext

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

HTTP

Im folgenden Beispiel sehen Sie, 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 Kundenservicemitarbeiters 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.