在 Firestore Studio 測試 QueryData

本文說明如何測試 QueryData，以及更新脈絡集檔案。您可以測試 QueryData 的能力，看看能否根據自然語言問題，生成與 MongoDB 相容的查詢語言 (MQL) 查詢。如果生成的查詢不準確，可以更新情境集檔案。

如要瞭解情境組合，請參閱「情境組合總覽」。

事前準備

請確認您已建立脈絡資料集，並將脈絡資料集檔案上傳至 QueryData 代理。詳情請參閱「在 Firestore Studio 中管理情境集」。

如要下載、更新及上傳情境集檔案，請確認 IAM 使用者具備專案的 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色。詳情請參閱「情境組合權限」。

測試 QueryData

如要測試 QueryData，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 Firestore 頁面。

    前往 Firestore

  2. 選取已新增脈絡資料集的資料庫。僅支援與 MongoDB 相容的 Firestore。

  3. 在導覽選單中，按一下「Firestore Studio」。

  4. 在「Explorer」窗格中，點選所用內容集旁邊的「查看動作」。

  5. 按一下「測試脈絡資料集」。

  6. 在查詢編輯器中，按一下「產生查詢」開啟「幫我寫程式碼」面板。

  7. 在編輯器中輸入自然語言問題，生成 MQL 查詢，然後按一下「生成」。

  8. 檢查 MQL 查詢是否正確。

下載及更新脈絡資料集

如果您對自然語言問題產生的 MQL 查詢不滿意，請下載現有的內容集檔案。接著，您可以查看及更新查詢範本，並將更新後的結構定義檔案重新上傳至代理。

如要下載及更新情境組合，請按照下列步驟操作：

  1. 在「Explorer」窗格中，點選「查看動作」。
  2. 按一下「下載脈絡資料檔案」。
  3. 按照「使用脈絡工程代理建構脈絡資料集」一節的步驟，使用其他查詢配對更新脈絡資料。
  4. 在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。
  5. 按一下「Edit context set」。
  6. 按一下「上傳情境集檔案」部分的「瀏覽」，然後選取更新後的情境集檔案。
  7. 按一下「儲存」，更新情境組合。

如果回覆準確度符合需求，您可以使用 QueryData 端點，將應用程式連結至情境集。

找出脈絡資料集 ID

如要將資料應用程式連結至 QueryData 代理，您需要取得脈絡資料集的 ID。

  1. 前往 Google Cloud 控制台的「Firestore」頁面。

    前往 Firestore

  2. 選取已新增脈絡資料集的資料庫。

  3. 在導覽選單中，按一下「Firestore Studio」。

  4. 在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。

  5. 按一下「Edit context set」。

  6. 請注意「脈絡資料集 ID」中的脈絡 ID。脈絡資料集 ID 格式類似於 projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates。

將 QueryData 連結至應用程式

在 QueryData 方法呼叫中設定內容集 ID，為資料庫資料來源 (例如 AlloyDB、Spanner、Cloud SQL、PostgreSQL 適用的 Cloud SQL 和 Firestore) 提供撰寫的內容。詳情請參閱「為資料庫資料來源定義資料代理程式環境」。

測試完情境集後，您可以在 QueryData 呼叫中參照資料庫資料來源。

包含撰寫情境的 QueryData 要求範例

以下範例顯示使用 firestore_reference (與 MongoDB 相容的 Firestore) 資料來源的 QueryData 要求。agent_context_reference.context_set_id 欄位用於連結至儲存在資料庫中的預先編寫情境。

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans?",
  "context": {
    "datasource_references": [
      {
        "firestore_reference": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

要求主體包含下列欄位：

  • prompt：來自使用者的自然語言問題。
  • context：包含資料來源的相關資訊。
    • datasource_references：指定資料來源類型。
      • firestore_reference：：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而變更。
        • database_reference：指定與資料庫執行個體相關的資訊。
          • project_id：資料庫的專案 ID。
          • region：資料庫的區域。
          • database_id：資料庫 ID。
        • agent_context_reference：連結至資料庫中編寫的內容。
          • context_set_id：儲存在資料庫中的完整情境集 ID。例如：projects/context-set-project/locations/us-central1/contextSets/bdf_gsql_gemini_all_templates。
  • generationOptions：設定要生成的輸出類型。
    • generate_query_result：設為 true 可產生並傳回查詢結果。
    • generate_natural_language_answer：選用。如果設為 true，就會生成自然語言答案。
    • generate_explanation：選用。如果設為 true，系統會產生 MQL 查詢的說明。
    • generate_disambiguation_question：選用。如果設為 true，系統會在查詢內容模稜兩可時生成消歧問題。

QueryData 回應範例

以下是 QueryData 呼叫成功的回應範例：

{
  "generated_query": "// Count the number of accounts in Prague that are eligible for loans\ndb.loans.aggregate([\n  // 1. Filter loans in the Prague region\n  { \n    $match: { \"district.name\": \"Prague\" } \n  },\n  // 2. Group by account_id to get distinct values, and count them\n  { \n    $group: { \n      _id: null, \n      uniqueAccounts: { $addToSet: \"$account_id\" } \n    } \n  },\n  // 3. Project the size of the unique accounts array\n  { \n    $project: { \n      _id: 0,\n      distinct_account_count: { $size: \"$uniqueAccounts\" } \n    } \n  }\n]);",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to filter the documents in the loans collection to only give me those in the Prague region. Then I need to group the loans by account ID to get distinct values and count them. Finally, I need to project the size of the array of unique accounts.",
  "query_result": {
    "columns": [
      {
        "name": "distinct_account_count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

後續步驟