KI-Datenagenten mit dem Python SDK erstellen

Auf dieser Seite erfahren Sie, wie Sie mit dem Python SDK Anfragen an die Conversational Analytics API senden. Das Python-Codebeispiel zeigt, wie Sie die folgenden Aufgaben ausführen:

Umgebung authentifizieren und einrichten

Wenn Sie das Python SDK für die Conversational Analytics API verwenden möchten, folgen Sie der Anleitung im Colaboratory-Notebook für das Conversational Analytics API SDK. Dort erfahren Sie, wie Sie das SDK herunterladen und installieren. Die Downloadmethode und der Inhalt des SDK-Colab können sich ändern.

Nachdem Sie die Einrichtungsanleitung im Notebook ausgeführt haben, können Sie mit dem folgenden Code die erforderlichen SDK-Bibliotheken importieren, Ihr Google-Konto in einer Colaboratory-Umgebung authentifizieren und einen Client für API-Anfragen initialisieren:

from google.colab import auth
auth.authenticate_user()

from google.cloud import geminidataanalytics

data_agent_client = geminidataanalytics.DataAgentServiceClient()
data_chat_client = geminidataanalytics.DataChatServiceClient()

Abrechnungsprojekt und Systemanweisungen angeben

Im folgenden Python-Codebeispiel werden das Abrechnungsprojekt, der Standort und die Systemanweisungen definiert, die in Ihrem gesamten Script verwendet werden:

# Billing project
billing_project = "my_project_name"
location = "global"

# System instructions
system_instruction = "Help the user analyze their data."

Ersetzen Sie die Beispielwerte so:

  • my_project_name: die ID Ihres Abrechnungsprojekts, in dem die erforderlichen APIs aktiviert sind.
  • Help the user analyze their data.: Systemanweisungen, um das Verhalten des KI-Agenten zu steuern und an Ihre Datenanforderungen anzupassen. Sie können beispielsweise Systemanweisungen verwenden, um geschäftliche Begriffe zu definieren, die Länge der Antworten zu steuern oder die Datenformatierung festzulegen. Idealerweise definieren Sie Systemanweisungen im empfohlenen YAML-Format, das unter Effektive Systemanweisungen schreiben beschrieben wird, um detaillierte und strukturierte Anleitungen zu geben.

Mit einer Datenquelle verbinden

In den folgenden Abschnitten wird beschrieben, wie Sie die Verbindungsdetails für die Datenquellen Ihres KI-Agenten definieren. Ihr Agent kann auf folgende Weise eine Verbindung zu Daten herstellen:

Verbindung zu Looker-Daten herstellen

In den folgenden Codebeispielen wird gezeigt, wie Sie die Details für eine Verbindung zu einem Looker-Explore mit API-Schlüsseln oder einem Zugriffstoken definieren. Mit der Conversational Analytics API können Sie gleichzeitig Verbindungen zu bis zu fünf Looker-Explores herstellen.

Beachten Sie Folgendes, wenn Sie eine Verbindung zu einer Looker-Datenquelle herstellen:

  • Sie können in einer Unterhaltung jedes enthaltene Explore abfragen.
  • Ein KI-Agent kann jeweils nur ein Explore abfragen. Abfragen für mehrere Explores können nicht gleichzeitig ausgeführt werden.
  • Ein KI-Agent kann in derselben Unterhaltung mehrere Explores abfragen.

  • Ein Agent kann in einer Unterhaltung, die Fragen mit mehreren Teilen oder Folgefragen enthält, mehrere Explores abfragen.

    Beispiel: Ein Nutzer verbindet zwei Explores, eins mit dem Namen cat-explore und eins mit dem Namen dog-explore. Der Nutzer gibt die Frage „Was ist größer: die Anzahl der Katzen oder die Anzahl der Hunde?“ ein. Dadurch werden zwei Abfragen erstellt: eine zum Zählen der Anzahl der Katzen in cat-explore und eine zum Zählen der Anzahl der Hunde in dog-explore. Der KI-Agent vergleicht die Zahlen aus beiden Anfragen, nachdem beide Anfragen abgeschlossen sind.

Im folgenden Beispielcode wird eine Verbindung zu mehreren Looker-Explores definiert. Um die Leistung des KI-Agenten zu verbessern, können Sie optional Golden Queries als strukturierten Kontext für Ihre Explores bereitstellen. Weitere Informationen finden Sie unter Kontext für KI-Datenagenten für Looker-Datenquellen definieren.

API-Schlüssel

Sie können eine Verbindung zu einer Looker-Instanz mit generierten Looker API-Schlüsseln herstellen, wie unter Mit der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen beschrieben.

looker_client_id = "my_looker_client_id"
looker_client_secret = "my_looker_client_secret"
looker_instance_uri = "https://my_company.looker.com"
lookml_model_1 = "my_model"
explore_1 = "my_explore"
lookml_model_2 = "my_model_2"
explore_2 = "my_explore_2"

looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = "my_model"
looker_explore_reference.explore = "my_explore"

looker_explore_reference2 = geminidataanalytics.LookerExploreReference()
looker_explore_reference2.looker_instance_uri = looker_instance_uri
looker_explore_reference2.lookml_model = "my_model_2"
looker_explore_reference2.explore = "my_explore_2"

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference, looker_explore_reference2]

# Do not include the following line during agent creation
datasource_references.credentials = credentials

Ersetzen Sie die Beispielwerte so:

  • my_looker_client_id: die Client-ID Ihres generierten Looker API-Schlüssels.
  • my_looker_client_secret: der Clientschlüssel Ihres generierten Looker API-Schlüssels.
  • https://my_company.looker.com: die vollständige URL Ihrer Looker-Instanz.
  • my_model: der Name des LookML-Modells, das den Explore enthält, zu dem Sie eine Verbindung herstellen möchten.
  • my_explore: der Name des Looker-Explore, das vom KI-Datenagenten abgefragt werden soll.
  • my_model_2: der Name des zweiten LookML-Modells, das das Explore enthält, zu dem Sie eine Verbindung herstellen möchten. Sie können diese Variable für zusätzliche Modelle für bis zu fünf Explores wiederholen.
  • my_explore_2: der Name des zusätzlichen Looker-Explore, das vom KI-Datenagenten abgefragt werden soll. Sie können diese Variable wiederholen, um bis zu fünf Explores einzuschließen.

