検索品質を評価する

Vertex AI Search の検索機能の一環として、サンプルクエリセットを使用して、汎用検索アプリの検索結果の品質を評価できます。

構造化データ、非構造化データ、ウェブサイトデータを含む汎用検索アプリのパフォーマンスを評価できます。複数のデータストアを使用するアプリのパフォーマンスを評価することはできません。

このページでは、評価方法を使用して検索品質を評価する理由、タイミング、方法について説明します。

概要

このセクションでは、検索品質評価を行う理由とタイミングについて説明します。検索品質評価を行う方法については、検索品質を評価するプロセスをご覧ください。

評価を行う理由

検索品質の評価では、次のようなタスクの実行に役立つ指標が提供されます。

集計レベルで検索エンジンのパフォーマンスを測定する
クエリレベルでパターンを見つけて、ランキングアルゴリズムの潜在的なバイアスや欠点を把握する
過去の評価結果を比較して、検索構成の変更の影響を把握する

指標のリストについては、結果の把握をご覧ください。

評価を実施するタイミング

Vertex AI Search は、検索エクスペリエンスを向上させるために、いくつかの検索構成を拡張しています。検索品質評価は、次の変更を行った後に実施できます。

検索行動は定期的に更新されるため、評価テストを定期的に実行することもできます。

サンプルクエリセットについて

サンプルクエリセットは品質評価に使用されます。サンプルクエリセットは、所定の形式に準拠し、次のネストされたフィールドを持つクエリエントリを含める必要があります。

クエリ: 評価指標の生成と検索品質の決定に使用される検索結果のクエリ。ユーザーの検索パターンと行動を反映した多様なクエリセットを使用することをおすすめします。
ターゲット: サンプルクエリの検索結果として想定されるドキュメントの URI。構造化検索アプリ、非構造化検索アプリ、ウェブサイト検索アプリのドキュメントの定義については、ドキュメントをご覧ください。

ターゲットドキュメントが検索レスポンスで取得されたドキュメントと比較されると、パフォーマンス指標が生成されます。指標は次の 2 つの手法を使用して生成されます。
- ドキュメントの照合: ターゲットドキュメントの URI が、取得されたドキュメントの URI と比較されます。これにより、期待されるドキュメントが検索結果に存在するかどうかが決まります。比較中、評価 API は次の順序で次のフィールドを抽出しようとします。最初に利用可能な値を使用して、ターゲットを取得したドキュメントと照合します。
  - ドキュメント定義の structData フィールドの cdoc_url
  - ドキュメント定義の structData フィールドの uri
  - ドキュメント定義の derivedStructData フィールドの link
  - ドキュメント定義の derivedStructData フィールドの url
- ページマッチング: サンプルターゲットにページ番号を含めると、評価 API はページ単位で結果を比較します。これにより、ターゲットに記載されているページが検索レスポンスでも引用されるかどうかが決まります。ページレベルのマッチングを有効にするには、抽出回答を有効にする必要があります。評価 API は、検索結果の最初の抽出回答のページと照合します。

サンプルクエリセットの目的

特定のデータストアに対するすべての検索品質評価に同じサンプルクエリセットを使用すると、検索品質の結果を一貫して信頼性の高い方法で測定できます。また、公正で再現可能なシステムも確立されます。

各評価の結果は、各サンプルクエリのターゲット結果と比較され、再現率、適合率、正規化された減損累積利得（NDCG）などのさまざまな指標が計算されます。これらの定量指標は、さまざまな検索構成の結果をランク付けするために使用されます。

割り当てと上限

サンプルクエリセットには、次の上限が適用されます。

各サンプルクエリセットに含めることができるクエリは最大 20,000 個です。

サンプルクエリセットには、次の割り当てが適用されます。

プロジェクトごとに最大 100 個のサンプルクエリセット、組織ごとに最大 500 個のサンプルクエリセットを作成できます。

詳細については、割り当てと上限をご覧ください。

サンプルクエリセットの形式

クエリセットを JSON 形式で作成する場合は、次のスキーマに準拠する必要があります。クエリセットには、各クエリエントリに 1 つのクエリを含む複数のクエリエントリを含めることができます。改行区切りの JSON（NDJSON）形式で指定する場合は、各クエリエントリを新しい行に配置する必要があります。

