Membangun set konteks menggunakan Gemini CLI

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:

Menyiapkan instance Cloud SQL

Peran dan izin yang diperlukan

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 database untuk penelusuran nilai

Untuk menggunakan penelusuran nilai semantik dan trigram, Anda harus mengonfigurasi instance Cloud SQL untuk MySQL agar mendukung embedding vektor dan pengindeksan n-gram.

  1. Untuk mengaktifkan instance Cloud SQL untuk MySQL agar dapat melakukan penelusuran nilai semantik, Anda harus mengaktifkan flag berikut.

    1. Aktifkan flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Aktifkan flag enable-google-ml-integration untuk mengizinkan instance Cloud SQL untuk MySQL berintegrasi dengan Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Buat kolom vektor untuk menyimpan embedding kota

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Buat dan simpan embedding vektor untuk nama kota

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Untuk mengaktifkan instance Cloud SQL untuk MySQL agar dapat melakukan penelusuran nilai trigram, lakukan langkah-langkah berikut.

    1. Aktifkan flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Buat indeks FULLTEXT untuk pencocokan trigram pada nama bandara

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

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

  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 Anda.

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.

  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. Keterampilan ini akan memandu Anda membuat file tools.yaml di direktori kerja Anda 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.

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.

Pastikan Anda menyelesaikan langkah-langkah di Menyiapkan database untuk penelusuran nilai.

Untuk membuat indeks nilai, lakukan langkah-langkah berikut:

  1. Jalankan perintah /generate_targeted_value_searches:

    /generate_targeted_value_searches
  1. Masukkan mysql untuk memilih MySQL sebagai mesin database. Pilih default untuk memilih MySQL 8.0.

  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 pencocokan 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. Untuk menggunakan TRIGRAM_STRING_MATCH, Anda harus menyiapkan database untuk mendukung pengindeksan n-gram.
      • 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 menyiapkan database untuk mendukung embedding vektor.

    • 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 mengajukan 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 Anda revisi.

  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