Membangun agen data menggunakan Python SDK

Halaman ini menunjukkan cara menggunakan Python SDK untuk membuat permintaan ke Conversational Analytics API. Kode Python contoh menunjukkan cara menyelesaikan tugas-tugas berikut:

Mengautentikasi dan menyiapkan lingkungan Anda

Untuk menggunakan Python SDK untuk Conversational Analytics API, ikuti petunjuk di notebook Colaboratory SDK Conversational Analytics API untuk mendownload dan menginstal SDK. Perhatikan bahwa metode download dan konten SDK Colab dapat berubah sewaktu-waktu.

Setelah menyelesaikan petunjuk penyiapan di notebook, Anda dapat menggunakan kode berikut untuk mengimpor library SDK yang diperlukan dan mengautentikasi Akun Google Anda dalam lingkungan Colaboratory:

from google.colab import auth
auth.authenticate_user()

from google.cloud import geminidataanalytics
from google.api_core import client_options

Mengonfigurasi setelan dan melakukan inisialisasi klien

Kode Python contoh berikut menentukan project penagihan, lokasi, dan petunjuk sistem yang digunakan di seluruh skrip Anda, serta menginisialisasi klien API dengan setelan endpoint berdasarkan lokasi:

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

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

# Set client options based on location.
if not location or location == "global":
  endpoint = "geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  endpoint = f"geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  endpoint = f"geminidataanalytics.{location}.rep.googleapis.com"
opts = client_options.ClientOptions(api_endpoint=endpoint)

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

Ganti nilai contoh sebagai berikut:

  • my_project_name: ID project Google Cloud tempat Anda mengaktifkan API yang diperlukan.

  • LOCATION: Lokasi tempat resource Anda disimpan. Untuk menggunakan endpoint global, tentukan global. Untuk memenuhi persyaratan residensi data, tentukan satu region yang didukung (seperti us-east4) atau multi-region (seperti eu atau us). Untuk mengetahui informasi selengkapnya, lihat Residensi data.

  • Help the user analyze their data.: Petunjuk sistem untuk memandu perilaku agen dan menyesuaikannya dengan kebutuhan data Anda. Misalnya, Anda dapat menggunakan petunjuk sistem untuk menentukan istilah bisnis, mengontrol panjang respons, atau menetapkan format data. Idealnya, tentukan petunjuk sistem menggunakan format YAML yang direkomendasikan dalam Menulis petunjuk sistem yang efektif untuk memberikan panduan yang mendetail dan terstruktur.

Menghubungkan ke sumber data

Bagian berikut menunjukkan cara menentukan detail koneksi untuk sumber data agen Anda. Agen Anda dapat terhubung ke data dengan cara berikut:

Menghubungkan ke data Looker

Contoh kode berikut menunjukkan cara menentukan detail koneksi ke Looker Explore dengan kunci API atau token akses. Anda dapat menghubungkan hingga lima Eksplorasi Looker sekaligus dengan Conversational Analytics API.

Kunci API

Anda dapat membuat koneksi dengan instance Looker menggunakan kunci Looker API yang dihasilkan, seperti yang dijelaskan dalam Mengautentikasi dan menghubungkan ke sumber data.

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]

Ganti nilai contoh sebagai berikut:

  • my_looker_client_id: Client ID kunci Looker API yang Anda buat.
  • my_looker_client_secret: Rahasia klien dari kunci Looker API yang Anda buat.
  • https://my_company.looker.com: URL lengkap instance Looker Anda.
  • my_model: Nama model LookML yang menyertakan Explore yang ingin Anda hubungkan.
  • my_explore: Nama Looker Explore yang ingin Anda kueri oleh agen data.
  • my_model_2: Nama model LookML kedua yang menyertakan Explore yang ingin Anda hubungkan. Anda dapat mengulangi variabel ini untuk model tambahan hingga lima Eksplorasi.
  • my_explore_2: Nama Looker Explore tambahan yang ingin Anda kueri oleh agen data. Anda dapat mengulangi variabel ini untuk menyertakan hingga lima Eksplorasi.

