Ringkasan set konteks

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan, dan Persyaratan Tambahan untuk Produk Pratinjau AI Generatif. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan antarmuka PostgreSQL: Contoh dalam topik ini ditujukan untuk database dialek GoogleSQL. Fitur ini tidak mendukung antarmuka PostgreSQL.

Set konteks memungkinkan Anda berinteraksi dengan data di database menggunakan bahasa percakapan dan digunakan oleh alat seperti QueryData untuk membangun agen percakapan. Anda dapat membuat set konteks dengan menentukan konteks untuk sekumpulan tabel dalam database Anda. Konteks ini memungkinkan QueryData menerjemahkan pertanyaan bahasa alami menjadi kueri yang akurat untuk kasus penggunaan target Anda.

Set konteks adalah kumpulan informasi khusus database yang memungkinkan QueryData membuat kueri dengan akurasi tinggi. Set konteks mencakup template, aspek, dan penelusuran nilai yang membantu QueryData memahami skema database dan logika bisnis aplikasi Anda.

Database berikut didukung:

• AlloyDB untuk PostgreSQL
• Cloud SQL untuk MySQL
• Cloud SQL untuk PostgreSQL
• Spanner

Kapan harus menggunakan set konteks

Anda dapat menggunakan set konteks untuk membuat aplikasi data percakapan yang ideal untuk kasus penggunaan seperti:

• Otomatisasi layanan pelanggan: Menangani pertanyaan dalam jumlah besar seperti "Di mana pesanan saya?" atau "Berapa saldo saya saat ini?".
• Asisten belanja e-commerce: Membantu pengguna menavigasi katalog produk besar dengan kueri bahasa alami seperti "Tampilkan sepatu lari di bawah Rp1.000.000".
• Alat operasi lapangan: Memungkinkan karyawan seluler untuk membuat kueri tingkat inventaris, ketersediaan suku cadang, atau detail tiket servis secara real-time.

Cara kerja set konteks

Untuk membangun aplikasi yang efektif, QueryData harus memahami organisasi data dan logika bisnis Anda. Anda memberikan informasi ini dalam bentuk set konteks.

Anda menentukan konteks dalam file yang berisi objek JSON untuk setiap jenis konteks. Anda membuat file konteks ini dengan bantuan Gemini CLI. Kemudian, Anda mengupload file konteks ke set konteks yang Anda buat di konsol Google Cloud. Proses ini memungkinkan QueryData mempelajari skema spesifik database dan logika bisnis aplikasi.

File konteks terlihat mirip dengan berikut ini:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Saat pengguna akhir mengajukan pertanyaan dalam bahasa alami, QueryData memprioritaskan pencocokan pertanyaan dengan template dan aspek yang telah diaudit oleh developer yang menyeleksi konteks. Setelah mengidentifikasi kecocokan, QueryData akan menggunakan template kueri dan faset yang dipilih untuk menyintesis kueri database. Logika set konteks kemudian menjalankan kueri tersebut terhadap database untuk menampilkan hasil yang akurat.

Langkah yang direkomendasikan adalah menentukan penelusuran nilai dalam konteks Anda. Penelusuran nilai memungkinkan agen memetakan frasa nilai ke nilai tertentu yang disimpan di kolom database Anda. Tindakan ini akan membatasi LLM pada data Anda yang sebenarnya, sehingga membantu menyelesaikan ambiguitas, seperti apakah suatu istilah merujuk pada nama District atau City.

Jika agen gagal menemukan template yang cocok, agen akan menggunakan penelusuran nilai untuk memetakan frasa bahasa alami ke nilai tertentu yang disimpan di kolom database Anda. Hal ini akan mendasarkan LLM pada data Anda yang sebenarnya, sehingga membantu LLM menyelesaikan ambiguitas, seperti apakah suatu istilah merujuk pada District, Name, atau City.

Endpoint QueryData di Conversational Analytics API adalah alat berbasis agen yang memungkinkan integrasi terprogram dengan aplikasi Anda untuk mengaktifkan pembuatan kueri SQL dari pertanyaan bahasa alami. Dalam aplikasi percakapan, endpoint QueryData harus digunakan dalam framework yang mengelola histori dan konteks percakapan.

File set konteks

File set konteks terdiri dari serangkaian template dan aspek yang dikurasi dalam format JSON yang memandu QueryData dalam menerjemahkan pertanyaan bahasa alami menjadi kueri untuk database tertentu. Menentukan konteks memastikan pembuatan SQL dengan akurasi tinggi untuk pola kueri umum.

Pastikan set konteks akurat dan komprehensif dalam cakupan kueri aplikasi yang diharapkan untuk memaksimalkan akurasi.

Set konteks dapat dibuat di region us-central1, us-east1, europe-west4, dan asia-southeast1.

Template kueri