Zugriffstoken

Sie können eine Verbindung zu einer Looker-Instanz mit einem Zugriffstoken herstellen, wie unter Mit der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen beschrieben.

looker_access_token = "my_access_token"
looker_instance_uri = "https://my_company.looker.com"
lookml_model = "my_model"
explore = "my_explore"
lookml_model_2 = "my_model_2"
explore_2 = "my_explore_2"

looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = "my_model"
looker_explore_reference.explore = "my_explore"

looker_explore_reference2 = geminidataanalytics.LookerExploreReference()
looker_explore_reference2.looker_instance_uri = looker_instance_uri
looker_explore_reference2.lookml_model = "my_model_2"
looker_explore_reference2.explore = "my_explore_2"

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference, looker_explore_reference2]

# Do not include the following line during agent creation
datasource_references.credentials = credentials

Ersetzen Sie die Beispielwerte so:

  • my_access_token: der access_token-Wert, den Sie zur Authentifizierung bei Looker generieren.
  • https://my_company.looker.com: die vollständige URL Ihrer Looker-Instanz.
  • my_model: der Name des LookML-Modells, das den Explore enthält, zu dem Sie eine Verbindung herstellen möchten.
  • my_explore: der Name des Looker-Explore, das vom KI-Datenagenten abgefragt werden soll.
  • my_model_2: der Name des zweiten LookML-Modells, das das Explore enthält, zu dem Sie eine Verbindung herstellen möchten. Sie können diese Variable für zusätzliche Modelle für bis zu fünf Explores wiederholen.
  • my_explore_2: der Name des zusätzlichen Looker-Explore, das vom KI-Datenagenten abgefragt werden soll. Sie können diese Variable wiederholen, um bis zu fünf Explores einzuschließen.

Verbindung zu BigQuery-Daten herstellen

Bei der Conversational Analytics API gibt es keine strikten Grenzwerte für die Anzahl der BigQuery-Tabellen, zu denen Sie eine Verbindung herstellen können. Wenn Sie jedoch zu einer großen Anzahl an Tabellen eine Verbindung herstellen, kann dies die Accuracy beeinträchtigen oder dazu führen, dass das Eingabetokenlimit des Modells überschritten wird.

Mit dem folgenden Beispielcode wird eine Verbindung zu mehreren BigQuery-Tabellen definiert. Er enthält Beispiele für optionale strukturierte Kontextfelder. Um die Leistung des KI-Agenten zu verbessern, können Sie optional strukturierten Kontext für Ihre BigQuery-Tabellen bereitstellen, z. B. Tabellen- und Spaltenbeschreibungen, Synonyme, Tags und Beispielabfragen. Weitere Informationen finden Sie unter Kontext für KI-Datenagenten für BigQuery-Datenquellen definieren.

bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "my_project_id_1"
bigquery_table_reference_1.dataset_id = "my_dataset_id_1"
bigquery_table_reference_1.table_id = "my_table_id_1"
bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "my_table_description"
bigquery_table_reference_1.schema.fields = [
  geminidataanalytics.Field(
    name="my_column_name",
    description="my_column_description"
  )
]

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_table_id_3"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference_1, bigquery_table_reference_2, bigquery_table_reference_3]

Ersetzen Sie die Beispielwerte so:

  • my_project_id_1: die ID des Projekts in Google Cloud , das das BigQuery-Dataset und die BigQuery-Tabelle enthält, zu denen Sie eine Verbindung herstellen möchten. Wenn Sie eine Verbindung zu einem öffentlichen Dataset herstellen möchten, geben Sie bigquery-public-data an.
  • my_dataset_id_1: Die ID des BigQuery-Datasets. Beispiel: san_francisco.
  • my_table_id_1: Die ID der BigQuery-Tabelle. Beispiel: street_trees.
  • my_table_description: Eine optionale Beschreibung des Inhalts und des Zwecks der Tabelle.
  • my_column_name: der Name einer Spalte in der Tabelle, für die Sie eine optionale Beschreibung angeben.
  • my_column_description: Eine optionale Beschreibung des Inhalts und des Zwecks der Spalte.

Verbindung zu Data Studio-Daten herstellen

Im folgenden Beispielcode wird eine Verbindung zu einer Data Studio-Datenquelle definiert.

studio_datasource_id = "my_datasource_id"

studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id

## Connect to your data source
datasource_references.studio.studio_references = [studio_references]

Ersetzen Sie im vorherigen Beispiel my_datasource_id durch die Datenquellen-ID.

Verbindung zu AlloyDB-Daten herstellen

Im folgenden Beispielcode wird eine Verbindung zu einer AlloyDB-Datenbank mit dem Python SDK definiert.

# Define the AlloyDB database reference
alloydb_database_reference = geminidataanalytics.AlloyDbDatabaseReference()
alloydb_database_reference.project_id = "PROJECT_ID"
alloydb_database_reference.region = "REGION"
alloydb_database_reference.cluster_id = "CLUSTER_ID"
alloydb_database_reference.instance_id = "INSTANCE_ID"
alloydb_database_reference.database_id = "DATABASE"
alloydb_database_reference.table_ids = ["TABLE_1_ID", "TABLE_2_ID"]

# Optional: Include this if you have created advanced context for the agent
agent_context_reference = geminidataanalytics.AgentContextReference()
agent_context_reference.context_set_id = f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"

# Add the AlloyDB reference to the DatasourceReferences object
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.alloydb.database_reference = alloydb_database_reference
# Optional:
# datasource_references.alloydb.agent_context_reference = agent_context_reference

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: Die ID des Google Cloud -Projekts, das den AlloyDB-Cluster enthält.
  • REGION: Die Region, in der sich der AlloyDB-Cluster befindet, z. B. us-central1.
  • CLUSTER_ID: Die ID des AlloyDB-Clusters.
  • INSTANCE_ID: Die ID der AlloyDB-Instanz.
  • DATABASE: Der Name der Zieldatenbank, z. B. financial.
  • TABLE_1_ID, TABLE_2_ID: Eine Liste der Tabellen in der Datenbank, die der Daten-Agent verwenden soll, z. B. "loan", "client", "disp".
  • your_context_set_id: Wenn Sie erweiterten Kontext für den Agent erstellt haben, die ID Ihres Kontextsets.

