REST Resource: projects.locations.evaluations

リソース: Evaluation

評価とは、評価プロセスの 1 回の実行のことです。評価の状態と結果のデータをカプセル化します。

JSON 表現 
{
  "name": string,
  "evaluationSpec": {
    object (EvaluationSpec)
  },
  "qualityMetrics": {
    object (QualityMetrics)
  },
  "state": enum (State),
  "error": {
    object (Status)
  },
  "createTime": string,
  "endTime": string,
  "errorSamples": [
    {
      object (Status)
    }
  ]
}
フィールド
name

string

ID。Evaluation の完全なリソース名（projects/{project}/locations/{location}/evaluations/{evaluation} 形式）。

このフィールドは、長さの上限が 1,024 文字の UTF-8 でエンコードされた文字列にする必要があります。
evaluationSpec

object (EvaluationSpec)

必須。評価の仕様。
qualityMetrics

object (QualityMetrics)

出力専用。評価によって生成された指標。SampleQuerySet 内のすべての SampleQuery で平均化されます。

評価の状態が SUCCEEDED の場合にのみ入力されます。
state

enum (State)

出力専用。評価の状態。
error

object (Status)

出力専用。評価中に発生したエラー。評価の状態が FAILED の場合にのみ入力されます。
createTime

string (Timestamp format)

出力専用。Evaluation が作成されたタイムスタンプ。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

出力専用。Evaluation が完了したタイムスタンプ。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。
errorSamples[]

object (Status)

出力専用。リクエストの処理中に発生したエラーのサンプル。

EvaluationSpec

評価の仕様を記述します。

JSON 表現 
{
  "querySetSpec": {
    object (QuerySetSpec)
  },

  // Union field search_spec can be only one of the following:
  "searchRequest": {
    object (SearchRequest)
  }
  // End of list of possible types for union field search_spec.
}
フィールド
querySetSpec

object (QuerySetSpec)

省略可。クエリセットの仕様。
共用体フィールド search_spec。検索仕様。search_spec は次のいずれかになります。
searchRequest

object (SearchRequest)

必須。評価の実行に使用される検索リクエスト。

SearchRequest 内の次のフィールドのみがサポートされています。他のフィールドを指定すると、UNSUPPORTED エラーが返されます。

SearchRequest

SearchService.Search メソッドに対するリクエスト メッセージ。

JSON 表現 
{
  "servingConfig": string,
  "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,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "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),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
フィールド
servingConfig

string

必須。検索サービス構成のリソース名（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 など）。このフィールドは、検索に使用されるサービス構成名とモデルのセットを識別するために使用されます。
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 Search でのフィルタリングは、LHS フィルタキーを Vertex AI 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 言語コード。詳細については、標準フィールドをご覧ください。このフィールドは、クエリの解釈を改善するのに役立ちます。値を指定しない場合、クエリ言語コードが自動的に検出されますが、正確でない可能性があります。
regionCode

string

「US」や「419」など、ロケーションの Unicode 国 / リージョン コード（CLDR）。詳細については、標準フィールドをご覧ください。設定されている場合、指定された regionCode に基づいて結果がブーストされます。
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)

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

object (EmbeddingSpec)

指定されたエンベディングを使用して、追加のセマンティック ドキュメント検索を行います。検索は、SearchRequest.EmbeddingSpec.EmbeddingVector.vector と SearchRequest.EmbeddingSpec.EmbeddingVector.field_path で提供されるドキュメント エンベディングの内積に基づいています。

SearchRequest.EmbeddingSpec.EmbeddingVector.field_path が指定されていない場合は、ServingConfig.EmbeddingConfig.field_path が使用されます。
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)

入力逐次検索の設定。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 を呼び出します。ここで、回答の生成は最初の検索呼び出しの検索結果のコンテキストで行われます。

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

object (SessionSpec)

セッションの仕様。

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

enum (RelevanceThreshold)

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

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

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

object (PersonalizationSpec)

パーソナライズの仕様。

ServingConfig.personalization_spec と SearchRequest.personalization_spec の両方が設定されている場合、SearchRequest.personalization_spec は ServingConfig.personalization_spec をオーバーライドします。
relevanceScoreSpec

