Test QueryData

Dokumen ini menjelaskan cara menguji QueryData untuk Spanner Graph dengan memanggil metode QueryData dari Analisis Percakapan API, dan cara memperbarui file set konteks. Anda dapat menguji kemampuan QueryData untuk membuat kueri Graph Query Language (GQL) dari pertanyaan bahasa alami. Jika kueri GQL yang dihasilkan tidak akurat, Anda dapat memperbarui file set konteks.

Untuk mempelajari set konteks untuk Spanner Graph, lihat Ringkasan set konteks.

Sebelum memulai

Menemukan ID set konteks yang ada

Untuk menguji QueryData dengan set konteks Anda, atau untuk menghubungkan aplikasi data ke QueryData, Anda memerlukan ID set konteks.

  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, klik View actions di samping set konteks yang Anda gunakan.

  5. Klik Edit context set.

  6. Catat ID set konteks di ID set konteks. Format ID set konteks mirip dengan projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

Menguji QueryData menggunakan HTTP POST

Untuk menguji QueryData untuk Spanner Graph, kirim permintaan POST HTTP QueryData yang menyertakan kolom graph_ids dan ID set konteks Anda:

  1. Buat file bernama request.json dengan konten berikut:

    {
      "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INSTANCE_ID: ID instance Spanner Anda.
    • DATABASE_ID: ID database Spanner Anda.
    • CONTEXT_SET_ID: ID set konteks lengkap yang Anda catat di Menemukan ID set konteks.
  2. Kirim permintaan:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. Dalam respons, tinjau kolom generatedQuery (GRAPH FinGraph MATCH ...) untuk memastikan akurasinya, dan tinjau kolom queryResult untuk baris yang ditampilkan.

Untuk menguji pertanyaan lain, ubah nilai prompt di request.json dan kirim permintaan lagi. Untuk melihat perilaku QueryData tanpa konteks yang ditulis, hapus objek agent_context_reference.

Untuk memeriksa apakah QueryData menggunakan set konteks Anda, ajukan pertanyaan yang bergantung pada set konteks tersebut (seperti "Siapa pemilik akun dana darurat?") dan bandingkan respons dengan dan tanpa objek agent_context_reference. Tanpa set konteks, QueryData mungkin memfilter 'rainy day' dan tidak menampilkan baris. Dengan konteks yang ditetapkan, model akan memfilter 'Rainy Day Fund' dan menampilkan Dana.

Mendownload dan memperbarui set konteks yang ada

Jika respons pengujian Anda menunjukkan bahwa kueri GQL yang dihasilkan untuk pertanyaan natural language perlu ditingkatkan, download file set konteks yang ada. Kemudian, Anda dapat meninjau dan memperbarui template kueri GQL, faset, atau penelusuran nilai, lalu mengupload file set konteks yang telah diperbarui ke set konteks.

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

  1. Di panel Explorer, klik View actions di samping set konteks Anda.
  2. Klik Download context file.
  3. Ikuti langkah-langkah di Membangun set konteks menggunakan agen rekayasa konteks untuk memperbarui set konteks dengan pasangan kueri bahasa alami ke GQL 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 set file, lalu pilih file set konteks yang telah diperbarui.
  7. Klik Save untuk memperbarui set konteks.
  8. Uji QueryData lagi untuk memverifikasi kueri GQL yang dihasilkan.

Setelah Anda puas dengan akurasi respons, Anda dapat menggunakan endpoint QueryData untuk menghubungkan aplikasi ke set konteks.

Menghubungkan QueryData ke aplikasi Anda

Tetapkan ID set konteks dan graph_ids target dalam panggilan metode QueryData untuk memberikan konteks yang dibuat dan mengaktifkan pembuatan kueri GQL untuk Spanner Graph. Untuk mengetahui informasi selengkapnya tentang penggunaan QueryData dengan sumber data database, lihat Menentukan konteks agen data untuk sumber data database. Untuk contoh yang menghubungkan aplikasi agen ke QueryData melalui alat HTTP kustom yang memanggil REST API QueryData, lihat Mengintegrasikan QueryData dengan aplikasi.

Contoh permintaan QueryData dengan konteks yang ditulis

Contoh berikut menunjukkan permintaan QueryData yang menggunakan sumber data database spanner_reference untuk grafik properti FinGraph. Anda harus menyediakan graph_ids di dalam spanner_reference.database_reference agar QueryData menargetkan grafik properti Anda dan menghasilkan kueri GQL. Kolom agent_context_reference.context_set_id ditautkan ke konteks yang telah ditulis sebelumnya dan disimpan dalam database:

{
  "parent": "projects/my-project/locations/global",
  "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
  "context": {
    "datasource_references": {
      "spanner_reference": {
        "database_reference": {
          "engine": "GOOGLE_SQL",
          "project_id": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

Isi permintaan berisi kolom berikut:

  • parent: Opsional. Project dan lokasi permintaan, dalam format projects/PROJECT_ID/locations/LOCATION. Gunakan project dan lokasi yang sama seperti di URL permintaan.
  • prompt: Pertanyaan bahasa alami dari pengguna akhir.
  • context: Berisi informasi tentang sumber data.
    • datasource_references: Menentukan sumber data. Kolom ini adalah objek, bukan daftar.
      • spanner_reference: Diperlukan saat mengkueri database Spanner.
        • database_reference: Menentukan informasi yang terkait dengan database Spanner dan grafik properti Anda.
          • engine: Dialek database. Tetapkan ke GOOGLE_SQL untuk database Spanner Graph.
          • project_id: Project ID instance Spanner.
          • instance_id: ID instance Spanner.
          • database_id: ID database Spanner.
          • graph_ids: Diperlukan untuk Spanner Graph. Daftar nama grafik properti dalam database yang akan dikueri (misalnya, ["FinGraph"]). Memberikan graph_ids akan menginstruksikan QueryData untuk membuat kueri GQL terhadap grafik properti yang ditentukan. Jika Anda menghilangkan graph_ids, QueryData hanya akan membuat kueri SQL relasional terhadap tabel yang mendasarinya.
        • agent_context_reference: Link ke konteks yang ditulis dalam database.
          • context_set_id: ID set konteks lengkap dari konteks yang disimpan dalam database, seperti projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • generation_options: Mengonfigurasi jenis output yang akan dibuat.
    • generate_query_result: Tetapkan ke true untuk menjalankan kueri GQL yang dihasilkan dan menampilkan hasil kueri.
    • generate_natural_language_answer: Opsional. Jika ditetapkan ke true, akan menghasilkan jawaban bahasa alami yang meringkas hasil kueri.
    • generate_explanation: Opsional. Jika ditetapkan ke true, akan menghasilkan penjelasan kueri GQL.
    • generate_disambiguation_question: Opsional. Jika ditetapkan ke true, akan menghasilkan pertanyaan disambiguasi jika perintah bahasa alami bersifat ambigu.

Contoh respons QueryData

Contoh berikut menunjukkan respons yang berhasil dari panggilan QueryData terhadap grafik properti FinGraph. REST API menampilkan nama kolom dalam camelCase, seperti generatedQuery dan queryResult. Karena pembuatan GQL bersifat nondeterministik, kueri, nama kolom, dan teks jawaban yang dihasilkan dapat berbeda di antara panggilan.

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

Langkah berikutnya