評估搜尋品質

使用 Gemini Enterprise 搜尋時，您可以透過範例查詢集，評估自訂搜尋應用程式的搜尋結果品質。

您可以評估含有結構化和非結構化資料的自訂搜尋應用程式成效。

您無法評估有多個資料儲存庫的應用程式效能。

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

總覽

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

執行評估的原因

評估搜尋品質後，您會取得指標，有助於執行下列工作：

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

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

執行評估的時機

Gemini Enterprise 提供多項搜尋設定，可提升搜尋體驗。進行下列變更後，即可執行搜尋品質評估：

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

關於範例查詢集

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

  • 查詢：系統會根據查詢的搜尋結果，產生評估指標並判斷搜尋品質。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：選用欄位，用於指出 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 方法執行這些步驟。

事前準備

  • 請注意以下限制：
    • 每個專案在特定時間只能有一項評估作業。
  • 適用配額如下：
    • 每個專案每天最多可發出五項評估要求。 詳情請參閱「配額與限制」。
  • 如要取得網頁層級指標，請啟用擷取式答案。

建立範例查詢集

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

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，在先前步驟啟動評估時傳回。

  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，在先前步驟啟動評估時傳回。

  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，在先前步驟啟動評估時傳回。

解讀結果

下表說明評估結果中傳回的指標。

名稱 說明 需求條件
docRecall

每份文件的喚回度，依據不同的前 k 個截斷層級。

召回率是指在所有相關文件中，檢索到的相關文件比例。 舉例來說，top5 值代表以下意義：

以單一查詢為例，如果在前 5 名中擷取到 5 份相關文件中的 3 份，則 docRecall 的計算結果為 3/5 或 0.6。

 範例查詢必須包含 URI 欄位。
pageRecall

各個 top-k 截斷層級的每頁喚回度。

召回率是指系統檢索到的相關網頁占所有相關網頁的分數。 舉例來說，top5 值代表以下意義：

如果單一查詢在前 5 個結果中擷取了 3 個相關網頁，則 pageRecall 可計算為 3/5 = 0.6
  • 範例查詢必須包含 URI 和頁面欄位。
  • 必須啟用擷取型答案。
docNdcg

每份文件的正規化折減累計增益 (NDCG)，在不同的前 k 個截斷層級。

NDCG 會評估排名品質，並提高頂端結果的關聯性。 您可以根據標準化 CDG 計算每項查詢的 NDCG 值。

 範例查詢必須包含 URI 欄位。
pageNdcg

各網頁的正規化折減累計增益 (NDCG)，以及各種前 k 個結果的截斷層級。

NDCG 會評估排名品質，並提高頂端結果的關聯性。 您可以根據標準化 CDG 計算每項查詢的 NDCG 值。
  • 範例查詢必須包含 URI 和頁面欄位。
  • 必須啟用擷取式答案。
docPrecision

每份文件的精確度，在各種前 k 個截斷層級。

精確度是指檢索到的文件中，相關文件的比例。舉例來說，top3 值代表以下意義：

以單一查詢為例，如果前 5 個擷取的相關文件中有 4 個，則 docPrecision 值可計算為 4/5 或 0.8。

 範例查詢必須包含 URI 欄位。

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

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

後續步驟