Menentukan konteks agen data untuk sumber data database

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

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:

  • alloydb untuk AlloyDB untuk PostgreSQL
  • spanner_reference untuk GoogleSQL untuk Spanner
  • cloud_sql_reference untuk 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 ke GOOGLE_SQL. Untuk instance Cloud SQL untuk MySQL, tetapkan ke MYSQL. Untuk instance Cloud SQL untuk PostgreSQL, tetapkan ke POSTGRESQL.
          • 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 menghilangkan graph_ids, QueryData akan menghasilkan kueri GoogleSQL terhadap tabel yang mendasarinya, bukan kueri GQL.
        • agent_context_reference: Link ke konteks yang ditulis dalam database.
  • 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."
}