object (RelevanceScoreSpec)

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

object (SearchAddonSpec)

省略可。SearchAddonSpec は、新しい再価格設定モデルに従って検索のアドオンを無効にするために使用されます。このフィールドは検索リクエストでのみサポートされています。

ImageQuery

画像クエリの入力を指定します。

JSON 表現 
{

  // Union field image can be only one of the following:
  "imageBytes": string
  // End of list of possible types for union field image.
}
フィールド

共用体フィールド image。

image は次のいずれかになります。
imageBytes

string

Base64 でエンコードされた画像バイト。サポートされている画像形式: JPEG、PNG、BMP。

DataStoreSpec

検索呼び出しでフィルタするデータストアと、それらのデータストアの構成を定義する構造体。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

JSON 表現 
{
  "dataStore": string,
  "filter": string,
  "boostSpec": {
    object (BoostSpec)
  },
  "customSearchOperators": string
}
フィールド
dataStore

string

必須。DataStore の完全なリソース名（projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId} など）。パスにはプロジェクト番号を含める必要があります。このフィールドではプロジェクト ID はサポートされていません。
filter

string

省略可。dataStore フィールドで指定されたデータストア内のドキュメントをフィルタするフィルタ仕様。フィルタリングの詳細については、フィルタリングをご覧ください。
boostSpec

object (BoostSpec)

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

string

省略可。カスタム検索演算子。指定すると、ワークスペース データストアの結果をフィルタするために使用されます。カスタム検索演算子の詳細については、SearchOperators をご覧ください。

BoostSpec

特定のドキュメントをブーストするブースト仕様。

JSON 表現 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
フィールド
conditionBoostSpecs[]

object (ConditionBoostSpec)

条件ブーストの仕様。ドキュメントが仕様の複数の条件に一致する場合、これらの仕様のブースト スコアはすべて適用され、非線形に結合されます。仕様の最大数は 20 です。

ConditionBoostSpec

ブーストは、条件に一致するドキュメントに適用されます。

JSON 表現 
{
  "condition": string,
  "boost": number,
  "boostControlSpec": {
    object (BoostControlSpec)
  }
}
フィールド
condition

string

ブースト条件を指定する式。構文とサポートされているフィールドは、フィルタ式と同じです。構文と制限事項の詳細については、SearchRequest.filter をご覧ください。

例:

  • ドキュメント ID が「doc_1」または「doc_2」で、色が「赤」または「青」のドキュメントをブーストするには: (documentId: ANY("doc_1", "doc_2")) AND (color: ANY("Red", "Blue"))
boost

number

条件ブーストの強度。[-1, 1] の範囲で指定します。ブーストが負の値である場合は順位を下げることを意味します。デフォルトは 0.0 です。

1.0 に設定すると、ドキュメントに強力なプロモーションが設定されます。ただし、ブーストされたドキュメントが常に上位の検索結果に表示されるわけではなく、他のドキュメントが除外されるとも限りません。条件に一致する結果がなくても、引き続き結果が表示されることがあります。また、検索クエリとの関連性が大幅に高い検索結果は、強くブーストされていても無関係なドキュメントより、上位にランクされることがあります。

-1.0 に設定すると、ドキュメントの降格が大きくなります。ただし、深く関連している結果が引き続き表示されることがあります。このドキュメントは上位にランクインするために上位のドキュメントと競合しますが、完全にブロックされることはありません。

0.0 に設定すると、ブーストは適用されません。ブースト条件は無視されます。（条件、ブースト）の組み合わせまたは以下の boostControlSpec のいずれか 1 つのみが設定されます。両方が設定されている場合、グローバル ブーストは無視され、よりきめ細かい boostControlSpec が適用されます。
boostControlSpec

object (BoostControlSpec)

顧客定義の属性値に基づくカスタム ランキングの複雑な仕様。

BoostControlSpec

顧客が指定した属性値に基づくカスタム ランキングの仕様。上記の単純な（条件、ブースト）の組み合わせよりも、カスタマイズされたランキングをより細かく制御できます。

JSON 表現 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
フィールド
fieldName

string