Verbindung zu Cloud SQL for MySQL-Daten herstellen

Um eine Verbindung zu einer Cloud SQL for MySQL-Instanz herzustellen, verwenden Sie die Klasse CloudSqlReference aus dem geminidataanalytics SDK. Dazu müssen Sie das Projekt, die Instanz, die Datenbank und optional die spezifischen Tabellen angeben, die der Agent berücksichtigen soll.

Bevor Sie eine Verbindung zu Cloud SQL for MySQL-Daten herstellen, müssen Sie sich mit Identity and Access Management (IAM) bei Cloud SQL for MySQL authentifizieren. Weitere Informationen finden Sie unter Authentifizierung bei Cloud SQL for MySQL und Cloud SQL for PostgreSQL.

Im folgenden Beispiel wird eine Verbindung zu einer Cloud SQL for MySQL-Datenbank mit dem Python SDK definiert.

# Import the necessary library
from google.cloud import geminidataanalytics

# Define the Cloud SQL database reference
cloud_sql_database_reference = geminidataanalytics.CloudSqlDatabaseReference(
    project_id="PROJECT_ID",
    instance_id="INSTANCE_ID",
    database_id="DATABASE_ID",
    # Optional: Specify table IDs to guide the agent
    table_ids=["TABLE_1_ID", "TABLE_2_ID"]
)

# Create a CloudSqlReference object
cloud_sql_reference = geminidataanalytics.CloudSqlReference(
    database_reference=cloud_sql_database_reference
    # Optional: Include this if you have created advanced context for the agent
    # agent_context_reference=geminidataanalytics.AgentContextReference(
    # context_set_id=f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
    # )
)

# Add the Cloud SQL reference to the DatasourceReferences object
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloud_sql = cloud_sql_reference

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: Die ID des Google Cloud -Projekts, das die Cloud SQL for MySQL-Instanz enthält.
  • INSTANCE_ID: Die ID der Cloud SQL for MySQL-Instanz.
  • DATABASE_ID: Der Name der Zieldatenbank in der Instanz, z. B. financial.
  • TABLE_1_ID, TABLE_2_ID: (Optional) Eine Liste mit bestimmten Tabellennamen in der Datenbank, die der Data-Agent verwenden soll, z. B. "orders" und "customers".
  • your_context_set_id: Wenn Sie erweiterten Kontext für den Agent erstellt haben, die ID Ihres Kontextsets.

Sie können das datasource_references-Objekt verwenden, wenn Sie den Daten-Agenten erstellen oder mit ihm interagieren.

Verbindung zu Cloud SQL for PostgreSQL-Daten herstellen

Um eine Verbindung zu einer Cloud SQL for PostgreSQL-Instanz herzustellen, verwenden Sie die Klasse CloudSqlReference aus dem geminidataanalytics SDK. Dazu müssen Sie das Projekt, die Instanz, die Datenbank und optional die spezifischen Tabellen angeben, die der Agent berücksichtigen soll.

Bevor Sie eine Verbindung zu Cloud SQL for PostgreSQL-Daten herstellen, müssen Sie sich mit IAM bei Cloud SQL for PostgreSQL authentifizieren. Weitere Informationen finden Sie unter Authentifizierung bei Cloud SQL for MySQL und Cloud SQL for PostgreSQL.

Im folgenden Beispiel wird eine Verbindung zu einer Cloud SQL for PostgreSQL-Datenbank mit dem Python SDK definiert.

# Import the necessary library
from google.cloud import geminidataanalytics

# Define the Cloud SQL database reference
cloud_sql_database_reference = geminidataanalytics.CloudSqlDatabaseReference(
    project_id="PROJECT_ID",
    instance_id="INSTANCE_ID",
    database_id="DATABASE_ID",
    # Optional: Specify table IDs to guide the agent
    table_ids=["TABLE_1_ID", "TABLE_2_ID"]
)

# Create a CloudSqlReference object
cloud_sql_reference = geminidataanalytics.CloudSqlReference(
    database_reference=cloud_sql_database_reference
    # Optional: Include this if you have created advanced context for the agent
    # agent_context_reference=geminidataanalytics.AgentContextReference(
    # context_set_id=f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
    # )
)

# Add the Cloud SQL reference to the DatasourceReferences object
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloud_sql = cloud_sql_reference

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: Die ID des Google Cloud -Projekts, das die Cloud SQL for PostgreSQL-Instanz enthält.
  • INSTANCE_ID: Die ID der Cloud SQL for PostgreSQL-Instanz.
  • DATABASE_ID: Der Name der Zieldatenbank in der Instanz, z. B. postgres.
  • TABLE_1_ID, TABLE_2_ID: (Optional) Eine Liste mit bestimmten Tabellennamen in der Datenbank, die der Daten-Agent verwenden soll, z. B. "users" und "products".
  • your_context_set_id: Wenn Sie erweiterten Kontext für den Agent erstellt haben, die ID Ihres Kontextsets.

Sie können das datasource_references-Objekt verwenden, wenn Sie den Daten-Agenten erstellen oder mit ihm interagieren.

Verbindung zu Cloud Spanner-Daten herstellen

Zum Herstellen einer Verbindung zu einer Spanner-Instanz verwenden Sie die Klasse SpannerReference aus dem geminidataanalytics SDK. Dazu müssen Sie das Projekt, die Instanz, die Datenbank und optional die spezifischen Tabellen angeben, die der Agent berücksichtigen soll.

Bevor Sie eine Verbindung zu Spanner-Daten herstellen, müssen Sie dafür sorgen, dass der Nutzer oder das Dienstkonto die IAM-Rolle spanner.databaseReader hat. Weitere Informationen finden Sie unter IAM-Rollen anwenden.

Im folgenden Python-Beispielcode wird eine Verbindung zu einer Spanner-Datenbank mit dem Python SDK definiert.

# Import the necessary library
from google.cloud import geminidataanalytics

# Define the Spanner database reference
spanner_database_reference = geminidataanalytics.SpannerDatabaseReference(
    project_id="PROJECT_ID",
    instance_id="INSTANCE_ID",
    database_id="DATABASE_ID",
    # Optional: Specify table IDs to guide the agent
    table_ids=["TABLE_1_ID", "TABLE_2_ID"]
)

