Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat kueri SQL menggunakan pertanyaan bahasa alami

Halaman ini menjelaskan cara menyiapkan, mengonfigurasi, dan membuat pernyataan SQL menggunakan bahasa alami AlloyDB AI. Natural language memungkinkan Anda membuat aplikasi AI generatif yang menghadap pengguna menggunakan natural language untuk membuat kueri database.

Untuk mengaktifkan ekstensi alloydb_ai_nl, yang merupakan API dukungan bahasa alami AlloyDB untuk PostgreSQL, Anda harus melakukan langkah-langkah tingkat tinggi berikut:

Instal ekstensi alloydb_ai_nl.
Tentukan konfigurasi bahasa alami untuk aplikasi Anda.
Mendaftarkan skema.
Tambahkan konteks.
Tambahkan template kueri.
Tentukan jenis konsep dan buat indeks nilai.
Buat pernyataan SQL menggunakan antarmuka bahasa alami.

Sebelum memulai

Minta akses ke bahasa alami AlloyDB AI dan tunggu hingga Anda menerima konfirmasi pengaktifan sebelum mengikuti petunjuk di halaman ini.
Pahami cara terhubung ke database AlloyDB dan menjalankan perintah PostgreSQL. Untuk mengetahui informasi selengkapnya, lihat Ringkasan koneksi.
Isi database dengan data dan skema yang ingin diakses pengguna akhir.

Membuat cluster dan mengaktifkan integrasi Vertex AI

Buat cluster dan instance AlloyDB. Anda menggunakan instance AlloyDB untuk membuat database dan skema aplikasi.
Aktifkan integrasi Vertex AI. Untuk mengetahui informasi selengkapnya, lihat Mengintegrasikan dengan Vertex AI.

Peran yang diperlukan

Untuk menginstal ekstensi alloydb_ai_nl dan memberikan akses kepada pengguna lain, Anda harus memiliki peran Identity and Access Management (IAM) berikut dalam project Google Cloud yang Anda gunakan:

roles/alloydb.admin: peran IAM bawaan Admin AlloyDB

Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna PostgreSQL dengan autentikasi bawaan.

Menyiapkan lingkungan Anda

Untuk bersiap membuat kueri bahasa alami, Anda harus menginstal ekstensi yang diperlukan, membuat konfigurasi, dan mendaftarkan skema.

Menginstal ekstensi `alloydb_nl_ai`

Ekstensi alloydb_ai_nl menggunakan ekstensi google_ml_integration, yang berinteraksi dengan model bahasa besar (LLM), termasuk model Gemini di Vertex AI.

Untuk menginstal ekstensi alloydb_ai_nl, hubungkan ke database dan jalankan perintah berikut:

CREATE EXTENSION alloydb_ai_nl cascade;

Membuat konfigurasi bahasa alami dan mendaftarkan skema

Bahasa alami AI AlloyDB menggunakan nl_config untuk mengaitkan aplikasi dengan skema, template kueri, dan endpoint model tertentu. nl_config adalah konfigurasi yang mengaitkan aplikasi dengan skema, template, dan konteks lainnya. Aplikasi besar juga dapat menggunakan konfigurasi yang berbeda untuk berbagai bagian aplikasi, selama Anda menentukan konfigurasi yang tepat saat pertanyaan dikirim dari bagian aplikasi tersebut. Anda dapat mendaftarkan seluruh skema, atau Anda dapat mendaftarkan objek skema tertentu, seperti tabel, tampilan, dan kolom.

Untuk membuat konfigurasi bahasa alami, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

gemini-2.0-flash:generateContent adalah endpoint model.

Untuk mendaftarkan skema untuk konfigurasi tertentu, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

Tambahkan konteks

Konteks mencakup semua jenis informasi yang dapat Anda gunakan untuk menjawab pertanyaan pengguna akhir. Konteks mencakup struktur dan hubungan skema, ringkasan dan deskripsi kolom, nilai kolom dan semantiknya, serta aturan atau pernyataan logika bisnis yang khusus untuk aplikasi atau domain.

