Auf dieser Seite wird die empfohlene Struktur für das Verfassen effektiver Prompts für Ihre Daten-Agenten für die Conversational Analytics API beschrieben. Diese Prompts sind Kontext, den Sie als Strings mit dem Parameter system_instruction definieren. Gut strukturierte Systemanweisungen können die Genauigkeit (Accuracy) und Relevanz der Antworten verbessern, die die API liefert.
Was sind Systemanweisungen?
Systemanweisungen sind benutzerdefinierte Anleitungen, die Entwickler bereitstellen können, um das Verhalten eines Daten-Agenten zu beeinflussen und die Antworten der API zu optimieren. Systemanweisungen sind Teil des Kontexts, den die API zum Beantworten von Fragen verwendet. Dieser Kontext umfasst auch verbundene Datenquellen (BigQuery-Tabellen, Looker-Explores, Looker Studio-Datenquellen) und den Unterhaltungsverlauf (für Multi-Turn-Unterhaltungen).
Wenn Sie durch Systemanweisungen klare, strukturierte Anleitungen geben, kann der Agent Nutzerfragen besser interpretieren und nützliche und genaue Antworten generieren. Gut definierte Systemanweisungen sind besonders nützlich, wenn Sie eine Verbindung zu Daten wie BigQuery-Tabellen herstellen, für die es möglicherweise keine vordefinierte semantische Ebene wie bei einem Looker-Explore gibt.
Sie können beispielsweise Systemanweisungen verwenden, um einem Agenten die folgenden Arten von Anleitungen zu geben:
- Unternehmensspezifische Logik: Einen treuen Kunden als jemanden definieren, der innerhalb eines bestimmten Zeitraums mehr als fünf Käufe getätigt hat.
- Antwortformatierung: Alle Antworten Ihres Daten-Agenten in maximal 20 Worten zusammenfassen, um Ihren Nutzern Zeit zu sparen.
- Datendarstellung: Alle Zahlen gemäß dem Styleguide des Unternehmens formatieren.
Systemanweisungen bereitstellen
Sie können der Conversational Analytics API Systemanweisungen als YAML-formatierte Zeichenfolge über den Parameter system_instruction bereitstellen. Der Parameter system_instruction ist zwar optional, aber es wird empfohlen, gut strukturierte Systemanweisungen anzugeben, um genaue und relevante Antworten zu erhalten.
Sie können den YAML-formatierten String in Ihrem Code bei der Ersteinrichtung definieren, wie unter Erste Einstellungen und Authentifizierung konfigurieren (HTTP) oder Abrechnungsprojekt und Systemanweisungen angeben (Python SDK) beschrieben. Sie können den system_instruction-Parameter dann in die folgenden API-Aufrufe einfügen:
- Nichtflüchtigen Daten-Agent erstellen: Fügen Sie den String
system_instructionin das Objektpublished_contextim Anfragetext ein, um das Agenten-Verhalten zu konfigurieren, das über mehrere Unterhaltungen hinweg beibehalten wird. Weitere Informationen finden Sie unter Daten-Agent erstellen (HTTP) oder Kontext für zustandsorientierten oder zustandslosen Chat einrichten (Python SDK). - Zustandslose Anfrage senden: Geben Sie den String
system_instructionim Objektinline_contextin der Chatanfrage an, um das Verhalten und den Kontext des Agenten für die Dauer dieses bestimmten API-Aufrufs zu definieren. Weitere Informationen finden Sie unter Zustandslose Multi-Turn Conversation erstellen (HTTP) oder Zustandslose Chatanfrage mit Inline-Kontext senden (Python SDK).
YAML-Vorlage für Systemanweisungen
Die folgende Vorlage zeigt die empfohlene YAML-Struktur für den String, den Sie für den Parameter system_instruction angeben, einschließlich der verfügbaren Schlüssel und erwarteten Datentypen. Ein Beispiel für eine Systemanweisung mit ausgefüllten Werten finden Sie unter Beispiel: Systemanweisungen.
Sie können die folgende YAML-Vorlage verwenden, um eigene Systemanweisungen anzugeben:
- 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.
- description: str # A description of the table.
- synonyms: list[str] # Alternative terms for referring to the table.
- tags: list[str] # Keywords or tags that are associated with 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.
- description: str # A description of the column.
- synonyms: list[str] # Alternative terms for referring to the column.
- tags: list[str] # Keywords or tags that are associated with the column.
- sample_values: list[str] # Sample values that are present within the column.
- aggregations: list[str] # Commonly used or default aggregations for the column.
- measures: # A list of calculated metrics (measures) for the table.
- measure: # Details about a single measure within the table.
- name: str # The name of the measure.
- description: str # A description of the measure.
- exp: str # The expression that is used to construct the measure.
- synonyms: list[str] # Alternative terms for referring to the measure.
- golden_queries: # A list of important or popular ("golden") queries for the table.
- golden_query: # Details about a single golden query.
- natural_language_query: str # The natural language query.
- sql_query: str # The SQL query that corresponds to the natural language query.
- golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
- golden_action_plan: # Details about a single action plan.
- natural_language_query: str # The natural language query.
- action_plan: # A list of the steps for this action plan.
- step: str # A single step within the action plan.
- 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.
Wichtige Komponenten von Systemanweisungen
In den folgenden Abschnitten werden die wichtigsten Komponenten von Systemanweisungen beschrieben und es wird erläutert, wie Sie sie verwenden können, um die Qualität der Antworten Ihres Agenten zu verbessern.
Rolle und Persona des Agenten mit system_instruction definieren
Definieren Sie die Rolle und Persona des Agenten mit dem Schlüssel system_instruction. Mit dieser ersten Anweisung werden Ton und Stil für die Antworten der API festgelegt und dem Agenten wird sein Hauptzweck verdeutlicht.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel system_instrucction:
- system_instruction: str
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.
Daten mit tables beschreiben
Der Schlüssel tables enthält eine Liste mit Tabellenbeschreibungen für den Agenten und Details zu den spezifischen Daten, die dem Agenten zum Beantworten von Fragen zur Verfügung stehen. Jedes table-Objekt in dieser Liste enthält die Metadaten für eine bestimmte Tabelle, einschließlich des Namens, der Beschreibung, der Synonyme, der Tags, der Felder, der Messwerte, der Golden Queries und der Golden Action Plans dieser Tabelle.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel tables:
- tables:
- table:
- name: str # The name of the table.
- description: str # A description of the table.
- synonyms: list[str] # Alternative terms for referring to the table.
- tags: list[str] # Keywords or tags that are associated with the table.
- fields: # A list of the fields in the table.
- measures: # A list of the measures in the table.
- golden_queries: # A list of golden queries for the table.
- golden_action_plans: # A list of golden action plans for the table.
Der folgende YAML-Codeblock zeigt beispielsweise die grundlegende Struktur für den Schlüssel tables für die Tabelle bigquery-public-data.thelook_ecommerce.orders:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- description: Data for customer orders in The Look fictitious e-commerce store.
- synonyms:
- sales
- orders_data
- tags:
- ecommerce
- transaction
Häufig verwendete Felder mit fields beschreiben
Der Schlüssel fields, der in einem table-Objekt verschachtelt ist, enthält eine Liste von Feldobjekten 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.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel fields:
- 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.
- description: str # A description of the column.
- synonyms: list[str] # Alternative terms for referring to the column.
- tags: list[str] # Keywords or tags that are associated with the column.
- sample_values: list[str] # Sample values that are present within the column.
- aggregations: list[str] # Commonly used or default aggregations for the column.
Im folgenden YAML-Beispielcode werden beispielsweise die wichtigsten Felder wie order_id, status, created_at, num_of_items und earnings für die Tabelle orders beschrieben:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- fields:
- field:
- name: order_id
- description: The unique identifier for each customer order.
- field:
- name: user_id
- description: The unique identifier for each customer.
- field:
- name: status
- description: The current status of the order.
- sample_values:
- complete
- shipped
- returned
- field:
- name: created_at
- description: The timestamp when the order was created.
- field:
- name: num_of_items
- description: The total number of items in the order.
- aggregations:
- sum
- avg
- field:
- name: earnings
- description: The sales amount for the order.
- aggregations:
- sum
- avg
Geschäftliche Messwerte mit measures definieren
Mit dem measures-Schlüssel, der in einem table-Objekt verschachtelt ist, werden benutzerdefinierte geschäftliche Messwerte oder Berechnungen definiert, die nicht direkt als Spalten in Ihren Tabellen vorhanden sind. Wenn Sie Kontext für Ergebnisse angeben, kann der Agent Fragen zu Leistungskennzahlen (KPIs) oder anderen berechneten Werten beantworten.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel measures:
- measures: # A list of calculated metrics (measures) for the table.
- measure: # Details about a single measure within the table.
- name: str # The name of the measure.
- description: str # A description of the measure.
- exp: str # The expression that is used to construct the measure.
- synonyms: list[str] # Alternative terms for referring to the measure.
Sie können beispielsweise einen profit-Messwert als Berechnung des Umsatzes abzüglich der Kosten definieren:
- tables:
- table:
- name: bigquery-public-data.thelook_ecommerce.orders
- measures:
- measure:
- name: profit
- description: Raw profit (earnings minus cost).
- exp: earnings - cost
- synonyms:
- gains
Genauigkeit mit golden_queries verbessern
Der Schlüssel golden_queries, der in einem table-Objekt verschachtelt ist, akzeptiert eine Liste von golden_query-Objekten. Mithilfe von Golden Queries kann der Agent genauere und relevantere Antworten auf häufige oder wichtige Fragen geben. Wenn Sie dem Agenten sowohl eine Anfrage in natürlicher Sprache als auch die entsprechende SQL-Abfrage für jede Golden Query zur Verfügung stellen, können Sie ihn anleiten, qualitativ hochwertige und konsistente Ergebnisse zu liefern.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel golden_queries:
- golden_queries: # A list of important or popular ("golden") queries for the table.
- golden_query: # Details about a single golden query.
- natural_language_query: str # The natural language query.
- sql_query: str # The SQL query that corresponds to the natural language query.
Sie können beispielsweise Gold-Abfragen für häufige Analysen für die Daten in der Tabelle orders so definieren:
- tables:
- table:
- golden_queries:
- golden_query:
- natural_language_query: How many orders are there?
- sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
- golden_query:
- natural_language_query: How many orders were shipped?
- sql_query: >-
SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
WHERE status = 'shipped'
Mehrstufige Aufgaben mit golden_action_plans skizzieren
Der Schlüssel golden_action_plans, der in einem table-Objekt verschachtelt ist, akzeptiert eine Liste von golden_action_plan-Objekten. Mit goldenen Aktionsplänen können Sie dem Agenten Beispiele dafür geben, wie er Anfragen mit mehreren Schritten verarbeiten soll, z. B. Daten abrufen und dann eine Visualisierung erstellen.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel golden_action_plans:
- golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
- golden_action_plan: # Details about a single action plan.
- natural_language_query: str # The natural language query.
- action_plan: # A list of the steps for this action plan.
- step: str # A single step within the action plan.
Sie können beispielsweise einen Aktionsplan definieren, um Aufschlüsselungen von Bestellungen nach Altersgruppe zu präsentieren, und Details zur SQL-Abfrage und zu den Schritten für die Visualisierung einfügen:
- tables:
- table:
- golden_action_plans:
- golden_action_plan:
- natural_language_query: Show me the number of orders broken down by age group.
- action_plan:
- step: >-
Run a SQL query that joins the table
sqlgen-testing.thelook_ecommerce.orders and
sqlgen-testing.thelook_ecommerce.users to get a
breakdown of order count by age group.
- step: >-
Create a vertical bar plot using the retrieved data,
with one bar per age group.
Tabellenverknüpfungen mit relationships definieren
Der Schlüssel relationships 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.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel relationships:
- relationships: # A list of join relationships between tables.
- relationship: # Details for a single join relationship.
- name: str # A unique name for this join relationship.
- description: str # A description of the relationship.
- relationship_type: str # The join relationship type (e.g., "one-to-one", "one-to-many", "many-to-one", "many-to-many").
- join_type: str # The join type (e.g., "inner", "outer", "left", "right", "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.
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
Geschäftsbedingungen mit glossaries erläutern
Unter glossaries 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.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel glossaries:
- 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.
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
Weitere Anweisungen mit additional_descriptions einfügen
Unter dem Schlüssel additional_descriptions werden alle zusätzlichen allgemeinen Anweisungen oder der Kontext aufgeführt, die nicht an anderer Stelle in den Systemanweisungen behandelt werden. Wenn Sie zusätzliche Beschreibungen angeben, kann der Agent den Kontext Ihrer Daten und Ihres Anwendungsfalls besser verstehen.
Der folgende YAML-Codeblock zeigt die grundlegende Struktur für den Schlüssel additional_descriptions:
- additional_descriptions: # A list of any other general instructions or content.
- text: str # Any additional general instructions or context not covered elsewhere.
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: Systemanweisungen
Das folgende Beispiel zeigt Beispielsystemanweisungen für einen fiktiven Agent für die Vertriebsanalyse.
- 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
- description: Data for orders in The Look, a fictitious ecommerce store.
- synonyms: sales
- tags: 'sale, order, sales_order'
- fields:
- field:
- name: order_id
- description: The unique identifier for each customer order.
- field:
- name: user_id
- description: The unique identifier for each customer.
- field:
- name: status
- description: The current status of the order.
- sample_values:
- complete
- shipped
- returned
- field:
- name: created_at
- description: >-
The date and time at which the order was created in timestamp
format.
- field:
- name: returned_at
- description: >-
The date and time at which the order was returned in timestamp
format.
- field:
- name: num_of_items
- description: The total number of items in the order.
- aggregations: 'sum, avg'
- field:
- name: earnings
- description: The sales revenue for the order.
- aggregations: 'sum, avg'
- field:
- name: cost
- description: The cost for the items in the order.
- aggregations: 'sum, avg'
- measures:
- measure:
- name: profit
- description: Raw profit (earnings minus cost).
- exp: earnings - cost
- synonyms: gains
- golden_queries:
- golden_query:
- natural_language_query: How many orders are there?
- sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
- golden_query:
- natural_language_query: How many orders were shipped?
- sql_query: >-
SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
WHERE status = 'shipped'
- golden_action_plans:
- golden_action_plan:
- natural_language_query: Show me the number of orders broken down by age group.
- action_plan:
- step: >-
Run a SQL query that joins the table
sqlgen-testing.thelook_ecommerce.orders and
sqlgen-testing.thelook_ecommerce.users to get a
breakdown of order count by age group.
- step: >-
Create a vertical bar plot using the retrieved data,
with one bar per age group.
- table:
- name: bigquery-public-data.thelook_ecommerce.users
- description: Data for users in The Look, a fictitious ecommerce store.
- synonyms: customers
- tags: 'user, customer, buyer'
- fields:
- field:
- name: id
- description: The unique identifier for each user.
- field:
- name: first_name
- description: The first name of the user.
- tag: person
- sample_values: 'alex, izumi, nur'
- field:
- name: last_name
- description: The first name of the user.
- tag: person
- sample_values: 'warmer, stilles, smith'
- field:
- name: age_group
- description: The age demographic group of the user.
- sample_values:
- 18-24
- 25-34
- 35-49
- 50+
- field:
- name: email
- description: The email address of the user.
- tag: contact
- sample_values: '222larabrown@gmail.com, cloudysanfrancisco@gmail.com'
- golden_queries:
- golden_query:
- natural_language_query: How many unique customers are there?
- sql_query: >-
SELECT COUNT(DISTINCT id) FROM
bigquery-public-data.thelook_ecommerce.users
- golden_query:
- natural_language_query: 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';
- 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:
- 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:
- text: All the sales data pertains to The Look, a fictitious ecommerce store.
- text: 'Orders can be of three categories: food, clothes, and electronics.'