# Create a SpannerReference object
spanner_reference = geminidataanalytics.SpannerReference(
    database_reference=spanner_database_reference
    # Optional: Include this if you have created advanced context for the agent
    # agent_context_reference=geminidataanalytics.AgentContextReference(
    # context_set_id=f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
    # )
)

# Add the Spanner reference to the DatasourceReferences object
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.spanner = spanner_reference

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: Die ID des Google Cloud -Projekts, das die Cloud Spanner-Instanz enthält.
  • INSTANCE_ID: Die ID der Spanner-Instanz.
  • DATABASE_ID: Der Name der Zieldatenbank in der Instanz.
  • TABLE_1_ID, TABLE_2_ID: (Optional) Eine Liste mit bestimmten Tabellennamen in der Datenbank, die der Daten-Agent verwenden soll, z. B. "Singers" und "Albums".
  • your_context_set_id: Wenn Sie erweiterten Kontext für den Agent erstellt haben, die ID Ihres Kontextsets.

Sie können das datasource_references-Objekt verwenden, wenn Sie den Daten-Agenten erstellen oder mit ihm interagieren.

Kontext für zustandsorientierte oder zustandslose Chats einrichten

Die Conversational Analytics API unterstützt Multi-Turn-Unterhaltungen, bei denen Nutzer weiterführende Fragen stellen können, die auf dem vorherigen Kontext aufbauen. Das folgende Python-Codebeispiel zeigt, wie Sie den Kontext für zustandsorientierte oder zustandslose Chats einrichten:

  • Zustandsorientierter Chat: Google Cloud speichert und verwaltet den Unterhaltungsverlauf. Der zustandsorientierte Chat ist grundsätzlich ein Multi-Turn-Chat, da die API den Kontext aus vorangegangenen Nachrichten beibehält. Sie müssen nur Ihre aktuelle Nachricht senden, um die Unterhaltung am Laufen zu halten.
  • Zustandsloser Chat: Ihre Anwendung verwaltet den Unterhaltungsverlauf. Sie müssen den gesamten Unterhaltungsverlauf in jede neue Nachricht einfügen. Ausführliche Beispiele zum Verwalten von Multi-Turn-Unterhaltungen im zustandslosen Modus finden Sie unter Zustandslose Multi-Turn-Unterhaltung erstellen.

Zustandsorientierter Chat

Im folgenden Codebeispiel wird der Kontext für den zustandsorientierten Chat eingerichtet. Dabei speichert und verwaltet Google Cloud den Unterhaltungsverlauf. Optional können Sie auch die erweiterte Analyse mit Python aktivieren, indem Sie die Zeile published_context.options.analysis.python.enabled = True im folgenden Beispielcode einfügen.

# Set up context for stateful chat
published_context = geminidataanalytics.Context()
published_context.system_instruction = system_instruction
published_context.datasource_references = datasource_references
# Optional: To enable advanced analysis with Python, include the following line:
published_context.options.analysis.python.enabled = True

Zustandsloser Chat

Im folgenden Beispielcode wird der Kontext für den zustandslosen Chat eingerichtet. Hier müssen Sie den gesamten Unterhaltungsverlauf mit jeder Nachricht senden. Optional können Sie auch die erweiterte Analyse mit Python aktivieren, indem Sie die Zeile inline_context.options.analysis.python.enabled = True in den folgenden Beispielcode einfügen.

# Set up context for stateless chat
# datasource_references.looker.credentials = credentials
inline_context = geminidataanalytics.Context()
inline_context.system_instruction = system_instruction
inline_context.datasource_references = datasource_references
# Optional: To enable advanced analysis with Python, include the following line:
inline_context.options.analysis.python.enabled = True

KI-Datenagenten erstellen

Mit dem folgenden Python-Codebeispiel wird eine API-Anfrage zum Erstellen eines KI-Datenagenten gesendet, mit dem Sie dann eine Unterhaltung über Ihre Daten führen können. Sie können einen Agent synchron oder asynchron erstellen. Der KI-Datenagent wird mit der angegebenen Datenquelle, den Systemanweisungen und dem Kontext konfiguriert.

Optional können Sie den KI-Datenagenten mit CMEK schützen, indem Sie bei der Erstellung eine kms_key angeben. CMEK wird nur für Looker-Datenquellen unterstützt. Weitere Informationen finden Sie unter Vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).

Synchron

  data_agent_id = "data_agent_1"

  # Optional: If using CMEK, replace the empty strings with your KMS key details.
  key_ring = ""    # KEY_RING_NAME
  key_name = ""    # KEY_NAME
  key_project = "" # KMS_PROJECT_ID (Defaults to billing_project if empty)

  data_agent = geminidataanalytics.DataAgent()
  data_agent.data_analytics_agent.published_context = published_context
  data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}" # Optional

  # Optional: Add CMEK key if details are provided
  if key_ring and key_name:
    if not key_project:
      key_project = billing_project
    kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
    data_agent.kms_key = kms_key_data_agent # Add for CMEK

  request = geminidataanalytics.CreateDataAgentRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    data_agent_id=data_agent_id, # Optional
    data_agent=data_agent,
  )

  try:
    response = data_agent_client.create_data_agent_sync(request=request)
    print("Data Agent created")
    print(response)
  except Exception as e:
    print(f"Error creating Data Agent: {e}")

Asynchron

  data_agent_id = "data_agent_1"

  # Optional: If using CMEK, replace the empty strings with your KMS key details.
  key_ring = ""    # KEY_RING_NAME
  key_name = ""    # KEY_NAME
  key_project = "" # KMS_PROJECT_ID (Defaults to billing_project if empty)

  data_agent = geminidataanalytics.DataAgent()
  data_agent.data_analytics_agent.published_context = published_context
  data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}" # Optional

  # Optional: Add CMEK key if details are provided
  if key_ring and key_name:
    if not key_project:
      key_project = billing_project
    kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
    data_agent.kms_key = kms_key_data_agent # Add for CMEK

  request = geminidataanalytics.CreateDataAgentRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    data_agent_id=data_agent_id, # Optional
    data_agent=data_agent,
  )

  try:
    data_agent_client.create_data_agent(request=request)
    print("Data Agent created")
  except Exception as e:
    print(f"Error creating Data Agent: {e}")

