Membangun set konteks menggunakan Gemini CLI

MySQL   |  PostgreSQL   |  SQL Server

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.

Dokumen ini menjelaskan cara menggunakan Gemini CLI dan MCP toolbox untuk membuat file konteks agen. File ini berisi template, aspek, dan penelusuran nilai yang memberikan konteks untuk membuat kueri SQL dari bahasa alami. Anda juga akan menggunakan ekstensi DB Context Enrichment.

Untuk mempelajari set konteks, lihat Ringkasan set konteks.

Untuk membuat file konteks agen, lakukan langkah-langkah tingkat tinggi berikut:

• Menyiapkan lingkungan Anda
• Membuat template yang ditargetkan
• Membuat aspek yang ditargetkan
• Membuat penelusuran nilai yang ditargetkan
• Opsional. Membuat template massal

Sebelum memulai

Selesaikan prasyarat berikut sebelum membuat agen.

Mengaktifkan layanan yang diperlukan

Aktifkan layanan berikut untuk project Anda:

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Dataplex Universal Catalog API

Menyiapkan instance Cloud SQL

Pastikan Anda memiliki akses ke instance Cloud SQL yang ada atau buat instance baru. Untuk mengetahui informasi selengkapnya, lihat Membuat instance untuk Cloud SQL.

Tutorial ini mengharuskan Anda memiliki database di instance Cloud SQL. Untuk mengetahui informasi selengkapnya, lihat Membuat database di instance Cloud SQL

Peran dan izin yang diperlukan

• Tambahkan akun pengguna atau layanan IAM ke instance. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi database IAM untuk Cloud SQL.
• Berikan peran cloudsql.studioUser, cloudsql.instanceUser, dan geminidataanalytics.queryDataUser kepada pengguna IAM di tingkat project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
• Anda juga harus memberikan hak istimewa database hanya baca kepada pengguna atau akun layanan IAM dengan login sebagai pengguna yang memiliki hak istimewa superuser, seperti pengguna postgres.
  
  GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;
  
  Ganti USER_NAME dengan alamat email pengguna. Anda harus menggunakan tanda kutip di sekitar email karena berisi karakter khusus (@ dan .).
  
  Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada pengguna atau akun layanan IAM.

Memberikan izin executesql ke instance Cloud SQL

Untuk memberikan izin executesql ke instance Cloud SQL dan mengaktifkan Cloud SQL Data API, jalankan perintah berikut:

gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Ganti kode berikut:

• PROJECT_ID: ID project Anda. Google Cloud
• INSTANCE_ID: ID instance Cloud SQL Anda.

Untuk melakukan langkah-langkah dalam tutorial ini, login ke Google Cloud, lalu lakukan autentikasi ke database menggunakan autentikasi IAM.

Menyiapkan lingkungan Anda

Anda dapat membuat file set konteks dari lingkungan pengembangan lokal atau IDE. Untuk menyiapkan lingkungan, lakukan langkah-langkah berikut:

• Menginstal Gemini CLI
• Menginstal ekstensi DB Context Enrichment
• Menyiapkan koneksi database

Menginstal Gemini CLI

Untuk menginstal Gemini CLI, lihat Memulai Gemini CLI.

Menginstal ekstensi MCP DB Context Enrichment

Ekstensi DB Context Enrichment menyediakan alur kerja interaktif terpandu untuk membuat konteks NL2SQL terstruktur dari skema database Anda.

Untuk mengetahui informasi selengkapnya tentang cara menginstal ekstensi DB Context Enrichment, lihat Ekstensi DB Context Enrichment.

Untuk menginstal ekstensi DB Context Enrichment, ikuti langkah-langkah berikut:

1. Instal ekstensi Gemini CLI DB Context Enrichment:

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

   Catatan: Ekstensi ini memerlukan kunci Gemini API saat penginstalan untuk melakukan autentikasi dengan Gemini API dan mengaktifkan pembuatan konteks. Untuk mengetahui informasi selengkapnya tentang cara menemukan kunci API, lihat Menggunakan kunci Gemini API.

2. (Opsional) Perbarui ekstensi DB Context Enrichment.

   Untuk memverifikasi versi ekstensi yang diinstal, jalankan perintah berikut:

   gemini extensions list

   Pastikan versinya adalah 0.4.2 atau yang lebih tinggi. Untuk memperbarui ekstensi DB Context Enrichment, jalankan perintah berikut:

     gemini extensions update mcp-db-context-enrichment

   Untuk memperbarui ekstensi DB Context Enrichment atau mengganti GEMINI_API_KEY, jalankan perintah berikut:

   gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

   Ganti GEMINI_API_KEY dengan kunci Gemini API Anda.

