Method: projects.locations.collections.engines.servingConfigs.searchLite

検索を実行します。SearchService.Search メソッドと同様ですが、認証に API キーを使用できるライト バージョンです。OAuth と IAM のチェックは必要ありません。

この方法では、一般公開ウェブサイトの検索のみがサポートされます。公開ウェブサイト検索に関連付けられていないデータストアとエンジンが指定されている場合は、FAILED_PRECONDITION エラーが返されます。

このメソッドを使用すると、認証バックエンドを実装しなくても簡単にオンボーディングできます。ただし、より優れたデータ セキュリティを実現するために、必要な OAuth と IAM チェックを使用して SearchService.Search を使用することを強くおすすめします。

HTTP リクエスト

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:searchLite

この URL では gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
servingConfig

string

必須。servingConfigs.search サービス構成のリソース名（projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config、projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config など）。このフィールドは、検索に使用されるサービス構成名とモデルのセットを識別するために使用されます。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  }
}
フィールド
branch

string

ブランチのリソース名（projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0 など）。

ブランチ ID として default_branch を使用するか、このフィールドを空白のままにして、デフォルト ブランチでドキュメントを検索します。
query

string

未加工の検索クエリ。
imageQuery

object (ImageQuery)

未加工の画像クエリ。
pageSize

integer

返す Document の最大数。許容される最大値は、データ型によって異なります。最大値を超える値は、最大値に強制変換されます。

  • 基本的なインデックス登録のウェブサイト: デフォルト 10、最大 25。
  • 高度なインデックス登録が有効になっているウェブサイト: デフォルト 25、最大 50。
  • その他: デフォルト 50、最大 100。

このフィールドが負の数の場合、INVALID_ARGUMENT が返されます。
pageToken

string

前回の SearchService.Search 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

ページ分割を行う場合、SearchService.Search に指定する他のすべてのパラメータは、ページトークンを提供した呼び出しと一致する必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
offset

integer

検索結果の現在のオフセット（つまり、API で関連すると見なされる Document における開始結果の場所）を指定する 0 から始まる整数。このフィールドは、pageToken が設定されていない場合にのみ考慮されます。

このフィールドが負の数の場合、INVALID_ARGUMENT が返されます。

大きなオフセットは、妥当なしきい値に制限されることがあります。
oneBoxPageSize

integer

OneBox で返される結果の最大数。これは、各 OneBox タイプに個別に適用されます。デフォルト値は 10 です。
dataStoreSpecs[]

object (DataStoreSpec)

検索する特定の DataStore と、それらのデータストアの構成を定義する仕様。これは、複数のデータストアを持つ Engine でのみ考慮されます。単一のデータストアを持つエンジンでは、SearchRequest の直下の仕様を使用する必要があります。
filter

string

フィルタ構文は、フィルタ対象となるドキュメントの 1 つ以上のフィールドから述語を生成するための式言語で構成されます。フィルタ式では大文字と小文字が区別されます。

このフィールドが認識できない場合、INVALID_ARGUMENT が返されます。

Vertex AI servingConfigs.search でのフィルタリングは、LHS フィルタキーを Vertex AI servingConfigs.search バックエンドで定義されたキー プロパティにマッピングすることで行われます。このマッピングは、スキーマでユーザーが定義します。たとえば、メディアのお客様のスキーマに「name」というフィールドがあるとします。この場合、フィルタは filter --> name:'ANY("king kong")' のようになります。

構文やフィルタ オペレータなどのフィルタリングの詳細については、フィルタをご覧ください。
canonicalFilter

string

ユーザーが検索ページでフィルタをオンにせずに検索を実行したときに適用されるデフォルトのフィルタ。

クエリ拡張などの品質改善が必要な場合に、すべての検索リクエストに適用されるフィルタ。クエリの結果が十分でない場合、このフィルタを使用して、クエリ拡張フローを有効にするかどうかを判断します。元のフィルタは、クエリ拡張検索で引き続き使用されます。このフィールドは、検索品質を高めるために強く推奨されます。

フィルタ構文の詳細については、SearchRequest.filter をご覧ください。
orderBy

string

ドキュメントが返される順序。ドキュメントは、Document オブジェクトのフィールドで並べ替えることができます。関連性で並べ替える場合は、設定しないままにします。orderBy 式では大文字と小文字が区別されます。

ウェブサイトの検索結果の並べ替えについて詳しくは、ウェブ検索結果を並べ替えるをご覧ください。医療検索結果の並べ替えの詳細については、医療検索結果を並べ替えるをご覧ください。このフィールドが認識できない場合、INVALID_ARGUMENT が返されます。
userInfo