Ersetzen Sie im vorherigen Beispiel die Werte so:

  • data_agent_1: eine eindeutige Kennung für den KI-Datenagenten.
  • KEY_RING_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Wenn Sie CMEK verwenden, die Projekt-ID, in der der Schlüssel gehostet wird.

Unterhaltung erstellen

Im folgenden Python-Codebeispiel wird eine API-Anfrage zum Erstellen einer Unterhaltung gesendet.

Sie können die Unterhaltung optional mit CMEK schützen, indem Sie beim Erstellen einen kms_key angeben. CMEK wird nur für Looker-Datenquellen unterstützt. Weitere Informationen finden Sie unter Vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).

# Initialize request arguments
data_agent_id = "data_agent_1"
conversation_id = "conversation_1"


# Optional: If using CMEK, replace the empty strings with your KMS key details.
key_ring = ""    # KEY_RING_NAME
key_name = ""    # KEY_NAME
key_project = "" # KMS_PROJECT_ID (Defaults to billing_project if empty)

if key_project == "":
  key_project = billing_project
kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f'projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}']
conversation.name = f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}"

# Optional: Add CMEK key if details are provided
if key_ring and key_name:
  if not key_project:
    key_project = billing_project
  kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
  conversation.kms_key = kms_key_conversation # Add for CMEK

request = geminidataanalytics.CreateConversationRequest(
  parent=f"projects/{billing_project}/locations/{location}",
  conversation_id=conversation_id,
  conversation=conversation,
)

# Make the request
response = data_chat_client.create_conversation(request=request)

# Handle the response
print(response)

Ersetzen Sie die Beispielwerte so:

  • data_agent_1: die ID des KI-Datenagenten, wie im Beispielcodeblock unter KI-Datenagenten erstellen definiert.
  • conversation_1: eine eindeutige Kennung für die Unterhaltung.
  • KEY_RING_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Wenn Sie CMEK verwenden, die Projekt-ID, in der der Schlüssel gehostet wird.

KI-Datenagenten und Unterhaltungen verwalten

Die folgenden Beispielcodes zeigen, wie Sie Ihre KI-Datenagenten und Unterhaltungen mit der Conversational Analytics API verwalten. Sie können folgende Aufgaben ausführen:

KI-Datenagenten abrufen

Im folgenden Python-Codebeispiel wird gezeigt, wie Sie eine API-Anfrage senden, um einen zuvor erstellten KI-Datenagenten abzurufen.

# Initialize request arguments
data_agent_id = "data_agent_1"
request = geminidataanalytics.GetDataAgentRequest(
  name=f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
)

# Make the request
response = data_agent_client.get_data_agent(request=request)

# Handle the response
print(response)

Ersetzen Sie im vorherigen Beispiel den Wert data_agent_1 durch die eindeutige Kennung des KI-Datenagenten, den Sie abrufen möchten.

KI-Datenagenten auflisten

Im folgenden Code wird gezeigt, wie Sie alle KI-Datenagenten für ein bestimmtes Projekt auflisten, indem Sie die Methode list_data_agents aufrufen. Zum Auflisten aller KI-Agenten benötigen Sie die Berechtigung geminidataanalytics.dataAgents.list für das Projekt. Weitere Informationen dazu, welche IAM-Rollen diese Berechtigung enthalten, finden Sie in der Liste der vordefinierten Rollen.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
request = geminidataanalytics.ListDataAgentsRequest(
  parent=f"projects/{billing_project}/locations/{location}",
)

# Make the request
page_result = data_agent_client.list_data_agents(request=request)

# Handle the response
for response in page_result:
  print(response)

Ersetzen Sie YOUR-BILLING-PROJECT durch die ID Ihres Abrechnungsprojekts.

Verfügbare KI-Datenagenten auflisten

Im folgenden Code wird gezeigt, wie Sie alle zugänglichen KI-Datenagenten für ein bestimmtes Projekt auflisten, indem Sie die Methode list_accessible_data_agents aufrufen.

billing_project = "YOUR-BILLING-PROJECT"
creator_filter = "YOUR-CREATOR-FILTER"
location = "global"
request = geminidataanalytics.ListAccessibleDataAgentsRequest(
  parent=f"projects/{billing_project}/locations/{location}",
  creator_filter=creator_filter
)

# Make the request
page_result = data_agent_client.list_accessible_data_agents(request=request)

# Handle the response
for response in page_result:
  print(response)

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • YOUR-CREATOR-FILTER: der Filter, der basierend auf dem Ersteller des KI-Datenagenten angewendet werden soll. Mögliche Werte sind NONE (Standard), CREATOR_ONLY und NOT_CREATOR_ONLY.

KI-Datenagenten aktualisieren

Im folgenden Beispielcode wird gezeigt, wie ein KI-Datenagent synchron oder asynchron aktualisiert wird, indem die Methode update_data_agent_sync oder update_data_agent für die KI-Datenagenten-Ressource aufgerufen wird. Für die Anfrage ist ein DataAgent-Objekt mit den neuen Werten für die Felder, die Sie ändern möchten, erforderlich. Außerdem benötigen Sie den Parameter update_mask, der ein FieldMask-Objekt verwendet. Damit wird angegeben, welche Felder aktualisiert werden sollen.

Zum Aktualisieren eines KI-Datenagenten benötigen Sie die IAM-Berechtigung geminidataanalytics.dataAgents.update für den KI-Agenten. Weitere Informationen dazu, welche IAM-Rollen diese Berechtigung enthalten, finden Sie in der Liste der vordefinierten Rollen.

Synchron

data_agent_id = "data_agent_1"
billing_project = "YOUR-BILLING-PROJECT"
data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.description = "Updated description of the data agent."

update_mask = field_mask_pb2.FieldMask(paths=['description', 'data_analytics_agent.published_context'])

request = geminidataanalytics.UpdateDataAgentRequest(
  data_agent=data_agent,
  update_mask=update_mask,
)

try:
  # Make the request
  response = data_agent_client.update_data_agent_sync(request=request)
  print("Data Agent Updated")
  print(response)
except Exception as e:
  print(f"Error updating Data Agent: {e}")

Asynchron

data_agent_id = "data_agent_1"
billing_project = "YOUR-BILLING-PROJECT"
data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.description = "Updated description of the data agent."

update_mask = field_mask_pb2.FieldMask(paths=['description', 'data_analytics_agent.published_context'])

