Method: projects.locations.dataStores.servingConfigs.search

Realiza una búsqueda.

Solicitud HTTP

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/dataStores/*/servingConfigs/*}:search

La URL utiliza la sintaxis de transcodificación a gRPC.

Parámetros de ruta

Parámetros
servingConfig

string

Obligatorio. Nombre del recurso de la configuración de publicación de la búsqueda servingConfigs, como projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config o projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. Este campo se usa para identificar el nombre de la configuración de servicio, el conjunto de modelos que se usan para hacer la búsqueda.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos que presentan la siguiente estructura:

Representación JSON 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  }
}
Campos
branch

string

Nombre de recurso de la sucursal, como projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

Usa default_branch como ID de rama o deja este campo vacío para buscar documentos en la rama predeterminada.
query

string

Consulta de búsqueda sin procesar.
imageQuery

object (ImageQuery)

Consulta de imagen RAW.
pageSize

integer

Número máximo de Documents que se devolverán. El valor máximo permitido depende del tipo de datos. Los valores superiores al valor máximo se convertirán al valor máximo.

  • Sitios web con indexación básica: Predeterminado 10 y Máximo 25.
  • Sitios web con indexación avanzada: Predeterminado 25 y Máximo 50.
  • Otros: predeterminado 50 y máximo 100.

Si este campo es negativo, se devuelve un error INVALID_ARGUMENT.
pageToken

string

Un token de página recibido de una llamada SearchService.Search anterior. Proporciona este elemento para obtener la siguiente página.

Al hacer la paginación, todos los demás parámetros proporcionados a SearchService.Search deben ser los mismos que aparecen en la llamada que proporcionó el token de la página. De lo contrario, se devuelve un error INVALID_ARGUMENT.
offset

integer

Un número entero indexado en 0 que especifica el desplazamiento actual (es decir, la ubicación del resultado inicial, entre los Documents que la API considera relevantes) en los resultados de búsqueda. Este campo solo se tiene en cuenta si pageToken no está definido.

Si este campo es negativo, se devuelve un error INVALID_ARGUMENT.

Es posible que se limite un desplazamiento grande a un umbral razonable.
oneBoxPageSize

integer

Número máximo de resultados que se devolverán para OneBox. Esto se aplica a cada tipo de OneBox de forma individual. El número predeterminado es 10.
dataStoreSpecs[]

object (DataStoreSpec)

Especificaciones que definen los DataStores concretos que se van a buscar, junto con las configuraciones de esos almacenes de datos. Esto solo se tiene en cuenta en los Engines con varios almacenes de datos. En el caso de los buscadores con un solo almacén de datos, deben usarse las especificaciones que se encuentran directamente en SearchRequest.
filter

string

La sintaxis del filtro consta de un lenguaje de expresiones para crear un predicado a partir de uno o varios campos de los documentos que se van a filtrar. La expresión de filtro distingue entre mayúsculas y minúsculas.

Si este campo no se reconoce, se devuelve un INVALID_ARGUMENT.

El filtrado en Vertex AI servingConfigs.search se realiza asignando la clave de filtro del lado izquierdo a una propiedad de clave definida en el backend de Vertex AI servingConfigs.search. El cliente define esta asignación en su esquema. Por ejemplo, un cliente de medios puede tener un campo "nombre" en su esquema. En este caso, el filtro sería el siguiente: filter --> name:'ANY("king kong")'

Para obtener más información sobre el filtrado, incluida la sintaxis y los operadores de filtro, consulta Filtrar.
canonicalFilter

string

Es el filtro predeterminado que se aplica cuando un usuario realiza una búsqueda sin marcar ningún filtro en la página de búsqueda.

Filtro que se aplica a cada solicitud de búsqueda cuando se necesita mejorar la calidad, por ejemplo, ampliando la consulta. Si una consulta no tiene una cantidad suficiente de resultados, se usará este filtro para determinar si se debe habilitar el flujo de ampliación de la consulta. El filtro original se seguirá usando en la búsqueda ampliada de la consulta. Se recomienda incluir este campo para conseguir una calidad de búsqueda alta.

Para obtener más información sobre la sintaxis de los filtros, consulta SearchRequest.filter.
orderBy

string

El orden en el que se devuelven los documentos. Los documentos se pueden ordenar por un campo de un objeto Document. Déjalo sin definir si los resultados se ordenan por relevancia. La expresión orderBy distingue entre mayúsculas y minúsculas.

Para obtener más información sobre cómo ordenar los resultados de búsqueda de sitios web, consulta el artículo Ordenar resultados de búsqueda web. Para obtener más información sobre cómo ordenar los resultados de búsqueda de atención sanitaria, consulta el artículo Ordenar resultados de búsqueda de atención sanitaria. Si este campo no se reconoce, se devuelve un INVALID_ARGUMENT.
userInfo

object (UserInfo)

Información sobre el usuario final. Muy recomendable para analíticas y personalización. UserInfo.user_agent se usa para deducir deviceType con fines analíticos.
languageCode

string

Se trata del código de idioma BCP-47, como "en-US" o "sr-Latn". Para obtener más información, consulta Campos estándar. Este campo ayuda a interpretar mejor la consulta. Si no se especifica ningún valor, el código de idioma de la consulta se detecta automáticamente, pero puede que no sea preciso.
facetSpecs[]

object (FacetSpec)

Especificaciones de facetas para la búsqueda por facetas. Si está vacío, no se devuelve ninguna faceta.

Se permiten un máximo de 100 valores. De lo contrario, se devuelve un error INVALID_ARGUMENT.
boostSpec

object (BoostSpec)

Aumenta la especificación para destacar determinados documentos. Para obtener más información sobre el aumento, consulta Aumento.
params

map (key: string, value: value (Value format))

Parámetros de búsqueda adicionales.

En el caso de la búsqueda en sitios web públicos, los valores admitidos son los siguientes:

  • user_country_code: cadena. El valor predeterminado es una cadena vacía. Si se define un valor no vacío, los resultados se restringen o se impulsan en función de la ubicación proporcionada. Por ejemplo, user_country_code: "au"

Para ver los códigos disponibles, consulta Códigos de país.

  • searchType: doble. El valor predeterminado es una cadena vacía. Habilita la búsqueda de contenido que no sea de páginas web en función del valor. El único valor no predeterminado válido es 1, que habilita la búsqueda de imágenes. Por ejemplo, searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

Especificación de ampliación de consultas que indica las condiciones en las que se produce la ampliación de consultas.
spellCorrectionSpec

object (SpellCorrectionSpec)

La especificación de corrección ortográfica que indica el modo en el que se aplica la corrección ortográfica.
userPseudoId

string

Identificador único para hacer un seguimiento de los visitantes. Por ejemplo, se podría implementar con una cookie HTTP, que debería poder identificar de forma única a un visitante en un solo dispositivo. Este identificador único no debería cambiar si el visitante inicia o cierra sesión en el sitio web.

Este campo NO debe tener un valor fijo, como unknown_visitor.

Debe ser el mismo identificador que UserEvent.user_pseudo_id y CompleteQueryRequest.user_pseudo_id.

El campo debe ser una cadena codificada en UTF-8 con un límite de 128 caracteres. De lo contrario, se devuelve un error INVALID_ARGUMENT.
contentSearchSpec

object (ContentSearchSpec)

Una especificación para configurar el comportamiento de la búsqueda de contenido.
rankingExpression

string

Opcional. La expresión de clasificación controla la clasificación personalizada de los documentos de recuperación. Esto anula ServingConfig.ranking_expression. La sintaxis y las funciones admitidas dependen del valor de rankingExpressionBackend. Si no se proporciona rankingExpressionBackend, se utiliza RANK_BY_EMBEDDING de forma predeterminada.

Si no se proporciona rankingExpressionBackend o se le asigna el valor RANK_BY_EMBEDDING, debe ser una sola función o varias funciones unidas por el signo "+".

  • rankingExpression = function, { " + ", function };

Funciones admitidas:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Variables de función:

  • relevanceScore: palabras clave predefinidas que se usan para medir la relevancia entre la consulta y el documento.
  • embedding_field_path: el campo de inserción de documentos que se usa con el vector de inserción de consultas.
  • dotProduct: función de incrustación entre embedding_field_path y el vector de incrustación de la consulta.

Expresión de clasificación de ejemplo:

Si el documento tiene un campo de inserción doc_embedding, la expresión de clasificación podría ser 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding).

Si rankingExpressionBackend tiene el valor RANK_BY_FORMULA, se admiten los siguientes tipos de expresiones (y las combinaciones de esas expresiones encadenadas mediante los operadores + o *):

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0): transformación de rango recíproco con el segundo argumento como constante de denominador.
  • isNan(signal): devuelve 0 si la señal es NaN y 1 en caso contrario.
  • fillNan(signal1, signal2 | double) -- si signal1 es NaN, devuelve signal2 | double; de lo contrario, devuelve signal1.

A continuación, se muestran algunos ejemplos de fórmulas de clasificación que usan los tipos de expresiones de clasificación admitidos:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore): se ordena principalmente por el logaritmo de keywordSimilarityScore con un ligero ajuste de semantic_smilarity_score.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) -- ordena por el exponente de semanticSimilarityScore. Si el valor es NaN, se sustituye por 0. También se añade un ajuste constante de 0,3 a la puntuación final si semanticSimilarityScore es NaN.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16): se ordena principalmente por el rango recíproco de keywordSimilarityScore con un ligero ajuste del rango recíproco de semantic_smilarity_score.

Se admiten las siguientes señales:

  • semanticSimilarityScore: ajuste de la similitud semántica que se calcula mediante las inserciones generadas por un modelo propietario de Google. Esta puntuación determina el grado de similitud semántica entre una consulta de búsqueda y un documento.
  • keywordSimilarityScore: el ajuste de la concordancia de palabras clave usa la función de clasificación Best Match 25 (BM25). Esta puntuación se calcula mediante un modelo probabilístico para estimar la probabilidad de que un documento sea pertinente para una consulta determinada.
  • relevanceScore: ajuste de relevancia semántica que usa un modelo propietario de Google para determinar el significado y la intención de la consulta de un usuario en el contexto del contenido de los documentos.
  • pctrRank: ajuste de la tasa de conversión prevista como uso de la clasificación. Se usa el porcentaje de clics previsto (pCTR) para medir la relevancia y el atractivo de un resultado de búsqueda desde el punto de vista del usuario. Un pCTR más alto sugiere que es más probable que el resultado satisfaga la consulta y la intención del usuario, por lo que es una señal valiosa para el ranking.
  • freshnessRank: ajuste de la actualización como clasificación
  • documentAge: tiempo transcurrido en horas desde la última actualización del documento. Es un número de coma flotante (por ejemplo, 0,25 significa 15 minutos).
  • topicalityRank: ajuste de la actualidad como factor de clasificación. Usa un modelo propietario de Google para determinar la superposición basada en palabras clave entre la consulta y el documento.
  • baseRank: el rango predeterminado del resultado
rankingExpressionBackend

enum (RankingExpressionBackend)

Opcional. Backend que se va a usar para la evaluación de la expresión de clasificación.
userLabels

map (key: string, value: string)

Las etiquetas de usuario aplicadas a un recurso deben cumplir los siguientes requisitos:

  • Cada recurso puede tener varias etiquetas, hasta un máximo de 64.
  • Cada etiqueta debe ser un par clave-valor.
  • Las claves tienen una longitud mínima de 1 carácter y una longitud máxima de 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y tener una longitud máxima de 63 caracteres.
  • Las claves y los valores solo pueden contener letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se pueden utilizar caracteres internacionales.
  • La parte de la clave de una etiqueta debe ser única. Sin embargo, puedes usar la misma clave con varios recursos.
  • Las claves deben empezar por una letra minúscula o un carácter internacional.

Consulta más información en el documento de Google Cloud.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Opcional. Configuración de las funciones de comprensión de consultas en lenguaje natural, como la extracción de filtros de campos estructurados de la consulta. Consulta esta documentación para obtener más información. Si no se especifica naturalLanguageQueryUnderstandingSpec, no se hará ninguna otra consulta en lenguaje natural.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search como configuración de escritura. Solo se admite en el vertical IndustryVertical.MEDIA.
displaySpec

object (DisplaySpec)

Opcional. Configuración de la función de visualización, como el resaltado de coincidencias en los resultados de búsqueda.
session

string

Nombre de recurso de la sesión. Opcional.

La sesión permite a los usuarios hacer llamadas a la API /search de varias fases o coordinar llamadas a la API /search y a la API /answer.

Ejemplo 1 (llamadas a la API /search de varias interacciones): llama a la API /search con el ID de sesión generado en la primera llamada. En este caso, la consulta de búsqueda anterior se tiene en cuenta en la posición de la consulta. Es decir, si la primera consulta es "¿Cómo le fue a Alphabet en el 2022?". y la consulta actual es "¿Y en el 2023?", se interpretará como "¿Cómo le fue a Alphabet en el 2023?".

Ejemplo 2 (coordinación entre llamadas a la API /search y llamadas a la API /answer): llama a la API /answer con el ID de sesión generado en la primera llamada. En este caso, la respuesta se genera en el contexto de los resultados de búsqueda de la primera llamada de búsqueda.

La función Multi-turn servingConfigs.search se encuentra en la fase de disponibilidad general privada. Usa la versión v1alpha o v1beta antes de que lancemos esta función para el público general. También puedes solicitar que se te incluya en la lista de permitidos a través del equipo de Asistencia de Google.
sessionSpec

object (SessionSpec)

Especificación de la sesión.

Solo se puede usar cuando se ha definido session.
relevanceThreshold

enum (RelevanceThreshold)

El umbral de relevancia de los resultados de búsqueda.

Se usa el umbral definido por Google, que aprovecha el equilibrio entre la precisión y la recuperación para ofrecer resultados muy precisos y una cobertura completa de la información pertinente.

Esta función no está disponible para las búsquedas relacionadas con la salud.
relevanceScoreSpec

object (RelevanceScoreSpec)

Opcional. Especificación para devolver la puntuación de relevancia.

Cuerpo de la respuesta

Si la solicitud se hace correctamente, en el cuerpo de la respuesta se incluye una instancia de SearchResponse.

Permisos de autorización

Debes disponer de uno de los siguientes permisos de OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

Para obtener más información, consulta el Authentication Overview.

Permisos de IAM

Requiere el siguiente permiso de gestión de identidades y accesos en el recurso servingConfig:

  • discoveryengine.servingConfigs.search

Para obtener más información, consulta la documentación de gestión de identidades y accesos.