评估搜索质量

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

您可以评估包含结构化数据、非结构化数据和网站数据的通用搜索应用的性能。您无法评估使用多个数据存储区的应用的性能。

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

概览

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

执行评估的原因

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

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

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

何时执行评估

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

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

示例查询集简介

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

  • 查询：搜索结果用于生成评估指标并确定搜索质量的查询。Google 建议您使用反映用户搜索模式和行为的一组多样化查询。

  • 目标：预期作为示例查询的搜索结果的文档的 URI。如需了解结构化搜索应用、非结构化搜索应用和网站搜索应用的文档定义，请参阅文档。

    将目标文档与搜索响应中检索到的文档进行比较时，系统会生成效果指标。系统会使用以下两种方法生成指标：

    • 文档匹配：将目标文档的 URI 与检索到的文档的 URI 进行比较。这决定了搜索结果中是否包含预期的文档。在比较期间，评估 API 会尝试按以下顺序提取以下字段，并使用第一个可用值将目标与检索到的文档进行匹配：
    • 页面匹配：如果您在示例目标中添加页码，评估 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"
            }
          ]
        }
      }
    ]
  }
}

评估搜索质量的流程

搜索质量评估流程如下：

  1. 创建示例查询集。
  2. 导入符合规定 JSON 格式的示例查询。
  3. 运行搜索质量评估。
  4. 了解结果。

以下部分介绍了使用 REST API 方法执行这些步骤的说明。

准备工作

  • 存在以下限制：
    • 在给定时间，每个项目只能有一个有效的评估。
  • 以下配额适用：
    • 您每天最多可以为每个项目发起 5 项评估请求。 如需了解详情，请参阅配额和限制。
  • 如需获取网页级指标，您必须启用提取式回答。

创建示例查询集

您可以创建一个示例查询集，并使用它来评估给定数据存储区的搜索响应质量。如需创建示例查询集，请执行以下操作。

REST

以下示例展示了如何使用 sampleQuerySets.create 方法创建示例查询集。

  1. 创建示例查询集。

    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：示例查询集的自定义名称。

导入示例查询数据

创建示例查询集后，导入示例查询数据。 如需导入示例查询数据，您可以执行以下任一操作：

  • 从 Cloud Storage 导入：从 Cloud Storage 位置导入 NDJSON 文件。
  • 从 BigQuery 导入：从 BigQuery 表导入 BigQuery 数据。如需根据 NDJSON 文件创建 BigQuery 表，请参阅从 Cloud Storage 加载 JSON 数据。
  • 从本地文件系统导入：在本地文件系统中创建示例查询集并将其导入。

Cloud Storage

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

  2. 使用 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 可以自动创建临时位置。

  3. 使用 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"

BigQuery

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

  2. 使用 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 可以自动创建临时位置。

  3. 使用 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"

本地文件系统

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

  2. 使用 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 文件的路径。

  3. 使用 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"

运行搜索质量评估

将示例查询数据导入示例查询集后，请按照以下步骤运行搜索质量评估。

REST

  1. 发起搜索质量评估。

    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。

  2. 监控评估进度。

    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，在上一步中启动评估时返回。

  3. 检索汇总结果。

    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，在上一步中启动评估时返回。

  4. 检索查询级结果。

    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，在上一步中启动评估时返回。

了解结果

下表介绍了评估结果中返回的指标。

名称 说明 要求
docRecall

在不同前 k 个截断级别下，每个文档的召回率。

召回率是指从所有相关文档中检索到的相关文档所占的比例。 例如，top5 值表示以下内容：

对于单个查询，如果 5 条相关文档中有 3 条在前 5 位中检索到，则 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) 等整体指标。
    • 这些指标可让您大致了解搜索引擎的效果。
  • 查看查询级结果：
    • 深入了解各个搜索查询，找出搜索引擎表现良好或不佳的具体方面。
    • 在结果中寻找规律，以了解排名算法中可能存在的偏差或缺点。
  • 比较一段时间内的结果：
    • 定期运行评估，以跟踪搜索质量随时间的变化。
    • 使用历史数据来发现趋势，并评估您对搜索引擎所做的任何更改的影响。

后续步骤