BigQuery と Cloud Storage からインポートする

次のセクションでは、BigQuery と Cloud Storage からインポートするためのサンプルクエリセットのテンプレートを示します。

非構造化データ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、メタデータを含む非構造化データを評価します。

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_1.docx"
      },
      {
        "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_2.pdf",
        "pageNumbers": [
        PAGE_NUMBER_1,
        PAGE_NUMBER_2
        ]
      },
      {
        "uri": "CDOC_URL"
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
PATH/TO/CLOUD/STORAGE/LOCATION: 期待される結果が存在する Cloud Storage のロケーションのパス。これは、ドキュメント定義の derivedStructData フィールド内の link フィールドの値です。
PAGE_NUMBER_1: クエリの想定されるレスポンスが存在する PDF ファイル内のページ番号を示すオプションフィールド。これは、ファイルに複数のページがある場合に便利です。
CDOC_URL: Vertex AI Search データストアスキーマのドキュメントメタデータ内のカスタムドキュメント ID cdoc_url フィールドを示すオプションフィールド。

構造化データ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、BigQuery の構造化データを評価します。

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "CDOC_URL"
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
CDOC_URL: Vertex AI Search データストアスキーマの構造化データフィールド内のカスタム cdoc_url フィールドを示す必須フィールド。

ウェブサイトのデータ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、ウェブサイトのコンテンツを評価します。

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "WEBSITE_URL"
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
WEBSITE_URL: クエリのターゲットウェブサイト。

JSON 形式と NDJSON 形式のサンプルクエリセットの例を次に示します。

JSON

[
  {
    "queryEntry": {
      "query": "2018 Q4 Google revenue",
      "targets": [
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"
        },
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"
        }
      ]
    }
  },
  {
    "queryEntry": {
      "query": "2019 Q4 Google revenue",
      "targets": [
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"
        }
      ]
    }
  }
]

NDJSON

{"queryEntry":{"query":"2018 Q4 Google revenue","targets":[{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"},{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"}]}}
{"queryEntry":{"query":"2019 Q4 Google revenue","targets":[{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"}]}}

ローカルファイルシステムからインポートする

次のセクションでは、ローカルファイルシステムからインポートするためのサンプルクエリセットのテンプレートを示します。

非構造化データ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、メタデータを含む非構造化データを評価します。

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_1.docx"
            },
            {
              "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_2.pdf",
              "pageNumbers": [
                PAGE_NUMBER_1,
                PAGE_NUMBER_2
              ]
            },
            {
              "uri": "CDOC_URL"
            }
          ]
        }
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
PATH/TO/CLOUD/STORAGE/LOCATION: クエリ対象の非構造化データファイルが存在する Cloud Storage のロケーションのパス。これは、ドキュメント定義の derivedStructData フィールド内の link フィールドの値です。
PAGE_NUMBER_1: クエリに必要なレスポンスが PDF ファイル内のどのページにあるかを示すオプションフィールド。これは、ファイルに複数のページがある場合に便利です。
CDOC_URL: Vertex AI Search データストアスキーマのドキュメントメタデータ内のカスタムドキュメント ID cdoc_url フィールドを示すオプションフィールド。

構造化データ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、BigQuery の構造化データを評価します。

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "CDOC_URL"
            }
          ]
        }
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
CDOC_URL: Vertex AI Search データストアスキーマの構造化データフィールド内のカスタム cdoc_url フィールドを示す必須フィールド。

ウェブサイトのデータ

次のテンプレートを使用して、JSON 形式のサンプルクエリファイルを作成し、ウェブサイトのコンテンツを評価します。

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "WEBSITE_URL"
            }
          ]
        }
      }
    ]
  }
}

以下を置き換えます。

SAMPLE_QUERY: 検索品質の評価に使用されるクエリ
WEBSITE_URL: クエリのターゲットウェブサイト。

サンプルクエリセットの例を次に示します。

JSON

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "2018 Q4 Google revenue",
          "targets": [
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"
            },
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"
            }
          ]
        }
      },
      {
        "queryEntry": {
          "query": "2019 Q4 Google revenue",
          "targets": [
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"
            }
          ]
        }
      }
    ]
  }
}