Template kueri adalah kumpulan pertanyaan bahasa alami representatif yang dikurasi dengan kueri SQL yang sesuai. Model ini juga menyertakan penjelasan untuk memberikan alasan deklaratif bagi pembuatan SQL dari bahasa alami.

Objek template kueri akan terlihat seperti berikut:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

Komponen utama objek JSON template kueri adalah sebagai berikut:

• nl_query: Contoh kueri bahasa alami yang ditangani QueryData.
• sql: Kueri SQL untuk kueri bahasa natural.
• intent: Sasaran atau tujuan kueri bahasa alami. Jika tidak ditetapkan, nilai ini secara default adalah kueri bahasa alami.
• manifest: Bentuk intent yang digeneralisasi dan dihasilkan otomatis.
• parameterized_intent: Bentuk intent yang dibuat otomatis dan menggunakan template, dengan nilai entity diganti dengan parameter.
• parameterized_sql: Bentuk kueri SQL yang dibuat otomatis dan menggunakan template yang sesuai dengan intent berparameter.

Facet kueri

Faset kueri adalah kumpulan kondisi bahasa alami representatif yang dikurasi dengan predikat SQL yang sesuai. Faset mengelola pemfilteran dan kondisi, yang memungkinkan template kueri melakukan penelusuran berfaset.

Objek aspek kueri terlihat mirip dengan berikut ini:

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Komponen utama objek JSON aspek adalah sebagai berikut:

• sql_snippet: Cuplikan SQL.
• intent: Penjelasan predikat SQL.
• manifest: Bentuk intent yang digeneralisasi dan dihasilkan otomatis.
• parameterized_intent: Bentuk intent yang dibuat otomatis dan menggunakan template, dengan nilai entity diganti dengan parameter.
• parameterized_sql_snippet: Bentuk sql_snippet yang dibuat otomatis dan menggunakan template yang sesuai dengan intent berparameter.

Kueri penelusuran nilai

Kueri penelusuran nilai adalah kueri yang ditentukan developer yang menggunakan fungsi pencocokan untuk menemukan nilai dan konteksnya dalam database. Penautan nilai menggunakan hasil kueri ini untuk mengidentifikasi tabel dan kolom mana yang berisi nilai yang cocok, memahami jenis konsep nilai, dan mengoreksi salah eja.

QueryData API menggunakan penautan nilai untuk mengonversi bahasa alami menjadi SQL secara lebih akurat. Dengan menggunakan kueri penelusuran nilai, API dapat mengoreksi salah eja dan menyelesaikan jenis nilai berdasarkan nilai database, sehingga meningkatkan akurasi konversi.

Penautan nilai meningkatkan akurasi konversi natural language ke SQL. Misalnya, jika pengguna bertanya, "Apakah ada penerbangan dari Heathrow?", database mungkin menyimpan nama bandara sebagai "London Heathrow". Tanpa penautan nilai, SQL yang dihasilkan dapat memfilter menurut WHERE name = 'Heathrow' dan tidak menampilkan hasil. Kueri penelusuran nilai memandu agen untuk memetakan "Heathrow" ke nilai database yang benar "London Heathrow" dan lokasi skemanya (airports.name), sehingga memastikan SQL yang dihasilkan akurat.

Contoh kueri penelusuran nilai adalah:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Komponen utama objek JSON penelusuran nilai adalah sebagai berikut:

• query: Pernyataan SQL berparameter yang menentukan logika untuk mencocokkan frasa nilai dengan nilai yang disimpan dalam kolom tabel di database. Set hasil biasanya memproyeksikan nilai yang cocok, lokasi skema, jenis konsep, dan metrik jarak yang dinormalisasi (antara 0 dan 1).
• concept_type: Label semantik yang ditetapkan ke nilai—misalnya, district atau loan_status. Label ini membantu penautan nilai dan pada akhirnya API QueryData memahami peran frasa nilai dalam skema. Hal ini juga membantu menghasilkan pernyataan SQL yang menargetkan konsep untuk nilai, serta tabel dan kolom tempat frasa nilai muncul.
• description: Deskripsi logika penelusuran.

Batasan

Set konteks memiliki batasan berikut:

• Set konteks untuk database hanya mendukung template, aspek, dan penelusuran nilai.
• Set konteks untuk database hanya digunakan oleh endpoint QueryData di Conversational Analytics API.

Peringatan: Semua konteks agen yang terkait dengan database dapat dilihat oleh semua pengguna dengan akses baca apa pun ke database tersebut. Dalam kasus saat pengguna memiliki akses yang lebih terbatas ke database, seperti kontrol akses terperinci Spanner, pengguna berpotensi menemukan kolom dan tabel lain dari konteks agen.

Langkah berikutnya

• Pelajari cara membuat atau menghapus set konteks di Spanner Studio.