request = geminidataanalytics.UpdateDataAgentRequest(
  data_agent=data_agent,
  update_mask=update_mask,
)

try:
  # Make the request
  data_agent_client.update_data_agent(request=request)
  print("Data Agent Updated")
except Exception as e:
  print(f"Error updating Data Agent: {e}")

Ersetzen Sie die Beispielwerte so:

  • data_agent_1: die ID des KI-Datenagenten, den Sie aktualisieren möchten.
  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • Updated description of the data agent.: eine Beschreibung des aktualisierten KI-Datenagenten.

IAM-Richtlinie für einen KI-Datenagenten abrufen

Der folgende Beispielcode zeigt, wie Sie die Methode get_iam_policy verwenden, um die IAM-Richtlinie für einen KI-Datenagenten abzurufen. In der Anfrage wird der Pfad zur KI-Datenagenten-Ressource angegeben.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"

resource = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
request = iam_policy_pb2.GetIamPolicyRequest(
      resource=resource,
    )
try:
  response = data_agent_client.get_iam_policy(request=request)
  print("IAM Policy fetched successfully!")
  print(f"Response: {response}")
except Exception as e:
  print(f"Error setting IAM policy: {e}")

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • data_agent_1: die ID des KI-Datenagenten, für den Sie die IAM-Richtlinie abrufen möchten.

IAM-Richtlinie für einen KI-Datenagenten festlegen

Wenn Sie einen KI-Agenten freigeben möchten, können Sie mit der Methode set_iam_policy Nutzern IAM-Rollen für einen bestimmten KI-Agenten zuweisen. Die Anfrage enthält Bindungen, in denen angegeben wird, welche Rollen welchen Nutzern zugewiesen werden sollen.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"
role = "roles/geminidataanalytics.dataAgentEditor"
users = "EMAIL_ADDRESS"

resource = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"

# Construct the IAM policy
binding = policy_pb2.Binding(
  role=role,
  members= [f"user:{i.strip()}" for i in users.split(",")]
)

policy = policy_pb2.Policy(bindings=[binding])

# Create the request
request = iam_policy_pb2.SetIamPolicyRequest(
  resource=resource,
  policy=policy
)

# Send the request
try:
  response = data_agent_client.set_iam_policy(request=request)
  print("IAM Policy set successfully!")
  print(f"Response: {response}")
except Exception as e:
  print(f"Error setting IAM policy: {e}")

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • data_agent_1: die ID des KI-Datenagenten, für den Sie die IAM-Richtlinie festlegen möchten.
  • EMAIL_ADDRESSES: eine kommagetrennte Liste von Nutzer-E-Mail-Adressen, denen Sie die angegebene Rolle zuweisen möchten.

KI-Datenagenten löschen

Der folgende Beispielcode zeigt, wie Sie die Methode delete_data_agent_sync oder delete_data_agent verwenden, um einen KI-Datenagenten synchron oder asynchron vorläufig zu löschen. Wenn Sie einen KI-Agenten vorläufig löschen, wird er gelöscht, kann aber innerhalb von 30 Tagen wiederhergestellt werden. In der Anfrage wird die URL der KI-Datenagenten-Ressource angegeben.

Synchron

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"

request = geminidataanalytics.DeleteDataAgentRequest(
  name=f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
)

try:
  # Make the request
  data_agent_client.delete_data_agent_sync(request=request)
  print("Data Agent Deleted")
except Exception as e:
  print(f"Error deleting Data Agent: {e}")

Asynchron

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"

request = geminidataanalytics.DeleteDataAgentRequest(
  name=f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
)

try:
  # Make the request
  data_agent_client.delete_data_agent(request=request)
  print("Data Agent Deleted")
except Exception as e:
  print(f"Error deleting Data Agent: {e}")

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • data_agent_1: die ID des KI-Datenagenten, den Sie löschen möchten.

Unterhaltung abrufen

Im folgenden Beispielcode wird gezeigt, wie Sie mit der Methode get_conversation Informationen zu einer vorhandenen Unterhaltung abrufen. In der Anfrage wird der Pfad zur Unterhaltungsressource angegeben.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
conversation_id = "conversation_1"

request = geminidataanalytics.GetConversationRequest(
  name = f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}"
)

# Make the request
response = data_chat_client.get_conversation(request=request)

# Handle the response
print(response)

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • conversation_1: die ID der Unterhaltung, die Sie abrufen möchten.

Unterhaltungen auflisten

Im folgenden Beispielcode wird gezeigt, wie Sie Unterhaltungen für ein bestimmtes Projekt auflisten, indem Sie die Methode list_conversations aufrufen. In der Anfrage wird die URL der übergeordneten Ressource angegeben, also das Projekt und der Ort (z. B. projects/my-project/locations/global).

Standardmäßig werden mit dieser Methode die Unterhaltungen zurückgegeben, die Sie erstellt haben. Administratoren (Nutzer mit der IAM-Rolle cloudaicompanion.topicAdmin) können alle Unterhaltungen im Projekt sehen.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
request = geminidataanalytics.ListConversationsRequest(
  parent=f"projects/{billing_project}/locations/{location}",
)

# Make the request
response = data_chat_client.list_conversations(request=request)

# Handle the response
print(response)

Ersetzen Sie YOUR-BILLING-PROJECT durch die ID des Abrechnungsprojekts, in dem Sie die erforderlichen APIs aktiviert haben.

Nachrichten in einer Unterhaltung auflisten

Der folgende Beispielcode zeigt, wie Sie mit der Methode list_messages alle Nachrichten in einer Unterhaltung abrufen. In der Anfrage wird der Pfad zur Unterhaltungsressource angegeben.

Zum Auflisten von Nachrichten benötigen Sie die Berechtigung cloudaicompanion.topics.get für die Unterhaltung.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"

conversation_id = "conversation_1"

request = geminidataanalytics.ListMessagesRequest(
  parent=f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
)

# Make the request
response = data_chat_client.list_messages(request=request)

# Handle the response
print(response)

Ersetzen Sie die Beispielwerte folgendermaßen:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • conversation_1: die ID der Unterhaltung, für die Sie Nachrichten auflisten möchten.

Unterhaltungen löschen

