Membangun set konteks menggunakan Gemini CLI

Dokumen ini menjelaskan cara membuat dan mengoptimalkan konteks yang memungkinkan Anda meningkatkan akurasi QueryData untuk membangun aplikasi agen data. Dengan menggunakan ekstensi pengayaan konteks DB di Gemini CLI, Anda dapat mengakses serangkaian alat developer yang mengotomatiskan pembuatan dan pengoptimalan set konteks.

Untuk mempelajari set konteks, lihat Ringkasan set konteks.

Ekstensi ini mengotomatiskan pembuatan dan pengoptimalan set konteks dalam urutan berikut:

Memahami aplikasi: Menyerap artefak seperti skema database, kode aplikasi, dan persyaratan bisnis untuk membuat logika bisnis dasar bagi agen data Anda.
Buat set data: Susun set data evaluasi yang berisi pertanyaan bahasa alami representatif dan jawaban SQL yang diharapkan. Menetapkan set data dasar ini sangat penting untuk mengukur performa dan melacak peningkatan dari waktu ke waktu.
Buat konteks awal: Buat set konteks dasar secara otomatis yang berasal langsung dari skema database dan artefak aplikasi opsional sebagai panduan memulai cepat.
Mengoptimalkan konteks secara iteratif: Evaluasi set data Anda untuk mengidentifikasi alasan kueri tertentu gagal. Gemini menggunakan penalaran otomatis untuk menyarankan pembaruan konteks yang ditargetkan, sehingga secara iteratif mencapai akurasi yang lebih tinggi.

Meskipun menawarkan alur kerja otomatis yang andal, ekstensi ini dapat disesuaikan dengan kebutuhan Anda. Anda dapat melewati otomatisasi untuk membuat dan menyisipkan konteks pada tingkat yang lebih terperinci. Dengan perintah pembuatan khusus, Anda dapat mengontrol pembuatan template, aspek, dan kueri penelusuran nilai berkualitas tinggi.

Sebelum memulai

Selesaikan prasyarat berikut sebelum membuat agen.

Mengaktifkan layanan yang diperlukan

Aktifkan layanan berikut untuk project Anda:

Menyiapkan instance Spanner

Pastikan instance Spanner tersedia. Untuk mengetahui informasi selengkapnya, lihat Membuat instance.
Pastikan Anda membuat database di instance tempat Anda akan membuat tabel. Untuk mengetahui informasi selengkapnya, lihat Membuat database di instance Spanner

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

Peran dan izin yang diperlukan

Tambahkan akun pengguna atau layanan IAM ke cluster. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.
Berikan peran spanner.databaseReader dan geminidataanalytics.queryDataUser kepada pengguna IAM di tingkat project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
Berikan peran dan izin kepada pengguna IAM di tingkat project untuk database yang diperlukan.

Menyiapkan lingkungan Anda

Anda dapat membuat file set konteks dari lingkungan pengembangan lokal atau IDE mana pun. Untuk mempersiapkan lingkungan Anda, 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 DB Context Enrichment

Ekstensi pengayaan konteks DB menyediakan alur kerja interaktif yang terpandu untuk membuat set konteks terstruktur dan melakukan iterasi pada set tersebut.

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

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

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 mengautentikasi dengan Gemini API dan mengaktifkan pembuatan konteks. Untuk mengetahui informasi selengkapnya tentang cara menemukan kunci API Anda, lihat Menggunakan kunci API Gemini.
(Opsional) Perbarui ekstensi Pengayaan Konteks DB.

Untuk memverifikasi versi ekstensi yang diinstal, jalankan perintah berikut:
```
gemini extensions list
```
Pastikan versinya adalah 0.5.0 atau yang lebih tinggi. Untuk mengupdate ekstensi Pengayaan Konteks DB, jalankan perintah berikut:
```
  gemini extensions update mcp-db-context-enrichment
```
Untuk mengupdate ekstensi Pengayaan Konteks DB atau mengganti GEMINI_API_KEY, jalankan perintah berikut:
```
gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY
```
Ganti GEMINI_API_KEY dengan kunci API Gemini Anda.

