Membangun set konteks menggunakan Gemini CLI

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:

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

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

  1. Agar instance Cloud SQL untuk MySQL 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 tanda enable-google-ml-integration agar instance Cloud SQL untuk MySQL dapat terintegrasi 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. Membuat dan menyimpan 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 for 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 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

  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.

  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.

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.

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