Se usó la API de Cloud Translation para traducir esta página.

Cómo evaluar la calidad de la búsqueda

Como parte de tu experiencia de búsqueda con Vertex AI Search, puedes evaluar la calidad de los resultados de la búsqueda de apps de búsqueda genéricas con conjuntos de consultas de muestra.

Puedes evaluar el rendimiento de las apps de búsqueda genéricas que contienen datos estructurados, no estructurados y de sitios web. No puedes evaluar el rendimiento de las apps con varios almacenes de datos.

En esta página, se explica por qué, cuándo y cómo evaluar la calidad de la búsqueda con el método de evaluación.

Descripción general

En esta sección, se describe por qué y cuándo realizar la evaluación de la calidad de la búsqueda. Si quieres obtener información para realizar la evaluación de la calidad de la búsqueda, consulta Proceso para evaluar la calidad de la búsqueda.

Motivos para realizar la evaluación

La evaluación de la calidad de tu búsqueda te proporciona métricas que te ayudan a realizar tareas como las siguientes:

Mide el rendimiento de tu motor de búsqueda a nivel agregado
A nivel de la consulta, busca patrones para comprender posibles sesgos o deficiencias en los algoritmos de clasificación.
Compara los resultados de las evaluaciones históricas para comprender el impacto de los cambios en la configuración de la búsqueda

Para obtener una lista de métricas, consulta Cómo interpretar los resultados.

Cuándo realizar la evaluación

Vertex AI Search extiende varias configuraciones de búsqueda para mejorar tu experiencia de búsqueda. Puedes realizar la evaluación de la calidad de la búsqueda después de realizar los siguientes cambios:

También puedes ejecutar las pruebas de evaluación con regularidad, ya que el comportamiento de la búsqueda se actualiza periódicamente.

Acerca de los conjuntos de consultas de muestra

Los conjuntos de consultas de muestra se usan para la evaluación de la calidad. El conjunto de consultas de muestra debe cumplir con su formato prescrito y debe contener entradas de consulta que tengan los siguientes campos anidados:

Consultas: Es la consulta cuyos resultados de la búsqueda se usan para generar las métricas de evaluación y determinar la calidad de la búsqueda. Google recomienda usar un conjunto diverso de consultas que reflejen el patrón de búsqueda y el comportamiento de tus usuarios.
Destinos: Es el URI del documento que se espera como resultado de la búsqueda de la consulta de ejemplo. Para comprender la definición de documento para apps de búsqueda de sitios web, estructurados y no estructurados, consulta Documentos.

Cuando se comparan los documentos de destino con los documentos recuperados en la respuesta de la búsqueda, se generan métricas de rendimiento. Las métricas se generan con estas dos técnicas:
- Coincidencia de documentos: Los URIs de los documentos de destino se comparan con los URIs de los documentos recuperados. Esto determina si los documentos esperados están presentes en los resultados de la búsqueda. Durante la comparación, la API de evaluación intenta extraer los siguientes campos en el siguiente orden y usar el primer valor disponible para hacer coincidir el objetivo con el documento recuperado:
  - cdoc_url en el campo structData de la definición del documento
  - uri en el campo structData de la definición del documento
  - link en el campo derivedStructData de la definición del documento
  - url en el campo derivedStructData de la definición del documento
- Coincidencia de páginas: Cuando incluyes números de página en tus objetivos de muestra, la API de evaluación compara los resultados a nivel de la página. Esto determina si las páginas mencionadas en los objetivos también se citan en la respuesta de la búsqueda. Debes habilitar las respuestas extractivas para habilitar la coincidencia a nivel de la página. La API de evaluación coincide con la página de la primera respuesta extractiva en el resultado de la búsqueda.

Propósito de los conjuntos de consultas de muestra

Usar el mismo conjunto de consultas de muestra para todas tus evaluaciones de calidad de la búsqueda de un almacén de datos determinado garantiza una forma coherente y confiable de medir los resultados de la calidad de la búsqueda. Esto también establece un sistema justo y repetible.

Los resultados de cada evaluación se comparan con los resultados objetivo de cada consulta de muestra para calcular diferentes métricas, como la recuperación, la precisión y la ganancia acumulada descontada normalizada (NDCG). Estas métricas cuantitativas se usan para clasificar los resultados de diferentes configuraciones de búsqueda.

Cuotas y límites

Se aplica el siguiente límite a los conjuntos de consultas de muestra:

Cada conjunto de consultas de muestra puede contener un máximo de 20,000 consultas.

La siguiente cuota se aplica a los conjuntos de consultas de muestra:

Puedes crear un máximo de 100 conjuntos de consultas de muestra por proyecto y 500 conjuntos de consultas de muestra por organización.

Para obtener más información, consulta Cuotas y límites.

Formato de ejemplo del conjunto de búsquedas