Token akses

Anda dapat membuat koneksi dengan instance Looker menggunakan token akses, seperti yang dijelaskan dalam Mengautentikasi dan menghubungkan ke sumber data dengan Conversational Analytics API.

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]

Ganti nilai contoh sebagai berikut:

  • my_access_token: Nilai access_token yang Anda buat untuk melakukan autentikasi ke Looker.
  • https://my_company.looker.com: URL lengkap instance Looker Anda.
  • my_model: Nama model LookML yang menyertakan Explore yang ingin Anda hubungkan.
  • my_explore: Nama Looker Explore yang ingin Anda kueri oleh agen data.
  • my_model_2: Nama model LookML kedua yang menyertakan Explore yang ingin Anda hubungkan. Anda dapat mengulangi variabel ini untuk model tambahan hingga lima Eksplorasi.
  • my_explore_2: Nama Looker Explore tambahan yang ingin Anda kueri oleh agen data. Anda dapat mengulangi variabel ini untuk menyertakan hingga lima Eksplorasi.

Untuk mengetahui informasi selengkapnya tentang cara terhubung ke Explore Looker, termasuk peran yang diperlukan, lihat Terhubung ke Looker.

Menghubungkan ke data BigQuery

Bagian berikut menunjukkan cara terhubung ke data BigQuery menggunakan referensi tabel, referensi grafik, atau keduanya. Untuk mengetahui informasi selengkapnya tentang cara terhubung ke tabel dan grafik, termasuk peran yang diperlukan, lihat Terhubung ke BigQuery.

Menghubungkan ke tabel BigQuery

Kode contoh berikut menentukan koneksi ke beberapa tabel BigQuery dan menyertakan contoh kolom konteks terstruktur opsional.

bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "PROJECT_ID_1"
bigquery_table_reference_1.dataset_id = "DATASET_ID_1"
bigquery_table_reference_1.table_id = "TABLE_ID_1"
bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "TABLE_DESCRIPTION"
bigquery_table_reference_1.schema.fields = [
  geminidataanalytics.Field(
    name="COLUMN_NAME",
    description="COLUMN_DESCRIPTION"
  )
]

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "PROJECT_ID_2"
bigquery_table_reference_2.dataset_id = "DATASET_ID_2"
bigquery_table_reference_2.table_id = "TABLE_ID_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "PROJECT_ID_3"
bigquery_table_reference_3.dataset_id = "DATASET_ID_3"
bigquery_table_reference_3.table_id = "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]

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID_1: ID project Google Cloud yang berisi set data dan tabel BigQuery yang ingin Anda hubungkan. Untuk terhubung ke set data publik, tentukan bigquery-public-data.
  • DATASET_ID_1: ID set data BigQuery. Contoh, san_francisco.
  • TABLE_ID_1: ID tabel BigQuery. Contoh, street_trees.
  • TABLE_DESCRIPTION: Deskripsi opsional tentang konten dan tujuan tabel.
  • COLUMN_NAME: Nama kolom dalam tabel yang deskripsi opsionalnya Anda berikan.
  • COLUMN_DESCRIPTION: Deskripsi opsional tentang konten dan tujuan kolom.

Menghubungkan ke BigQuery Graph

Anda juga dapat terhubung ke grafik menggunakan BigQuery Graph. Berikan satu atau beberapa referensi grafik di kolom property_graph_references.

Untuk mengetahui informasi tentang persyaratan edisi BigQuery dan batasan kueri grafik, lihat Menghubungkan ke BigQuery Graph.

# BigQuery graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]

Ganti nilai contoh sebagai berikut:

  • GRAPH_PROJECT_ID: ID project Google Cloud yang berisi grafik BigQuery.
  • GRAPH_DATASET_ID: ID set data BigQuery yang berisi grafik.
  • GRAPH_ID: ID grafik BigQuery.

