Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

QueryData をテストする

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

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

始める前に

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

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

QueryData をテストする

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

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

AlloyDB に移動する
リストからクラスタを選択します。
ナビゲーションメニューで [AlloyDB Studio] をクリックします。
Identity and Access Management 認証を使用して Studio にログインします。
[エクスプローラ] ペインで、使用しているコンテキストセットの横にある [アクションを表示] をクリックします。
[テストコンテキストセット] をクリックします。
クエリエディタで、[Generate SQL using QueryData with: CONTEXT_SET_NAME] をクリックして、クエリ生成パネルを開きます。
クエリ生成パネルに自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。
SQL クエリの精度を確認します。[挿入] をクリックして、クエリをエディタに追加します。

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

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

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

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

レスポンスの精度が納得できるものになったら、アプリケーションからのリクエストでコンテキストセット ID をステートレス QueryData エンドポイントに渡すことができます。

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

アプリケーションからステートレス QueryData エンドポイントを呼び出すときに、Knowledge Catalog に保存されている作成済みのコンテキストセットを参照するには、コンテキストセット ID が必要です。

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

AlloyDB に移動する
リストからクラスタを選択します。
ナビゲーションメニューで [AlloyDB Studio] をクリックします。
Identity and Access Management 認証を使用して Studio にログインします。
[エクスプローラ] ペインで、使用しているコンテキストセットの横にある [アクションを表示] をクリックします。
[コンテキストセットを編集] をクリックします。
[コンテキストセット ID] に示されているコンテキストセットのリソース名をメモします。QueryData エンドポイントは、Knowledge Catalog で次の両方のコンテキストセットリソース名形式をサポートしています。
- 6 セグメント形式: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID（例: projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates）
- 8 セグメント形式: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION（例: @v1）

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

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

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

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

次の例では、alloydb データベースをデータソースとして使用して、ステートレスな QueryData リクエストを送信します。agent_context_reference.context_set_id フィールドは、リクエストを、データベースではなく Knowledge Catalog に保存されている事前作成済みのコンテキストセットにリンクします。

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
  }
}'

次のように置き換えます。

PROJECT_ID: リクエストに使用される Google Cloud プロジェクトの ID。
LOCATION: リクエストのリージョン（us-central1 など）。
CLUSTER_ID: AlloyDB クラスタのクラスタ ID。
INSTANCE_ID: AlloyDB インスタンスのインスタンス ID。
DATABASE_ID: データベースの ID。
CONTEXT_SET_ID: コンテキストセットの ID。

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

prompt: エンドユーザーからの自然言語による質問。
context: データソースに関する情報を入力します。
- datasource_references: データソースのタイプを指定します。
  - alloydb: データベースのクエリを実行する際に必須となります。
    - database_reference: データベースインスタンスに関する情報を指定します。
      - cluster_id: データベースインスタンスのクラスタ ID。
      - project_id: データベースインスタンスのプロジェクト ID。
      - region: AlloyDB インスタンスのリージョン。
      - instance_id: AlloyDB インスタンスのインスタンス ID。
      - database_id: データベースの ID。
    - agent_context_reference: ステートレス QueryData リクエストを、データベースではなく Knowledge Catalog に保存されている作成済みコンテキストセットにリンクします。
      - context_set_id: Knowledge Catalog に保存されているコンテキストセットの完全なリソース名。6 セグメント形式（projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID）または 8 セグメント形式（projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION、例: @v1）を指定できます。
generation_options: 生成する出力のタイプを構成します。
- generate_query_result: クエリ結果を生成して取得する場合は true に設定します。
- generate_natural_language_answer: 省略可。true に設定すると、自然言語による回答が生成されます。
- generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。
- generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合はクエリを明確にするための質問が生成されます。

`QueryData` の回答の例

以下は、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
  }
}

次のステップ

コンテキストセットの詳細を確認する。
コンテキストエンジニアリングエージェントを使用してコンテキストセットを構築する方法を確認する。
AlloyDB Studio でコンテキストセットを管理する方法を確認する。

QueryData をテストする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

QueryData をテストする

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

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

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

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

QueryData の回答の例

次のステップ

QueryData をテストする

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

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

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

`QueryData` の回答の例