Bigtable Studio で QueryData をテストする

このドキュメントでは、QueryData をテストしてコンテキスト セット ファイルを更新する方法について説明します。自然言語による質問から SQL クエリを生成する QueryData の機能をテストできます。生成されたクエリが正確でない場合は、コンテキスト セット ファイルを更新できます。

コンテキスト セットの詳細については、コンテキスト セットの概要をご覧ください。

始める前に

コンテキスト セットがすでに作成され、コンテキスト セット ファイルが QueryData エージェントにアップロードされていることを確認します。詳細については、Bigtable Studio でコンテキスト セットを管理するをご覧ください。

コンテキスト セット ファイルをダウンロード、更新、アップロードするには、IAM ユーザーにプロジェクトの Dataplex Catalog 編集者（roles/dataplex.catalogEditor）ロールまたは Dataplex Catalog 管理者（roles/dataplex.catalogAdmin）ロールが付与されていることを確認します。詳細については、コンテキスト セットの権限をご覧ください。

QueryData をテストする

QueryData をテストする手順は次のとおりです。

  1. Google Cloud コンソールで、[Bigtable] ページに移動します。

    Bigtable に移動

  2. リストからインスタンスを選択します。

  3. ナビゲーション メニューで [Bigtable Studio] をクリックします。

  4. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。

  5. [テスト コンテキスト セット] をクリックします。

  6. クエリエディタで、[Generate SQL using QueryData with: CONTEXT_SET_NAME] をクリックして [コーディング サポート] パネルを開きます。

  7. エディタに自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。

  8. SQL クエリの精度を確認します。[挿入] をクリックして、クエリをエディタに追加します。

コンテキスト セットをダウンロードして更新する

自然言語による質問に対して生成された SQL クエリにご納得いただけない場合は、既存のコンテキスト セット ファイルをダウンロードします。次に、クエリ テンプレートを確認して更新し、更新したコンテキスト ファイルをエージェントに再アップロードできます。

コンテキスト セットをダウンロードして更新する手順は次のとおりです。

  1. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。
  2. [コンテキスト ファイルをダウンロード] をクリックします。
  3. コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築するの手順に沿ってクエリのペアを追加し、コンテキストを更新します。
  4. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。
  5. [コンテキスト セットを編集] をクリックします。
  6. [コンテキスト ファイルのアップロード] セクションで [参照] をクリックし、更新したコンテキスト セット ファイルを選択します。
  7. [保存] をクリックして、コンテキスト セットを更新します。

レスポンスの精度が納得できるものになったら、QueryData エンドポイントを使用してアプリケーションをコンテキスト セットに接続できます。

コンテキスト セット ID を確認する

データ アプリケーションを QueryData エージェントに接続するには、コンテキスト セットの ID が必要です。

  1. Google Cloud コンソールで、[Bigtable] ページに移動します。

    Bigtable に移動

  2. リストからインスタンスを選択します。

  3. ナビゲーション メニューで [Bigtable Studio] をクリックします。

  4. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。

  5. [コンテキスト セットを編集] をクリックします。

  6. [コンテキスト セット ID] に示されているコンテキスト ID をメモします。コンテキスト セット ID の形式は projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@v1 のようになります。

QueryData をアプリケーションに接続する

QueryData メソッド呼び出しでコンテキスト セット ID を設定して、AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL、Firestore、Bigtable などのデータベース データソースの作成済みコンテキストを提示します。詳細については、データベースのデータソースのデータ エージェント コンテキストを定義するをご覧ください。

コンテキスト セットをテストしたら、QueryData 呼び出しでデータベースのデータソースを参照できます。

作成されたコンテキストを含む QueryData リクエストの例

以下の例は、bigtable_reference データベースをデータソースとして使用した QueryData リクエストを示しています。agent_context_reference.context_set_id フィールドは、作成したコンテキストを含むコンテキスト セットにリンクするために使用されます。

POST https://geminidataanalytics.googleapis.com/v1beta/projects/context-set-project/locations/us-central1:queryData
 
{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "List the names and ratings of all hotels located in London.",
  "context": {
    "datasource_references": {
      "bigtable_reference": {
        "database_reference": {
          "project_id": "context-set-project",
          "instance_id": "evalbench"
        },
        "agent_context_reference": {
          "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/hotels_bigtable_all_templates"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

リクエスト本文には次のフィールドが含まれます。

  • prompt: エンドユーザーからの自然言語による質問。
  • context: データソースに関する情報を入力します。
    • datasource_references: データソースのタイプを指定します。
      • bigtable_reference: データベースのクエリを実行する際に必須となります。このフィールドは、クエリの実行対象とするデータベースによって異なります。
        • database_reference: Bigtable インスタンスに関連する情報を指定します。
          • project_id: Bigtable インスタンスが属するプロジェクト ID。
          • instance_id: Bigtable インスタンスのインスタンス ID。
          • table_ids: 省略可。エージェントのスコープを設定するテーブル ID。設定しない場合、インスタンス内のすべてのテーブルが含まれます。
        • agent_context_reference: 作成済みコンテキストへのリンク。
          • context_set_id: 作成したコンテキストを含むコンテキスト セットの完全なコンテキスト セット ID。例: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@v1
  • generation_options: 生成する出力のタイプを構成します。
    • generate_query_result: クエリ結果を生成して取得する場合は true に設定します。
    • generate_natural_language_answer: 省略可。true に設定すると、自然言語による回答が生成されます。
    • generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。
    • generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合はクエリを明確にするための質問が生成されます。

QueryData の回答の例

以下は、QueryData 呼び出しによる回答の成功例です。

{
  "generatedQuery": "SELECT COUNT(*) FROM `hotels` WHERE CAST(cf['location'] AS STRING) = 'London'",
  "intentExplanation": "count of hotels in London",
  "queryResult": {
    "columns": [
      {
        "name": "$col1",
        "type": "int64_type:{}"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "Based on the data, there are 2 hotels located in London."
}

次のステップ