Untuk mengkueri tabel dan grafik dengan agen data yang sama, tetapkan table_references dan property_graph_references di datasource_references.bq.

Menghubungkan ke data Data Studio

Kode contoh berikut menentukan koneksi ke sumber data Data Studio.

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]

Pada contoh sebelumnya, ganti my_datasource_id dengan ID sumber data.

Menghubungkan ke data AlloyDB

Kode contoh berikut menentukan koneksi ke database AlloyDB menggunakan Python SDK.

# 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

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi cluster AlloyDB.
  • REGION: Region tempat cluster AlloyDB berada—misalnya, us-central1.
  • CLUSTER_ID: ID cluster AlloyDB.
  • INSTANCE_ID: ID instance AlloyDB.
  • DATABASE: Nama database target—misalnya, financial.
  • TABLE_1_ID, TABLE_2_ID: Daftar tabel dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "loan", "client", "disp".
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Menghubungkan ke data Cloud SQL untuk MySQL

Untuk terhubung ke instance Cloud SQL untuk MySQL, gunakan class CloudSqlReference dari geminidataanalytics SDK. Hal ini melibatkan penentuan project, instance, database, dan secara opsional, tabel tertentu yang ingin Anda pertimbangkan oleh agen.

Sebelum terhubung ke data Cloud SQL untuk MySQL, pastikan Anda melakukan autentikasi ke Cloud SQL untuk MySQL menggunakan Identity and Access Management (IAM). Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi ke Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL.

Contoh berikut menentukan koneksi ke database Cloud SQL untuk MySQL menggunakan Python SDK.

# 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

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi instance Cloud SQL untuk MySQL.
  • INSTANCE_ID: ID instance Cloud SQL untuk MySQL.
  • DATABASE_ID: Nama database target dalam instance—misalnya, financial.
  • TABLE_1_ID, TABLE_2_ID: (Opsional) Daftar nama tabel tertentu dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "orders" dan "customers".
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Anda dapat menggunakan objek datasource_references saat membuat atau berinteraksi dengan agen data.

Menghubungkan ke data Cloud SQL untuk PostgreSQL

Untuk terhubung ke instance Cloud SQL untuk PostgreSQL, gunakan class CloudSqlReference dari geminidataanalytics SDK. Hal ini melibatkan penentuan project, instance, database, dan secara opsional, tabel tertentu yang ingin Anda pertimbangkan oleh agen.

Sebelum terhubung ke data Cloud SQL untuk PostgreSQL, pastikan Anda melakukan autentikasi ke Cloud SQL untuk PostgreSQL menggunakan IAM. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi ke Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL.

Contoh berikut menentukan koneksi ke database Cloud SQL untuk PostgreSQL menggunakan Python SDK.

# 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

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi instance Cloud SQL untuk PostgreSQL.
  • INSTANCE_ID: ID instance Cloud SQL untuk PostgreSQL.
  • DATABASE_ID: Nama database target dalam instance—misalnya, postgres.
  • TABLE_1_ID, TABLE_2_ID: (Opsional) Daftar nama tabel tertentu dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "users" dan "products".
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Anda dapat menggunakan objek datasource_references saat membuat atau berinteraksi dengan agen data.

Menghubungkan ke data Spanner

Untuk terhubung ke instance Spanner, gunakan class SpannerReference dari geminidataanalytics SDK. Hal ini melibatkan penentuan project, instance, database, dan secara opsional, tabel tertentu yang ingin Anda pertimbangkan oleh agen.

Sebelum Anda terhubung ke data Spanner, pastikan akun pengguna atau layanan memiliki peran IAM spanner.databaseReader. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.

Kode Python contoh berikut menentukan koneksi ke database Spanner menggunakan Python SDK.

# 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

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi instance Spanner.
  • INSTANCE_ID: ID instance Spanner.
  • DATABASE_ID: Nama database target dalam instance.
  • TABLE_1_ID, TABLE_2_ID: (Opsional) Daftar nama tabel tertentu dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "Singers" dan "Albums".
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Anda dapat menggunakan objek datasource_references saat membuat atau berinteraksi dengan agen data.

