Method: projects.locations.dataStores.servingConfigs.searchLite

Realiza una búsqueda. Es similar al método SearchService.Search, pero es una versión ligera que permite la clave de API para la autenticación, en la que no se requieren verificaciones de OAuth ni de IAM.

Este método solo admite la búsqueda en sitios web públicos. Si se especifican almacenes de datos y motores que no están asociados con la búsqueda en sitios web públicos, se muestra un error FAILED_PRECONDITION.

Este método se puede usar para una incorporación sencilla sin tener que implementar un backend de autenticación. Sin embargo, se recomienda usar SearchService.Search con las verificaciones obligatorias de OAuth y IAM para brindar una mejor seguridad de los datos.

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta de acceso

Parámetros
servingConfig

string

Obligatorio. Nombre del recurso de la configuración de entrega de servingConfigs.search, 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 entrega, el conjunto de modelos que se usan para realizar la búsqueda.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con 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 del recurso de la rama, como projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

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

query

string

Es la búsqueda sin procesar.

imageQuery

object (ImageQuery)

Es la búsqueda de imágenes sin procesar.

pageSize

integer

Cantidad máxima de Documents que se devolverán. El valor máximo permitido depende del tipo de datos. Los valores superiores al valor máximo se convierten al valor máximo.

  • Sitios web con indexación básica: 10 predeterminado y 25 máximo.
  • Sitios web con indexación avanzada: Predeterminado 25, Máximo 50.
  • Otro: El valor predeterminado es 50 y el máximo es 100.

Si este campo es negativo, se devuelve un INVALID_ARGUMENT.

pageToken

string

Es un token de página que se recibió de una llamada a SearchService.Search anterior. Proporciona esto para recuperar la página siguiente.

Cuando se pagina, todos los demás parámetros proporcionados a SearchService.Search deben coincidir con la llamada que proporcionó el token de la página. De lo contrario, se muestra un error INVALID_ARGUMENT.

offset

integer

Es un número entero con índice 0 que especifica la compensación actual (es decir, la ubicación del resultado inicial, entre los Documents que la API considera relevantes) en los resultados de la búsqueda. Este campo solo se tiene en cuenta si pageToken no está configurado.

Si este campo es negativo, se devuelve un INVALID_ARGUMENT.

Un desfase grande puede limitarse a un umbral razonable.

oneBoxPageSize

integer

Es la cantidad máxima de resultados que se devolverán para OneBox. Esto se aplica a cada tipo de OneBox de forma individual. La cantidad predeterminada es 10.

dataStoreSpecs[]

object (DataStoreSpec)

Son especificaciones que definen los DataStores específicos que se buscarán, junto con las configuraciones de esos almacenes de datos. Esto solo se considera para los Engines con varios almacenes de datos. Para los motores con un solo almacén de datos, se deben usar las especificaciones directamente debajo de SearchRequest.

filter

string

La sintaxis del filtro consta de un lenguaje de expresión para construir un predicado a partir de uno o más campos de los documentos que se filtran. La expresión del filtro distingue mayúsculas de minúsculas.

Si este campo no se puede reconocer, se devuelve un INVALID_ARGUMENT.

El filtrado en Vertex AI servingConfigs.search se realiza asignando la clave del 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 podría tener un campo "nombre" en su esquema. En este caso, el filtro se vería de la siguiente manera: filter --> name:'ANY("king kong")'

Para obtener más información sobre los filtros, incluidos los operadores y la sintaxis de filtros, consulta Filtro.

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.

Es el filtro que se aplica a cada solicitud de búsqueda cuando se necesita una mejora de la calidad, como la búsqueda expandida. En el caso de que una búsqueda no tenga una cantidad suficiente de resultados, se usará este filtro para determinar si se habilita o no el flujo de búsqueda expandida. El filtro original se seguirá usando para la búsqueda expandida de la consulta. Se recomienda encarecidamente usar este campo para lograr una alta calidad de búsqueda.

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

orderBy

string