ブースト量を決定するために値が使用されるフィールドの名前。
attributeType

enum (AttributeType)

ブースト額の決定に使用する属性のタイプ。属性値は、指定された fieldName のフィールド値から導出できます。数値の場合、attributeValue = numerical_field_value となります。ただし、鮮度の場合は、attributeValue = (time.now() - datetime_field_value) となります。
interpolationType

enum (InterpolationType)

以下にリストされているコントロール ポイントを接続するために適用される補間タイプ。
controlPoints[]

object (ControlPoint)

曲線の定義に使用されるコントロール ポイント。単調関数（上記の interpolationType で定義）は、ここに記載されている制御点を通過します。

AttributeType

カスタム ランキングを適用する属性（または関数）。

列挙型
ATTRIBUTE_TYPE_UNSPECIFIED AttributeType が指定されていません。
NUMERICAL 数値フィールドの値は、ブースト額を動的に更新するために使用されます。この場合、コントロール ポイントの attributeValue（x 値）は、boostAmount が指定されている数値フィールドの実際の値になります。
FRESHNESS 鮮度のユースケースでは、属性値は現在時刻と指定された datetime フィールドの日付の間の期間になります。値は、XSD dayTimeDuration 値（ISO 8601 期間値の制限付きサブセット）としてフォーマットする必要があります。このパターンは [nD][T[nH][nM][nS]] です。たとえば、5D、3DT12H30M、T24H。

InterpolationType

適用する補間タイプ。デフォルトは線形（区分線形）です。

列挙型
INTERPOLATION_TYPE_UNSPECIFIED 補間タイプが指定されていません。この場合、デフォルトは Linear になります。
LINEAR 区分線形補間が適用されます。

ControlPoint

曲線の定義に使用されるコントロール ポイント。これらの制御点を通過する曲線は、単調に増加または減少する（定数値は許容される）必要があります。

JSON 表現 
{
  "attributeValue": string,
  "boostAmount": number
}
フィールド
attributeValue

string

次のいずれかになります。1. 数値フィールドの値。2. 鮮度の期間仕様: 値は XSD dayTimeDuration 値（ISO 8601 期間値の制限付きサブセット）としてフォーマットする必要があります。このパターンは [nD][T[nH][nM][nS]] です。
boostAmount

number

attributeValue が上記で指定した値と評価された場合にスコアをブーストする値（-1 ～ 1）。

FacetSpec

ファセット検索を実行するファセットの仕様。

JSON 表現 
{
  "facetKey": {
    object (FacetKey)
  },
  "limit": integer,
  "excludedFilterKeys": [
    string
  ],
  "enableDynamicPosition": boolean
}
フィールド
facetKey

object (FacetKey)

必須。ファセット キーの仕様。
limit

integer

このファセットに対して返されるファセット値の最大数。指定しない場合、デフォルトは 20 です。最大値は 300 です。300 を超える値は 300 に強制変換されます。医療検索の集計では、[FacetKey.key] が「healthcare_aggregation_key」の場合、ここで設定された値に関係なく、上限は内部的に 10,000 にオーバーライドされます。

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

string

ファセット処理時に除外するキーのリスト。

デフォルトでは、このフィールドにリストされていない限り、FacetKey.key はフィルタから除外されません。

このフィールドにファセットキーを登録すると、検索結果から除外された場合でも、その値がファセット結果として表示されます。このフィールドを使用しても、返される検索結果には影響しません。

たとえば、色のファセット「赤」を含むドキュメントが 100 個、色のファセット「青」を含むドキュメントが 200 個あるとします。フィルタ「color:ANY("Red")」を含み、FacetKey.key として「color」を持つクエリは、デフォルトで検索結果に「Red」ドキュメントのみを返し、カウント 100 の「Red」を唯一のカラー ファセットとして返します。青いドキュメントも利用可能ですが、「青」は利用可能なファセット値として表示されません。

「color」が「excludedFilterKeys」にリストされている場合、クエリはファセット値「Red」（カウント 100）と「Blue」（カウント 200）を返します。これは、「color」キーがフィルタから除外されたためです。このフィールドは検索結果に影響しないため、検索結果は引き続き正しくフィルタリングされ、「赤」のドキュメントのみが返されます。

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