Menyiapkan konteks untuk chat stateful atau stateless

Conversational Analytics API mendukung percakapan multi-giliran, yang memungkinkan pengguna mengajukan pertanyaan lanjutan yang didasarkan pada konteks sebelumnya. Kode Python contoh berikut menunjukkan cara menyiapkan konteks untuk chat stateful atau stateless:

  • Chat stateful: Google Cloud menyimpan dan mengelola histori percakapan. Chat stateful pada dasarnya bersifat multi-turn, karena API mempertahankan konteks dari pesan sebelumnya. You only need to send the current message for each turn.
  • Chat stateless: Aplikasi Anda mengelola histori percakapan. Anda harus menyertakan seluruh histori percakapan dengan setiap pesan baru. Untuk contoh mendetail tentang cara mengelola percakapan multi-turn dalam mode stateless, lihat Membuat percakapan multi-turn stateless.

Chat stateful

Contoh kode berikut menyiapkan konteks untuk chat stateful, tempat Google Cloud menyimpan dan mengelola histori percakapan. Anda juga dapat mengaktifkan analisis lanjutan dengan Python secara opsional dengan menyertakan baris published_context.options.analysis.python.enabled = True dalam kode contoh berikut.

# 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
# Optional: To limit query costs to 100 MiB, include the following line:
published_context.options.datasource.big_query_max_billed_bytes.value = 104857600

Chat stateless

Kode contoh berikut menyiapkan konteks untuk chat stateless, yang mengharuskan Anda mengirim seluruh histori percakapan dengan setiap pesan. Anda juga dapat mengaktifkan analisis lanjutan dengan Python secara opsional dengan menyertakan baris inline_context.options.analysis.python.enabled = True dalam kode contoh berikut.

# Set up context for stateless chat
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
# Optional: To limit query costs to 100 MiB, include the following line:
inline_context.options.datasource.big_query_max_billed_bytes = 104857600

Membuat agen data

Kode Python contoh berikut membuat permintaan API untuk membuat agen data, yang kemudian dapat Anda gunakan untuk melakukan percakapan tentang data Anda. Anda dapat membuat agen secara sinkron atau asinkron. Agen data dikonfigurasi dengan sumber data, petunjuk sistem, dan konteks yang ditentukan.

Anda dapat melindungi agen data dengan CMEK secara opsional dengan menetapkan kolom kms_key saat membuat agen data. Untuk mengetahui informasi selengkapnya, lihat Kunci enkripsi yang dikelola pelanggan (CMEK).

Sinkron

  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)
  key_location = "" # KEY_LOCATION (Defaults to location if empty; except eu)

  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
    if not key_location:
      key_location = location
    kms_key_data_agent = f"projects/{key_project}/locations/{key_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}")

Asinkron

  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)
  key_location = "" # KEY_LOCATION (Defaults to location if empty; except eu)

  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
    if not key_location:
      key_location = location
    kms_key_data_agent = f"projects/{key_project}/locations/{key_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}")

Dalam contoh sebelumnya, ganti nilai sebagai berikut:

  • data_agent_1: ID unik untuk agen data.
  • KEY_RING_NAME: Jika menggunakan CMEK, nama key ring Cloud KMS Anda.
  • KEY_NAME: Jika menggunakan CMEK, nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Jika menggunakan CMEK, project ID tempat kunci dihosting.
  • KEY_LOCATION: Jika menggunakan CMEK, lokasi key ring Anda. Untuk multi-region eu, gunakan europe. Untuk semua lokasi lainnya, gunakan lokasi yang sama dengan agen data. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke lokasi agen data, yang berfungsi untuk semua lokasi kecuali multi-region eu. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.

Membuat percakapan

Contoh kode Python berikut membuat permintaan API untuk membuat percakapan.

