评估搜索质量

作为 Gemini Enterprise 搜索体验的一部分，您可以使用示例查询集评估自定义搜索应用的搜索结果质量。

您可以评估包含结构化和非结构化数据的自定义搜索应用的性能。

您无法评估具有多个数据存储区的应用的性能。

本页面将介绍为何、何时以及如何使用评估方法来评估搜索质量。

概览

本部分介绍了为何以及何时执行搜索质量评估。 如需了解如何执行搜索质量评估，请参阅搜索质量评估流程。

执行评估的原因

搜索质量评估可为您提供相关指标，帮助您执行以下任务：

  • 在汇总层面，衡量您的搜索引擎性能
  • 在查询层面，查找模式以了解排名算法中可能存在的偏差或缺陷
  • 比较历史评估结果，了解搜索配置更改的影响

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

何时执行评估

Gemini Enterprise 扩展了多项搜索配置以增强您的搜索体验。您可以在进行以下更改后执行搜索质量评估：

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

示例查询集简介

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

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

  • 目标：预期作为示例查询的搜索结果的文档 URI。如需了解结构化和非结构化文档的定义，请参阅连接器和数据存储区概念。

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

    • 文档匹配：目标文档的 URI 会与检索到的文档的 URI 进行比较。这确定了预期文档是否出现在搜索结果中。在比较过程中，评估 API 会尝试按以下顺序提取以下字段，并使用第一个可用值来将目标与检索到的文档进行匹配：
    • 页面匹配：如果您在示例目标中包含了页码，则评估 API 会在页面级别比较结果。这确定了目标中提及的页面是否也在搜索响应中被引用。您必须启用提取式回答才能启用页面级别匹配。评估 API 会从搜索结果中的第一个提取式回答匹配页面。

示例查询集的用途

对给定数据存储区的所有搜索质量评估都使用相同的示例查询集，可确保以一致且可靠的方式衡量搜索质量结果。这也建立了一个公平且可重复的系统。

每次评估的结果都会与每个示例查询的目标结果进行比较，以计算不同的指标，例如召回率、精确率和归一化折损累计增益 (NDCG)。这些定量指标用于对不同搜索配置的结果进行排名。

配额和限制

以下限制适用于示例查询集：

  • 每个示例查询集最多可包含 20,000 个查询。

以下配额适用于示例查询集：

  • 每个项目最多可以创建 100 个示例查询集，每个组织最多可以创建 500 个示例查询集。如需了解详情，请参阅配额和限制。

示例查询集的格式

以 JSON 格式构建查询集时，该查询集必须符合以下架构。查询集可以包含多个查询条目，每个查询条目中包含一个查询。当以 NDJSON（换行符分隔的 JSON）格式呈现时，每个查询条目都必须位于新的一行。

从 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"
            }
          ]
        }
      }
    ]
  }
}

评估搜索质量的流程

搜索质量评估流程如下：

  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：您的项目的 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：您的项目的 ID。
    • SAMPLE_QUERY_SET_ID：您在创建示例查询集期间为示例查询集定义的自定义 ID。
    • INPUT_FILE_PATH：示例查询集的 Cloud Storage 位置的路径。
    • ERROR_DIRECTORY：一个可选字段，用于指定发生导入错误时，错误文件被记录到的 Cloud Storage 位置的路径。Google 建议将其留空或移除 errorConfig 字段，以便 Gemini Enterprise 可以自动创建一个临时位置。

  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：您的项目的 ID。
    • SAMPLE_QUERY_SET_ID：您在创建示例查询集期间为示例查询集定义的自定义 ID。
    • DATASET_ID：包含示例查询集的 BigQuery 数据集的 ID。
    • TABLE_ID：包含示例查询集的 BigQuery 表的 ID。
    • ERROR_DIRECTORY：一个可选字段，用于指定发生导入错误时，错误文件被记录到的 Cloud Storage 位置的路径。Google 建议将其留空或移除“errorConfig”字段，以便 Gemini Enterprise 可以自动创建一个临时位置。

  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：您的项目的 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：您的项目的 ID。
    • SAMPLE_QUERY_SET_ID：您在创建示例查询集期间为示例查询集定义的自定义 ID。
    • APP_ID：您要评估其搜索质量的 Gemini Enterprise 应用的 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：您的项目的 ID。
    • EVALUATION_ID：评估作业的 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：您的项目的 ID。
    • EVALUATION_ID：评估作业的 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：您的项目的 ID。
    • EVALUATION_ID：评估作业的 ID，该 ID 是您发起评估时在上一步中返回的。

解读结果

下表列出了评估结果中返回的指标。

名称 说明 要求
docRecall

每个文档的召回率，在各种 top-k 截止级别。

召回率是检索到的相关文档占所有相关文档的比例。例如，top5 值表示以下含义：

对于单个查询，如果在 top-5 中检索到 5 个相关文档中的 3 个，则 docRecall 可以计算为 3/5 或 0.6。

 示例查询必须包含 URI 字段。
pageRecall

每个页面的召回率，在各种 top-k 截止级别。

召回率是检索到的相关页面占所有相关页面的比例。例如，top5 值表示以下含义：

对于单个查询，如果在 top-5 中检索到 5 个相关页面中的 3 个，则 pageRecall 可以计算为 3/5 = 0.6
  • 示例查询必须包含 URI 和 pages 字段。
  • 必须启用提取式回答。
docNdcg

每个文档的归一化折损累计增益 (NDCG)，在各种 top-k 截止级别。

NDCG 可衡量排名质量，为靠前的结果赋予更高的相关性。可以根据归一化 CDG 计算每个查询的 NDCG 值。

 示例查询必须包含 URI 字段。
pageNdcg

每个页面的归一化折损累计增益 (NDCG)，在各种 top-k 截止级别。

NDCG 可衡量排名质量，为靠前的结果赋予更高的相关性。可以根据归一化 CDG 计算每个查询的 NDCG 值。
  • 示例查询必须包含 URI 和 pages 字段。
  • 必须启用提取式回答。
docPrecision

每个文档的精确率，在各种 top-k 截止级别。

精确率是检索到的相关文档占检索到的文档总数的比例。例如，top3 值表示以下含义：

对于单个查询，如果在 top-5 中检索到的 5 个文档中有 4 个相关，则 docPrecision 值可以计算为 4/5 或 0.8。

 示例查询必须包含 URI 字段。

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

  • 分析汇总指标：
    • 检查诸如平均召回率、精确率和归一化折损累计增益 (NDCG) 等总体指标。
    • 这些指标提供了您的搜索引擎性能的总体概览。
  • 查看查询级别结果：
    • 深入分析各个搜索查询，找出搜索引擎表现良好或不佳的具体方面。
    • 在结果中查找模式，以了解排名算法中可能存在的偏差或缺陷。
  • 比较随时间变化的结果：
    • 定期运行评估以跟踪搜索质量随时间的变化情况。
    • 使用历史数据来识别趋势并评估您对搜索引擎所做任何更改的影响。

后续步骤