測試 QueryData

本文說明如何呼叫 對話式數據分析 API 的 QueryData 方法,測試 Spanner Graph 的 QueryData,以及如何更新情境集檔案。您可以測試 QueryData 的能力,看看能否根據自然語言問題生成 Graph Query Language (GQL) 查詢。如果生成的 GQL 查詢不準確,可以更新情境集檔案。

如要瞭解 Spanner Graph 的情境集,請參閱「情境集總覽」。

事前準備

找出既有的情境資料集 ID

如要使用脈絡資料集測試 QueryData,或將資料應用程式連結至 QueryData,您需要脈絡資料集 ID。

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

    前往「Spanner」頁面

  2. 從清單中選取執行個體,然後選取資料庫。

  3. 在導覽選單中,點選「Spanner Studio」。

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

  5. 按一下「編輯情境組合」。

  6. 記下「Context set ID」(脈絡資料集 ID) 中的脈絡資料集 ID。脈絡資料集 ID 的格式類似於 projects/my-project/locations/us-central1/contextSets/fingraph-assistant。

使用 HTTP POST 測試 QueryData

如要測試 Spanner Graph 的 QueryData,請傳送 QueryData HTTP POST 要求,其中包含 graph_ids 欄位和情境集 ID:

  1. 建立名為 request.json 的檔案,並在其中加入下列內容:

    {
      "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
      }
    }

    更改下列內容:

    • PROJECT_ID:您的 Google Cloud 專案 ID。
    • INSTANCE_ID:Spanner 執行個體 ID。
    • DATABASE_ID:Spanner 資料庫 ID。
    • CONTEXT_SET_ID:您在「找出脈絡資料集 ID」中記下的完整脈絡資料集 ID。
  2. 傳送要求:

    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. 在回應中,檢查 generatedQuery 欄位 (GRAPH FinGraph MATCH ...) 是否正確,並查看 queryResult 欄位傳回的資料列。

如要測試其他問題,請變更 request.json 中的 prompt 值,然後再次傳送要求。如要查看 QueryData 在沒有編寫內容時的行為,請移除 agent_context_reference 物件。

如要確認 QueryData 是否使用您的情境集,請提出相關問題 (例如「誰擁有雨天帳戶?」),並比較有無 agent_context_reference 物件的回覆。如果未設定情境,QueryData 可能會篩選 'rainy day',且不會傳回任何資料列。設定情境後,系統會篩選 'Rainy Day Fund' 並傳回 Dana。

下載並更新現有的脈絡資料集

如果測試回覆顯示,自然語言問題生成的 GQL 查詢需要改善,請下載現有的情境集檔案。接著,您可以查看及更新 GQL 查詢範本、facet 或值搜尋,並將更新後的內容集檔案上傳至內容集。

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

  1. 在「Explorer」窗格中,點選情境集旁邊的「查看動作」。
  2. 按一下「下載脈絡資料檔案」。
  3. 按照「使用脈絡工程代理建立脈絡資料集」一節的步驟操作,使用其他自然語言轉 GQL 查詢配對更新脈絡資料集。
  4. 在「Explorer」窗格中,找到您使用的情境集,然後點選旁邊的「查看動作」。
  5. 按一下「編輯情境組合」。
  6. 按一下「上傳情境集檔案」部分的「瀏覽」,然後選取更新後的情境集檔案。
  7. 按一下「儲存」,更新情境組合。
  8. 再次測試 QueryData,驗證生成的 GQL 查詢。

如果對回覆準確度感到滿意,可以使用 QueryData 端點,將應用程式連結至情境集。

將 QueryData 連結至應用程式

在 QueryData 方法呼叫中設定情境集 ID 和目標 graph_ids,提供編寫的情境,並啟用 Spanner Graph 的 GQL 查詢生成功能。如要進一步瞭解如何搭配使用 QueryData 與資料庫資料來源,請參閱「定義資料庫資料來源的資料代理程式情境」。如需範例,瞭解如何透過呼叫 QueryData REST API 的自訂 HTTP 工具,將代理應用程式連結至 QueryData,請參閱「將 QueryData 與應用程式整合」。

包含編寫內容的 QueryData 要求範例

以下範例顯示 QueryData 要求,使用 spanner_reference 資料庫資料來源,建立 FinGraph 屬性圖。您必須在 spanner_reference.database_reference 中提供 graph_ids,QueryData 才能指定屬性圖並生成 GQL 查詢。agent_context_reference.context_set_id 欄位會連結至儲存在資料庫中的預先編寫情境:

{
  "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
  }
}

要求主體包含下列欄位:

  • parent:選用。要求的專案和位置,格式為 projects/PROJECT_ID/locations/LOCATION。請使用與要求網址相同的專案和位置。
  • prompt:使用者提出的自然語言問題。
  • context:包含資料來源的相關資訊。
    • datasource_references:指定資料來源。這個欄位是物件,而非清單。
      • spanner_reference:查詢 Spanner 資料庫時必須提供。
        • database_reference:指定 Spanner 資料庫和屬性圖的相關資訊。
          • engine:資料庫的方言。如果是 Spanner Graph 資料庫,請設為 GOOGLE_SQL。
          • project_id:Spanner 執行個體的專案 ID。
          • instance_id:Spanner 執行個體的 ID。
          • database_id:Spanner 資料庫的 ID。
          • graph_ids:Spanner Graph 必須提供。資料庫中要查詢的屬性圖名稱清單 (例如 ["FinGraph"])。提供 graph_ids 會指示 QueryData 針對指定的屬性圖生成 GQL 查詢。如果省略 graph_ids,QueryData 只會針對基礎資料表生成關聯式 SQL 查詢。
        • agent_context_reference:資料庫中編寫內容的連結。
          • context_set_id:資料庫中儲存的完整情境集 ID,例如 projects/my-project/locations/us-central1/contextSets/fingraph-assistant。
  • generation_options:設定要生成的輸出類型。
    • generate_query_result:設為 true,即可執行生成的 GQL 查詢並傳回查詢結果。
    • generate_natural_language_answer:選用。如果設為 true,系統會生成自然語言答案,總結查詢結果。
    • generate_explanation:選用。如果設為 true,則會生成 GQL 查詢的說明。
    • generate_disambiguation_question:選用。如果設為 true,當自然語言提示詞語意不明時,系統會生成釐清問題。

QueryData 回應範例

以下範例顯示對 FinGraph 屬性圖發出 QueryData 呼叫後,成功傳回的回應。REST API 會以駝峰式大小寫傳回欄位名稱,例如 generatedQuery 和 queryResult。由於 GQL 生成作業不具確定性,因此每次呼叫生成的查詢、資料欄名稱和答案文字可能不同。

{
  "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**"
}

後續步驟