boolean

このファセットの動的位置を有効にします。true に設定すると、レスポンス内のすべてのファセットにおけるこのファセットの位置が自動的に決定されます。動的ファセットが有効になっている場合は、一緒に並べ替えられます。false に設定すると、レスポンスでのこのファセットの位置はリクエストでの位置と同じになり、動的ポジションが有効になっているファセットとすべての動的ファセットの前にランク付けされます。

たとえば、レスポンスで常に評価ファセットを返すようにしたいが、評価ファセットを常に上部に表示する必要はない場合があります。その場合は、enableDynamicPosition を true に設定して、レスポンス内の評価ファセットの位置を自動的に決定できます。

別の例として、リクエストに次のファセットがあるとします。

  • "rating", enableDynamicPosition = true

  • "price"、enableDynamicPosition = false

  • 「brands」、enableDynamicPosition = false

また、動的ファセットが有効になっているため、ファセット gender が生成されます。レスポンス内のファセットの最終的な順序は、API が「性別」と「評価」のファセットをどのように順序付けるかによって、（「価格」、「ブランド」、「評価」、「性別」）または（「価格」、「ブランド」、「性別」、「評価」）になります。ただし、「price」と「brands」は enableDynamicPosition が false であるため、常に 1 位と 2 位にランク付けされます。

FacetKey

ファセットの計算方法を指定します。

JSON 表現 
{
  "key": string,
  "intervals": [
    {
      object (Interval)
    }
  ],
  "restrictedValues": [
    string
  ],
  "prefixes": [
    string
  ],
  "contains": [
    string
  ],
  "caseInsensitive": boolean,
  "orderBy": string
}
フィールド
key

string

必須。Document オブジェクトでサポートされているテキストと数値のファセットキー。ファセット値が計算されます。ファセットキーでは大文字と小文字が区別されます。
intervals[]

object (Interval)

値を区間に分類する場合にのみ設定します。数値を含むファセットに設定する必要があります。テキスト値を含むファセットには設定できません。インターバルの最大数は 30 です。
restrictedValues[]

string

指定された制限付きの値のファセットのみを取得します。テキスト フィールドでのみサポートされます。たとえば、「category」に「Action > 2022」、「Action > 2021」、「Sci-Fi > 2022」の 3 つの値があるとします。「restrictedValues」を「Action > 2022」に設定すると、「category」ファセットには「Action > 2022」のみが含まれます。テキスト フィールドでのみサポートされます。最大値は 10 です。
prefixes[]

string

指定された文字列プレフィックスで始まるファセット値のみを取得します。たとえば、「category」に「Action > 2022」、「Action > 2021」、「Sci-Fi > 2022」の 3 つの値があるとします。「prefixes」を「Action」に設定すると、「category」ファセットには「Action > 2022」と「Action > 2021」のみが含まれます。テキスト フィールドでのみサポートされます。最大値は 10 です。
contains[]

string

指定された文字列を含むファセット値のみを取得します。たとえば、「category」に「Action > 2022」、「Action > 2021」、「Sci-Fi > 2022」の 3 つの値があるとします。「contains」を「2022」に設定すると、「category」ファセットには「Action > 2022」と「Sci-Fi > 2022」のみが含まれます。テキスト フィールドでのみサポートされます。最大値は 10 です。
caseInsensitive

boolean

接頭辞または contains を使用してファセット値を取得するときに、ファセットキーを大文字と小文字を区別しないようにする場合は true。それ以外の場合は false。
orderBy

string

ドキュメントが返される順序。

指定できる値は次のとおりです。

設定されていない場合、テキスト値は自然順序で並べ替えられ、数値間隔は FacetSpec.FacetKey.intervals で指定された順序で並べ替えられます。

間隔

浮動小数点間隔。

JSON 表現 
{

  // Union field min can be only one of the following:
  "minimum": number,
  "exclusiveMinimum": number
  // End of list of possible types for union field min.

  // Union field max can be only one of the following:
  "maximum": number,
  "exclusiveMaximum": number
  // End of list of possible types for union field max.
}
Fields

