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 AI AlloyDB. Natural language memungkinkan Anda membuat aplikasi AI generatif yang ditampilkan kepada 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 oleh 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 di project Google Cloud yang Anda gunakan:

roles/alloydb.admin (peran IAM bawaan AlloyDB Admin)

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

Menyiapkan lingkungan Anda

Untuk menyiapkan pembuatan 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, yang mengaktifkan ekstensi google_ml_integration dan alloydb_ai_nl.

CREATE EXTENSION google_ml_integration;
CREATE EXTENSION alloydb_ai_nl cascade;

Membuat konfigurasi natural language dan mendaftarkan skema

Bahasa alami AI AlloyDB menggunakan nl_config untuk mengaitkan aplikasi ke skema, template kueri, dan endpoint model tertentu. nl_config adalah konfigurasi yang mengaitkan aplikasi ke 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 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.

Daftarkan skema untuk konfigurasi yang ditentukan menggunakan contoh berikut:

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

Menambahkan 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 spesifik untuk aplikasi atau domain.

Menambahkan konteks umum untuk aturan khusus 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 terhadap 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 termasuk tabel, tampilan, tampilan terwujud, dan kolom. Konteks ini disimpan sebagai COMMENT dari setiap objek skema.

Untuk membuat konteks 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: Perbarui konteks skema yang dihasilkan.

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.

-- 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: Tetapkan konteks skema secara manual.

-- 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 dibuat dengan LLM, Anda dapat menambahkan template. Template kueri adalah kumpulan pertanyaan bahasa alami yang mewakili atau umum, dengan kueri SQL yang sesuai, serta penjelasan untuk memberikan alasan deklaratif untuk pembuatan natural language-to-SQL (NL2SQL). Template terutama ditujukan untuk ditentukan oleh aplikasi, tetapi template juga dapat otomatis dibuat 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 secara dinamis menggabungkan template SQL yang relevan dalam proses pembuatan pernyataan SQL untuk menjawab pertanyaan pengguna. template_store mengidentifikasi template dengan intent yang serupa dengan pertanyaan bahasa alami yang diajukan, mengidentifikasi pernyataan SQL berparameter yang sesuai, dan menyintesis pernyataan SQL dengan membuat instance parameter dengan nilai dari pertanyaan bahasa alami. Namun, jika tidak ada template dengan niat yang sama seperti pertanyaan yang diajukan pengguna, alloydb_ai_nl akan menggunakan setiap template dan konteks yang relevan untuk membuat pernyataan SQL.

Anda menambahkan template dengan menentukan pertanyaan (menggunakan parameter bernama intent) dan kueri SQL.

Untuk menambahkan template ke galeri 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 akan ditambahkan.

Membuat template secara otomatis

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

Setelah Anda menjalankan kueri, bahasa alami AlloyDB AI dapat otomatis membuat template berdasarkan histori kueri. Anda dapat memanggil API berikut untuk membuat template. Anda perlu meninjau dan menerapkan template yang dihasilkan sebelum template tersebut diterapkan.

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
File yang dapat dieksekusi: kueri berhasil diproses oleh perintah EXPLAIN.
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 dihasilkan 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

Untuk mengupdate template yang dihasilkan, 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 peninjauan.
```
-- 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 natural language AI AlloyDB, 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 bentuknya yang literal.

Misalnya, dua nama negara mungkin sama meskipun satu nama negara ditulis dalam huruf besar, misalnya, USA, dan nama negara lainnya ditulis dalam 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 ke jenis konsep, membuat dan memuat ulang indeks nilai, serta menggunakan kumpulan 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 dikaitkan 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.

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 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 salah satu sinonim muncul dalam pertanyaan dalam natural language, natural language AI AlloyDB akan mencocokkan sinonim dengan nilai dalam tabel Anda.

Lakukan penelusuran nilai untuk menemukan nilai database yang benar, dengan mempertimbangkan array frasa nilai.

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 AI AlloyDB 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.

Natural language menemukan hasil—nilai USA— yang mendekati 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';

Jenis konsep bawaan yang ditentukan oleh bahasa alami AlloyDB AI tercantum dalam tabel berikut.

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. Maksimal tiga kolom jenis string dapat digunakan untuk nama lengkap orang. Setiap kolom dapat dilewati saat mengaitkan kolom nama ke `full_person_name`. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	Satu kolom string 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 bahasa alami AlloyDB AI untuk membuat pernyataan SQL dari input bahasa alami. Saat Anda menjalankan pernyataan SQL yang dihasilkan, pernyataan tersebut akan menyediakan data dari database yang Anda perlukan 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 meningkatkan kualitas

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