このページでは、Google Cloud コンソールを使用して検索結果をプレビューし、API を使用して検索結果を取得する方法について説明します。
また、ウェブページに追加する検索ウィジェットを作成する代わりに、API 呼び出しを行って、その呼び出しをサーバーまたはアプリケーションに統合することもできます。このページでは、サービス アカウントで gRPC クライアント ライブラリを使用して検索クエリを作成する方法のコードサンプルを示します。
検索の要約はモデルによって異なります
クエリの検索のサマリーを生成すると、コンソールの結果と API の結果でサマリーが異なる場合があります。このような場合は、コンソールが API とは異なる LLM モデルを使用している可能性があります。このページの curl とコードの例では、安定版の LLM モデルを使用しています。
UI の [プレビュー] ページで使用されている LLM モデルを変更または表示するには、アプリの [構成] ページ > [UI] タブに移動します。
メソッド呼び出しで、安定版モデル以外の LLM モデルを使用する場合は、要約モデルを指定するをご覧ください。
ウェブサイト データを含むアプリの検索結果を取得する
Console
Google Cloud コンソールを使用して、ウェブサイト データを含むアプリの検索結果をプレビューする手順は次のとおりです。
Google Cloud コンソールで、[Agent Builder] ページに移動します。
編集するアプリの名前をクリックします。
[プレビュー] をクリックします。
コンソールで [プレビュー] ページを開きます。
省略可: 複数のデータストアをアプリに接続していて、特定のデータストアからのみ結果を取得する場合は、結果を取得するデータストアを選択します。
検索語句を入力します。
- 予測入力を有効にしている場合、入力すると検索バーの下に予測入力候補のリストが表示されます。
Enter キーを押してクエリを送信します。
- 検索結果のリストが検索バーの下に表示されます。
- 各結果には、タイトル、スニペット、URL が含まれます。
- 検索結果をクリックすると、その URL が開きます。
結果リストの下にある矢印をクリックすると、結果の次のページが読み込まれます。
REST
API を使用してウェブサイト データを含むアプリの検索結果を取得するには、engines.servingConfigs.search
メソッドを使用します。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[Agent Builder] ページに移動します。
[アプリ] ページでアプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
検索結果を取得します。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "params": {"user_country_code": "USER_COUNTRY_CODE", "searchType": "SEARCH_TYPE"}, "filter": "FILTER", "boostSpec": "BOOST_SPEC", "contentSearchSpec": { "searchResultMode": "RESULT_MODE" }, "dataStoreSpec": {"DATA_STORE_SPEC"} }'
- PROJECT_ID: Google Cloud プロジェクトの ID。
- APP_ID: クエリする Vertex AI Search アプリの ID。
- QUERY: 検索するクエリテキスト。
PAGE_SIZE: 検索によって返された結果の数。許可される最大ページサイズはデータ型によって異なります。最大値を超えるページサイズは、最大値に強制変換されます。
- 基本インデックス登録を使用するウェブサイト: デフォルト
10
、最大25
- 高度なインデックス登録を使用するウェブサイト: デフォルト
25
、最大50
- その他: デフォルト
50
、最大100
- 基本インデックス登録を使用するウェブサイト: デフォルト
OFFSET: 結果の開始インデックス。デフォルト値は 0 です。
たとえば、オフセットが 2、ページサイズが 10、返される結果が 15 個ある場合、1 ページ目には 2 から 12 個の結果が返されます。
ORDER_BY: 結果の並べ替え順序。並べ替える属性には、数値として解釈できる値(価格や日付など)が必要です。
USER_COUNTRY_CODE: ユーザーのロケーション。この Key-Value ペアは、
params
マップ フィールドでサポートされている唯一のエントリです。デフォルト値は空です。使用可能な値については、Programmable Search Engine JSON API リファレンス ドキュメントの国コードをご覧ください。SEARCH_TYPE: 実行する検索のタイプ。デフォルト値は、ドキュメント検索の場合は 0 です。その他のサポートされている値は、画像検索の場合は 1 です。
FILTER: フィルタ式を使用して検索結果をフィルタリングするためのテキスト フィールド。デフォルト値は空文字列です。
filter
フィールドの使用方法については、ウェブサイト検索をフィルタするをご覧ください。BOOST_SPEC: 省略可。ドキュメントをブーストまたは非表示にする仕様。値:
BOOST
: -1 から 1 の浮動小数点数。値が負の場合、結果は降格されます(結果の下位に表示されます)。値が正の場合、結果は昇格されます(結果の上位に表示されます)。CONDITION
: ブーストを適用するドキュメントを選択するテキスト フィルタ式。フィルタはブール値に評価される必要があります。 構造化検索のブーストについては、検索結果をブーストするをご覧ください。
RESULT_MODE: 検索結果を完全なドキュメントとして返すか、チャンクとして返すかを決定します。チャンクを取得するには、データストアでドキュメント チャンキングがオンになっている必要があります。指定できる値は
documents
およびchunks
です。データストアでチャンキングがオンの場合、デフォルト値はchunks
です。それ以外の場合は、デフォルトはdocuments
です。ドキュメント チャンキングについては、ドキュメントの解析とチャンク処理をご覧ください。このフィールドは公開プレビュー版です。使用するには、curl コマンドでv1
をv1alpha
に変更します。DATA_STORE_SPEC: 検索対象の特定のデータストアのフィルタ。検索アプリが複数のデータストアに接続されているが、特定のデータストアの結果が必要な場合は、
dataStoreSpec
を使用します。
C#
詳細については、Vertex AI Agent Builder C# API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
詳細については、Vertex AI Agent Builder Java API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
詳細については、Vertex AI Agent Builder Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
詳細については、Vertex AI Agent Builder PHP API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
詳細については、Vertex AI Agent Builder Ruby API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
構造化データまたは非構造化データを含むアプリの検索結果を取得する
検索結果は、Google Cloud コンソールからプレビューできます。また、API を使用して検索結果を取得することもできます。
Console
Google Cloud コンソールを使用して、構造化データまたは非構造化データを含むアプリの検索結果をプレビューする手順は次のとおりです。
- コンソールで [プレビュー] ページを開きます。
- 検索語句を入力します。
- 手順 1 で予測入力を有効にした場合、入力すると検索バーの下に予測入力候補のリストが表示されます。
- (省略可)複数のデータストアをアプリに接続していて、特定のデータストアからの結果のみを取得する場合は、結果を取得するデータストアを選択します。
- Enter キーを押してクエリを送信します。
- 検索結果のリストが検索バーの下に表示されます。
- [構成] ページで属性マッピングが定義されていない場合、各検索結果は未加工の属性名と値のリストとして表示されます。
- [構成] ページに属性マッピングが保存されている場合、検索結果には [構成] ページのプレビューと同じ画像が表示されます。
- [構成] ページでファセットが指定されている場合は、同じ方法で表示されます。
- 結果リストの下にある矢印をクリックして、結果の次のページを読み込みます。
REST
API を使用して、構造化データまたは非構造化データを含むアプリの検索結果を取得するには、engines.servingConfigs.search
メソッドを使用します。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[Agent Builder] ページに移動します。
[アプリ] ページでアプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
検索結果を取得します。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "userPseudoId": "USER_PSEUDO_ID", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "filter": "FILTER", "boostSpec": "BOOST_SPEC", "facetSpec": "FACET_SPEC", "queryExpansionSpec": "QUERY_EXPANSION_SPEC", "spellCorrectionSpec": "SPELL_CORRECTION_SPEC", "contentSearchSpec": "CONTENT_SEARCH_SPEC", "dataStoreSpec": {"DATA_STORE_SPEC"}, }'
- PROJECT_ID: Google Cloud プロジェクトの ID。
- APP_ID: クエリする Vertex AI Search アプリの ID。
- QUERY: 検索するクエリテキスト。
- USER_PSEUDO_ID: 省略可。これは、検索訪問者のトラッキング用の仮名化 ID です。このフィールドを使用することを強くおすすめします。これにより、モデルのパフォーマンスとパーソナライズの品質が向上します。このフィールドには HTTP Cookie を使用できます。これにより、1 つのデバイス上の訪問者を一意に識別できます。この ID は、訪問者がウェブサイトにログインまたはログアウトしても変更されません。このフィールドを複数のユーザーに対して同じ ID に設定しないでください。イベント履歴が統合され、モデルの品質が低下します。このフィールドには、個人を特定できる情報(PII)は含めないでください。
PAGE_SIZE: 検索によって返された結果の数。 許可される最大ページサイズはデータ型によって異なります。最大値を超えるページサイズは、最大値に強制変換されます。
- 基本インデックス登録を使用するウェブサイト: デフォルト
10
、最大25
- 高度なインデックス登録を使用するウェブサイト: デフォルト
25
、最大50
- その他: デフォルト
50
、最大100
- 基本インデックス登録を使用するウェブサイト: デフォルト
OFFSET: 省略可。結果の開始インデックス。 デフォルト値は 0 です。
たとえば、オフセットが 2、ページサイズが 10、返される結果が 15 個ある場合、1 ページ目には 2 から 12 個の結果が返されます。
ORDER_BY: 省略可。結果の並べ替え順序。
FILTER: 省略可。フィルタ式を使用して検索結果をフィルタリングするためのテキスト フィールド。デフォルト値は空の文字列です。つまり、フィルタは適用されません。
例:
color: ANY("red", "blue") AND score: IN(*, 100.0e)
詳細については、構造化データまたは非構造化データの検索をフィルタするをご覧ください。
BOOST_SPEC: 省略可。ドキュメントをブーストまたは非表示にする仕様。値:
BOOST
: -1 から 1 の浮動小数点数。値が負の場合、結果は降格されます(結果の下位に表示されます)。値が正の場合、結果は昇格されます(結果の上位に表示されます)。CONDITION
: ブーストを適用するドキュメントを選択するテキスト フィルタ式。フィルタはブール値に評価される必要があります。
構造化検索のブーストについては、検索結果をブーストするをご覧ください。
FACET_SPEC: 省略可。ファセット検索を実行するファセット仕様。
QUERY_EXPANSION_SPEC: 省略可。クエリ拡張を行う条件を決定する仕様。デフォルトは
DISABLED
です。SPELL_CORRECTION_SPEC: 省略可。スペルチェックを行う条件を決定する仕様。デフォルトは
AUTO
です。CONTENT_SEARCH_SPEC: 省略可。スニペット、抽出回答、抽出セグメント、検索のサマリーを取得します。非構造化データのみ。詳しくは以下をご覧ください。
DATA_STORE_SPEC: 検索対象の特定のデータストアのフィルタ。これは、検索アプリが複数のデータストアに接続されている場合に使用できます。
検索レスポンスでガイド付きの検索結果を表示する:
ガイド付きの検索結果は、構造化検索と非構造化検索の検索レスポンスとともに返されます。ガイド付きの検索結果には、検索結果ドキュメントに基づいて抽出された属性の Key-Value ペアのリストが含まれます。これにより、ユーザーは一部属性のキーと値をフィルタとして使用して、検索結果を絞り込むことができます。
このレスポンスの例では、フィルタ フィールドを
_gs.color: ANY("green")
として指定した新しい検索リクエストを発行することで、検索結果を絞り込むために緑色が使用されています。{ "guidedSearchResult": { "refinementAttributes": [ { "attributeKey": "_gs.color", "attributeValue" : "green" }, { "attributeKey": "_gs.category", "attributeValue" : "shoe" } ] } }
C#
詳細については、Vertex AI Agent Builder C# API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
詳細については、Vertex AI Agent Builder Java API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
詳細については、Vertex AI Agent Builder Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
詳細については、Vertex AI Agent Builder PHP API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
詳細については、Vertex AI Agent Builder Ruby API のリファレンス ドキュメントをご覧ください。
Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。
メディアアプリの入力逐次検索結果を取得する
メディア検索の場合、Vertex AI Agent Builder には次の 2 種類の検索動作があります。
ユーザーが検索語句を入力し、Enter キーを押します。これはデフォルトであり、ウィジェットでの検索や、メディア以外の(汎用)アプリの検索と同じ動作です。構造化データまたは非構造化データを含むアプリの検索結果を取得するをご覧ください。
ユーザーが入力する文字ごとに、新しい検索結果が返されます。これは入力逐次検索と呼ばれ、テレビのリモコンなど、操作しにくいインターフェースから検索語句を入力するユーザーに特に便利です。
メディアアプリの入力逐次検索の結果を取得するには:
Console
Google Cloud コンソールを使用してウィジェットアプリの入力逐次検索を有効にするには:
Google Cloud コンソールで、[Agent Builder] ページに移動します。
入力逐次検索に使用するメディア検索アプリの名前をクリックします。
[設定] をクリックします。
[UI] タブをクリックします。
[入力逐次検索を有効にする] トグルをクリックします。
[プレビュー] ペインで、クエリの入力を開始します。
検索結果はキー入力のたびに更新されます。
入力逐次検索設定を維持するには、[保存して公開] をクリックします。
REST
dataStores.servingConfigs.search
メソッドを使用して、メディアアプリの検索結果を取得します。
アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
Google Cloud コンソールで、[Agent Builder] ページに移動します。
[アプリ] ページでアプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の curl コマンドを実行して、入力逐次検索の結果を取得します。
contentSearchSpec
を除くすべてのフィールドは、searchAsYouTypeSpec
フィールドと組み合わせて使用できます。わかりやすくするため、省略可能なフィールドは curl コマンドから省略されています。省略可能なフィールドについては、構造化データまたは非構造化データを含むアプリの検索結果を取得するをご覧ください。curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'
- PROJECT_ID: Google Cloud プロジェクトの ID。
- APP_ID: クエリする Vertex AI Search アプリの ID。
- QUERY: 検索するクエリテキスト。
curl コマンドの例については、こちらをクリックしてください。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/12345/locations/global/collections/default_collection/engines/my-app_4321/servingConfigs/default_search:search" -d '{ "query": "midsummer night", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'