共用体フィールド min。区間の下限。最小フィールドのいずれも設定されていない場合、下限は負の無限大になります。

このフィールドは最大値以下にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。min は次のいずれかになります。
minimum

number

境界値を含む下限。
exclusiveMinimum

number

境界値を含まない下限。

共用体フィールド max。間隔の上限。max フィールドがどちらも設定されていない場合、上限は正の無限大になります。

このフィールドは min 以上である必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。max は次のいずれかになります。
maximum

number

境界値を含む上限。
exclusiveMaximum

number

境界値を含まない上限。

QueryExpansionSpec

クエリ拡張を行う条件を決定する仕様。

JSON 表現 
{
  "condition": enum (Condition),
  "pinUnexpandedResults": boolean
}
フィールド
condition

enum (Condition)

クエリ拡張を行う条件。デフォルトは Condition.DISABLED です。
pinUnexpandedResults

boolean

展開されていない結果を固定するかどうか。このフィールドが true に設定されている場合、拡張されていない商品は常に検索結果の先頭に表示され、その後に拡張された結果が表示されます。

条件

クエリ拡張を行う条件を説明する列挙型。

列挙型
CONDITION_UNSPECIFIED クエリ拡張条件が指定されていません。この場合、サーバーの動作はデフォルトで Condition.DISABLED になります。
DISABLED クエリ拡張が無効になっています。SearchResponse.total_size がゼロの場合でも、完全一致の検索クエリのみが使用されます。
AUTO Search API によって構築された自動クエリ拡張。

SpellCorrectionSpec

クエリのスペル修正の仕様。

JSON 表現 
{
  "mode": enum (Mode)
}
フィールド
mode

enum (Mode)

スペル修正によって元の検索クエリが置き換えられるモード。デフォルトは Mode.AUTO です。

モード

スペル修正を行うモードを記述する列挙型。

列挙型
MODE_UNSPECIFIED スペル修正モードが指定されていません。この場合、サーバーの動作はデフォルトで Mode.AUTO になります。
SUGGESTION_ONLY Search API はスペル候補を探します。候補が見つかった場合は、SearchResponse.corrected_query に入れられます。スペル候補は検索クエリとして使用されません。
AUTO Search API によって構築された自動スペル修正。修正されたクエリが見つかった場合、検索は修正されたクエリに基づいて行われます。

EmbeddingSpec

カスタマイズされたクエリ エンベディング ベクトルを使用してセマンティック ドキュメント取得を行う仕様。

JSON 表現 
{
  "embeddingVectors": [
    {
      object (EmbeddingVector)
    }
  ]
}
フィールド
embeddingVectors[]

object (EmbeddingVector)

取得に使用されるエンベディング ベクトル。1 に制限します。

EmbeddingVector

エンベディング ベクトル。

JSON 表現 
{
  "fieldPath": string,
  "vector": [
    number
  ]
}
フィールド
fieldPath

string

スキーマ内のエンベディング フィールドのパス。
vector[]

number

クエリ エンベディング ベクトル。

RankingExpressionBackend

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

列挙型
RANKING_EXPRESSION_BACKEND_UNSPECIFIED 未指定または不明な値のデフォルト オプション。
BYOE

非推奨: 代わりに、RANK_BY_EMBEDDING を使用してください。カスタム エンベディング モデルによるランキング。ランキング式を評価するデフォルトの方法です。以前の列挙型オプション。代わりに RANK_BY_EMBEDDING を使用してください。
CLEARBOX

非推奨: 代わりに、RANK_BY_FORMULA を使用してください。カスタム数式によるランキング。以前の列挙型オプション。代わりに RANK_BY_FORMULA を使用してください。
RANK_BY_EMBEDDING カスタム エンベディング モデルによるランキング。ランキング式を評価するデフォルトの方法。
RANK_BY_FORMULA カスタム数式によるランキング。

NaturalLanguageQueryUnderstandingSpec

検索リクエストの自然言語理解機能を有効にするための仕様。