Es el orden en que se muestran los documentos. Los documentos se pueden ordenar por un campo en un objeto Document. Déjalo sin configurar si se ordena por relevancia. La expresión orderBy distingue mayúsculas de minúsculas.

Para obtener más información sobre cómo ordenar los resultados de la búsqueda en el sitio web, consulta Cómo ordenar los resultados de la búsqueda web. Para obtener más información sobre el orden de los resultados de la búsqueda de atención médica, consulta Cómo ordenar los resultados de la búsqueda de atención médica. Si este campo no se puede reconocer, se devuelve un INVALID_ARGUMENT.

userInfo

object (UserInfo)

Es la información sobre el usuario final. Se recomienda para las estadísticas y la personalización. UserInfo.user_agent se usa para deducir deviceType para las estadísticas.

languageCode

string

El 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 búsqueda. Si no se especifica un valor, el código de idioma de la búsqueda se detecta automáticamente, lo que puede no ser preciso.

facetSpecs[]

object (FacetSpec)

Son las especificaciones de facetas para la búsqueda por facetas. Si está vacío, no se devuelven facetas.

Se permite un máximo de 100 valores. De lo contrario, se muestra un error INVALID_ARGUMENT.

boostSpec

object (BoostSpec)

Especificación de refuerzo para reforzar ciertos documentos. Para obtener más información sobre el aumento, consulta Aumento.

params

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

Son parámetros de búsqueda adicionales.

Solo para la búsqueda en sitios web públicos, los valores admitidos son los siguientes:

  • user_country_code: cadena. El valor predeterminado es vacío. Si se establece como no vacío, los resultados se restringen o se potencian según la ubicación proporcionada. Por ejemplo, user_country_code: "au"

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

  • searchType: double. El valor predeterminado es vacío. Habilita la búsqueda que no es de páginas web según el 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)

Es la especificación de búsqueda expandida que indica las condiciones en las que se produce la búsqueda expandida.

spellCorrectionSpec

object (SpellCorrectionSpec)

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

userPseudoId

string

Es un identificador único para hacer un seguimiento de los visitantes. Por ejemplo, esto 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 debe cambiar si el visitante accede al sitio web o sale de él.

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 muestra un error INVALID_ARGUMENT.

contentSearchSpec

object (ContentSearchSpec)

Es 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 recuperados. Esto anula ServingConfig.ranking_expression. La sintaxis y las funciones admitidas dependen del valor de rankingExpressionBackend. Si no se proporciona rankingExpressionBackend, el valor predeterminado es RANK_BY_EMBEDDING.

Si no se proporciona rankingExpressionBackend o se establece en RANK_BY_EMBEDDING, debe ser una sola función o varias funciones unidas por "+".

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

Funciones compatibles:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Variables de función:

  • relevanceScore: Son palabras clave predefinidas que se usan para medir la relevancia entre la búsqueda y el documento.
  • embedding_field_path: Es el campo de incorporación de documentos que se usa con el vector de incorporación de la búsqueda.
  • dotProduct: Es la función de embedding entre embedding_field_path y el vector de embedding de la búsqueda.

Ejemplo de expresión de clasificación:

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

Si rankingExpressionBackend se configura como RANK_BY_FORMULA, se admiten los siguientes tipos de expresiones (y combinaciones de esos tipos encadenados con los operadores + o *):

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0): Es una transformación del rango recíproco en la que el segundo argumento es una constante del denominador.
  • isNan(signal): Muestra 0 si el indicador 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): Principalmente, se clasifica según el logaritmo de keywordSimilarityScore con un pequeño ajuste de semantic_smilarity_score.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore): Clasifica según el exponente de semanticSimilarityScore y completa el valor con 0 si es NaN. También agrega 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): Principalmente, se clasifica según la clasificación recíproca de keywordSimilarityScore con un pequeño ajuste de la clasificación recíproca de semantic_smilarity_score.

