このドキュメントでは、会話型分析 API の QueryData メソッドを呼び出して Spanner Graph の QueryData をテストする方法と、コンテキスト セット ファイルを更新する方法について説明します。自然言語による質問から Graph Query Language(GQL)クエリを生成する QueryData の機能をテストできます。生成された GQL クエリが正確でない場合は、コンテキスト セット ファイルを更新できます。
Spanner Graph のコンテキスト セットの詳細については、コンテキスト セットの概要をご覧ください。
始める前に
- Spanner データベースに
FinGraphプロパティ グラフ スキーマとサンプルデータが構成されていることを確認します。FinGraphスキーマを作成してサンプルデータを挿入する手順については、Spanner Graph を設定してクエリを実行するをご覧ください。 - コンテキスト セットがすでに作成され、コンテキスト セット ファイルがデータベースにアップロードされていることを確認します。詳細については、Spanner Studio でコンテキスト セットを管理するをご覧ください。
- Google Cloud CLI をインストールして初期化します。
既存のコンテキスト セット ID を確認する
コンテキスト セットを使用して QueryData をテストする場合や、データ アプリケーションを QueryData に接続する場合は、コンテキスト セット ID が必要です。
Google Cloud コンソールで、[Spanner] ページに移動します。
リストからインスタンスを選択し、データベースを選択します。
ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。
[コンテキスト セットを編集] をクリックします。
[コンテキスト セット ID] に示されているコンテキスト セット ID をメモします。コンテキスト セット ID の形式は
projects/my-project/locations/us-central1/contextSets/fingraph-assistantのようになります。
HTTP POST を使用して QueryData をテストする
Spanner Graph の QueryData をテストするには、graph_ids フィールドとコンテキスト セット ID を含む QueryData HTTP POST リクエストを送信します。
次の内容で
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。
リクエストを送信します。
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
レスポンスで、
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 クエリ テンプレート、ファセット、値検索を確認して更新し、更新したコンテキスト セット ファイルをコンテキスト セットにアップロードできます。
コンテキスト セットをダウンロードして更新する手順は次のとおりです。
- [エクスプローラ] ペインで、コンテキスト セットの横にある [アクションを表示] をクリックします。
- [コンテキスト ファイルをダウンロード] をクリックします。
- コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築するの手順に沿って、自然言語から GQL へのクエリペアを追加してコンテキスト セットを更新します。
- [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。
- [コンテキスト セットを編集] をクリックします。
- [コンテキスト セット ファイルのアップロード] セクションで [参照] をクリックし、更新したコンテキスト セット ファイルを選択します。
- [保存] をクリックして、コンテキスト セットを更新します。
- [Test QueryData] をもう一度クリックして、生成された GQL クエリを確認します。
レスポンスの精度が納得できるものになったら、QueryData エンドポイントを使用してアプリケーションをコンテキスト セットに接続できます。
QueryData をアプリケーションに接続する
QueryData メソッド呼び出しでコンテキスト セット ID とターゲット graph_ids を設定して、作成済みコンテキストを提示し、Spanner Graph の GQL クエリ生成を有効にします。データベース データソースで QueryData を使用する方法については、データベース データソースのデータ エージェント コンテキストを定義するをご覧ください。QueryData REST API を呼び出すカスタム HTTP ツールを介してエージェント アプリケーションを QueryData に接続する例については、QueryData をアプリケーションと統合するをご覧ください。
作成されたコンテキストを含む QueryData リクエストの例
次の例は、FinGraph プロパティ グラフの spanner_reference データベース データソースを使用した QueryData リクエストを示しています。QueryData がプロパティ グラフをターゲットにして GQL クエリを生成するように、spanner_reference.database_reference 内に graph_ids を指定する必要があります。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形式)。リクエスト URL と同じプロジェクトとロケーションを使用します。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: 生成された GQL クエリを実行してクエリ結果を返すには、trueに設定します。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**"
}
次のステップ
- コンテキスト セットの詳細を確認する。
- コンテキスト エンジニアリング エージェントを使用してコンテキスト セットを構築する方法を確認する。
- Spanner Studio でコンテキスト セットを管理する方法を確認する。