Der folgende Beispielcode zeigt, wie eine Unterhaltung gelöscht wird. Administratoren (Nutzer mit der IAM-Rolle „cloudaicompanion.topicAdmin“) oder Nutzer mit der IAM-Berechtigung cloudaicompanion.topics.delete können Unterhaltungen im Projekt löschen.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
conversation_id = "conversation_1"

request = geminidataanalytics.DeleteConversationRequest(
  name = f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}"
)

# Make the request
response = data_chat_client.delete_conversation(request=request)

# Handle the response
print(response)

Ersetzen Sie die Beispielwerte so:

  • YOUR-BILLING-PROJECT: die ID Ihres Abrechnungsprojekts.
  • conversation_1: die ID der Unterhaltung, für die Sie Nachrichten auflisten möchten.

API zum Stellen von Fragen verwenden

Nachdem Sie einen KI-Datenagenten und für zustandsorientierte Chats eine Unterhaltung erstellt haben, können Sie Anfragen an den Agenten senden. Die folgenden Codebeispiele zeigen, wie die Methode data_chat_client.chat aufgerufen wird. In diesen Beispielen werden die Kontextvariablen (z. B. Datenquelle und Systemanweisungen) verwendet, die Sie in Kontext für zustandsorientierte oder zustandslose Chats einrichten konfiguriert haben.

Wenn Sie eine Anfrage senden, gibt die API einen Stream von Message-Objekten zurück. Dieser Stream kann verschiedene Arten von Nachrichten enthalten, darunter Text, Datentabellen und Diagramme. SMS können Aufschluss über die Argumentation des Agenten geben, über den Fortschritt berichten oder die endgültige Antwort liefern. Der Zweck der einzelnen Nachricht wird durch den TextType-Wert angegeben:

  • THOUGHT: Hier wird der interne Denkprozess des KI-Agents angezeigt, während er plant, wie er Ihre Anfrage beantworten soll. THOUGHT-Nachrichten bieten eine schrittweise Übersicht über den Denk- und Entscheidungsprozess des Agenten und bestehen aus zwei Teilen: parts[0] ist die Zusammenfassung des Gedankens, die den vollständigen Gedankentext kurz zusammenfasst, und parts[1] ist der vollständige Gedankentext.
  • PROGRESS: Gibt den Fortschritt des Agenten bei einer Aktion an, z. B. beim Abrufen von Daten oder bei einem Tool, das aufgerufen wird. Dieser Wert wird nur für Looker-Datenquellen zurückgegeben und besteht aus zwei Teilen: parts[0] ist die Zusammenfassung und parts[1] der vollständige Fortschrittstext.
  • FINAL_RESPONSE: Hier finden Sie die endgültige Antwort auf Ihre Anfrage.

In den folgenden Codebeispielen wird die Hilfsfunktion show_message verwendet, die in Hilfsfunktionen definieren definiert ist, um jede Nachricht im Stream zu verarbeiten und anzuzeigen. Eine Anleitung zum Rendern dieser Meldungen in einer Benutzeroberfläche, wenn Sie Looker-Datenquellen verwenden, finden Sie unter KI-Agent-Antworten für Looker-Datenquellen rendern.

Zustandsorientierter Chat

Zustandsorientierte Chatanfrage mit einem Conversation-Verweis senden

Sie können eine zustandsorientierte Chatanfrage an den KI-Datenagenten senden, indem Sie auf eine zuvor erstellte Conversation-Ressource verweisen.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

data_agent_id = "data_agent_1"
conversation_id = "conversation_1"

# Create a conversation_reference
conversation_reference = geminidataanalytics.ConversationReference()
conversation_reference.conversation = f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}"
conversation_reference.data_agent_context.data_agent = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
# conversation_reference.data_agent_context.credentials = credentials

