검색 품질 평가

Vertex AI Search로 검색을 수행할 때는 샘플 쿼리 집합을 사용하여 일반 검색 앱의 검색 결과 품질을 평가할 수 있습니다.

정형, 비정형, 웹사이트 데이터가 포함된 일반 검색 앱의 성능을 평가할 수 있습니다. 데이터 스토어가 여러 개 있는 앱 성능은 평가할 수 없습니다.

이 페이지에서는 평가 방법을 사용해서 검색 품질을 평가하는 경우와 방법 그리고 이유를 알아봅니다.

개요

이 섹션에서는 검색 품질 평가를 수행하는 경우와 그 이유를 설명합니다. 검색 품질 평가 수행 방법은 검색 품질 평가 프로세스를 참조하세요.

평가를 수행하는 이유

검색 품질을 평가하면 다음과 같이 태스크 수행에 도움이 되는 측정항목을 얻을 수 있습니다.

집계 수준에서 검색 엔진의 성능을 측정할 수 있습니다.
쿼리 수준에서 순위 알고리즘의 잠재적 편향 또는 문제를 이해하는 데 도움이 되는 패턴을 찾을 수 있습니다.
과거 평가 결과를 비교하여 검색 설정의 변화가 미치는 영향을 확인할 수 있습니다.

측정항목 목록은 결과 이해를 참조하세요.

평가를 수행해야 하는 경우

Vertex AI Search는 검색 경험을 개선하는 데 도움이 되는 다양한 검색 구성을 제공합니다. 특정 변경을 수행한 후 검색 품질을 평가할 수 있습니다.

또한 검색 동작이 주기적으로 업데이트되기 때문에 평가 테스트를 정기적으로 실행할 수도 있습니다.

샘플 쿼리 집합 정보

샘플 쿼리 집합은 품질 평가를 위해 사용됩니다. 샘플 쿼리 집합은 특정 형식을 따라야 하며, 다음과 같이 중첩된 필드가 포함된 쿼리 항목을 포함해야 합니다.

쿼리: 쿼리의 검색 결과는 평가 측정항목을 생성하고 검색 품질을 확인하기 위해 사용됩니다. 사용자의 검색 패턴 및 동작을 반영하는 다양한 쿼리 집합을 사용하는 것이 좋습니다.
대상: 샘플 쿼리의 검색 결과로 예상되는 문서의 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 필드를 나타내는 선택적인 필드입니다.

구조화된 데이터

다음 템플릿을 사용하여 BigQuery에서 정형 데이터를 평가하도록 JSON 형식으로 샘플 쿼리 파일을 생성할 수 있습니다.

{
  "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 필드를 나타내는 선택적인 필드입니다.

구조화된 데이터

다음 템플릿을 사용하여 BigQuery에서 정형 데이터를 평가하도록 JSON 형식으로 샘플 쿼리 파일을 생성할 수 있습니다.

{
  "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: 샘플 쿼리 집합의 커스텀 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 위치의 경로를 지정하는 선택적인 필드입니다. Vertex AI Search가 임시 위치를 자동으로 만들도록 하려면 비워 두거나 errorConfig 필드를 삭제하는 것이 좋습니다.
응답

다음과 비슷한 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 위치의 경로를 지정하는 선택적인 필드입니다. Vertex AI Search가 임시 위치를 자동으로 만들도록 하려면 비워 두거나 `errorConfig` 필드를 삭제하는 것이 좋습니다.
응답

다음과 비슷한 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"

응답

{
 "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"

응답

{
 "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`	다양한 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와 페이지 필드가 포함되어야 합니다. 추출형 답변을 사용 설정해야 합니다.
`docNdcg`	다양한 Top-K 컷오프 수준에서 문서당 정규화된 할인 누적 이득(NDCG)입니다. NDCG는 순위 품질을 측정하고 최상위 결과에 높은 관련성을 부여합니다. NDCG 값은 정규화된 CDG에 따라 각 쿼리에 대해 계산할 수 있습니다.	샘플 쿼리에는 URI 필드가 포함되어야 합니다.
`pageNdcg`	다양한 Top-K 컷오프 수준에서 페이지당 정규화된 할인 누적 이득(NDCG)입니다 NDCG는 순위 품질을 측정하고 최상위 결과에 높은 관련성을 부여합니다. NDCG 값은 정규화된 CDG에 따라 각 쿼리에 대해 계산할 수 있습니다.	샘플 쿼리에는 URI와 페이지 필드가 포함되어야 합니다. 추출형 답변을 사용 설정해야 합니다.
`docPrecision`	다양한 Top-K 컷오프 수준에서 문서당 정밀도입니다. 정밀도는 관련성 있는 검색된 문서의 비율입니다. 예를 들어 `top3` 값은 다음을 나타냅니다. 단일 쿼리에서 Top-5에서 5개의 검색된 문서 중 4개가 관련성이 있으면 `docPrecision` 값이 4/5 또는 0.8로 계산될 수 있습니다.	샘플 쿼리에는 URI 필드가 포함되어야 합니다.

이러한 지원되는 측정항목의 값을 기반으로 다음 태스크를 수행할 수 있습니다.

집계된 측정항목 분석:
- 평균 재현율, 정밀도, 정규화된 할인 누적 이득(NDCG)와 같은 전반적인 측정항목을 조사합니다.
- 이러한 측정항목은 검색 엔진 성능에 대한 대략적인 뷰를 제공합니다.
쿼리 수준 결과를 검토합니다.
- 개별 쿼리를 드릴다운하여 검색 엔진 성능이 적절하거나 부적절한 특정 부분을 식별합니다.
- 결과의 패턴을 찾아서 순위 알고리즘의 잠재적 편향 또는 문제를 파악합니다.
시간 경과에 따라 결과를 비교합니다.
- 시간 경과에 따라 검색 품질의 변화를 추적하기 위해 정기적으로 평가를 실행합니다.
- 과거 데이터를 사용해서 추세를 파악하고 검색 엔진에 수행하는 변경사항의 영향을 평가합니다.

다음 단계

Cloud Scheduler를 사용하여 예약된 품질 평가를 설정합니다. 자세한 내용은 HTTP 대상에 인증 사용을 참조하세요.