El conjunto de consultas debe cumplir con el siguiente esquema cuando se construye en formato JSON. El conjunto de consultas puede contener varias entradas de consulta con una consulta en cada una. Cuando se presenta en formato JSON (NDJSON) delimitado por saltos de línea, cada entrada de consulta debe estar en una línea nueva.

Importa desde BigQuery y Cloud Storage

En la siguiente sección, se proporcionan las plantillas de conjuntos de consultas de muestra para importar desde BigQuery y Cloud Storage.

Datos no estructurados

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de muestra en formato JSON para evaluar datos no estructurados con metadatos.

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

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
PATH/TO/CLOUD/STORAGE/LOCATION: Es la ruta de acceso a la ubicación de Cloud Storage en la que reside el resultado esperado. Este es el valor del campo link en el campo derivedStructData de la definición del documento.
PAGE_NUMBER_1: Es un campo opcional para indicar los números de página del archivo PDF en los que se encuentra la respuesta esperada para la consulta. Esto es útil cuando el archivo tiene varias páginas.
CDOC_URL: Es un campo opcional para indicar el campo cdoc_url de ID de documento personalizado en los metadatos del documento en el esquema del almacén de datos de Vertex AI Search.

Datos estructurados

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de muestra en formato JSON para evaluar los datos estructurados de BigQuery.

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "CDOC_URL"
      }
    ]
  }
}

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
CDOC_URL: Es un campo obligatorio para indicar el campo cdoc_url personalizado para el campo de datos estructurados en el esquema del almacén de datos de Vertex AI Search.

Datos del sitio web

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de ejemplo en formato JSON para evaluar el contenido del sitio web.

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "WEBSITE_URL"
      }
    ]
  }
}

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
WEBSITE_URL: Es el sitio web de destino de la consulta.

Este es un ejemplo de una consulta de muestra establecida en formatos JSON y 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"}]}}

Importa desde el sistema de archivos local

En la siguiente sección, se proporcionan las plantillas de conjuntos de consultas de muestra para importar desde el sistema de archivos local.

Datos no estructurados

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de muestra en formato JSON para evaluar datos no estructurados con metadatos.

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

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
PATH/TO/CLOUD/STORAGE/LOCATION: Es la ruta de acceso a la ubicación de Cloud Storage en la que reside el archivo de datos no estructurados que se consultará. Este es el valor del campo link en el campo derivedStructData de la definición del documento.
PAGE_NUMBER_1: Es un campo opcional para indicar los números de página en los que se puede encontrar la respuesta requerida para la consulta en el archivo PDF. Esto es útil si el archivo tiene varias páginas.
CDOC_URL: Es un campo opcional para indicar el campo cdoc_url de ID de documento personalizado en los metadatos del documento en el esquema del almacén de datos de Vertex AI Search.

Datos estructurados

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de muestra en formato JSON para evaluar los datos estructurados de BigQuery.

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "CDOC_URL"
            }
          ]
        }
      }
    ]
  }
}

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
CDOC_URL: Es un campo obligatorio para indicar el campo cdoc_url personalizado para el campo de datos estructurados en el esquema del almacén de datos de Vertex AI Search.

Datos del sitio web

Usa la siguiente plantilla para crear un borrador de un archivo de consulta de ejemplo en formato JSON para evaluar el contenido del sitio web.

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "WEBSITE_URL"
            }
          ]
        }
      }
    ]
  }
}

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la consulta que se usa para probar y evaluar la calidad de la búsqueda.
WEBSITE_URL: Es el sitio web de destino de la consulta.

A continuación, se muestra un ejemplo de un conjunto de consultas de muestra:

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

Proceso para evaluar la calidad de la búsqueda

El proceso de evaluación de la calidad de la búsqueda es el siguiente:

Crea un conjunto de consultas de muestra.
Importa una consulta de muestra que cumpla con el formato JSON prescrito.
Ejecuta la evaluación de la calidad de la búsqueda.
Cómo interpretar los resultados.

En las siguientes secciones, se proporcionan las instrucciones para realizar estos pasos con los métodos de la API de REST.

Antes de comenzar

Se aplica el siguiente límite:
- En un momento determinado, solo puedes tener una evaluación activa por proyecto.
Se aplica la siguiente cuota:
- Puedes iniciar un máximo de cinco solicitudes de evaluación por día y por proyecto. Para obtener más información, consulta Cuotas y límites.
Para obtener métricas a nivel de la página, debes habilitar las respuestas extractivas.

Crea un conjunto de consultas de muestra

Puedes crear un conjunto de consultas de muestra y usarlo para evaluar la calidad de las respuestas de la búsqueda de un almacén de datos determinado. Para crear un conjunto de consultas de muestra, haz lo siguiente:

REST

En el siguiente ejemplo, se muestra cómo crear el conjunto de consultas de muestra con el método sampleQuerySets.create.