Menyiapkan koneksi database

Ekstensi ini memerlukan koneksi database untuk mengambil skema dan kemampuan untuk memvalidasi sintaksis konteks SQL yang dihasilkan. Agar ekstensi dapat berinteraksi dengan database Anda, konfigurasi kredensial autentikasi dan tentukan konfigurasi koneksi database Anda.

Mengonfigurasi Kredensial Default Aplikasi

Konfigurasi 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 koneksi database

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

File konfigurasi menentukan sumber database dan alat yang diperlukan untuk mengambil skema atau menjalankan SQL. Ekstensi pengayaan konteks DB dilengkapi dengan Keterampilan Agen yang telah diinstal sebelumnya untuk membantu Anda membuat konfigurasi.

Mulai Gemini CLI:
```
gemini
```
Pastikan keterampilan aktif dengan mengetikkan perintah berikut di Gemini CLI:
```
/skills
```
Ketik perintah, misalnya, help me set up the database connection. Skill ini memandu Anda membuat file konfigurasi di direktori kerja saat ini sebagai autoctx/tools.yaml.
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 konfigurasi database secara manual, lihat Konfigurasi MCP Toolbox.

Membuat konteks dengan alur kerja otomatis

Meningkatkan akurasi melalui rekayasa konteks biasanya merupakan proses manual yang dilakukan dengan mencoba-coba. Developer sering kali menebak alasan kueri gagal, menulis perbaikan, dan mengujinya secara manual. Ekstensi Pengayaan Konteks DB di Gemini CLI mengotomatiskan proses peningkatan ini. Alat ini menggunakan set data evaluasi—kumpulan pertanyaan dengan jawaban SQL yang benar—untuk mengukur performa dan mengidentifikasi alasan kegagalan kueri tertentu. Kemudian, Gemini akan otomatis menyarankan pembaruan konteks tertentu untuk mencapai akurasi yang lebih tinggi. Selesaikan langkah-langkah berikut untuk meningkatkan akurasi agen data Anda secara sistematis.

Melakukan inisialisasi ruang kerja

Perintah inisialisasi menyiapkan ruang kerja lokal Anda, termasuk konfigurasi koneksi database dan direktori eksperimen. Ruang kerja khusus ini memastikan bahwa semua konfigurasi, eksperimen, dan file yang dihasilkan disusun di satu tempat, sehingga memudahkan pengelolaan dan pelacakan upaya pengoptimalan konteks Anda.

Buat direktori baru untuk digunakan sebagai ruang kerja Anda untuk alur pengoptimalan iteratif, lalu buka direktori tersebut.
Mulai Gemini CLI di direktori baru:
```
gemini
```

Jalankan perintah inisialisasi:

/autoctx:init

Agen akan memandu Anda membuat file tools.yaml jika tidak ada koneksi database yang disiapkan, dan juga menginisialisasi file state.md lokal dan direktori experiments.

Setelah inisialisasi, ruang kerja Anda akan terlihat seperti berikut:

my-workspace/
└── autoctx/
    ├── tools.yaml          # Database connection and tools configuration
    ├── state.md            # Local file to track the experiment progress
    └── experiments/        # Dedicated directory for future experiment-specific files

Menyiapkan dan memperluas set data

Agar Gemini dapat melakukan pengoptimalan secara sistematis pada set konteks Anda, siapkan set data evaluasi yang berisi pertanyaan natural language yang representatif dan jawaban SQL yang diharapkan ("goldens") untuk mengevaluasi set konteks Anda. Set data evaluasi berkualitas tinggi sangat penting untuk mengukur performa, mengidentifikasi kegagalan kueri, dan melacak peningkatan dari waktu ke waktu. Set data harus berupa file JSON yang berisi Pertanyaan Bahasa Alami (NLQ) dan SQL standar yang mencakup kasus penggunaan yang ditargetkan dalam aplikasi data Anda.

