本頁面由 Cloud Translation API 翻譯而成。

評估搜尋品質

在 Vertex AI Search 的搜尋體驗中，您可以使用範例查詢集來評估自訂搜尋應用程式的搜尋結果品質。

您可以評估包含結構化、非結構化和網站資料的自訂搜尋應用程式成效。您無法評估使用多個資料儲存庫的應用程式成效。

本頁面說明使用評估方法評估搜尋品質的原因、時機和方式。

總覽

本節說明執行搜尋品質評估的原因和時機。如要進一步瞭解如何執行搜尋品質評估，請參閱評估搜尋品質的程序。

評估的原因

搜尋品質評估會提供指標，協助您執行下列任務：

在匯總層級評估搜尋引擎的成效
在查詢層級找出模式，瞭解排名演算法可能存在的偏差或缺點
比較歷來評估結果，瞭解搜尋設定變更的影響

如需指標清單，請參閱「解讀結果」。

評估時機

Vertex AI Search 擴充了多項搜尋設定，可提升搜尋體驗。完成下列變更後，即可進行搜尋品質評估：

搜尋行為會定期更新，因此您也可以定期執行評估測試。

關於範例查詢集

樣本查詢集合會用於品質評估。樣本查詢集合必須遵循規定的格式，且必須包含具有下列巢狀欄位的查詢項目：

查詢：系統會使用查詢的搜尋結果產生評估指標，並判斷搜尋品質。Google 建議您使用多種不同的查詢，反映使用者的搜尋模式和行為。
目標：預期會成為範例查詢搜尋結果的文件 URI。如要瞭解結構化、非結構化和網站搜尋應用程式中的文件定義，請參閱「文件」。

當目標文件與搜尋回應中擷取的文件進行比較時，系統會產生效能指標。系統會使用以下兩種技術產生指標：
- 文件比對：將目標文件的 URI 與擷取文件的 URI 進行比對。這會決定搜尋結果中是否包含預期的文件。在比較期間，評估 API 會嘗試按照以下順序擷取下列欄位，並使用第一個可用的值，將目標與擷取的文件進行比對：
  - 文件定義的 structData 欄位中的 cdoc_url
  - 文件定義的 structData 欄位中的 uri
  - 文件定義的 derivedStructData 欄位中的 link
  - 文件定義的 derivedStructData 欄位中的 url
- 網頁比對：如果您在樣本目標中加入網頁編號，評估 API 會在網頁層級比較結果。這項設定會決定目標中提及的網頁是否會在搜尋回應中引用。您必須啟用擷取式答案，才能啟用網頁層級比對功能。評估 API 會比對搜尋結果中第一個擷取式答案的網頁。

範例查詢集的用途

針對特定資料儲存庫的所有搜尋品質評估，使用相同的查詢樣本集，可確保以一致且可靠的方式評估搜尋品質結果。這也能建立公平且可重複執行的系統。

系統會將每項評估的結果與每個樣本查詢的目標結果進行比較，以便計算不同的指標，例如回溯率、精確率和標準化折扣累積增益 (NDCG)。這些量化指標可用來為不同搜尋設定的結果進行排名。

配額與限制

以下限制適用於範例查詢集：

每個範例查詢集最多可包含 20,000 個查詢。

以下配額適用於範例查詢集：

每個專案最多可建立 100 個範例查詢集，每個機構最多可建立 500 個範例查詢集。

詳情請參閱「配額與限制」。

查詢集格式範例

以 JSON 格式建構時，查詢集必須符合下列結構定義。查詢集合可包含多個查詢項目，每個查詢項目中含有一項查詢。以換行符號分隔的 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 方法執行這些步驟。

事前準備

適用下列限制：
- 每個專案只能在特定時間內進行一次評估。
適用下列配額：
- 每個專案每天最多可提出五項評估要求。詳情請參閱「配額與限制」。
如要取得網頁層級指標，您必須啟用摘要答案。

建立範例查詢集