JSON 表現 
{
  "filterExtractionCondition": enum (FilterExtractionCondition),
  "geoSearchQueryDetectionFieldNames": [
    string
  ],
  "extractedFilterBehavior": enum (ExtractedFilterBehavior),
  "allowedFieldNames": [
    string
  ]
}
フィールド
filterExtractionCondition

enum (FilterExtractionCondition)

フィルタ抽出を行う条件。サーバーの動作はデフォルトで DISABLED に設定されます。
geoSearchQueryDetectionFieldNames[]

string

位置情報に基づくフィルタリングに使用されるフィールド名。自然言語検索クエリで位置情報フィルタが検出された場合に使用されます。FilterExtractionCondition が ENABLED に設定されている場合にのみ有効です。

このフィールドが設定されている場合、ServingConfig.geo_search_query_detection_field_names で設定されているフィールド名がオーバーライドされます。
extractedFilterBehavior

enum (ExtractedFilterBehavior)

省略可。抽出されたフィルタが検索に適用される動作を制御します。デフォルトの動作はリクエストによって異なります。単一データストアの構造化検索の場合、デフォルトは HARD_FILTER です。マルチデータストア検索の場合、デフォルトの動作は SOFT_BOOST です。位置情報に基づくフィルタは常にハードフィルタとして適用され、SOFT_BOOST 設定は影響しません。このフィールドは、[SearchRequest.natural_language_query_understanding_spec.filter_extraction_condition][] が FilterExtractionCondition.ENABLED に設定されている場合にのみ使用されます。
allowedFieldNames[]

string

省略可。自然言語フィルタの抽出に使用できるフィールドの許可リスト。デフォルトでは、この設定が指定されていない場合、インデックス登録可能なすべてのフィールドが自然言語フィルタの抽出対象になります（ただし、必ず使用されるとは限りません）。allowedFieldNames でフィールドが指定されている場合、スキーマでインデックス可能としてマークされ、許可リストで指定されているフィールドのみが自然言語フィルタの抽出の対象となります。注: マルチデータストア検索では、これはまだサポートされておらず、無視されます。

FilterExtractionCondition

フィルタの抽出を行う条件を説明する列挙型。

列挙型
CONDITION_UNSPECIFIED サーバーの動作はデフォルトで DISABLED に設定されます。
DISABLED NL フィルタの抽出を無効にします。
ENABLED NL フィルタの抽出を有効にします。

ExtractedFilterBehavior

抽出されたフィルタが検索にどのように適用されるかを記述する列挙型。

列挙型
EXTRACTED_FILTER_BEHAVIOR_UNSPECIFIED EXTRACTED_FILTER_BEHAVIOR_UNSPECIFIED は、抽出されたフィルタのデフォルトの動作を使用します。単一データストア検索の場合、デフォルトではハードフィルタとして適用されます。マルチ データストア検索の場合、デフォルトではソフトブーストとして適用されます。
HARD_FILTER 抽出されたすべてのフィルタを結果にハードフィルタとして適用します。抽出されたフィルタを通過しない結果は、結果セットで返されません。
SOFT_BOOST 抽出されたすべてのフィルタをソフトブーストとして適用します。フィルタを通過した結果は、結果セットの上位にブーストされます。

SearchAsYouTypeSpec

検索リクエストでの入力中の検索の仕様。

JSON 表現 
{
  "condition": enum (Condition)
}
フィールド
condition

enum (Condition)

入力中の検索が行われる条件。デフォルトは Condition.DISABLED です。

条件

入力中の検索が実行される条件を記述する列挙型。

列挙型
CONDITION_UNSPECIFIED サーバーの動作はデフォルトで Condition.DISABLED に設定されます。
DISABLED 入力逐次検索を無効にします。
ENABLED 入力逐次検索を有効にします。
AUTO 入力逐次検索モードと標準検索モードを自動的に切り替えるため、単一 API 実装（デバウンスなど）に最適です。

DisplaySpec

一致のハイライト表示など、表示する機能を指定します。

JSON 表現 
{
  "matchHighlightingCondition": enum (MatchHighlightingCondition)
}
フィールド
matchHighlightingCondition

enum (MatchHighlightingCondition)

一致するハイライト表示を行う条件。

MatchHighlightingCondition

一致のハイライト表示を行う条件を記述する列挙型。