Menambahkan konteks umum untuk aturan spesifik per aplikasi

Item konteks umum mencakup aturan khusus aplikasi, pernyataan logika bisnis, atau terminologi khusus aplikasi dan domain yang tidak ditautkan ke objek skema tertentu.

Untuk menambahkan konteks umum untuk aturan khusus aplikasi dan terminologi khusus aplikasi atau domain, ikuti langkah-langkah berikut:

Untuk menambahkan item konteks umum untuk konfigurasi yang ditentukan, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );

Pernyataan sebelumnya membantu bahasa alami AlloyDB AI memberikan respons berkualitas lebih tinggi atas pertanyaan bahasa alami pengguna.

Untuk melihat konteks umum untuk konfigurasi yang ditentukan, jalankan pernyataan berikut:
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

Membuat dan meninjau konteks skema

Konteks skema menjelaskan objek skema, yang mencakup tabel, tampilan, tampilan terwujud, dan kolom. Konteks ini disimpan sebagai COMMENT setiap objek skema.

Untuk membuat konteks untuk objek skema, panggil API berikut. Untuk mendapatkan hasil terbaik, pastikan tabel database berisi data yang representatif.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

Tinjau konteks skema yang dihasilkan dengan menjalankan pernyataan berikut:
```
SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;
```
Konteks skema yang dihasilkan disimpan dalam tampilan sebelumnya.

Opsional: Untuk memperbarui konteks skema yang dihasilkan, jalankan pernyataan berikut:

SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

Terapkan konteks. Saat Anda menerapkan konteks, konteks tersebut akan langsung berlaku dan dihapus dari generated_schema_context_view. Jalankan perintah berikut:

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

Opsional: verifikasi konteks yang dihasilkan. API berikut memungkinkan Anda memeriksa konteks skema, yang digunakan saat Anda membuat pernyataan SQL:

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

Opsional: untuk menetapkan konteks skema secara manual, jalankan pernyataan berikut:

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

Membuat template kueri

Untuk meningkatkan kualitas aplikasi AI generatif yang dibangun dengan LLM, Anda dapat menambahkan template. Template kueri adalah kumpulan terkurasi dari pertanyaan bahasa alami yang representatif atau umum, dengan kueri SQL yang sesuai, serta penjelasan untuk memberikan alasan deklaratif bagi pembuatan natural language-to-SQL (NL2SQL). Template terutama ditujukan untuk ditentukan oleh aplikasi, tetapi template juga dapat dibuat secara otomatis oleh ekstensi alloydb_ai_nl berdasarkan kueri SQL yang sering digunakan. Setiap template harus dikaitkan dengan nl_config.

Ekstensi alloydb_ai_nl menggunakan template_store untuk menggabungkan template SQL yang relevan secara dinamis dalam proses pembuatan pernyataan SQL untuk menjawab pertanyaan pengguna. template_store mengidentifikasi template dengan maksud yang serupa dengan pertanyaan bahasa alami yang diajukan, mengidentifikasi pernyataan SQL berparameter yang sesuai, dan menyintesis pernyataan SQL dengan membuat parameter dengan nilai dari pertanyaan bahasa alami. Namun, jika tidak ada template dengan maksud yang sama dengan pertanyaan yang diajukan pengguna, alloydb_ai_nl menggunakan setiap template dan konteks yang relevan untuk menyusun pernyataan SQL.

Untuk menambahkan template, Anda menentukan pertanyaan—menggunakan parameter bernama intent—dan kueri SQL.

Untuk menambahkan template ke toko template, jalankan pernyataan berikut:

