検索品質を評価する

Gemini Enterprise の検索機能の一部として、サンプルクエリセットを使用してカスタム検索アプリの検索結果の品質を評価できます。

構造化データと非構造化データを含むカスタム検索アプリのパフォーマンスを評価できます。

複数のデータストアがあるアプリのパフォーマンスを評価することはできません。

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

概要

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

評価を実施する理由

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

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

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

評価の実施時期

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

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

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

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

クエリ: 検索結果が評価指標の生成と検索品質の判定に使用されるクエリ。ユーザーの検索パターンと行動を反映した多様なクエリを使用することをおすすめします。
ターゲット: サンプルクエリの検索結果として想定されるドキュメントの 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: Gemini Enterprise データストアスキーマのドキュメントメタデータ内のカスタムドキュメント ID cdoc_url フィールドを示すオプションフィールド。

構造化データ

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

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

次のように置き換えます。

SAMPLE_QUERY: 検索品質のテスト評価に使用されるクエリ
CDOC_URL: Gemini Enterprise データストアスキーマの構造化データフィールド内のカスタム cdoc_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: Gemini Enterprise データストアスキーマのドキュメントメタデータ内のカスタムドキュメント ID cdoc_url フィールドを示すオプションフィールド。

構造化データ

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

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

次のように置き換えます。

SAMPLE_QUERY: 検索品質のテスト評価に使用されるクエリ
CDOC_URL: Gemini Enterprise データストアスキーマの構造化データフィールド内のカスタム cdoc_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: 実際のプロジェクトの 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: 実際のプロジェクトの ID。
- SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
- INPUT_FILE_PATH: サンプルクエリセットの Cloud Storage ロケーションのパス。
- ERROR_DIRECTORY: インポートエラーが発生したときにエラーファイルがロギングされる Cloud Storage ロケーションのパスを指定するオプションフィールド。Gemini Enterprise が一時的なロケーションを自動的に作成できるように、このフィールドを空のままにするか、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: 実際のプロジェクトの ID。
- SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
- DATASET_ID: サンプルクエリセットを含む BigQuery データセットの ID。
- TABLE_ID: サンプルクエリセットを含む BigQuery テーブルの ID。
- ERROR_DIRECTORY: インポートエラーが発生したときにエラーファイルがロギングされる Cloud Storage ロケーションのパスを指定するオプションフィールド。Gemini Enterprise が一時的なロケーションを自動的に作成できるように、このフィールドを空のままにするか、「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: 実際のプロジェクトの 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: 実際のプロジェクトの ID。
SAMPLE_QUERY_SET_ID: サンプルクエリセットの作成時に定義したサンプルクエリセットのカスタム ID。
APP_ID: 検索品質を評価する Gemini Enterprise アプリの 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: 実際のプロジェクトの 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: 実際のプロジェクトの 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: 実際のプロジェクトの 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

レスポンス

レスポンス

レスポンス

レスポンス

結果を把握する

次のステップ

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

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

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

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

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

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

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