Memeriksa dan memanggil agen data

Dokumen ini menjelaskan cara memeriksa agen dan memperbarui file konteks agen. Anda dapat memeriksa agen untuk menguji kemampuannya membuat kueri SQL dari pertanyaan bahasa alami. Jika kueri yang dihasilkan tidak akurat, Anda dapat memperbarui konteks agen.

Untuk mempelajari agen data, lihat Ringkasan agen data.

Sebelum memulai

Pastikan agen data sudah dibuat dan konteks agen diupload ke agen data. Untuk mengetahui informasi selengkapnya, lihat Mengelola agen data di Spanner Studio.

Memeriksa agen data

Untuk memeriksa agen data, lakukan langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Spanner.

    Buka Spanner

  2. Pilih instance dari daftar, lalu pilih database.

  3. Di menu navigasi, klik Spanner Studio.

  4. Di panel Explorer, di samping Agen Data, klik Lihat tindakan.

  5. Klik Periksa agen.

  6. Di editor kueri, klik Generate SQL untuk membuka panel Help me code.

  7. Masukkan pertanyaan bahasa alami untuk membuat kueri SQL, lalu klik Buat.

  8. Tinjau akurasi kueri SQL.

Mendownload dan memperbarui konteks untuk agen data

Jika Anda tidak puas dengan kueri SQL yang dihasilkan untuk pertanyaan bahasa alami, download file konteks agen yang ada. Kemudian, Anda dapat meninjau dan memperbarui template kueri, lalu mengupload ulang file konteks yang telah diperbarui ke agen.

Untuk mendownload dan memperbarui konteks agen data, lakukan langkah-langkah berikut:

  1. Di panel Explorer, di samping Agen Data, klik Lihat tindakan.
  2. Klik Download file konteks agen.
  3. Ikuti langkah-langkah dalam Membangun konteks menggunakan Gemini CLI untuk memperbarui konteks dengan pasangan kueri tambahan.
  4. Di panel Explorer, di samping agen data Anda, klik View actions.
  5. Klik Edit agen.
  6. Klik Jelajahi di bagian Upload file konteks agen, lalu pilih file konteks agen yang diperbarui.
  7. Klik Simpan untuk memperbarui konteks agen.

Setelah merasa puas dengan akurasi respons Anda, Anda dapat menggunakan endpoint QueryData untuk menghubungkan aplikasi Anda ke agen data.

Menemukan ID konteks agen

Untuk menghubungkan aplikasi data ke agen data, Anda memerlukan ID konteks agen.

  1. Di konsol Google Cloud , buka halaman Spanner.

    Buka Spanner

  2. Pilih instance dari daftar, lalu pilih database.

  3. Di menu navigasi, klik Spanner Studio.

  4. Di panel Explorer, di samping Agen Data, klik Lihat tindakan.

  5. Klik Edit agen.

  6. Catat ID konteks di ID konteks agen. Format ID konteks agen mirip dengan projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Menghubungkan agen data ke aplikasi

Tetapkan ID konteks agen dalam panggilan metode QueryData untuk menyediakan konteks yang dibuat untuk sumber data database seperti AlloyDB, Spanner, Cloud SQL, dan Cloud SQL untuk PostgreSQL. Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data database

Setelah memeriksa agen data, Anda dapat mereferensikan sumber data database dalam panggilan QueryData.

Contoh permintaan QueryData dengan konteks yang dibuat

Contoh berikut menunjukkan permintaan QueryData menggunakan sumber data database spanner_reference. Kolom agent_context_reference.context_set_id digunakan untuk menautkan ke konteks yang ditulis sebelumnya dan disimpan dalam database.

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

Isi permintaan berisi kolom berikut:

  • prompt: Pertanyaan bahasa alami dari pengguna akhir.
  • context: Berisi informasi tentang sumber data.
    • datasource_references: Menentukan jenis sumber data.
      • spanner_reference: Diperlukan saat membuat kueri database. Kolom ini berubah berdasarkan database yang Anda kueri.
        • database_reference: Menentukan informasi terkait instance database Anda.
          • engine: Dialek SQL database. Tetapkan ke GOOGLE_SQL untuk database Spanner.
          • project_id: Project ID instance database.
          • region: Region instance Spanner.
          • instance_id: ID instance Spanner.
          • database_id: ID database.
        • agent_context_reference: Menautkan ke konteks yang dibuat dalam database.
          • context_set_id: ID konteks agen lengkap dari konteks yang disimpan dalam database. Contoh, projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: Mengonfigurasi jenis output yang akan dibuat.
    • generate_query_result: Tetapkan ke benar untuk membuat dan menampilkan hasil kueri.
    • generate_natural_language_answer: Opsional. Jika disetel ke benar (true), akan menghasilkan jawaban dalam bahasa alami.
    • generate_explanation: Opsional. Jika disetel ke benar (true), akan membuat penjelasan kueri SQL.
    • generate_disambiguation_question: Opsional. Jika disetel ke benar (true), akan membuat pertanyaan penghilangan ambiguitas jika kueri ambigu.

Contoh Respons QueryData

Berikut adalah contoh respons yang berhasil dari panggilan QueryData:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

Langkah berikutnya