Menyiapkan Koneksi DB

Ekstensi ini memerlukan koneksi database untuk pembuatan konteks guna mengambil skema dan menjalankan pernyataan SQL. Agar ekstensi dapat berinteraksi dengan database Anda, Anda harus mengonfigurasi kredensial autentikasi dan menentukan sumber serta alat database.

Mengonfigurasi Kredensial Default Aplikasi

Anda harus mengonfigurasi Kredensial Default Aplikasi (ADC) untuk memberikan kredensial pengguna bagi dua komponen utama:

• Server MCP Toolbox: menggunakan kredensial untuk terhubung ke database Anda, mengambil skema, dan menjalankan SQL untuk validasi.
• Ekstensi DB Context Enrichment: menggunakan kredensial untuk melakukan autentikasi dan memanggil Gemini API.

Jalankan perintah berikut di terminal Anda untuk melakukan autentikasi:

gcloud auth application-default login

Mengonfigurasi file tools.yaml

Ekstensi ini memerlukan koneksi database untuk pembuatan konteks, yang didukung oleh MCP Toolbox dan ditentukan dalam file konfigurasi tools.yaml.

File tools.yaml menentukan sumber dan alat database yang diperlukan untuk mengambil skema atau menjalankan SQL. Ekstensi ini dilengkapi dengan Agent Skills yang telah diinstal sebelumnya untuk membantu Anda membuat konfigurasi.

Catatan: Jika koneksi ini tidak dibuat, ekstensi akan menampilkan pesan error, seperti "Error Discovering tools from mcp_toolbox" dan pembuatan konteks tidak akan berfungsi.

1. Mulai Gemini CLI:

   gemini

2. Verifikasi bahwa kemampuan aktif dengan mengetik di Gemini CLI:

   /skills

3. Ketik perintah seperti help me setup the database connection. Kemampuan ini akan memandu Anda membuat file tools.yaml di direktori kerja saat ini.

4. Jalankan perintah berikut di Gemini CLI untuk menerapkan konfigurasi tools.yaml ke server MCP Toolbox.

   /mcp reload

Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi file tools.yaml secara manual, lihat Konfigurasi MCP Toolbox.

Membuat Konteks

Ekstensi yang diinstal sebelumnya memungkinkan Gemini CLI membantu Anda membuat konteks dalam bentuk file JSON.

Catatan: Gemini CLI dapat mengakses file lokal Anda untuk mengurangi overhead seperti menentukan lokasi file yang tepat di direktori lokal Anda. Misalnya, jika langkah dalam alur kerja Gemini CLI meminta informasi yang dapat Anda temukan di file tools.yaml, Anda dapat meminta Gemini CLI untuk use tools.yaml atau merespons dengan perintah seperti look it up.

Membuat template yang ditargetkan

Jika ingin menambahkan pasangan kueri tertentu sebagai template kueri ke set konteks, Anda dapat menggunakan perintah /generate_targeted_templates. Untuk mengetahui informasi selengkapnya tentang template, lihat Ringkasan set konteks

Untuk menambahkan template kueri ke set konteks, lakukan langkah-langkah berikut:

1. Di direktori yang sama, mulai Gemini CLI:

   gemini

2. Selesaikan Penyiapan Autentikasi Gemini CLI.

3. Pastikan MCP toolbox dan ekstensi pengayaan database siap digunakan:

   /mcp reload

4. Jalankan perintah /generate_targeted_templates:

   /generate_targeted_templates

5. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

6. Masukkan kueri SQL yang sesuai ke template kueri.

7. Tinjau template kueri yang dibuat. Anda dapat menyimpan template kueri sebagai file set konteks atau menambahkannya ke file set konteks yang ada.

File set konteks yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file set konteks dan template kueri, lihat Ringkasan set konteks.

Membuat aspek yang ditargetkan

Jika ingin menambahkan pasangan kueri tertentu sebagai aspek ke file set konteks, Anda dapat menggunakan perintah /generate_targeted_facets.

Untuk menambahkan aspek ke file set konteks, lakukan langkah-langkah berikut:

1. Jalankan perintah /generate_targeted_facets:

   /generate_targeted_facets

2. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

