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 para las apps de búsqueda personalizadas con conjuntos de muestras de búsquedas.

Puedes evaluar el rendimiento de las apps de búsqueda personalizadas 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 la búsqueda te proporciona métricas que te ayudan a realizar tareas como las siguientes:

Evalúa el rendimiento de tu motor de búsqueda a nivel agregado
A nivel de la búsqueda, ubica patrones para comprender los posibles sesgos o deficiencias en los algoritmos de clasificación.
Compara los resultados históricos de la evaluación para comprender el impacto de los cambios en la configuración de la búsqueda

Para obtener una lista de las 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 muestras de búsquedas se usan para la evaluación de la calidad. El conjunto de muestras de búsqueda debe cumplir con el formato prescrito y debe contener entradas de búsqueda que tengan los siguientes campos anidados:

Queries: Es la búsqueda cuyos resultados 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 búsquedas que reflejen el patrón y el comportamiento de búsqueda 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 las apps de búsqueda estructurada, no estructurada y de sitios web, consulta Documentos.

Cuando se comparan los documentos objetivo con los documentos recuperados en la respuesta de 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 objetivo 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 usa 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 muestras de objetivos, 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 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 muestras de búsquedas para todas las 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 búsqueda de muestra para calcular diferentes métricas, como la recuperación, la precisión y la ganancia acumulada con descuento normalizada (NDCG). Estas métricas cuantitativas se utilizan 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 muestras de búsquedas puede contener un máximo de 20,000 búsquedas.

Se aplica la siguiente cuota a los conjuntos de consultas de muestra:

Puedes crear un máximo de 100 conjuntos de muestras de búsquedas por proyecto y 500 conjuntos de muestras de búsquedas por organización.

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

Formato de conjunto de búsquedas de ejemplo

El conjunto de consultas debe cumplir con el siguiente esquema cuando se construye en formato JSON. El conjunto de búsquedas puede contener varias entradas de búsqueda, con una búsqueda en cada entrada. Cuando se presenta en formato JSON delimitado por saltos de línea (NDJSON), cada entrada de búsqueda 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 redactar 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 búsqueda que se usa para 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 se encuentra 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 búsqueda. Esto es útil cuando el archivo tiene varias páginas.
CDOC_URL: Es un campo opcional para indicar el campo de ID de documento personalizado cdoc_url en los metadatos del documento en el esquema del almacén de datos de Vertex AI Search.

Datos estructurados

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

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

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la búsqueda que se usa para 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 de sitio web

Usa la siguiente plantilla para redactar un archivo de consulta de muestra 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 búsqueda que se usa para evaluar la calidad de la búsqueda.
WEBSITE_URL: Es el sitio web objetivo de la búsqueda.

Este es un ejemplo de un conjunto de muestras de consultas 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"}]}}

Importar desde el sistema de archivos local

En la siguiente sección, se proporcionan las plantillas de conjuntos de búsquedas de ejemplo para importar desde el sistema de archivos local.

Datos no estructurados

Usa la siguiente plantilla para redactar 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 búsqueda que se usa para 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 búsqueda en el archivo PDF. Esto es útil si el archivo tiene varias páginas.
CDOC_URL: Es un campo opcional para indicar el campo de ID de documento personalizado cdoc_url en los metadatos del documento en el esquema del almacén de datos de Vertex AI Search.

Datos estructurados

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

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

Reemplaza lo siguiente:

SAMPLE_QUERY: Es la búsqueda que se usa para 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 de sitio web

Usa la siguiente plantilla para redactar un archivo de consulta de muestra 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 búsqueda que se usa para evaluar la calidad de la búsqueda.
WEBSITE_URL: Es el sitio web objetivo de la búsqueda.

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

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 muestras de consultas.
Importa una consulta de muestra que cumpla con el formato JSON prescrito.
Ejecuta una 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 muestras de preguntas y usarlo para evaluar la calidad de las respuestas de búsqueda de un almacén de datos determinado. Para crear un conjunto de muestras de consultas, haz lo siguiente:

REST

En el siguiente ejemplo, se muestra cómo crear el conjunto de búsquedas de ejemplo 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: Es el ID de tu proyecto de Google Cloud .
SAMPLE_QUERY_SET_ID: Es un ID personalizado para tu conjunto de consultas de ejemplo.
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 consultas de muestra

Después de crear el conjunto de consultas de muestra, importa los datos de las consultas de muestra. Para importar los datos de la 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 Carga datos JSON desde Cloud Storage.
Importa desde tu sistema de archivos local: Crea el conjunto de muestras de consultas en tu sistema de archivos local y, luego, impórtalo.

Cloud Storage