Crea el conjunto de consultas de muestra.

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"
}'

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud.
SAMPLE_QUERY_SET_ID: Un ID personalizado para tu conjunto de consultas de muestra.
SAMPLE_QUERY_SET_DISPLAY_NAME: Es un nombre personalizado para tu conjunto de consultas de muestra.

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID",
  "displayName": "SAMPLE_QUERY_SET_DISPLAY_NAME",
  "createTime": "CREATION_DATETIME"
}

Importa datos de consulta de muestra

Después de crear el conjunto de consultas de muestra, importa los datos de consulta de muestra. Para importar los datos de consulta de muestra, puedes realizar cualquiera de las siguientes acciones:

Importar desde Cloud Storage: Importa un archivo NDJSON desde una ubicación de Cloud Storage.
Importar desde BigQuery: Importa datos de BigQuery desde una tabla de BigQuery. Para crear la tabla de BigQuery a partir de tu archivo NDJSON, consulta Cómo cargar datos JSON desde Cloud Storage.
Importar desde tu sistema de archivos local: Crea el conjunto de consultas de muestra en tu sistema de archivos local y, luego, impórtalo.

Cloud Storage

Crea los conjuntos de consultas de muestra que cumplan con el formato de conjunto de consultas de muestra.
Importa el archivo JSON que contiene el conjunto de consultas de muestra desde una ubicación de Cloud Storage con el método 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"
  }
}'
```
Reemplaza lo siguiente:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- SAMPLE_QUERY_SET_ID: Es el ID personalizado del conjunto de consultas de muestra que definiste durante la creación del conjunto de consultas de muestra.
- INPUT_FILE_PATH: Es la ruta de acceso a la ubicación de Cloud Storage de tu conjunto de consultas de muestra.
- ERROR_DIRECTORY: Es un campo opcional para especificar la ruta de acceso a la ubicación de Cloud Storage en la que se registran los archivos de error cuando se producen errores de importación. Google recomienda dejar este campo vacío o quitar el campo errorConfig para que Vertex AI Search pueda crear automáticamente una ubicación temporal.
Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Anota el valor de OPERATION_ID. Necesitarás este valor en el siguiente paso para sondear el estado de esta operación de larga duración (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"
  }
}
```

Obtén el estado de la operación de larga duración (LRO) con el método operations.get.

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"

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Si hay errores y la importación falló, la respuesta muestra un campo failureCount para indicar la cantidad de consultas de muestra que no se pudieron importar.

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

Crea los conjuntos de consultas de muestra que cumplan con el formato de conjunto de consultas de muestra.
Importa el archivo JSON que contiene el conjunto de consultas de muestra desde una ubicación de BigQuery con el método 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 '{
  "bigquerySource": {
    "projectId": "PROJECT_ID",
    "datasetId":"DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
```
Reemplaza lo siguiente:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- SAMPLE_QUERY_SET_ID: Es el ID personalizado del conjunto de consultas de muestra que definiste durante la creación del conjunto de consultas de muestra.
- DATASET_ID: Es el ID del conjunto de datos de BigQuery que contiene el conjunto de consultas de muestra.
- TABLE_ID: Es el ID de la tabla de BigQuery que contiene el conjunto de consultas de muestra.
- ERROR_DIRECTORY: Es un campo opcional para especificar la ruta de acceso a la ubicación de Cloud Storage en la que se registran los archivos de error cuando se producen errores de importación. Google recomienda dejar este campo vacío o quitar el campo "errorConfig" para que Vertex AI Search pueda crear automáticamente una ubicación temporal.
Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Anota el valor de OPERATION_ID. Necesitarás este valor en el siguiente paso para sondear el estado de esta operación de larga duración (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"
  }
}
```

Obtén el estado de la operación de larga duración (LRO) con el método operations.get.

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"

Respuesta

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

Sistema de archivos local

Crea los conjuntos de consultas de muestra que cumplan con el formato de conjunto de consultas de muestra.
Importa el archivo JSON que contiene el conjunto de consultas de muestra desde una ubicación del sistema de archivos local con el método 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
```
Reemplaza lo siguiente:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- SAMPLE_QUERY_SET_ID: Es el ID personalizado del conjunto de consultas de muestra que definiste durante la creación del conjunto de consultas de muestra.
- PATH/TO/LOCAL/FILE.json: Es la ruta de acceso al archivo JSON que contiene el conjunto de consultas de muestra.
Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Anota el valor de OPERATION_ID. Necesitarás este valor en el siguiente paso para sondear el estado de esta operación de larga duración (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"
  }
}
```

Obtén el estado de la operación de larga duración (LRO) con el método operations.get.

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"

Respuesta

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

Ejecuta la evaluación de la calidad de la búsqueda

Después de importar los datos de consulta de muestra a los conjuntos de consultas de muestra, sigue estos pasos para ejecutar la evaluación de calidad de la búsqueda.

REST

Inicia una evaluación de la calidad de la búsqueda.

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"
   }
 }
}'

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud.
SAMPLE_QUERY_SET_ID: Es el ID personalizado del conjunto de consultas de muestra que definiste durante la creación del conjunto de consultas de muestra.
APP_ID: El ID de la app de Vertex AI Search cuya calidad de búsqueda deseas evaluar.

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Anota el valor de EVALUATION_ID. Necesitarás este valor en el siguiente paso para sondear el estado de la evaluación, que es una operación de larga duración (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"
 }
}