object (UserInfo)

エンドユーザーに関する情報。分析とパーソナライズに強く推奨されます。UserInfo.user_agent は、分析用の deviceType を推測するために使用されます。
languageCode

string

「en-US」や「sr-Latn」などの BCP-47 言語コード。詳細については、標準フィールドをご覧ください。このフィールドは、クエリの解釈を改善するのに役立ちます。値を指定しない場合、クエリ言語コードが自動的に検出されますが、正確でない可能性があります。
facetSpecs[]

object (FacetSpec)

ファセット検索のファセット仕様。空の場合、ファセットは返されません。

最大 100 個の値を指定できます。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
boostSpec

object (BoostSpec)

特定のドキュメントをブーストするブースト仕様。ブーストの詳細については、ブーストをご覧ください。
params

map (key: string, value: value (Value format))

追加の検索パラメータ。

一般公開ウェブサイト検索のみの場合、サポートされる値は次のとおりです。

  • user_country_code: 文字列。デフォルトは空です。空でない値に設定すると、指定された場所に基づいて結果が制限またはブーストされます。例: user_country_code: "au"

利用可能なコードについては、国コードをご覧ください。

  • searchType: double。デフォルトは空です。値に応じて、ウェブページ以外の検索を有効にします。デフォルト以外の有効な値は 1 のみです。この値は画像検索を有効にします。例: searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

クエリ拡張が行われる条件を指定するクエリ拡張仕様。
spellCorrectionSpec

object (SpellCorrectionSpec)

スペル補正が有効になるモードを指定するスペル補正仕様。
userPseudoId

string

訪問者をトラッキングするための一意の識別子。たとえば、これは HTTP Cookie で実装できます。これにより、1 台のデバイス上の訪問者を一意に識別できます。この一意の識別子は、訪問者がウェブサイトに対してログインまたはログアウトしても変更されません。

このフィールドには、unknown_visitor などの固定値は設定しないでください。

これは、UserEvent.user_pseudo_id および CompleteQueryRequest.user_pseudo_id と同じ識別子にする必要があります。

このフィールドは、長さの上限が 128 文字の UTF-8 でエンコードされた文字列にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
contentSearchSpec

object (ContentSearchSpec)

コンテンツ検索の動作を構成するための仕様。
rankingExpression

string

省略可。ランキング式は、取得ドキュメントのカスタマイズされたランキングを制御します。これは ServingConfig.ranking_expression をオーバーライドします。構文とサポートされている機能は、rankingExpressionBackend の値によって異なります。rankingExpressionBackend が指定されていない場合、デフォルトは RANK_BY_EMBEDDING です。

rankingExpressionBackend が指定されていないか、RANK_BY_EMBEDDING に設定されている場合は、単一の関数または「+」で結合された複数の関数にする必要があります。

  • rankingExpression = function, { " + ", function };

サポートされている関数:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

関数変数:

  • relevanceScore: 事前定義されたキーワード。クエリとドキュメントの関連性を測定するために使用されます。
  • embedding_field_path: クエリ エンベディング ベクトルで使用されるドキュメント エンベディング フィールド。
  • dotProduct: embedding_field_path とクエリ エンベディング ベクトルの間のエンベディング関数。

ランキング式の例:

ドキュメントにエンベディング フィールド doc_embedding がある場合、ランキング式は 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding) になります。

rankingExpressionBackend が RANK_BY_FORMULA に設定されている場合、次の式型（および + 演算子または * 演算子を使用して連結されたこれらの型の組み合わせ）がサポートされます。

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0) - 逆数ランク変換。2 番目の引数は分母の定数です。
  • isNan(signal) - シグナルが NaN の場合は 0、それ以外の場合は 1 を返します。
  • fillNan(signal1, signal2 | double) -- signal1 が NaN の場合は signal2 | double を返し、それ以外の場合は signal1 を返します。

サポートされているランキング式の型を使用するランキング数式の例を次に示します。

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- ほとんどの場合、keywordSimilarityScore の対数でランク付けされ、semantic_smilarity_score の調整がわずかに加えられます。
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) -- semanticSimilarityScore の指数でランク付けします。値が NaN の場合は 0 で埋めます。また、semanticSimilarityScore が NaN の場合は、最終スコアに定数 0.3 の調整を加えます。
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16) - ほとんどは keywordSimilarityScore の逆数ランクで、semantic_smilarity_score の逆数ランクがわずかに調整されています。

