このページは Cloud Translation API によって翻訳されました。

データベースデータソースのデータエージェントコンテキストを定義する

作成されたコンテキストは、データエージェントのオーナーがデータエージェントの動作を形成し、API の回答を絞り込むために提供できるガイダンスです。効果的な作成済みコンテキストにより、Conversational Analytics API データエージェントは、データソースに関する質問に回答するための有用なコンテキストを取得できます。

このページでは、QueryData メソッドを使用して、データベースデータソースの作成済みコンテキストを指定する方法について説明します。AlloyDB、GoogleSQL for Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベースデータソースの場合、作成されたコンテキストを提供するには、まずデータベースでコンテキストを定義して保存し、QueryData 呼び出しで参照します。

精度の高いコンテキストを提供することで、API はより正確で関連性の高い SQL クエリと回答を生成できます。

始める前に

データベースにエージェントコンテキストがアップロードされたデータエージェントが存在する。詳細については、AlloyDB 用データエージェント、GoogleSQL for Spanner 用データエージェント、Cloud SQL 用データエージェント、Cloud SQL for PostgreSQL 用データエージェントをご覧ください。
次のように、インスタンスの Cloud SQL Data API を有効にします。
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
INSTANCE_ID は、Cloud SQL または Cloud SQL for PostgreSQL インスタンスの ID に置き換えます。

また、IAM ユーザーまたはサービスアカウントにデータベース権限を付与する必要があります。詳細については、Cloud SQL で個々の IAM ユーザーまたはサービスアカウントにデータベース権限を付与すると Cloud SQL for PostgreSQL で個々の IAM ユーザーまたはサービスアカウントにデータベース権限を付与するをご覧ください。

`QueryData` でコンテキストを提供する

QueryData メソッドを呼び出すときに、QueryDataRequest.context.datasourceReferences フィールド内でデータソースとコンテキスト情報を提供します。データベースソースの場合は、次のいずれかを使用する必要があります。

AlloyDB for PostgreSQL の alloydb、
Spanner 用 GoogleSQL の spanner_reference
Cloud SQL と Cloud SQL for PostgreSQL の cloud_sql_reference

これらの参照内で、databaseReference フィールドを使用してデータベースとテーブルを指定します。作成されたコンテキストを含めるには、context_set_id を指す agentContextReference も指定する必要があります。

作成済みコンテキストを含む `QueryData` リクエストの例

次の例は、alloydb を使用した QueryData リクエストを示しています。agent_context_reference.context_set_id フィールドは、データベースに保存されている事前作成済みのコンテキストにリンクするために使用されます。

AlloyDB

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

Spanner 用 GoogleSQL

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

Cloud SQL と Cloud SQL for PostgreSQL

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "cloud_sql_reference": {
          "database_reference": {
            "engine": "MYSQL"
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/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: データソースのタイプを指定します。
  - alloydb: データベースのクエリ時に必要です。このフィールドは、クエリを実行するデータベースによって異なります。
    - database_reference: データベースインスタンスに関連する情報を指定します。
      - engine:
      - project_id: データベースインスタンスのプロジェクト ID。
      - region: データベースインスタンスのリージョン。
      - cluster_id: データベースインスタンスのクラスタ ID。
      - instance_id: データベースのインスタンス ID。
      - database_id: データベースの ID。
    - agent_context_reference: データベース内の作成されたコンテキストへのリンク。
      - context_set_id: データベースに保存されているエージェントコンテキスト ID。コンテキストセット ID を見つける方法については、AlloyDB でエージェントコンテキスト ID を見つける、GoogleSQL for Spanner でエージェントコンテキスト ID を見つける、Cloud SQL でエージェントコンテキスト ID を見つける、Cloud SQL for PostgreSQL でエージェントコンテキスト ID を見つけるをご覧ください。
generationOptions: 生成する出力のタイプを構成します。
- generate_query_result: クエリ結果を生成して返す場合は true に設定します。
- generate_natural_language_answer: 省略可。true に設定すると、自然言語の回答が生成されます。
- generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。
- generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合に曖昧さ回避の質問が生成されます。

`QueryData` レスポンスの例

以下は、QueryData 呼び出しからの成功したレスポンスの例です。

{
  "generated_query": "-- 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",
  "intent_explanation": "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.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

データベース データソースのデータ エージェント コンテキストを定義する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。