Berikut ini contoh format yang diharapkan:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

Ekstensi Gemini CLI menyertakan perintah yang disediakan untuk membuat dan menskalakan dasar kecil pertanyaan untuk tujuan evaluasi.

Buka folder ruang kerja Anda.
Mulai Gemini CLI di direktori baru:
```
gemini
```
Jalankan perintah /autoctx:generate-dataset di Gemini CLI:
```
/autoctx:generate-dataset
```
Saat diminta oleh agen, berikan benih, yang merupakan contoh awal atau sekumpulan kecil contoh yang memandu pembuatan set data yang lebih besar. Seed dapat berupa salah satu dari berikut:
- File set data rujukan kecil
- Pasangan emas natural language ke SQL (NL2SQL) tertentu
Misalnya, Anda dapat memberikan pasangan emas NL2SQL berikut sebagai awalan:
```
Question: "What are the names of all airports in California?"
SQL: "SELECT name FROM airports WHERE state = 'CA';"
```
Agen akan meminta izin untuk memverifikasi sintaksis dan validitas eksekusi menggunakan alat execute_sql. Langkah ini opsional.
Agen akan menanyakan apakah akan memperluas set data dengan variasi dari data awal (menerapkan berbagai filter, sinonim, dan sebagainya). Langkah ini opsional.

Agen menggunakan alat execute_sql untuk menjalankan kueri SQL yang baru dibuat terhadap database guna memverifikasi sintaksis dan validitas eksekusi sebelum menampilkannya kepada Anda.

Menerima, mengedit, atau menolak saran secara selektif. Pasangan yang disetujui akan otomatis disimpan secara lokal dan siap dievaluasi.

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json  # Generated dataset
    └── experiments/

Membuat set data konteks awal

Membuat set konteks awal memberikan dasar pengukuran untuk evaluasi dan peningkatan iteratif. Langkah ini menggunakan skema database dan artefak aplikasi Anda untuk membuat konteks dasar yang mencerminkan logika bisnis Anda.

Ekstensi Gemini CLI menyertakan perintah bawaan untuk membuat kumpulan awal template dan aspek berdasarkan skema database dan informasi tentang aplikasi agen data Anda, misalnya, kode aplikasi atau file dengan informasi tentang persyaratan bisnis Anda. Untuk membuat set konteks dasar dari awal:

Buka folder ruang kerja Anda.
Mulai Gemini CLI di direktori baru:
```
gemini
```
Jalankan perintah /autoctx:bootstrap di Gemini CLI:
```
/autoctx:bootstrap
```
Anda umumnya dapat mengharapkan hal berikut dari agen.
- Agen akan meminta Anda menentukan nama eksperimen. Eksperimen adalah folder ruang kerja khusus yang mencakup siklus proses lengkap konfigurasi konteks database, melacak status dasarnya, hasil pengujian evaluasi, dan peningkatan iteratif berikutnya. Nama ini digunakan untuk mengatur semua file yang dihasilkan di folder eksperimen di ruang kerja Anda; pilih nama yang deskriptif dan mudah diingat.
- Agen mengambil dan mencantumkan skema dari database target Anda, dan meminta Anda untuk memberikan resource atau file tambahan secara opsional. Jika skemanya rumit, agen juga akan meminta Anda memilih skema atau tabel tertentu untuk set konteks awal. Jika Anda tidak menentukan tabel apa pun, semua tabel yang tersedia dalam skema database saat ini akan diasumsikan.

Tinjau dan perbaiki set data konteks yang dihasilkan jika perlu. Setelah disempurnakan, agen akan menghasilkan file konteks JSON langsung di disk lokal Anda di folder ruang kerja Anda:

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json  # The generated initial context set file

Ikuti petunjuk untuk mengupload konteks dari Spanner Studio.

Mengevaluasi efektivitas konteks