Crea los conjuntos de consultas de muestra que se ajusten al formato de conjunto de consultas de muestra.
Importa el archivo JSON que contiene el conjunto de muestras de consultas 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: Es el ID de tu proyecto de Google Cloud .
- SAMPLE_QUERY_SET_ID: Es el ID personalizado de tu 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 para 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: Toma nota del 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 falla, la respuesta muestra un campo failureCount para indicar la cantidad de búsquedas 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 se ajusten al 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: Es el ID de tu proyecto de Google Cloud .
- SAMPLE_QUERY_SET_ID: Es el ID personalizado de tu 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 tu 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: Toma nota del 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 se ajusten al formato de conjunto de consultas de muestra.
Importa el archivo JSON que contiene el conjunto de muestras de consultas 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: Es el ID de tu proyecto de Google Cloud .
- SAMPLE_QUERY_SET_ID: Es el ID personalizado de tu 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: Toma nota del 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 la consulta de muestra en los conjuntos de consultas de muestra, sigue estos pasos para ejecutar la evaluación de la 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: Es el ID de tu proyecto de Google Cloud .
SAMPLE_QUERY_SET_ID: Es el ID personalizado de tu conjunto de consultas de muestra que definiste durante la creación del conjunto de consultas de muestra.
APP_ID: Es 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: Toma nota del 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: Es el ID de tu proyecto de Google Cloud .
EVALUATION_ID: Es el ID de tu trabajo de evaluación que se devolvió 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: Es el ID de tu proyecto de Google Cloud .
EVALUATION_ID: Es el ID de tu trabajo de evaluación que se devolvió 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"
}

Recupera los resultados a nivel de la búsqueda.

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: Es el ID de tu proyecto de Google Cloud .
EVALUATION_ID: Es el ID de tu trabajo de evaluación que se devolvió 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
        }
      }
   }
 ]
}

Cómo comprender 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 los primeros k resultados. La recuperación es la fracción de documentos pertinentes recuperados de todos los documentos pertinentes. Por ejemplo, el valor `top5` significa lo siguiente: Para una sola búsqueda, si se recuperan 3 de los 5 documentos pertinentes en los primeros 5 resultados, el `docRecall` se puede calcular como 3/5 o 0.6.	La consulta de ejemplo debe contener el campo URI.
`pageRecall`	Recuperación por página, en varios niveles de corte de los primeros k resultados. 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 las 5 páginas relevantes en los primeros 5 resultados, el `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`	Es la ganancia acumulada normalizada y con descuento (NDCG) por documento, en varios niveles de corte de los primeros k resultados. El NDCG mide la calidad de la clasificación y otorga mayor relevancia a los resultados principales. El valor del NDCG se puede calcular para cada búsqueda según el CDG normalizado.	La consulta de ejemplo debe contener el campo URI.
`pageNdcg`	Ganancia acumulada normalizada y con descuento (NDCG) por página, en varios niveles de corte de los primeros k resultados. El NDCG mide la calidad de la clasificación y otorga mayor relevancia a los resultados principales. El valor del NDCG se puede calcular para cada búsqueda según el CDG normalizado.	La consulta de muestra debe contener los campos URI y páginas. Las respuestas extractivas deben estar habilitadas.
`docPrecision`	Es la precisión por documento, en varios niveles de corte de los primeros k resultados. La precisión es la fracción de documentos recuperados que son pertinentes. Por ejemplo, el valor `top3` significa lo siguiente: Para una sola búsqueda, si 4 de los 5 documentos recuperados en los 5 primeros resultados son relevantes, el valor de `docPrecision` se puede calcular como 4/5 o 0.8.	La consulta de ejemplo debe contener el campo URI.

Según 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 general del rendimiento de tu motor de búsqueda.
Revisa los resultados a nivel de la búsqueda:
- Analiza 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:
- Realiza evaluaciones periódicamente para hacer un seguimiento de los cambios en la calidad de la búsqueda a lo largo del tiempo.
- Utiliza 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.

Cómo evaluar la calidad de la búsqueda Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

Motivos para realizar la evaluación

Cuándo realizar la evaluación

Acerca de los conjuntos de consultas de muestra

Propósito de los conjuntos de consultas de muestra

Cuotas y límites

Formato de conjunto de búsquedas de ejemplo

Importa desde BigQuery y Cloud Storage

Datos no estructurados

Datos estructurados

Datos de sitio web

JSON

NDJSON

Importar desde el sistema de archivos local

Datos no estructurados

Datos estructurados

Datos de sitio web

JSON

Proceso para evaluar la calidad de la búsqueda

Antes de comenzar

Crea un conjunto de consultas de muestra

REST

Respuesta

Importa datos de consultas de muestra

Cloud Storage

Respuesta

Respuesta

BigQuery

Respuesta

Respuesta

Sistema de archivos local

Respuesta

Respuesta

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

REST

Respuesta

Respuesta

Respuesta

Respuesta

Cómo comprender los resultados

¿Qué sigue?

Cómo evaluar la calidad de la búsqueda