列挙型
MATCH_HIGHLIGHTING_CONDITION_UNSPECIFIED サーバーの動作は MATCH_HIGHLIGHTING_DISABLED と同じです。
MATCH_HIGHLIGHTING_DISABLED すべてのドキュメントで一致する部分のハイライト表示を無効にします。
MATCH_HIGHLIGHTING_ENABLED すべてのドキュメントで一致する部分のハイライト表示を有効にします。

SessionSpec

セッションの仕様。

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

JSON 表現 
{
  "queryId": string,
  "searchResultPersistenceCount": integer
}
フィールド
queryId

string

設定されている場合、検索結果はこのクエリ ID で指定された「ターン」に保存されます。

例: セッションが次のようになっているとします。session { name: ".../sessions/xxx" turns { query { text: "What is foo?" queryId: ".../questions/yyy" } answer: "Foo is ..." } turns { query { text: "How about bar then?" queryId: ".../questions/zzz" } } }

ユーザーは、次のようなリクエストで /search API を呼び出すことができます。

session: ".../sessions/xxx" sessionSpec { queryId: ".../questions/zzz" }

API は、最後のターンに関連付けられた検索結果を保存します。保存された検索結果は、後続の /answer API 呼び出し（セッション ID とクエリ ID を指定）で使用できます。また、同じセッション ID とクエリ ID を使用して /search と /answer を並行して呼び出すこともできます。
searchResultPersistenceCount

integer

保持する上位の検索結果の数。永続化された検索結果は、後続の /answer API 呼び出しに使用できます。

このフィールドは、SearchRequest.ContentSearchSpec.SummarySpec.summary_result_count の summaryResultCount フィールドに似ています。

ドキュメント モードの場合は最大 10 件、チャンク モードの場合は最大 50 件の結果。

RelevanceThreshold

検索結果の関連性のしきい値。関連性のしきい値が高いほど、関連性の高い結果が表示され、返される結果の数が少なくなります。

列挙型
RELEVANCE_THRESHOLD_UNSPECIFIED デフォルト値。この場合、サーバーの動作はデフォルトで Google が定義したしきい値になります。
LOWEST 関連性のしきい値が最も低い。
LOW 関連性のしきい値が低い。
MEDIUM 関連性のしきい値（中）。
HIGH 関連性のしきい値が高い。

RelevanceScoreSpec

ドキュメントの関連性スコアを返すための仕様。

JSON 表現 
{
  "returnRelevanceScore": boolean
}
フィールド
returnRelevanceScore

boolean

省略可。検索結果の関連性スコアを返すかどうか。スコアが高いほど、ドキュメントがクエリに関連していることを示します。

SearchAddonSpec

SearchAddonSpec は、新しい再価格設定モデルに従って検索のアドオンを無効にするために使用されます。SearchAddonSpec が指定されていない場合、デフォルトでは、お客様が適用可能な場所で有効にしたいと考えていると見なされます。

JSON 表現 
{
  "disableSemanticAddOn": boolean,
  "disableKpiPersonalizationAddOn": boolean,
  "disableGenerativeAnswerAddOn": boolean
}
フィールド
disableSemanticAddOn

boolean

省略可。true の場合、セマンティック アドオンは無効になります。セマンティック アドオンには、エンベディングと jetstream が含まれます。
disableKpiPersonalizationAddOn

boolean

省略可。true の場合、イベントの再ランキングとパーソナライズを無効にして、KPI を最適化し、結果をパーソナライズします。
disableGenerativeAnswerAddOn

boolean

省略可。true の場合、生成回答アドオンは無効になります。生成回答アドオンには、自然言語からフィルタへの変換とシンプルな回答が含まれています。

QuerySetSpec

クエリセットの仕様を記述します。

JSON 表現 
{
  "sampleQuerySet": string
}
フィールド
sampleQuerySet

string

省略可。評価に使用される SampleQuerySet の完全なリソース名（projects/{project}/locations/{location}/sampleQuerySets/{sampleQuerySet} 形式）。

QualityMetrics

評価によって生成された指標について説明します。