3. Masukkan kueri SQL yang sesuai ke template kueri.

4. Tinjau aspek yang dibuat. Anda dapat menyimpan aspek ke file set konteks atau menambahkannya ke file set konteks yang ada.

File set konteks yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file set konteks dan aspek, lihat Ringkasan set konteks

Membuat kueri penelusuran nilai

Jika ingin membuat penelusuran nilai yang menentukan cara sistem harus menelusuri dan mencocokkan nilai tertentu dalam jenis konsep, Anda dapat menggunakan perintah /generate_targeted_value_searches.

Untuk membuat indeks nilai, lakukan langkah-langkah berikut:

1. Jalankan perintah /generate_targeted_value_searches:

   /generate_targeted_value_searches

1. Masukkan postgresql untuk memilih AlloyDB sebagai mesin database.

2. Masukkan versi PostgreSQL yang ingin Anda gunakan. Pilih default untuk memilih PostgreSQL 16.

1. Masukkan konfigurasi penelusuran nilai sebagai berikut:

   Table name: TABLE_NAME
   Column name: COLUMN_NAME
   Concept type: CONCEPT_TYPE
   Match function: MATCH_FUNCTION
   Description: DESCRIPTION
   

   Ganti kode berikut:

   • TABLE_NAME: Tabel tempat kolom yang terkait dengan jenis konsep berada.
   • COLUMN_NAME: Nama kolom yang terkait dengan jenis konsep.
   • CONCEPT_TYPE: Jenis konsep yang ingin Anda tentukan—misalnya, City name.

   • MATCH_FUNCTION: Fungsi kecocokan yang akan digunakan untuk penelusuran nilai. Anda dapat menggunakan salah satu fungsi berikut:

     • EXACT_STRING_MATCH: Untuk kecocokan yang tepat dari dua nilai string. Paling cocok untuk ID, kode, dan kunci utama yang unik.
     • TRIGRAM_STRING_MATCH: Untuk pencocokan fuzzy yang menghitung jarak trigram yang dinormalisasi. Paling cocok untuk penelusuran pengguna dan koreksi nama.
     • SEMANTIC_SIMILARITY_MATCH: Untuk penelusuran semantik pada nilai string. Paling cocok untuk penelusuran lintas bahasa dan sinonim. Untuk mengetahui daftar model yang didukung, lihat Model Google yang didukung. Untuk menggunakan SEMANTIC_SIMILARITY_MATCH, Anda harus mengaktifkan ekstensi vector dan google_ml_integration.

   • DESCRIPTION: (Opsional) Deskripsi kueri penelusuran nilai.

2. Tambahkan penelusuran nilai tambahan sesuai kebutuhan. Jika Anda tidak menambahkan indeks nilai tambahan, pembuatan SQL berbasis template akan beralih ke langkah berikutnya.

3. Tinjau penelusuran nilai yang dibuat. Anda dapat menyimpan set konteks sebagai file set konteks atau menambahkannya ke file set konteks yang ada.

File set konteks yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang indeks nilai, lihat Ringkasan set konteks

Opsional: Membuat template massal

Jika ingin membuat file set konteks secara otomatis berdasarkan skema dan data database Anda, Anda dapat menggunakan perintah /generate_bulk_templates.

Untuk membuat template massal secara otomatis, lakukan langkah-langkah berikut:

1. Jalankan perintah /generate_bulk_templates:

   /generate_bulk_templates

2. Berdasarkan skema database Anda, pembuatan SQL berbasis template akan memandu Anda melalui serangkaian pertanyaan terkait verifikasi informasi database dan pemberian izin untuk mengakses skema database.

3. Tinjau template kueri yang dibuat. Anda dapat menyetujui template atau memperbarui pasangan kueri yang ingin direvisi.

4. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

5. Masukkan kueri SQL yang sesuai ke template kueri.

6. Tinjau template kueri yang dibuat. Anda dapat menyimpan template kueri sebagai file set konteks atau menambahkannya ke file konteks yang ada.

7. Setelah menyetujui template kueri, Anda dapat membuat file template baru atau menambahkan pasangan kueri ke file template yang ada. Template kueri disimpan sebagai file JSON di direktori lokal Anda.

File set konteks yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file set konteks, lihat Ringkasan set konteks.

Langkah berikutnya

• Pelajari lebih lanjut set konteks.
• Pelajari cara membuat atau menghapus set konteks di Cloud SQL Studio
• Pelajari cara menguji set konteks