您可以建立查詢範例集，用於評估特定資料儲存庫的搜尋回應品質。如要建立範例查詢集，請按照下列步驟操作。

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 方法，從 Cloud Storage 位置匯入含有範例查詢集的 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" \
-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 位置的路徑，以便在發生匯入錯誤時記錄錯誤檔案。Google 建議您將這個欄位留空或移除 errorConfig 欄位，以便 Vertex AI Search 自動建立暫時位置。
回應

您應該會收到類似以下的 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 方法，從 BigQuery 位置匯入含有範例查詢集的 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" \
-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 位置的路徑，以便在發生匯入錯誤時記錄錯誤檔案。Google 建議您將這個欄位留空或移除 `errorConfig` 欄位，讓 Vertex AI Search 自動建立暫時位置。
回應

您應該會收到類似以下的 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_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"

回應

您應該會收到類似以下的 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_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`	在各種前幾名截止值下，每份文件的回傳率。喚回率是指從所有相關文件中擷取相關文件的比例。例如，`top5` 值表示以下內容：對於單一查詢，如果前 5 筆結果中有 3 筆相關文件，`docRecall` 的計算值為 3/5 或 0.6。	範例查詢必須包含 URI 欄位。
`pageRecall`	在各種前 k 個截止值水準下，每個網頁的回憶率。喚回率是指從所有相關網頁中擷取的相關網頁比例。例如，`top5` 值表示以下內容：對於單一查詢，如果前 5 個結果中，有 3 個相關網頁，`pageRecall` 的計算方式為 3/5 = 0.6	範例查詢必須包含 URI 和 pages 欄位。必須啟用擷取答案功能。
`docNdcg`	在各種前 k 個截止值層級，每份文件的正規化折減累計增益 (NDCG)。 NDCG 會評估排名品質，讓前幾項搜尋結果的關聯性更高。系統可根據標準化 CDG，為每個查詢計算 NDCG 值。	範例查詢必須包含 URI 欄位。
`pageNdcg`	在各個前 k 個截斷值等級中，每個網頁的正規化折減累計增益 (NDCG)。 NDCG 會評估排名品質，讓前幾項搜尋結果的關聯性更高。系統可根據標準化 CDG，為每個查詢計算 NDCG 值。	範例查詢必須包含 URI 和 pages 欄位。必須啟用擷取答案功能。
`docPrecision`	每份文件的精確度，以及各種前 k 個截止值。精確度是指擷取的文件中，與查詢相關的文件比率。例如，`top3` 值表示以下內容：對於單一查詢，如果前 5 個擷取的文件中有 4 個與查詢相關，`docPrecision` 值可計算為 4/5 或 0.8。	範例查詢必須包含 URI 欄位。

您可以根據這些支援指標的值執行下列工作：

分析匯總指標：
- 檢視整體指標，例如平均喚回率、精確度和正規化折減累計增益 (NDCG)。
- 這些指標可讓您概略瞭解搜尋引擎的成效。
查看查詢層級結果：
- 深入瞭解個別查詢，找出搜尋引擎成效良好或不佳的特定領域。
- 找出結果中的模式，瞭解排名演算法可能存在的偏差或缺陷。
比較不同時間點的結果：
- 定期執行評估，追蹤搜尋品質隨時間的變化。
- 運用歷來資料找出趨勢，並評估對搜尋引擎所做的任何變更所造成的影響。

後續步驟

使用 Cloud Scheduler 設定定期品質評估。詳情請參閱「使用驗證搭配 HTTP 目標」。

評估搜尋品質 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

評估的原因

評估時機

關於範例查詢集

範例查詢集的用途

配額與限制

查詢集格式範例

從 BigQuery 和 Cloud Storage 匯入

非結構化資料

結構化資料

網站資料

JSON

NDJSON

從本機檔案系統匯入

非結構化資料

結構化資料

網站資料

JSON

評估搜尋品質的程序

事前準備

建立範例查詢集

REST

回應

匯入查詢資料範例

Cloud Storage

回應

回應

BigQuery

回應

回應

本機檔案系統

回應

回應

執行搜尋品質評估

REST

回應

回應

回應

回應

解讀結果

後續步驟

評估搜尋品質