# Form the request
request = geminidataanalytics.ChatRequest(
    parent = f"projects/{billing_project}/locations/{location}",
    messages = messages,
    conversation_reference = conversation_reference
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

Ersetzen Sie die Beispielwerte so:

  • Which species of tree is most prevalent?: eine Frage in natürlicher Sprache, die an den KI-Datenagenten gesendet werden soll.
  • data_agent_1: die eindeutige Kennung für den KI-Datenagenten, wie in KI-Datenagenten erstellen definiert.
  • conversation_1: die eindeutige Kennung für die Unterhaltung, wie in Unterhaltung erstellen definiert.

Zustandsloser Chat

Die folgenden Codebeispiele zeigen, wie Sie eine Anfrage an den KI-Datenagenten senden, wenn Sie Kontext für den zustandslosen Chat eingerichtet haben. Sie können zustandslose Anfragen senden, indem Sie auf eine zuvor definierte DataAgent-Ressource verweisen oder Inline-Kontext in der Anfrage verwenden.

Zustandslose Chatanfrage mit einem DataAgent-Verweis senden

Sie können eine Anfrage an den KI-Datenagenten senden, indem Sie auf eine zuvor erstellte DataAgent-Ressource verweisen.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

data_agent_id = "data_agent_1"

data_agent_context = geminidataanalytics.DataAgentContext()
data_agent_context.data_agent = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
# data_agent_context.credentials = credentials

# Form the request
request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    messages=messages,
    data_agent_context = data_agent_context
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

Ersetzen Sie die Beispielwerte so:

  • Which species of tree is most prevalent?: eine Frage in natürlicher Sprache, die an den KI-Datenagenten gesendet werden soll.
  • data_agent_1: die eindeutige Kennung für den KI-Datenagenten, wie in KI-Datenagenten erstellen definiert.

Zustandslose Chatanfrage mit Inline-Kontext senden

Der folgende Beispielcode zeigt, wie Sie den Parameter inline_context verwenden, um Kontext direkt in Ihrer zustandslosen Chatanfrage bereitzustellen.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

request = geminidataanalytics.ChatRequest(
    inline_context=inline_context,
    parent=f"projects/{billing_project}/locations/{location}",
    messages=messages,
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

Ersetzen Sie im vorherigen Beispiel Which species of tree is most prevalent? durch eine Frage in natürlicher Sprache, die an den KI-Datenagenten gesendet werden soll.

Zustandslose Multi-Turn-Unterhaltung erstellen

Wenn Sie in einer zustandslosen Unterhaltung weiterführende Fragen stellen möchten, muss Ihre Anwendung den Kontext der Unterhaltung verwalten, indem sie den gesamten Nachrichtenverlauf mit jeder neuen Anfrage sendet. Im folgenden Beispiel wird gezeigt, wie Sie eine Multi-Turn-Unterhaltung erstellen, indem Sie auf einen KI-Datenagenten verweisen oder die Datenquelle direkt über Inline-Kontext angeben.

# List that is used to track previous turns and is reused across requests
conversation_messages = []

data_agent_id = "data_agent_1"

# Use data agent context
data_agent_context = geminidataanalytics.DataAgentContext()
data_agent_context.data_agent = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
# data_agent_context.credentials = credentials

# Helper function for calling the API
def multi_turn_Conversation(msg):

  message = geminidataanalytics.Message()
  message.user_message.text = msg

  # Send a multi-turn request by including previous turns and the new message
  conversation_messages.append(message)

  request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    messages=conversation_messages,
    # Use data agent context
    data_agent_context=data_agent_context,
    # Use inline context
    # inline_context=inline_context,
  )

  # Make the request
  stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

  # Handle the response
  for response in stream:
    show_message(response)
    conversation_messages.append(response)

# Send the first turn request
multi_turn_Conversation("Which species of tree is most prevalent?")

# Send follow-up turn request
multi_turn_Conversation("Can you show me the results as a bar chart?")

Ersetzen Sie im vorherigen Beispiel die Beispielwerte so:

  • data_agent_1: die eindeutige Kennung für den KI-Datenagenten, wie im Beispielcodeblock unter KI-Datenagenten erstellen definiert.
  • Which species of tree is most prevalent?: eine Frage in natürlicher Sprache, die an den KI-Datenagenten gesendet werden soll.
  • Can you show me the results as a bar chart?: eine weiterführende Frage, die auf der vorangegangenen Frage aufbaut oder sie verfeinert.

Hilfsfunktionen definieren

Der folgende Beispielcode enthält Definitionen von Hilfsfunktionen, die in den vorherigen Codebeispielen verwendet werden. Diese Funktionen helfen dabei, die Antwort der API zu parsen und die Ergebnisse anzuzeigen.

import json as json_lib
import textwrap
import time

import altair as alt
import IPython
import pandas as pd
import proto
import requests

from google.protobuf.json_format import MessageToDict, MessageToJson
from IPython.display import display, HTML
from pygments import highlight, lexers, formatters
from google.protobuf import field_mask_pb2
from google.iam.v1 import policy_pb2
from google.iam.v1 import iam_policy_pb2

def handle_text_response(resp):
  parts = resp.parts
  full_text = "".join(parts)
  if "\n" not in full_text and len(full_text) > 80:
    wrapped_text = textwrap.fill(full_text, width=80)
    print(wrapped_text)
  else:
    print(full_text)

def display_schema(data):
  fields = getattr(data, "fields")
  df = pd.DataFrame({
    "Column": map(lambda field: getattr(field, 'name'), fields),
    "Type": map(lambda field: getattr(field, 'type'), fields),
    "Description": map(lambda field: getattr(field, 'description', '-'), fields),
    "Mode": map(lambda field: getattr(field, 'mode'), fields)
  })
  display(df)

def display_section_title(text):
  display(HTML('<h2>{}</h2>'.format(text)))

def format_looker_table_ref(table_ref):
  return 'lookmlModel: {}, explore: {}, lookerInstanceUri: {}'.format(table_ref.lookml_model, table_ref.explore, table_ref.looker_instance_uri)

def format_bq_table_ref(table_ref):
  return '{}.{}.{}'.format(table_ref.project_id, table_ref.dataset_id, table_ref.table_id)

def display_datasource(datasource):
  source_name = ''
  if 'studio_datasource_id' in datasource:
    source_name = getattr(datasource, 'studio_datasource_id')
  elif 'looker_explore_reference' in datasource:
    source_name = format_looker_table_ref(getattr(datasource, 'looker_explore_reference'))
  else:
    source_name = format_bq_table_ref(getattr(datasource, 'bigquery_table_reference'))

  print(source_name)
  display_schema(datasource.schema)

def handle_schema_response(resp):
  if 'query' in resp:
    print(resp.query.question)
  elif 'result' in resp:
    display_section_title('Schema resolved')
    print('Data sources:')
    for datasource in resp.result.datasources:
      display_datasource(datasource)

def handle_data_response(resp):
  if "query" in resp:
    query = resp.query
    display_section_title("Retrieval query")
    print(f"Query name: {query.name}")
    if "question" in query:
      print(f"Question: {query.question}")
    if "datasources" in query:
      print("Data sources:")
      for datasource in query.datasources:
        display_datasource(datasource)
  elif "generated_sql" in resp:
    display_section_title("SQL generated")
    print(resp.generated_sql)
  elif "result" in resp:
    display_section_title("Data retrieved")

    fields = [field.name for field in resp.result.schema.fields]
    d = {}
    for el in resp.result.data:
      for field in fields:
        if field in d:
          d[field].append(el[field])
        else:
          d[field] = [el[field]]

    display(pd.DataFrame(d))

def handle_chart_response(resp):
  def _value_to_dict(v):
    if isinstance(v, proto.marshal.collections.maps.MapComposite):
      return _map_to_dict(v)
    elif isinstance(v, proto.marshal.collections.RepeatedComposite):
      return [_value_to_dict(el) for el in v]
    elif isinstance(v, (int, float, str, bool)):
      return v
    else:
      return MessageToDict(v)

  def _map_to_dict(d):
    out = {}
    for k in d:
      if isinstance(d[k], proto.marshal.collections.maps.MapComposite):
        out[k] = _map_to_dict(d[k])
      else:
        out[k] = _value_to_dict(d[k])
    return out

  if 'query' in resp:
    print(resp.query.instructions)
  elif 'result' in resp:
    vegaConfig = resp.result.vega_config
    vegaConfig_dict = _map_to_dict(vegaConfig)
    alt.Chart.from_json(json_lib.dumps(vegaConfig_dict)).display();

def show_message(msg):
  m = msg.system_message
  if 'text' in m:
    handle_text_response(getattr(m, 'text'))
  elif 'schema' in m:
    handle_schema_response(getattr(m, 'schema'))
  elif 'data' in m:
    handle_data_response(getattr(m, 'data'))
  elif 'chart' in m:
    handle_chart_response(getattr(m, 'chart'))
  print('\n')