Anda dapat melindungi percakapan dengan CMEK secara opsional dengan menetapkan kolom kms_key saat membuat percakapan. Untuk mengetahui informasi selengkapnya, lihat Kunci enkripsi yang dikelola pelanggan (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)
key_location = "" # KEY_LOCATION (Defaults to location if empty; single regions only)

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
  if not key_location:
    key_location = location
  kms_key_conversation = f"projects/{key_project}/locations/{key_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)

Ganti nilai contoh sebagai berikut:

  • data_agent_1: ID agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.
  • conversation_1: ID unik untuk percakapan.
  • KEY_RING_NAME: Jika menggunakan CMEK, nama key ring Cloud KMS Anda.
  • KEY_NAME: Jika menggunakan CMEK, nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Jika menggunakan CMEK, project ID tempat kunci dihosting.
  • KEY_LOCATION: Jika menggunakan CMEK, lokasi key ring Anda. Untuk multi-region us, gunakan us-central1. Untuk multi-region eu, gunakan europe-west1. Untuk satu region, gunakan region yang sama dengan percakapan. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke lokasi percakapan, yang hanya berfungsi untuk satu region. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.

Mengelola agen data dan percakapan

Contoh kode berikut menunjukkan cara mengelola agen data dan percakapan Anda menggunakan Conversational Analytics API. Anda dapat melakukan tugas berikut:

Mendapatkan agen data

Contoh kode Python berikut menunjukkan cara membuat permintaan API untuk mengambil agen data yang telah Anda buat sebelumnya.

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

Pada contoh sebelumnya, ganti nilai data_agent_1 dengan ID unik untuk agen data yang ingin Anda ambil.

Mencantumkan agen data

Kode berikut menunjukkan cara mencantumkan semua agen data untuk project tertentu dengan memanggil metode list_data_agents. Untuk mencantumkan semua agen, Anda harus memiliki izin geminidataanalytics.dataAgents.list pada project. Untuk mengetahui informasi selengkapnya tentang peran IAM yang menyertakan izin ini, lihat daftar peran yang telah ditetapkan.

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)

Ganti YOUR-BILLING-PROJECT dengan ID project penagihan Anda.

Mencantumkan agen data yang dapat diakses

Kode berikut menunjukkan cara mencantumkan semua agen data yang dapat diakses untuk project tertentu dengan memanggil metode list_accessible_data_agents.

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)

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • YOUR-CREATOR-FILTER: Filter yang akan diterapkan berdasarkan pembuat agen data. Nilai yang mungkin mencakup NONE (default), CREATOR_ONLY, dan NOT_CREATOR_ONLY.

Memperbarui agen data

Kode contoh berikut menunjukkan cara mengupdate agen data secara sinkron atau asinkron dengan memanggil metode update_data_agent_sync atau update_data_agent pada resource agen data. Permintaan memerlukan objek DataAgent yang menyertakan nilai baru untuk kolom yang ingin Anda ubah, dan parameter update_mask yang menggunakan objek FieldMask untuk menentukan kolom yang akan diperbarui.

Untuk memperbarui agen data, Anda harus memiliki izin IAM geminidataanalytics.dataAgents.update pada agen. Untuk mengetahui informasi selengkapnya tentang peran IAM yang menyertakan izin ini, lihat daftar peran yang telah ditetapkan.

Sinkron

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}")

Asinkron

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}")

Ganti nilai contoh sebagai berikut:

  • data_agent_1: ID agen data yang ingin Anda perbarui.
  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • Updated description of the data agent.: Deskripsi agen data yang diperbarui.

Mendapatkan kebijakan IAM untuk agen data

Kode contoh berikut menunjukkan cara menggunakan metode get_iam_policy untuk mengambil kebijakan IAM untuk agen data. Permintaan menentukan jalur resource agen data.

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}")

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • data_agent_1: ID agen data yang kebijakan IAM-nya ingin Anda dapatkan.

Menetapkan kebijakan IAM untuk agen data