SELECT
  alloydb_ai_nl.add_template(
    nl_config => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    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''',
    check_intent => TRUE
  );

Jika check_intent adalah TRUE, alloydb_ai_nl akan melakukan pemeriksaan semantik untuk mengonfirmasi bahwa intent yang diberikan cocok dengan pernyataan SQL yang diteruskan. Jika intent tidak cocok dengan pernyataan SQL, template tidak ditambahkan.

Membuat template secara otomatis

Setelah Anda memiliki set data representatif di tabel, sebaiknya Anda menjalankan kueri SQL yang sesuai dengan pertanyaan umum yang kemungkinan akan diajukan oleh pengguna akhir Anda. Anda harus memastikan bahwa kueri memiliki rencana kueri yang baik dan berperforma baik.

Setelah Anda menjalankan kueri, bahasa alami AlloyDB AI dapat membuat template secara otomatis berdasarkan histori kueri. Anda dapat memanggil API berikut untuk membuat template. Anda harus meninjau dan menerapkan template yang dibuat sebelum template tersebut berlaku.

Pembuatan otomatis template didasarkan pada kueri yang paling sering digunakan dalam log kueri, google_db_advisor_workload_statements. Kueri difilter berdasarkan kriteria berikut:

Pernyataan SELECT
Dapat dieksekusi: perintah EXPLAIN berhasil memproses kueri.
Tidak ada duplikasi: kueri belum pernah digunakan sebelumnya untuk membuat template.
Semua tabel dan tampilan yang dirujuk berada dalam cakupan nl_config.

Untuk membuat, meninjau, dan menerapkan template secara otomatis, ikuti langkah-langkah berikut:

Minta AlloyDB untuk membuat template berdasarkan histori kueri Anda:
```
SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);
```
Gunakan tampilan yang disediakan, alloydb_ai_nl.generated_templates_view, untuk meninjau generated_templates.

Output berikut menunjukkan jumlah template yang dihasilkan:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

Tinjau template yang dibuat menggunakan tampilan generated_templates_view.

SELECT *
FROM alloydb_ai_nl.generated_templates_view;

Berikut adalah contoh output yang ditampilkan:

-[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

manifest dalam output yang ditampilkan adalah template umum atau deskripsi luas tentang jenis pertanyaan atau operasi yang dapat dilakukan. pintent adalah versi berparameter dari intent, dan menggeneralisasi intent dengan mengganti nilai tertentu (1997) dengan placeholder ($1).

Untuk memperbarui template yang dibuat, jalankan contoh pernyataan berikut:

SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

Terapkan template. Template yang Anda terapkan akan langsung ditambahkan ke toko template, dan dihapus dari tampilan ulasan.

-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

Mengonfigurasi keamanan untuk bahasa alami

Untuk mengonfigurasi keamanan untuk natural language AlloyDB AI, lihat Mengelola keamanan aplikasi data menggunakan tampilan aman berparameter.

Menentukan jenis konsep dan indeks nilai

Anda menentukan jenis konsep dan indeks nilai untuk memberikan pemahaman yang lebih mendalam tentang pertanyaan yang diajukan. Jenis konsep adalah kategori atau class entitas yang mengidentifikasi makna semantik kata dan frasa, bukan hanya bentuk literalnya.

Misalnya, dua nama negara mungkin sama meskipun salah satu nama negara menggunakan huruf kapital, misalnya, USA, dan nama negara lainnya menggunakan huruf kecil, misalnya, usa. Dalam hal ini, nama negara adalah jenis konsep. Contoh jenis konsep lainnya mencakup nama orang, nama kota, dan tanggal.

Indeks nilai adalah indeks di atas nilai dalam kolom yang merupakan bagian dari konfigurasi bahasa alami nl_config, berdasarkan jenis konsep yang terkait dengan setiap kolom. Indeks nilai memungkinkan pencocokan frasa nilai yang efisien untuk pertanyaan yang diajukan dan nilai dalam database.

Untuk menentukan jenis konsep dan indeks nilai, ikuti langkah-langkah berikut menggunakan contoh yang diberikan. Contoh ini mengaitkan kolom dengan jenis konsep, membuat dan memperbarui indeks nilai, serta menggunakan set sinonim untuk melakukan penelusuran nilai.

Untuk mengaitkan kolom dengan jenis konsep, jalankan kueri berikut:

SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

Untuk membuat indeks nilai berdasarkan semua kolom yang merupakan bagian dari konfigurasi bahasa alami dan terkait dengan jenis konsep, jalankan pernyataan berikut:
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Saat Anda mengaitkan jenis konsep ke kolom baru, muat ulang indeks nilai untuk mencerminkan perubahan. Gunakan pernyataan berikut:
```
SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Untuk mengaktifkan bahasa alami AI AlloyDB agar cocok dengan sinonim nilai, jalankan contoh pernyataan berikut:
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
Meskipun data dalam tabel Anda mungkin menggunakan nilai tertentu—misalnya, jika United States digunakan untuk mengidentifikasi negara—Anda dapat menentukan kumpulan sinonim yang berisi semua sinonim untuk United States. Jika ada sinonim yang muncul dalam pertanyaan natural language, AlloyDB AI akan mencocokkan sinonim tersebut dengan nilai dalam tabel Anda.

Lakukan penelusuran nilai untuk menemukan nilai database yang benar, mengingat array frasa nilai, menggunakan pernyataan berikut:

SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

Misalnya, jika pengguna mengajukan pertanyaan seperti "Berapa populasi Amerika Serikat?" yang menggunakan kueri get_sql berikut, bahasa alami AlloyDB AI menggunakan fungsi get_concept_and_value dengan frasa nilai United States untuk melakukan penelusuran fuzzy terhadap indeks nilai. Penelusuran fuzzy adalah teknik penelusuran yang menemukan kecocokan meskipun kueri penelusuran tidak cocok dengan data terkait.

Bahasa alami menemukan hasil—nilai USA—yang mirip dengan kueri penelusuran, dan menggunakan hasil tersebut untuk membuat kueri SQL.

SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

Tabel berikut mencantumkan jenis konsep bawaan yang ditentukan oleh bahasa alami AI AlloyDB:

Nama konsep	Deskripsi
`generic_entity_name`	Satu kolom jenis string dapat digunakan untuk nama entity generik. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
`country_name`, `city_name`, `region_name`	Nama negara, kota, dan wilayah. Penggunaannya sama persis dengan jenis konsep `generic_entity_name`.
`full_person_name`	Nama orang, yang terdiri dari nama depan, nama belakang, dan nama tengah. Hingga tiga kolom jenis string dapat digunakan untuk nama lengkap seseorang. Kolom mana pun dapat dilewati saat mengaitkan kolom nama ke `full_person_name`. Contoh: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	Kolom string tunggal yang berisi nomor jaminan sosial. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
`date`	Tanggal atau stempel waktu. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Membuat pernyataan SQL dari input bahasa alami

Anda dapat menggunakan natural language AlloyDB AI untuk membuat pernyataan SQL dari input natural language. Saat Anda menjalankan pernyataan SQL yang dihasilkan, pernyataan tersebut akan memberikan data dari database yang Anda butuhkan untuk menjawab pertanyaan bahasa alami.

Untuk menggunakan bahasa alami guna mendapatkan hasil dari database menggunakan fungsi alloydb_ai_nl.get_sql, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

Output JSON berikut akan ditampilkan:

{
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

Opsional: Untuk mengekstrak kueri SQL yang dihasilkan sebagai string teks, tambahkan ->>'sql':
```
SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';
```
Operator ->> digunakan untuk mengekstrak nilai JSON sebagai teks. Fungsi alloydb_ai_nl.get_sql menampilkan objek JSON, yang merupakan bagian dari pernyataan yang mengambil nilai yang terkait dengan kunci sql. Nilai ini adalah kueri SQL yang dihasilkan.

Menguji dan menyempurnakan

Untuk mendapatkan kueri yang dibuat secara otomatis yang lebih baik, ubah atau tambahkan konteks yang lebih baik, template kueri, dan indeks nilai, lalu lakukan iterasi hingga Anda mendapatkan hasil yang diinginkan.