JSON 表現 
{
  "docRecall": {
    object (TopkMetrics)
  },
  "docPrecision": {
    object (TopkMetrics)
  },
  "docNdcg": {
    object (TopkMetrics)
  },
  "pageRecall": {
    object (TopkMetrics)
  },
  "pageNdcg": {
    object (TopkMetrics)
  }
}
フィールド
docRecall

object (TopkMetrics)

さまざまな Top-K カットオフ レベルにおけるドキュメントあたりの再現率。

再現率は、すべての関連ドキュメントのうち、取得された関連ドキュメントの割合です。

例（上位 5 件）: * 1 つの SampleQuery で、関連するドキュメントのうち 5 件中 3 件が上位 5 件に取得された場合、recall@5 = 3/5 = 0.6
docPrecision

object (TopkMetrics)

さまざまな Top-K カットオフ レベルにおけるドキュメントあたりの適合率。

適合率は、取得されたドキュメントのうち関連性のあるドキュメントの割合です。

例（上位 5 件）: * 単一の SampleQuery の場合、上位 5 件の取得ドキュメントのうち 4 件が関連する場合、precision@5 = 4/5 = 0.8
docNdcg

object (TopkMetrics)

さまざまな Top-K カットオフ レベルにおける、ドキュメントあたりの正規化された減損累積利得（NDCG）。

NDCG はランキングの品質を測定し、上位の結果に高い関連性を与えます。

例（上位 3 件）: 3 つの取得ドキュメント（D1、D2、D3）と、関連性のバイナリ判定（関連性ありの場合は 1、関連性なしの場合は 0）を含む SampleQuery を想定します。

取得: [D3 (0)、D1 (1)、D2 (1)] 理想: [D1 (1)、D2 (1)、D3 (0)]

各 SampleQuery の NDCG@3 を計算します。* DCG@3: 0/log2(1+1) + 1/log2(2+1) + 1/log2(3+1) = 1.13 * 理想的な DCG@3: 1/log2(1+1) + 1/log2(2+1) + 0/log2(3+1) = 1.63 * NDCG@3: 1.13/1.63 = 0.693
pageRecall

object (TopkMetrics)

さまざまな Top-K カットオフ レベルでのページあたりの再現率。

再現率は、すべての関連ページのうち、取得された関連ページの割合です。

例（上位 5 件）: * 1 つの SampleQuery で、関連するページのうち 5 件中 3 件が上位 5 件に取得された場合、recall@5 = 3/5 = 0.6
pageNdcg

object (TopkMetrics)

さまざまな Top-K のカットオフ レベルにおける、ページあたりの正規化された減損累積利得（NDCG）。

NDCG はランキングの品質を測定し、上位の結果に高い関連性を与えます。

例（上位 3 件）: 3 つの取得済みページ（P1、P2、P3）とバイナリ関連性判定（関連性ありの場合は 1、関連性なしの場合は 0）を含む SampleQuery を想定します。

取得済み: [P3（0）、P1（1）、P2（1）] 理想: [P1（1）、P2（1）、P3（0）]

SampleQuery の NDCG@3 を計算します。 * DCG@3: 0/log2(1+1) + 1/log2(2+1) + 1/log2(3+1) = 1.13 * 理想的な DCG@3: 1/log2(1+1) + 1/log2(2+1) + 0/log2(3+1) = 1.63 * NDCG@3: 1.13/1.63 = 0.693

TopkMetrics

特定のトップ k レベルで指標値を保存します。

JSON 表現 
{
  "top1": number,
  "top3": number,
  "top5": number,
  "top10": number
}
フィールド
top1

number

上位 1 つの値。
top3

number

上位 3 つの値。
top5

number

上位 5 つの値。
top10

number

上位 10 個の値。

状態

評価の状態を表します。

列挙型
STATE_UNSPECIFIED 評価が指定されていません。
PENDING サービスは評価を実行する準備をしています。
RUNNING 評価が進行中です。
SUCCEEDED 評価は正常に完了しました。
FAILED 評価に失敗しました。

メソッド

create

 Evaluation を作成します。

get

 Evaluation を取得します。

list

 Evaluation のリストを取得します。

listResults

 指定された Evaluation の結果のリストを取得します。