Se admiten los siguientes indicadores:

  • semanticSimilarityScore: Ajuste de similitud semántica que se calcula con los embeddings generados por un modelo propietario de Google. Esta puntuación determina qué tan similar semánticamente es una búsqueda a 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 con un modelo probabilístico para estimar la probabilidad de que un documento sea pertinente para una búsqueda determinada.
  • relevanceScore: Ajuste de relevancia semántica que usa un modelo propietario de Google para determinar el significado y la intención detrás de la búsqueda de un usuario en el contexto del contenido de los documentos.
  • pctrRank: Ajuste del porcentaje de conversiones previsto como uso del ranking. El porcentaje de clics previsto (pCTR) se utiliza para medir la relevancia y el atractivo de un resultado de la búsqueda desde la perspectiva del usuario. Un pCTR más alto sugiere que es más probable que el resultado satisfaga la búsqueda y la intención del usuario, lo que lo convierte en un indicador valioso para la clasificación.
  • freshnessRank: Ajuste de actualidad como un ranking
  • documentAge: Es el tiempo en horas transcurrido desde la última actualización del documento, un número de punto flotante (p.ej., 0.25 significa 15 minutos.
  • topicalityRank: Ajuste de la relevancia del tema como una clasificación. Usa el modelo propietario de Google para determinar la superposición basada en palabras clave entre la búsqueda y el documento.
  • baseRank: Es el rango predeterminado del resultado.
rankingExpressionBackend

enum (RankingExpressionBackend)

Opcional. Es el backend que se usará para la evaluación de la expresión de clasificación.

userLabels

map (key: string, value: string)

Las etiquetas de usuario que se aplican a un recurso deben cumplir con los siguientes requisitos:

  • Cada recurso puede tener varias etiquetas, hasta 64.
  • Cada etiqueta debe ser un par clave-valor.
  • Las claves deben tener 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 su longitud máxima es de 63 caracteres.
  • Las claves y los valores solo pueden contener letras en minúscula, números, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales.
  • La porción de clave de una etiqueta debe ser única. Sin embargo, puedes usar la misma clave en varios recursos.
  • Las claves deben comenzar con una letra en minúscula o un carácter internacional.

Consulta Google Cloud Document para obtener más detalles.

naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Opcional. Es la configuración para las capacidades de comprensión de consultas de 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 realizará ninguna comprensión adicional de la búsqueda en lenguaje natural.

searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

Es la configuración de servingConfigs.search mientras escribes. Solo se admite para la vertical de IndustryVertical.MEDIA.

displaySpec

object (DisplaySpec)

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

session

string

Es el nombre del recurso de sesión. Opcional.

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

Ejemplo 1 (llamadas a la API de /search de varios turnos): Llama a la API de /search con el ID de sesión generado en la primera llamada. Aquí, la búsqueda anterior se considera en la posición de la consulta. Es decir, si la primera búsqueda es "¿Cómo le fue a Alphabet en 2022?". y la búsqueda actual es "¿Qué tal 2023?", se interpretará como "¿Cómo le fue a Alphabet en 2023?".

Ejemplo 2 (coordinación entre las llamadas a la API de /search y las llamadas a la API de /answer): Llama a la API de /answer con el ID de sesión generado en la primera llamada. Aquí, la generación de respuestas se produce en el contexto de los resultados de la búsqueda de la primera llamada de búsqueda.

Actualmente, la función Multi-turn servingConfigs.search se encuentra en la etapa de DG privada. Usa la versión v1alpha o v1beta antes de que lancemos esta función para la DG pública, o bien solicita que se agregue a la lista de entidades permitidas a través del equipo de Atención al cliente de Google.

sessionSpec

object (SessionSpec)

Es la especificación de la sesión.

Solo se puede usar cuando se establece session.

relevanceThreshold

enum (RelevanceThreshold)

Es el umbral de relevancia de los resultados de la búsqueda.

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

Esta función no es compatible con la búsqueda de atención médica.

relevanceScoreSpec

object (RelevanceScoreSpec)

Opcional. Es la especificación para devolver la puntuación de relevancia.

Cuerpo de la respuesta

Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de SearchResponse.

Alcances de autorización

Se necesita 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 Authentication Overview.