次のシグナルがサポートされています。

  • semanticSimilarityScore: Google の独自モデルで生成されたエンベディングを使用して計算されるセマンティック類似性の調整。このスコアは、検索クエリとドキュメントの意味的な類似性を決定します。
  • keywordSimilarityScore: キーワード マッチの調整では、Best Match 25（BM25）ランキング関数が使用されます。このスコアは、確率モデルを使用して、ドキュメントが特定のクエリに関連する確率を推定して計算されます。
  • relevanceScore: 独自の Google モデルを使用して、ドキュメント内のコンテンツのコンテキストでユーザーのクエリの意図と意味を判断するセマンティック関連性調整。
  • pctrRank: ランクの使用として予測されるコンバージョン率の調整。予測されるクリック率（pCTR）を使用して、ユーザーの視点から検索結果の関連性と魅力度を測定します。pCTR が高いほど、検索結果がユーザーのクエリと意図を満たす可能性が高く、ランキングの貴重なシグナルとなります。
  • freshnessRank: 鮮度調整をランクとして指定します
  • documentAge: ドキュメントが最後に更新されてからの経過時間（時間単位）。浮動小数点数（例: 0.25 は 15 分を意味します）。
  • topicalityRank: ランクとしてのトピック性調整。Google 所有のモデルを使用して、クエリとドキュメント間のキーワード ベースの重複を判断します。
  • baseRank: 結果のデフォルトのランク
rankingExpressionBackend

enum (RankingExpressionBackend)

省略可。ランキング式の評価に使用するバックエンド。
userLabels

map (key: string, value: string)

リソースに適用するユーザーラベルは、次の要件を満たす必要があります。

  • 1 つのリソースには、最大 64 個のラベルを適用できます。
  • ラベルは、Key-Value ペアでなければなりません。
  • キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
  • キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
  • ラベルのキー部分は一意でなければなりません。ただし、複数のリソースで同じキーを使用できます。
  • キーは、小文字または国際文字で始める必要があります。

詳細については、Google Cloud ドキュメントをご覧ください。
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

省略可。クエリから構造化フィールド フィルタを抽出するなど、自然言語クエリ理解機能の構成。詳しくは、こちらのドキュメントをご覧ください。naturalLanguageQueryUnderstandingSpec が指定されていない場合、自然言語クエリの追加の理解は行われません。
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search の入力逐次検索構成。IndustryVertical.MEDIA 業種でのみサポートされています。
displaySpec

object (DisplaySpec)

省略可。検索結果での一致のハイライト表示などの表示機能の設定。
session

string

セッション リソース名。省略可。

セッションを使用すると、ユーザーは /search API 呼び出しを複数回実行したり、/search API 呼び出しと /answer API 呼び出しを連携させたりできます。

例 1（マルチターン /search API 呼び出し）: 最初の呼び出しで生成されたセッション ID を使用して /search API を呼び出します。ここでは、以前の検索クエリがクエリのスタンディングで考慮されます。たとえば、最初のクエリが「Alphabet の 2022 年の業績はどうでしたか？」の場合、現在のクエリが「2023 年はどうでしたか？」の場合、現在のクエリは「Alphabet の 2023 年の業績はどうでしたか？」と解釈されます。

例 2（/search API 呼び出しと /answer API 呼び出しの連携）: 最初の呼び出しで生成されたセッション ID を使用して /answer API を呼び出します。ここで、回答の生成は最初の検索呼び出しの検索結果のコンテキストで行われます。

Multi-turn servingConfigs.search 機能は現在、限定公開の一般提供段階です。この機能が一般提供（GA）されるまでは、代わりに v1alpha バージョンまたは v1beta バージョンを使用してください。または、Google サポートチームを通じて許可リストへの登録をリクエストしてください。
sessionSpec

object (SessionSpec)

セッションの仕様。

session が設定されている場合にのみ使用できます。
relevanceThreshold

enum (RelevanceThreshold)

検索結果の関連性のしきい値。

Google が定義したしきい値をデフォルトで使用し、精度と再現性のバランスを活かして、関連性の高い情報を網羅的にカバーしつつ、精度の高い結果を提供します。

この機能は医療検索ではサポートされていません。
relevanceScoreSpec

object (RelevanceScoreSpec)

省略可。関連性スコアを返すための仕様。

レスポンスの本文

成功した場合、レスポンスの本文には SearchResponse のインスタンスが含まれます。

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

詳細については、Authentication Overview をご覧ください。