検索品質を評価するプロセス

検索品質評価のプロセスは次のとおりです。

サンプルクエリセットを作成する。
指定された JSON 形式に準拠したサンプルクエリをインポートします。
検索の精度評価を実行する。
結果を把握する。

以降のセクションでは、REST API メソッドを使用してこれらの手順を実行する手順について説明します。

始める前に

次の上限が適用されます。
- 一度に有効にできる評価は、プロジェクトごとに 1 つだけです。
次の割り当てが適用されます。
- 1 プロジェクトあたり 1 日に開始できる評価リクエストは最大 5 件です。詳細については、割り当てと上限をご覧ください。
ページレベルの指標を取得するには、抽出回答を有効にする必要があります。

サンプルクエリセットを作成する

サンプルクエリセットを作成して、特定のデータストアの検索レスポンスの品質を評価できます。サンプルクエリセットを作成するには、次の操作を行います。

REST

次のサンプルは、sampleQuerySets.create メソッドを使用してサンプルクエリセットを作成する方法を示しています。

サンプルクエリセットを作成します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets?sampleQuerySetId=SAMPLE_QUERY_SET_ID" \
    -d '{
  "displayName": "SAMPLE_QUERY_SET_DISPLAY_NAME"
}'

以下を置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID。
SAMPLE_QUERY_SET_ID: サンプルクエリセットのカスタム ID。
SAMPLE_QUERY_SET_DISPLAY_NAME: サンプルクエリセットのカスタム名。

レスポンス

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID",
  "displayName": "SAMPLE_QUERY_SET_DISPLAY_NAME",
  "createTime": "CREATION_DATETIME"
}

サンプルクエリデータをインポートする

サンプルクエリセットを作成したら、サンプルクエリデータをインポートします。サンプルクエリデータをインポートするには、次のいずれかを行います。

Cloud Storage からインポート: Cloud Storage のロケーションから NDJSON ファイルをインポートします。
BigQuery からインポート: BigQuery テーブルから BigQuery データをインポートします。NDJSON ファイルから BigQuery テーブルを作成するには、Cloud Storage からの JSON データの読み込みをご覧ください。
ローカルファイルシステムからインポートする: ローカルファイルシステムにサンプルクエリセットを作成し、インポートします。

Cloud Storage

サンプルクエリセットの形式に準拠するサンプルクエリセットを作成します。
sampleQueries.import メソッドを使用して、サンプルクエリセットを含む JSON ファイルを Cloud Storage のロケーションからインポートします。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
-d '{
  "gcsSource": {
    "inputUris": ["INPUT_FILE_PATH"],
  },
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
```
以下を置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID。
- SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
- INPUT_FILE_PATH: サンプルクエリセットの Cloud Storage ロケーションのパス。
- ERROR_DIRECTORY: インポートエラーが発生したときにエラーファイルがロギングされる Cloud Storage ロケーションのパスを指定するオプションフィールド。Vertex AI Search が一時的なロケーションを自動的に作成できるように、このフィールドを空のままにするか、errorConfig フィールドを削除することをおすすめします。
レスポンス

次のような JSON レスポンスが返されます。OPERATION_ID の値をメモします。この値は、次の手順でこの長時間実行オペレーション（LRO）のステータスをポーリングする際に必要になります。
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

operations.get メソッドを使用して、長時間実行オペレーション（LRO）のステータスを取得します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

レスポンス

次のような JSON レスポンスが返されます。エラーが発生してインポートに失敗した場合、レスポンスの failureCount フィールドに、インポートに失敗したサンプルクエリの数が表示されます。

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_NUMBER_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

BigQuery

サンプルクエリセットの形式に準拠するサンプルクエリセットを作成します。
sampleQueries.import メソッドを使用して、サンプルクエリセットを含む JSON ファイルを BigQuery のロケーションからインポートします。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
-d '{
  "bigquerySource": {
    "projectId": "PROJECT_ID",
    "datasetId":"DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
```
以下を置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID。
- SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
- DATASET_ID: サンプルクエリセットを含む BigQuery データセットの ID。
- TABLE_ID: サンプルクエリセットを含む BigQuery テーブルの ID。
- ERROR_DIRECTORY: インポートエラーが発生したときにエラーファイルがロギングされる Cloud Storage ロケーションのパスを指定するオプションフィールド。Vertex AI Search が一時的なロケーションを自動的に作成できるように、このフィールドを空のままにするか、「errorConfig」フィールドを削除することをおすすめします。
レスポンス

