Test QueryData

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

Untuk mempelajari set konteks, lihat Ringkasan set konteks.

Sebelum memulai

Pastikan Anda telah membuat set konteks di Knowledge Catalog dan mengupload file set konteks ke set konteks. Untuk mengetahui informasi selengkapnya, lihat Mengelola set konteks di AlloyDB Studio.

Untuk mendownload, memperbarui, dan mengupload file set konteks, pastikan pengguna IAM memiliki peran Dataplex Catalog Editor (roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) di project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks.

Menguji QueryData

Untuk menguji QueryData, lakukan langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman AlloyDB.

    Buka AlloyDB

  2. Pilih cluster dari daftar.

  3. Di menu navigasi, klik AlloyDB Studio.

  4. Login ke Studio menggunakan autentikasi Identity and Access Management.

  5. Di panel Explorer, klik View actions di samping set konteks yang Anda gunakan.

  6. Klik Test context set.

  7. Di editor kueri, klik Generate SQL using QueryData with: CONTEXT_SET_NAME untuk membuka panel pembuatan kueri.

  8. Masukkan pertanyaan bahasa alami di panel pembuatan kueri untuk membuat kueri SQL, lalu klik Generate.

  9. Tinjau kueri SQL untuk memastikan akurasinya. Klik Insert untuk menambahkan kueri ke editor.

Mendownload dan memperbarui set konteks

Jika Anda tidak puas dengan kueri SQL yang dihasilkan untuk pertanyaan bahasa alami, download file set konteks yang ada. Kemudian, Anda dapat meninjau dan memperbarui template kueri, serta mengupload file set konteks yang diperbarui ke set konteks di Knowledge Catalog.

Untuk mendownload dan mengupdate set konteks, lakukan langkah-langkah berikut:

  1. Di panel Explorer, klik View actions di samping set konteks yang Anda gunakan.
  2. Klik Download context file.
  3. Ikuti langkah-langkah di bagian Membangun set konteks menggunakan agen rekayasa konteks untuk memperbarui konteks dengan pasangan kueri tambahan.
  4. Di panel Explorer, klik View actions di samping set konteks yang Anda gunakan.
  5. Klik Edit context set.
  6. Klik Browse di bagian Upload context file, lalu pilih file set konteks yang telah diperbarui.
  7. Klik Save untuk memperbarui set konteks.

Setelah Anda puas dengan akurasi respons, Anda dapat meneruskan ID set konteks ke endpoint QueryData stateless dalam permintaan dari aplikasi Anda.

Menemukan ID set konteks

Untuk mereferensikan set konteks yang Anda buat dan disimpan di Knowledge Catalog saat memanggil endpoint QueryData stateless dari aplikasi, Anda memerlukan ID set konteks.

  1. Di konsol Google Cloud , buka halaman AlloyDB.

    Buka AlloyDB

  2. Pilih cluster dari daftar.

  3. Di menu navigasi, klik AlloyDB Studio.

  4. Login ke Studio menggunakan autentikasi Identity and Access Management.

  5. Di panel Explorer, klik View actions di samping set konteks yang Anda gunakan.

  6. Klik Edit context set.

  7. Catat nama resource set konteks di Context set ID. Endpoint QueryData mendukung kedua format nama resource set konteks berikut di Knowledge Catalog:

    • Format 6 segmen: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, seperti projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • Format 8 segmen: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (misalnya, @v1)

Menghubungkan QueryData ke aplikasi Anda

Tetapkan ID set konteks dalam panggilan metode QueryData untuk memberikan konteks yang dibuat dari Knowledge Catalog untuk sumber data database seperti AlloyDB, Spanner, Cloud SQL untuk MySQL, Cloud SQL untuk PostgreSQL, Firestore, dan Bigtable. Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data database.

Setelah menguji set konteks, Anda dapat mereferensikan sumber data database dan set konteks dalam panggilan QueryData stateless.

Contoh permintaan QueryData dengan konteks yang ditulis

Contoh berikut mengirimkan permintaan QueryData stateless menggunakan sumber data database alloydb. Kolom agent_context_reference.context_set_id menautkan permintaan ke set konteks yang telah Anda buat sebelumnya dan disimpan di Knowledge Catalog, bukan di database Anda:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": {
      "alloydb": {
        "database_reference": {
          "project_id": "PROJECT_ID",
          "region": "LOCATION",
          "cluster_id": "CLUSTER_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud yang digunakan untuk permintaan.
  • LOCATION: region untuk permintaan, seperti us-central1.
  • CLUSTER_ID: ID cluster dari cluster AlloyDB.
  • INSTANCE_ID: ID instance dari instance AlloyDB.
  • DATABASE_ID: ID database.
  • CONTEXT_SET_ID: ID set konteks Anda.

Isi permintaan berisi kolom berikut:

  • prompt: Pertanyaan bahasa alami dari pengguna akhir.
  • context: Berisi informasi tentang sumber data.
    • datasource_references: Menentukan jenis sumber data.
      • alloydb: Diperlukan saat membuat kueri database.
        • database_reference: Menentukan informasi yang terkait dengan instance database Anda.
          • cluster_id: ID cluster instance database.
          • project_id: Project ID instance database.
          • region: Region instance AlloyDB.
          • instance_id: ID instance dari instance AlloyDB.
          • database_id: ID database.
        • agent_context_reference: Menautkan permintaan QueryData stateless ke set konteks yang Anda buat dan disimpan di Knowledge Catalog, bukan di database Anda.
          • context_set_id: Nama resource lengkap dari set konteks yang disimpan di Knowledge Catalog. Anda dapat menentukan format 6 segmen, projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, atau format 8 segmen, projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (misalnya, @v1).
  • generation_options: Mengonfigurasi jenis output yang akan dibuat.
    • generate_query_result: Tetapkan ke true untuk membuat dan menampilkan hasil kueri.
    • generate_natural_language_answer: Opsional. Jika ditetapkan ke true, akan menghasilkan jawaban dalam bahasa alami.
    • generate_explanation: Opsional. Jika ditetapkan ke true, akan menghasilkan penjelasan kueri SQL.
    • generate_disambiguation_question: Opsional. Jika ditetapkan ke true, akan menghasilkan pertanyaan disambiguasi jika kueri bersifat ambigu.

Contoh respons QueryData

Berikut adalah contoh respons yang berhasil dari panggilan QueryData:

{
  "generatedQuery": "-- 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",
  "intentExplanation": "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.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

Langkah berikutnya