Supervisa el progreso de la evaluación.

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"

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud.
EVALUATION_ID: Es el ID de la tarea de evaluación que se mostró en el paso anterior cuando iniciaste la evaluación.

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El estado de la evaluación se muestra como PENDING hasta que se completa.

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

Recupera los resultados agregados.

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"

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud.
EVALUATION_ID: Es el ID de la tarea de evaluación que se mostró en el paso anterior cuando iniciaste la evaluación.

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El estado de la evaluación se muestra como PENDING hasta que se completa.

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

Recuperar resultados a nivel de la consulta

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"

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud.
EVALUATION_ID: Es el ID de la tarea de evaluación que se mostró en el paso anterior cuando iniciaste la evaluación.

Respuesta

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El estado de la evaluación se muestra como PENDING hasta que se completa.

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

Comprende los resultados

En la siguiente tabla, se describen las métricas que se muestran en los resultados de la evaluación.

Nombre	Descripción	Requisitos
`docRecall`	Recuperación por documento en varios niveles de corte de Top-K La recuperación es la fracción de documentos relevantes recuperados de todos los documentos relevantes. Por ejemplo, el valor `top5` significa lo siguiente: Para una sola consulta, si se recuperan 3 de 5 documentos relevantes en los 5 principales, `docRecall` se puede calcular como 3/5 o 0.6.	La consulta de muestra debe contener el campo URI.
`pageRecall`	Recuperación por página, en varios niveles de corte de Top-K La recuperación es la fracción de páginas relevantes recuperadas de todas las páginas relevantes. Por ejemplo, el valor `top5` significa lo siguiente: Para una sola búsqueda, si se recuperan 3 de 5 páginas relevantes en las 5 principales, `pageRecall` se puede calcular como 3/5 = 0.6.	La consulta de muestra debe contener los campos URI y páginas. Las respuestas extractivas deben estar habilitadas.
`docNdcg`	Ganancia acumulada normalizada y con descuento (NDCG) por documento, en varios niveles de corte de Top-K El NDCG mide la calidad de la clasificación, lo que otorga mayor relevancia a los resultados principales. El valor de NDCG se puede calcular para cada consulta según el CDG normalizado.	La consulta de muestra debe contener el campo URI.
`pageNdcg`	Ganancia acumulada normalizada y con descuento (NDCG) por página, en varios niveles de corte de Top-K El NDCG mide la calidad de la clasificación, lo que otorga mayor relevancia a los resultados principales. El valor de NDCG se puede calcular para cada consulta según el CDG normalizado.	La consulta de muestra debe contener los campos URI y páginas. Las respuestas extractivas deben estar habilitadas.
`docPrecision`	Precisión por documento, en varios niveles de corte de Top-K La precisión es la fracción de documentos recuperados que son relevantes. Por ejemplo, el valor `top3` significa lo siguiente: Para una sola consulta, si 4 de los 5 documentos recuperados en los 5 principales son relevantes, el valor de `docPrecision` se puede calcular como 4/5 o 0.8.	La consulta de muestra debe contener el campo URI.

En función de los valores de estas métricas admitidas, puedes realizar las siguientes tareas:

Analiza las métricas agregadas:
- Examina las métricas generales, como la recuperación promedio, la precisión y la ganancia acumulada normalizada y con descuento (NDCG).
- Estas métricas proporcionan una vista de alto nivel del rendimiento de tu motor de búsqueda.
Revisa los resultados a nivel de la consulta:
- Desglosa las búsquedas individuales para identificar áreas específicas en las que el motor de búsqueda tiene un buen o mal rendimiento.
- Busca patrones en los resultados para comprender los posibles sesgos o deficiencias en los algoritmos de clasificación.
Compara los resultados a lo largo del tiempo:
- Ejecuta evaluaciones con regularidad para hacer un seguimiento de los cambios en la calidad de la búsqueda a lo largo del tiempo.
- Usa los datos históricos para identificar tendencias y evaluar el impacto de los cambios que realices en tu motor de búsqueda.

¿Qué sigue?

Usa Cloud Scheduler para configurar la evaluación de calidad programada. Para obtener más información, consulta Usa la autenticación con destinos de HTTP.