Ekstensi Gemini CLI menyertakan perintah bawaan untuk mengevaluasi agen data Anda menggunakan set data standar. Ekstensi ini terintegrasi dengan Evalbench untuk melakukan evaluasi dengan membuat kueri QueryData API agen menggunakan pertanyaan yang ditentukan dalam set standar, lalu membandingkan SQL yang dihasilkan dan hasil eksekusinya dengan SQL standar. Evaluasi adalah kunci untuk memahami efektivitas set konteks Anda saat ini. Dengan membandingkan SQL yang dihasilkan dengan set data standar, Anda dapat menunjukkan kueri tertentu yang gagal dan mengidentifikasi area yang perlu ditingkatkan konteksnya.

Untuk mengukur efektivitas konteks saat ini terhadap set data emas Anda:

Upload konteks dari Spanner Studio ke set konteks target untuk evaluasi. Langkah ini bersifat opsional jika konteks yang akan dievaluasi tidak diupload.
Buka folder ruang kerja Anda.
Mulai Gemini CLI di folder:
```
gemini
```
Jalankan perintah /autoctx:evaluate di Gemini CLI:
```
/autoctx:evaluate
```

Berikan jalur untuk set data emas Anda, ID set konteks untuk pembuatan konfigurasi evaluasi dan menjalankan evaluasi, serta direktori output yang ditentukan.

Setelah selesai, agen akan menghasilkan hasil evaluasi sebagai file di folder eksperimen Anda dan meringkas hasil evaluasi.

Atau, Anda dapat memeriksa evaluasi secara manual dari laporan evaluasi mendetail, yang disimpan sebagai file CSV di folder eksperimen Anda.

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
                └── <configs_for_eval_run>/
            └── eval_reports/
                └── <eval_id>/
                    └── eval_report/
                        ├── configs.csv
                        ├── evals.csv
                        ├── scores.csv
                        └── summary.csv

Melakukan analisis kesenjangan dan pengoptimalan konteks

Sebagai langkah penting dalam mengoptimalkan set konteks, ekstensi Gemini CLI menyertakan perintah bawaan untuk melakukan analisis kesenjangan pada set konteks yang ada dan menyarankan perubahan untuk meningkatkan kualitasnya. Analisis kesenjangan sangat penting untuk memahami alasan kueri tertentu gagal dan tempat konteks dapat ditingkatkan. Berdasarkan analisis ini, Gemini menggunakan penalaran otomatis untuk menyarankan pembaruan konteks yang ditargetkan—seperti template atau aspek baru—untuk mengatasi kegagalan ini dan meningkatkan akurasi kueri secara iteratif.

Buka folder ruang kerja Anda.
Mulai Gemini CLI di folder:
```
gemini
```

Jalankan perintah /autoctx:hillclimb di Gemini CLI:

/autoctx:hillclimb

Agen secara otomatis mengidentifikasi hasil evaluasi dan konteks dasar yang paling sesuai untuk pendakian bukit dan meminta konfirmasi jika ada beberapa opsi.

Jika tidak ada hasil evaluasi yang tersedia, agen akan meminta Anda untuk menjalankan evaluasi dengan set data dan set konteks.

Setelah siap, agen akan membaca hasil evaluasi dan set konteks yang ada, lalu membuat laporan analisis kesenjangan.

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                └── gap_analysis_v1.md

Agen merumuskan perbaikan dengan mengusulkan template dan aspek preskriptif baru, yang secara opsional menguji SQL terhadap DB melalui execute_sql.

Setelah siap, file JSON konteks baru yang lebih baik akan dibuat secara lokal, sehingga file JSON konteks dasar tetap utuh.

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                ├── gap_analysis_v1.md
                └── improved_context_v1.md

Ikuti petunjuk untuk mengupload konteks ke set konteks target dari Spanner Studio, yang siap untuk putaran iterasi berikutnya yang dimulai dengan evaluasi.

Batasan

Alur kerja otomatis hanya mendukung pembuatan dan pengoptimalan template dan aspek. Jika Anda ingin mengonfigurasi penelusuran nilai untuk agen data, lihat Membuat kueri penelusuran nilai.