Untuk membagikan agen, Anda dapat menggunakan metode set_iam_policy untuk menetapkan peran IAM kepada pengguna di agen tertentu. Permintaan ini menyertakan binding yang menentukan peran yang harus ditetapkan kepada pengguna tertentu.

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}")

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • data_agent_1: ID agen data yang ingin Anda tetapkan kebijakan IAM-nya.
  • EMAIL_ADDRESSES: Daftar email pengguna yang dipisahkan koma yang ingin Anda beri peran yang ditentukan.

Menghapus agen data

Kode contoh berikut menunjukkan cara menggunakan metode delete_data_agent_sync atau delete_data_agent untuk menghapus agen data secara sinkron atau asinkron. Saat Anda menghapus agen data, agen tersebut akan memasuki periode penghapusan sementara selama 30 hari dan tidak dapat dipulihkan. Untuk mengetahui informasi selengkapnya, lihat Retensi dan penghapusan data. Permintaan menentukan URL resource agen data.

Sinkron

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}")

Asinkron

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}")

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • data_agent_1: ID agen data yang ingin Anda hapus.

Mendapatkan percakapan

Contoh kode berikut menunjukkan cara menggunakan metode get_conversation untuk mengambil informasi tentang percakapan yang ada. Permintaan menentukan jalur resource percakapan.

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)

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • conversation_1: ID percakapan yang ingin Anda ambil.

Membuat daftar percakapan

Kode contoh berikut menunjukkan cara mencantumkan percakapan untuk project tertentu dengan memanggil metode list_conversations. Permintaan menentukan URL resource induk, yaitu project dan lokasi (misalnya, projects/my-project/locations/global).

Secara default, metode ini menampilkan percakapan yang Anda buat. Admin (pengguna dengan peran IAM cloudaicompanion.topicAdmin) dapat melihat semua percakapan dalam project.

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)

Ganti YOUR-BILLING-PROJECT dengan ID project penagihan tempat Anda mengaktifkan API yang diperlukan.

Mencantumkan pesan dalam percakapan

Kode contoh berikut menunjukkan cara menggunakan metode list_messages untuk mengambil semua pesan dalam percakapan. Permintaan menentukan jalur resource percakapan.

Untuk mencantumkan pesan, Anda harus memiliki izin cloudaicompanion.topics.get pada percakapan.

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)

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • conversation_1: ID percakapan yang pesannya ingin Anda cantumkan.

Menghapus percakapan

Kode contoh berikut menunjukkan cara menghapus percakapan. Admin (pengguna dengan peran Identity and Access Management cloudaicompanion.topicAdmin) atau pengguna dengan izin Identity and Access Management cloudaicompanion.topics.delete dapat menghapus percakapan dalam project.

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)

Ganti nilai contoh sebagai berikut:

  • YOUR-BILLING-PROJECT: ID project penagihan Anda.
  • conversation_1: ID percakapan yang pesannya ingin Anda cantumkan.

Menggunakan API untuk mengajukan pertanyaan

Setelah membuat agen data dan, untuk chat stateful, percakapan, Anda dapat mengirim kueri ke agen. Contoh kode berikut menunjukkan cara memanggil metode data_chat_client.chat. Contoh ini menggunakan variabel konteks (seperti sumber data dan petunjuk sistem) yang Anda konfigurasi di Menyiapkan konteks untuk chat stateful atau stateless.

Saat Anda mengirim kueri, API akan menampilkan aliran objek Message. Streaming ini dapat berisi berbagai jenis pesan, termasuk teks, tabel data, dan diagram. Pesan teks dapat memberikan insight tentang penalaran agen, melaporkan progresnya, atau memberikan jawaban akhir. Tujuan setiap pesan teks ditunjukkan oleh nilai TextType:

  • THOUGHT: Menampilkan proses penalaran internal agen saat merencanakan cara menjawab kueri Anda. Pesan THOUGHT memberikan insight langkah demi langkah tentang proses penalaran dan pengambilan keputusan agen, serta berisi dua bagian: parts[0] adalah ringkasan pemikiran, yang meringkas teks pemikiran lengkap secara singkat, dan parts[1] adalah teks pemikiran lengkap.
  • PROGRESS: Melaporkan progres agen dalam suatu tindakan, seperti pengambilan data atau alat yang sedang dipanggil. Nilai ini hanya ditampilkan untuk sumber data Looker dan berisi dua bagian: parts[0] adalah ringkasan, dan parts[1] adalah teks progres lengkap.
  • FINAL_RESPONSE: Memberikan jawaban akhir untuk kueri Anda.

