此页面由 Cloud Translation API 翻译。

评估搜索质量

在使用 Vertex AI Search 的搜索体验中，您可以使用示例查询集评估通用搜索应用的搜索结果质量。

您可以评估包含结构化数据、非结构化数据和网站数据您无法评估多个数据存储区。

本页介绍了使用评估方法评估搜索质量的原因、时间和方法。

概览

本部分介绍了执行搜索质量评估的原因和时间。如需了解如何执行搜索质量评估，请参阅搜索质量评估流程。

执行评估的原因

搜索质量评估可为您提供有助于执行以下任务的指标：

在汇总级别衡量搜索引擎的效果
在查询一级，查找模式，以了解排名算法中的潜在偏差或缺点
比较历史评估结果，了解您的搜索配置

如需查看指标列表，请参阅了解结果。

何时执行评估

Vertex AI Search 扩展了多种搜索配置，以提升您的搜索体验。您可以在进行以下更改后执行搜索质量评估：

由于搜索行为会定期更新，因此您也可以定期运行评估测试。

示例查询集简介

示例查询集用于质量评估。示例查询集必须遵循规定的格式，并且必须包含包含以下嵌套字段的查询条目：

查询：使用其搜索结果生成评估指标并确定搜索质量。Google 建议您使用反映用户搜索模式和行为的一组多样化查询。
Targets：应作为示例查询。为了了解结构化文档的定义，非结构化应用和网站搜索应用，请参阅文档。

当将目标文档与搜索响应，就会生成效果指标。系统会使用以下两种方法生成指标：
- 文档匹配：将目标文档的 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 位置的路径。这是第 link 字段的文档定义的 derivedStructData 字段。
PAGE_NUMBER_1：一个可选字段，用于指明 PDF 文件中包含查询预期响应的页码。当文件包含多个页面时，这非常有用。
CDOC_URL：可选字段，用于指明文档元数据中的文档 ID cdoc_url 字段， Vertex AI Search 数据存储区架构。

结构化数据

使用以下模板起草 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 位置所查询的命令这是第 link 字段的文档定义的 derivedStructData 字段。
PAGE_NUMBER_1：可选字段，用于指明包含查询所需响应的页码。如果文件包含多个页面，这将非常有用。
CDOC_URL：可选字段，用于指明文档元数据中的文档 ID cdoc_url 字段， Vertex AI Search 数据存储区架构。

结构化数据

使用以下模板起草 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 方法。

准备工作

适用的限制如下：
- 在给定时间，每个项目只能有一个有效的评估。
以下配额适用：
- 您每天最多可以为每个项目发起 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：示例查询集。
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

创建符合示例查询集格式的示例查询集。
从 Cloud Storage 导入包含示例查询集的 JSON 文件使用 sampleQueries.import 方法确定位置。
```
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：您的您在创建示例查询集期间定义的示例查询集。
- INPUT_FILE_PATH：Cloud Storage 的路径位置。
- ERROR_DIRECTORY：用于指定的可选字段 Cloud Storage 位置路径，在 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：您的您在创建示例查询集期间定义的示例查询集。
- DATASET_ID：BigQuery 的 ID 数据集。
- TABLE_ID：包含示例查询集的 BigQuery 表的 ID。
- ERROR_DIRECTORY：用于指定的可选字段 Cloud Storage 位置路径，在 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"
   }
 }
}

本地文件系统

创建符合示例查询集格式的示例查询集。

从本地文件系统导入包含示例查询集的 JSON 文件使用 sampleQueries.import 方法确定位置。

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：您的您在创建示例查询集期间定义的示例查询集。
APP_ID：您希望优化其搜索质量的 Vertex AI Search 应用评估。

响应

您应该收到类似以下内容的 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`	在不同前 k 个截断级别下，每个文档的召回率。召回率是从所有相关文档中检索到的相关文档所占的比例。例如，`top5` 值表示以下内容：对于单个查询，如果前 5 个结果中有 3 个是相关文档，则 `docRecall` 可计算为 3/5 或 0.6。	示例查询必须包含 URI 字段。
`pageRecall`	在不同前 k 个截断级别下，每个网页的召回率。召回率是从所有相关网页中检索到的相关网页所占的比例。例如，`top5` 值表示以下内容：对于单次查询，如果检索到的 5 个相关网页中有 3 个排名前 5，则 `pageRecall` 的计算公式为：3/5 = 0.6	示例查询必须包含 URI 和 Pages 字段。必须启用提取回答。
`docNdcg`	在各种前 k 个截断级别下，每个文档的归一化折扣累计增益 (NDCG)。 NDCG 会衡量排名质量，从而给出与排名靠前的搜索结果更高的相关性。您可以根据标准化 CDG 计算每次查询的 NDCG 值。	示例查询必须包含 URI 字段。
`pageNdcg`	在各种 Top-k 截止时间下，每页的标准化折扣累计增益 (NDCG) 增益值。 NDCG 会衡量排名质量，从而给出与排名靠前的搜索结果更高的相关性。您可以根据标准化 CDG 计算每次查询的 NDCG 值。	示例查询必须包含 URI 和 pages 字段。必须启用提取回答。
`docPrecision`	在各种前 k 个截断级别下，每个文档的精确度。精确率是指检索到的相关文档所占的比例。例如，`top3` 值表示以下内容：对于单个查询，如果前 5 个检索到的文档中有 4 个相关，则 `docPrecision` 值可以计算为 4/5 或 0.8。	示例查询必须包含 URI 字段。

根据这些受支持指标的值，您可以执行以下任务：

分析汇总指标：
- 研究平均召回率、精确率和归一化折扣累计增益 (NDCG) 等总体指标。
- 这些指标可以让您大致了解搜索引擎的效果。
查看查询级结果：
- 深入了解各个搜索查询，找出搜索引擎表现良好或不佳的具体方面。
- 在结果中寻找规律，以了解排名算法中可能存在的偏差或缺点。
比较不同时间段的结果：
- 定期运行评估，以跟踪搜索质量随时间的变化。
- 使用历史数据来发现趋势，并评估您对搜索引擎所做的任何更改的影响。

后续步骤

使用 Cloud Scheduler 设置计划的质量评估。如需了解详情，请参阅对 HTTP 目标使用身份验证。