Halaman ini menjelaskan cara memberikan konteks yang ditulis untuk agen data yang menggunakan sumber data database.
Konteks yang ditulis adalah panduan yang dapat diberikan oleh pemilik agen data untuk membentuk perilaku agen data dan menyempurnakan respons API. Konteks buatan yang efektif memberikan konteks yang berguna kepada agen data Analisis Percakapan API Anda untuk menjawab pertanyaan tentang sumber data Anda.
Untuk sumber data database seperti AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL, Anda memberikan konteks yang ditulis dengan terlebih dahulu menentukan dan menyimpan konteks dalam database, lalu mereferensikannya dalam referensi sumber data Anda. Contoh di halaman ini menggunakan metode QueryData.
Dengan memberikan konteks akurasi tinggi, API dapat menghasilkan kueri SQL dan jawaban yang lebih akurat dan relevan.
Sebelum memulai
- Anda memerlukan agen data dengan konteks agen yang diupload untuk database yang ingin Anda kueri. Untuk mengetahui informasi selengkapnya, lihat dokumentasi agen data untuk AlloyDB, Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL. Untuk Spanner Graph, lihat Mengelola set konteks di Spanner Studio.
- Untuk membuat, mengupload, dan mengelola set konteks untuk sumber data database, aktifkan Knowledge Catalog API dan berikan peran Dataplex Catalog Editor (
roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) kepada pengguna IAM atau akun layanan di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks. Aktifkan Cloud SQL Data API untuk instance Anda sebagai berikut:
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_APIGanti
INSTANCE_IDdengan ID instance Cloud SQL untuk MySQL atau Cloud SQL untuk PostgreSQL Anda.Anda juga harus memberikan hak istimewa database kepada pengguna atau akun layanan IAM. Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada akun layanan atau pengguna IAM perorangan di Cloud SQL untuk MySQL dan Memberikan hak istimewa database kepada akun layanan atau pengguna IAM perorangan di Cloud SQL untuk PostgreSQL.
Memberikan konteks dengan QueryData
Saat memanggil metode QueryData, Anda memberikan informasi sumber data dan konteks dalam kolom QueryDataRequest.context.datasourceReferences. Untuk sumber data database, Anda harus menggunakan salah satu opsi berikut:
alloydbuntuk AlloyDB untuk PostgreSQLspanner_referenceuntuk GoogleSQL untuk Spannercloud_sql_referenceuntuk Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL
Dalam referensi ini, Anda menentukan database dan tabel menggunakan kolom databaseReference. Untuk menyertakan konteks yang ditulis, Anda juga harus memberikan agentContextReference yang mengarah ke context_set_id.
Contoh permintaan QueryData dengan konteks yang ditulis
Contoh berikut menunjukkan permintaan QueryData yang menggunakan alloydb. Kolom agent_context_reference.context_set_id digunakan untuk menautkan ke konteks yang telah dibuat sebelumnya dan disimpan dalam database.
AlloyDB
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "alloydb": { "database_reference": { "project_id": "data-agents-project", "region": "us-central1", "cluster_id": "sqlgen-magic", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
GoogleSQL untuk Spanner
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "spanner_reference" { "database_reference" { "engine": "GOOGLE_SQL" "project_id": "data-agents-project" "instance_id": "evalbench" "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Spanner Graph
{ "parent": "projects/data-agents-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "data-agents-project", "instance_id": "data-agents-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL untuk MySQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "MYSQL" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL untuk PostgreSQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "POSTGRES" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Isi permintaan berisi kolom berikut:
prompt: Pertanyaan bahasa alami dari pengguna akhir.context: Berisi informasi tentang sumber data.datasource_references: Menentukan jenis sumber data.alloydb: Diperlukan saat membuat kueri database. Kolom ini berubah berdasarkan database yang Anda kueri.database_reference: Menentukan informasi yang terkait dengan instance database Anda.engine: Mesin database atau dialek SQL. Opsional untuk AlloyDB. Untuk database Spanner, tetapkan keGOOGLE_SQL. Untuk instance Cloud SQL untuk MySQL, tetapkan keMYSQL. Untuk instance Cloud SQL untuk PostgreSQL, tetapkan kePOSTGRESQL.project_id: Project ID instance database.region: Region instance database.cluster_id: ID cluster instance database.instance_id: ID instance database.database_id: ID database.graph_ids: Diperlukan untuk Spanner Graph. Daftar nama grafik properti dalam database Spanner yang akan dikueri (misalnya,["FinGraph"]). Jika Anda menghilangkangraph_ids, QueryData akan menghasilkan kueri GoogleSQL terhadap tabel yang mendasarinya, bukan kueri GQL.
agent_context_reference: Link ke konteks yang ditulis dalam database.context_set_id: ID konteks agen yang disimpan dalam database. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat dokumentasi untuk AlloyDB, Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL. Untuk Spanner Graph, lihat Menemukan ID set konteks.
generationOptions: Mengonfigurasi jenis output yang akan dibuat.generate_query_result: Tetapkan ke true untuk membuat dan menampilkan hasil kueri.generate_natural_language_answer: Opsional. Jika ditetapkan ke true, akan menghasilkan jawaban dalam bahasa alami.generate_explanation: Opsional. Jika ditetapkan ke true, akan menghasilkan penjelasan kueri SQL.generate_disambiguation_question: Opsional. Jika disetel ke true, akan menghasilkan pertanyaan disambiguasi jika kueri bersifat ambigu.
Contoh Respons QueryData
Berikut adalah contoh respons yang berhasil dari panggilan QueryData:
{
"generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
"intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
"query_result": {
"columns": [
{
"name": "count"
}
],
"rows": [
{
"values": [
{
"value": "2"
}
]
}
],
"total_row_count": 1
},
"natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}