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 toolbox MCP 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 umum berikut:

• Menyiapkan lingkungan Anda
• Membuat template yang ditargetkan
• Membuat aspek bertarget
• 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 dengan Gemini
• Gemini for Google Cloud API
• Dataplex Universal Catalog API

Siapkan 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 informasi selengkapnya, lihat Membuat database pada instance Cloud SQL.

Peran dan izin yang diperlukan

• Tambahkan akun pengguna atau layanan IAM ke instance. Untuk 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 akun layanan atau pengguna IAM perorangan.

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 Google Cloud project Anda.
• INSTANCE_ID: ID instance Cloud SQL Anda.

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

Menyiapkan lingkungan Anda

Anda dapat membuat file konteks agen dari lingkungan pengembangan lokal atau IDE mana pun. 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 Mulai Menggunakan Gemini CLI.

Menginstal ekstensi MCP Pengayaan Konteks DB

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

Untuk mengetahui informasi selengkapnya tentang cara menginstal ekstensi Pengayaan Konteks DB, lihat Ekstensi Pengayaan Konteks DB.

Untuk menginstal ekstensi Pengayaan Konteks DB, ikuti langkah-langkah berikut:

1. Instal ekstensi Gemini CLI MCP Toolbox:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

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

2. (Opsional) Perbarui ekstensi Pengayaan Konteks DB.

   Untuk memverifikasi versi ekstensi yang diinstal, jalankan perintah berikut:

   gemini extensions list

   Pastikan versinya adalah 0.4.2 atau yang lebih tinggi. Untuk mengupdate ekstensi Pengayaan Konteks DB, jalankan perintah berikut:

     gemini extensions update mcp-db-context-enrichment

   Untuk mengupdate 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 dalam mengambil skema dan menjalankan pernyataan SQL. Agar ekstensi dapat berinteraksi dengan database, Anda harus mengonfigurasi kredensial autentikasi serta menentukan sumber dan 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 mengautentikasi dan memanggil Gemini API.

Jalankan perintah berikut di terminal Anda untuk mengautentikasi:

gcloud auth application-default login

Mengonfigurasi file tools.yaml

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

File tools.yaml menentukan sumber database dan alat yang diperlukan untuk mengambil skema atau menjalankan SQL. Ekstensi ini dilengkapi dengan Keterampilan Agen 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 keterampilan aktif dengan mengetik di Gemini CLI:

   /skills

3. Ketik perintah seperti help me setup the database connection. Skill 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.

Buat 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 persis file di direktori lokal Anda. Misalnya, jika langkah dalam alur kerja Gemini CLI meminta informasi yang dapat Anda temukan dalam 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. Verifikasi bahwa toolbox MCP 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 dihasilkan. 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 bertarget

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 dihasilkan. 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 Anda 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 pencocokan yang akan digunakan untuk penelusuran nilai. Anda dapat menggunakan salah satu fungsi berikut:

     • EXACT_STRING_MATCH: Untuk kecocokan persis dua nilai string. Paling cocok untuk ID unik, kode, dan kunci utama.
     • TRIGRAM_STRING_MATCH: Untuk pencocokan tidak jelas 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 melewati penambahan indeks nilai tambahan, pembuatan SQL berbasis template akan beralih ke langkah berikutnya.

3. Tinjau penelusuran nilai yang dihasilkan. 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 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 dihasilkan. 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 dihasilkan. 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