次のような JSON レスポンスが返されます。OPERATION_ID の値をメモします。この値は、次の手順でこの長時間実行オペレーション（LRO）のステータスをポーリングする際に必要になります。
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

operations.get メソッドを使用して、長時間実行オペレーション（LRO）のステータスを取得します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

レスポンス

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_ID_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

ローカルファイルシステム

サンプルクエリセットの形式に準拠するサンプルクエリセットを作成します。
sampleQueries.import メソッドを使用して、サンプルクエリセットを含む JSON ファイルをローカルファイルシステムのロケーションからインポートします。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
--data @PATH/TO/LOCAL/FILE.json
```
以下を置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID。
- SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
- PATH/TO/LOCAL/FILE.json: サンプルクエリセットを含む JSON ファイルのパス。
レスポンス

次のような JSON レスポンスが返されます。OPERATION_ID の値をメモします。この値は、次の手順でこの長時間実行オペレーション（LRO）のステータスをポーリングする際に必要になります。
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

operations.get メソッドを使用して、長時間実行オペレーション（LRO）のステータスを取得します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

レスポンス

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_ID_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

検索品質評価を実行する

サンプルクエリデータをサンプルクエリセットにインポートしたら、次の手順で検索品質評価を実行します。

REST

検索品質の評価を開始します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations" \
-d '{
 "evaluationSpec": {
   "querySetSpec": {
     "sampleQuerySet": "projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
   },
   "searchRequest": {
     "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
   }
 }
}'

以下を置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID。
SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
APP_ID: 検索品質を評価する Vertex AI Search アプリの ID。

レスポンス

次のような JSON レスポンスが返されます。EVALUATION_ID の値をメモします。この値は、長時間実行オペレーション（LRO）である評価のステータスをポーリングする次の手順で必要になります。

{
 "name": "projects/PROJECT_NUMBER/locations/global/operations/OPERATION_ID",
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.Evaluation",
   "name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
   "evaluationSpec": {
     "querySetSpec": {
       "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
     },
     "searchRequest": {
       "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
     }
   },
   "state": "PENDING"
 }
}

評価の進行状況をモニタリングします。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID"

以下を置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID。
EVALUATION_ID: 評価を開始した前の手順で返された評価ジョブの ID。

レスポンス

次のような JSON レスポンスが返されます。評価が完了するまで、評価のステータスは PENDING と表示されます。

{
"name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
"evaluationSpec": {
  "querySetSpec": {
    "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
  },
  "searchRequest": {
    "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
  }
},
"state": "PENDING"
"createTime": "CREATION_DATETIME"
}

集計結果を取得します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID"

以下を置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID。
EVALUATION_ID: 評価を開始した前の手順で返された評価ジョブの ID。

レスポンス

次のような JSON レスポンスが返されます。評価が完了するまで、評価のステータスは PENDING と表示されます。

{
 "name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
 "evaluationSpec": {
   "querySetSpec": {
     "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
   },
   "searchRequest": {
     "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
   }
 },
 "qualityMetrics": {
   "docRecall": {
     "top1": DOC_RECALL_TOP_1,
     "top3": DOC_RECALL_TOP_3,
     "top5": DOC_RECALL_TOP_5,
     "top10": DOC_RECALL_TOP_10
   },
   "docPrecision": {
     "top1": DOC_PRECISION_TOP_1,
     "top3": DOC_PRECISION_TOP_3,
     "top5": DOC_PRECISION_TOP_5,
     "top10": DOC_PRECISION_TOP_10
   },
   "docNdcg": {
     "top1": DOC_NDCG_TOP_1,
     "top3": DOC_NDCG_TOP_3,
     "top5": DOC_NDCG_TOP_5,
     "top10": DOC_NDCG_TOP_10
   },
   "pageRecall": {
     "top1": PAGE_RECALL_TOP_1,
     "top3": PAGE_RECALL_TOP_3,
     "top5": PAGE_RECALL_TOP_5,
     "top10": PAGE_RECALL_TOP_10
   },
   "pageNdcg": {
     "top1": PAGE_NDCG_TOP_1,
     "top3": PAGE_NDCG_TOP_3,
     "top5": PAGE_NDCG_TOP_5,
     "top10": PAGE_NDCG_TOP_10
    }
  },
 "state": "SUCCEEDED",
 "error": {},
 "createTime": "CREATION_DATETIME",
 "endTime": "END_DATETIME"
}

クエリレベルの結果を取得します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID:listResults"

以下を置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID。
EVALUATION_ID: 評価を開始した前の手順で返された評価ジョブの ID。

レスポンス

次のような JSON レスポンスが返されます。評価が完了するまで、評価のステータスは PENDING と表示されます。

{
 "evaluationResults": [
   {
     "sampleQuery": {
       "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries/QUERY_ID_1",
       "queryEntry": {
         "query": "SAMPLE_QUERY_1",
         "targets": [
           {
             "uri": "URI_1"
           }
         ]
       }
     },
     "qualityMetrics": {
       "docRecall": {
         "top1": DOC_RECALL_TOP_1,
         "top3": DOC_RECALL_TOP_3,
         "top5": DOC_RECALL_TOP_5,
         "top10": DOC_RECALL_TOP_10
       },
       "docPrecision": {
         "top1": DOC_PRECISION_TOP_1,
         "top3": DOC_PRECISION_TOP_3,
         "top5": DOC_PRECISION_TOP_5,
         "top10": DOC_PRECISION_TOP_10
       },
       "docNdcg": {
         "top1": DOC_NDCG_TOP_1,
         "top3": DOC_NDCG_TOP_3,
         "top5": DOC_NDCG_TOP_5,
         "top10": DOC_NDCG_TOP_10
       },
       "pageRecall": {
         "top1": PAGE_RECALL_TOP_1,
         "top3": PAGE_RECALL_TOP_3,
         "top5": PAGE_RECALL_TOP_5,
         "top10": PAGE_RECALL_TOP_10
       },
       "pageNdcg": {
         "top1": PAGE_NDCG_TOP_1,
         "top3": PAGE_NDCG_TOP_3,
         "top5": PAGE_NDCG_TOP_5,
         "top10": PAGE_NDCG_TOP_10
        }
      }
   },
   {
     "sampleQuery": {
       "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries/QUERY_ID_2",
       "queryEntry": {
         "query": "SAMPLE_QUERY_2",
         "targets": [
           {
             "uri": "URI_2"
           }
         ]
       }
     },
     "qualityMetrics": {
       "docRecall": {
         "top1": DOC_RECALL_TOP_1,
         "top3": DOC_RECALL_TOP_3,
         "top5": DOC_RECALL_TOP_5,
         "top10": DOC_RECALL_TOP_10
       },
       "docPrecision": {
         "top1": DOC_PRECISION_TOP_1,
         "top3": DOC_PRECISION_TOP_3,
         "top5": DOC_PRECISION_TOP_5,
         "top10": DOC_PRECISION_TOP_10
       },
       "docNdcg": {
         "top1": DOC_NDCG_TOP_1,
         "top3": DOC_NDCG_TOP_3,
         "top5": DOC_NDCG_TOP_5,
         "top10": DOC_NDCG_TOP_10
       },
       "pageRecall": {
         "top1": PAGE_RECALL_TOP_1,
         "top3": PAGE_RECALL_TOP_3,
         "top5": PAGE_RECALL_TOP_5,
         "top10": PAGE_RECALL_TOP_10
       },
       "pageNdcg": {
         "top1": PAGE_NDCG_TOP_1,
         "top3": PAGE_NDCG_TOP_3,
         "top5": PAGE_NDCG_TOP_5,
         "top10": PAGE_NDCG_TOP_10
        }
      }
   }
 ]
}

結果を把握する

次の表に、評価結果で返される指標を示します。

名前	説明	要件
`docRecall`	さまざまな Top-K カットオフレベルにおけるドキュメントあたりの再現率。再現率は、すべての関連ドキュメントのうち、取得された関連ドキュメントの割合です。たとえば、`top5` 値は以下を意味します。 1 つのクエリで、関連するドキュメントのうち 5 件中 3 件が top-5 に取得された場合、`docRecall` は 3/5 または 0.6 と計算されます。	サンプルクエリには URI フィールドを含める必要があります。
`pageRecall`	さまざまな Top-K カットオフレベルでのページあたりの再現率。再現率は、すべての関連ページのうち、取得された関連ページの割合です。たとえば、`top5` 値は以下を意味します。 1 つのクエリで、関連するページのうち 5 件中 3 件が top-5 に取得された場合、`pageRecall` は 3/5 = 0.6 と計算できます。	サンプルクエリには、URI フィールドとページフィールドを含める必要があります。抽出回答が有効になっている必要があります。
`docNdcg`	さまざまな Top-K カットオフレベルにおける、ドキュメントあたりの正規化された減損累積利得（NDCG）。 NDCG はランキングの品質を測定し、上位の結果に高い関連性を与えます。 NDCG 値は、正規化された CDG に従ってクエリごとに計算できます。	サンプルクエリには URI フィールドを含める必要があります。
`pageNdcg`	さまざまな Top-K のカットオフレベルにおける、ページあたりの正規化された減損累積利得（NDCG）。 NDCG はランキングの品質を測定し、上位の結果に高い関連性を与えます。 NDCG 値は、正規化された CDG に従ってクエリごとに計算できます。	サンプルクエリには、URI フィールドとページフィールドを含める必要があります。抽出回答が有効になっている必要があります。
`docPrecision`	さまざまな Top-K カットオフレベルにおけるドキュメントあたりの適合率。適合率は、取得されたドキュメントのうち関連性のあるドキュメントの割合です。たとえば、`top3` 値は以下を意味します。 1 つのクエリで、top-5 の取得ドキュメントのうち 4 件が関連する場合、`docPrecision` 値は 4/5 または 0.8 と計算されます。	サンプルクエリには URI フィールドを含める必要があります。

これらのサポートされている指標の値に基づいて、次のタスクを実行できます。

集計指標を分析します。
- 平均再現率、適合率、正規化された減損累積利得（NDCG）などの全体的な指標を確認します。
- これらの指標は、検索エンジンのパフォーマンスの概要を示します。
クエリレベルの結果を確認します。
- 個々のクエリをドリルダウンして、検索エンジンのパフォーマンスが優れている領域と劣っている領域を特定します。
- 結果のパターンを探して、ランキングアルゴリズムの潜在的なバイアスや欠陥を把握します。
期間ごとの結果を比較します。
- 評価を定期的に実行して、検索品質の変化を時系列で追跡します。
- 過去のデータを使用してトレンドを特定し、検索エンジンに加えた変更の影響を評価します。

次のステップ

Cloud Scheduler を使用して、スケジュール設定された品質評価を設定します。詳細については、HTTP ターゲットの認証を使用するをご覧ください。

検索品質を評価する

概要

評価を行う理由

評価を実施するタイミング

サンプル クエリセットについて

サンプル クエリセットの目的

割り当てと上限

サンプル クエリセットの形式

BigQuery と Cloud Storage からインポートする

非構造化データ

構造化データ

ウェブサイトのデータ

JSON

NDJSON

ローカル ファイル システムからインポートする

非構造化データ

構造化データ

ウェブサイトのデータ

JSON

検索品質を評価するプロセス

始める前に

サンプル クエリセットを作成する

REST

レスポンス

サンプル クエリデータをインポートする

Cloud Storage

レスポンス

レスポンス

BigQuery

レスポンス

レスポンス

ローカル ファイル システム

レスポンス

レスポンス

検索品質評価を実行する

REST

レスポンス

レスポンス

レスポンス

レスポンス

結果を把握する

次のステップ

サンプルクエリセットについて

サンプルクエリセットの目的

サンプルクエリセットの形式

ローカルファイルシステムからインポートする

サンプルクエリセットを作成する

サンプルクエリデータをインポートする

ローカルファイルシステム