Membuat konteks yang ditargetkan

Jika lebih memilih pendekatan yang lebih disesuaikan untuk pembuatan konteks, Anda dapat menggunakan ekstensi DB Context Enrichment untuk membuat elemen konteks tertentu secara manual. Perintah berikut memandu Anda membuat konteks sebagai file JSON, sehingga Anda dapat mengontrol secara terperinci pembuatan kueri penelusuran template, aspek, dan nilai.

Membuat template yang ditargetkan

Untuk menambahkan pasangan kueri-SQL tertentu sebagai template kueri ke set konteks, gunakan perintah /generate_targeted_templates.

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

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

Jalankan perintah /generate_targeted_templates di Gemini CLI:
```
/generate_targeted_templates
```
Masukkan kueri bahasa alami yang akan ditambahkan ke template kueri.
Masukkan kueri SQL yang sesuai ke template kueri.
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, misalnya, my-cluster-psc-primary_postgres_context_set_20251104111122.json, disimpan di direktori tempat Anda menjalankan perintah.

Untuk menambahkan kueri tertentu ke kondisi SQL sebagai aspek ke file set konteks, gunakan perintah /generate_targeted_facets.

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

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

Jalankan perintah /generate_targeted_facets di Gemini CLI:
```
/generate_targeted_facets
```
Masukkan maksud bahasa alami yang akan ditambahkan ke aspek.
Masukkan cuplikan SQL yang sesuai ke aspek.
Tinjau aspek yang dihasilkan. Anda dapat menyimpan aspek ke file set konteks atau menambahkannya ke file set konteks yang ada.

File set konteks, misalnya, my-cluster-psc-primary_postgres_context_set_20251104111122.json, disimpan di direktori tempat Anda menjalankan perintah.

Membuat kueri penelusuran nilai

Untuk membuat penelusuran nilai yang menentukan cara sistem menelusuri dan mencocokkan nilai tertentu dalam jenis konsep, gunakan perintah /generate_targeted_value_searches.

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

Untuk membuat indeks nilai, selesaikan langkah-langkah berikut:

Jalankan perintah /generate_targeted_value_searches:
```
/generate_targeted_value_searches
```
Masukkan spanner untuk memilih Spanner sebagai mesin database.
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 akan ditentukan—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. Terbaik untuk penelusuran pengguna dan koreksi nama.
- DESCRIPTION: (Opsional) Deskripsi kueri penelusuran nilai.
Tambahkan penelusuran nilai tambahan sesuai kebutuhan. Jika Anda melewati penambahan indeks nilai tambahan, pembuatan SQL berbasis template akan beralih ke langkah berikutnya.
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, misalnya, my-cluster-psc-primary_postgres_context_set_20251104111122.json, disimpan di direktori tempat Anda menjalankan perintah.

Langkah berikutnya

Pelajari lebih lanjut set konteks.
Pelajari cara membuat atau menghapus set konteks di Spanner Studio
Pelajari cara menguji set konteks

Membangun set konteks menggunakan Gemini CLI Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mengaktifkan layanan yang diperlukan

Menyiapkan instance Spanner

Peran dan izin yang diperlukan

Menyiapkan lingkungan Anda

Menginstal Gemini CLI

Menginstal ekstensi DB Context Enrichment

Menyiapkan koneksi database

Mengonfigurasi Kredensial Default Aplikasi

Mengonfigurasi file koneksi database

Membuat konteks dengan alur kerja otomatis

Melakukan inisialisasi ruang kerja

Menyiapkan dan memperluas set data

Membuat set data konteks awal

Mengevaluasi efektivitas konteks

Melakukan analisis kesenjangan dan pengoptimalan konteks

Batasan

Membuat konteks yang ditargetkan

Membuat template yang ditargetkan

Membuat aspek bertarget

Membuat kueri penelusuran nilai

Langkah berikutnya

Membangun set konteks menggunakan Gemini CLI