Contoh kode berikut menggunakan fungsi bantuan show_message, yang ditentukan dalam Menentukan fungsi bantuan, untuk memproses dan menampilkan setiap pesan dalam streaming. Untuk panduan tentang cara merender pesan ini di antarmuka pengguna saat Anda menggunakan sumber data Looker, lihat Merender respons agen untuk sumber data Looker.

Chat stateful

Mengirim permintaan chat stateful dengan referensi Conversation

Anda dapat mengirim permintaan chat stateful ke agen data dengan mereferensikan resource Conversation yang telah Anda buat sebelumnya.

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

# Form the request
request = geminidataanalytics.ChatRequest(
    parent = f"projects/{billing_project}/locations/{location}",
    # credentials = credentials,
    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)

Ganti nilai contoh sebagai berikut:

  • Which species of tree is most prevalent?: Pertanyaan dalam bahasa alami untuk dikirim ke agen data.
  • data_agent_1: ID unik untuk agen data, seperti yang ditentukan dalam Membuat agen data.
  • conversation_1: ID unik untuk percakapan, seperti yang ditentukan dalam Membuat percakapan.

Chat stateless

Contoh kode berikut menunjukkan cara mengirim kueri ke agen data saat Anda telah menyiapkan konteks untuk chat stateless. Anda dapat mengirim kueri stateless dengan mereferensikan resource DataAgent yang telah ditentukan sebelumnya atau dengan menggunakan konteks inline dalam permintaan.

Mengirim permintaan chat stateless dengan referensi DataAgent

Anda dapat mengirim kueri ke agen data dengan mereferensikan resource DataAgent yang telah Anda buat sebelumnya.

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

# Form the request
request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    # credentials=credentials,
    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)

Ganti nilai contoh sebagai berikut:

  • Which species of tree is most prevalent?: Pertanyaan dalam bahasa alami untuk dikirim ke agen data.
  • data_agent_1: ID unik untuk agen data, seperti yang ditentukan dalam Membuat agen data.

Mengirim permintaan chat stateless dengan konteks inline

Kode contoh berikut menunjukkan cara menggunakan parameter inline_context untuk memberikan konteks langsung dalam permintaan chat stateless Anda.

# 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}",
    # credentials=credentials,
    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)

Pada contoh sebelumnya, ganti Which species of tree is most prevalent? dengan pertanyaan bahasa alami untuk dikirim ke agen data.

Membuat percakapan multi-giliran stateless

Untuk mengajukan pertanyaan lanjutan dalam percakapan stateless, aplikasi Anda harus mengelola konteks percakapan dengan mengirimkan seluruh histori pesan bersama setiap permintaan baru. Contoh berikut menunjukkan cara membuat percakapan multi-turn dengan mereferensikan agen data atau menggunakan konteks inline untuk menyediakan sumber data secara langsung.

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

# 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}",
    # credentials=credentials,
    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?")

Pada contoh sebelumnya, ganti nilai contoh sebagai berikut:

  • data_agent_1: ID unik untuk agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.
  • Which species of tree is most prevalent?: Pertanyaan dalam bahasa alami untuk dikirim ke agen data.
  • Can you show me the results as a bar chart?: Pertanyaan lanjutan yang mengembangkan atau menyempurnakan pertanyaan sebelumnya.

Menentukan fungsi bantuan

Kode contoh berikut berisi definisi fungsi bantuan yang digunakan dalam contoh kode sebelumnya. Fungsi ini membantu mengurai respons dari API dan menampilkan hasilnya.

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