En esta página, se muestra cómo obtener una vista previa de los resultados de la búsqueda con la consola y cómo obtener resultados de la búsqueda con la API. Google Cloud
Además, en lugar de crear un widget de búsqueda para agregarlo a tu página web, puedes realizar llamadas a la API e integrar esas llamadas a tu servidor o aplicación. En esta página, se incluyen muestras de código para realizar búsquedas con las bibliotecas cliente de gRPC y una cuenta de servicio.
Cómo obtener resultados de la búsqueda de una app con datos de sitios web
Console
Para usar la consola de Google Cloud y obtener una vista previa de los resultados de la búsqueda de una app con datos del sitio web, sigue estos pasos:
En la consola de Google Cloud , ve a la página AI Applications.
Haz clic en el nombre de la app que deseas editar.
Haz clic en Vista previa.
Abre la página Preview en la consola.
Opcional: Si conectaste varios almacenes de datos a tu app, pero solo quieres obtener resultados de un almacén de datos específico, selecciónalo.
Escribe una búsqueda.
Si habilitaste el autocompletado, aparecerá una lista de sugerencias debajo de la barra de búsqueda a medida que escribas.
Presiona Intro para enviar la consulta.
- Debajo de la barra de búsqueda, aparece una lista de resultados.
- Cada resultado contiene un título, un fragmento y una URL.
- Si haces clic en un resultado, se abrirá esa URL.
- Si las funciones avanzadas de LLM están habilitadas para la app, también podría aparecer una respuesta generada.
REST
Para usar la API y obtener resultados de la búsqueda de una app con datos del sitio web, usa el método engines.servingConfigs.search
:
Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.
En la consola de Google Cloud , ve a la página AI Applications.
Ve a Apps.
En la página Apps, busca el nombre de tu app y obtén su ID en la columna ID.
Obtener resultados de la búsqueda
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "params": {"user_country_code": "USER_COUNTRY_CODE", "searchType": "SEARCH_TYPE"}, "filter": "FILTER", "boostSpec": "BOOST_SPEC", "contentSearchSpec": { "searchResultMode": "RESULT_MODE" }, "dataStoreSpecs": [{"DATA_STORE_SPEC"}] }'
Reemplaza lo siguiente:
PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .APP_ID
: Es el ID de la app de Vertex AI Search que deseas consultar.QUERY
: Es el texto de la búsqueda.PAGE_SIZE
: Es la cantidad de resultados que muestra la búsqueda. El tamaño de página máximo permitido depende del tipo de datos. Los tamaños de página superiores al valor máximo se convertirán al valor máximo.- Sitios web con indexación básica: Predeterminado
10
, máximo25
- Sitios web con indexación avanzada: Predeterminado
25
, máximo50
- Otro: Valor predeterminado
50
, máximo100
- Sitios web con indexación básica: Predeterminado
OFFSET
: Es el índice inicial de los resultados. El valor predeterminado es 0.Por ejemplo, si el desplazamiento es 2, el tamaño de la página es 10 y hay 15 resultados para devolver, los resultados del 2 al 12 se devuelven en la primera página.
ORDER_BY
: Es el orden en el que se organizan los resultados. El atributo según el cual se ordena debe tener una interpretación numérica; por ejemplo,date
. Para obtener más información, consulta Cómo ordenar los resultados de la búsqueda web.USER_COUNTRY_CODE
: Es la ubicación del usuario. Este par clave-valor es la única entrada admitida para el campo del mapaparams
. El valor predeterminado es vacío. Para conocer los valores aceptables, consulta Códigos de país en la documentación de referencia de la API de JSON del Motor de Búsqueda Programable.SEARCH_TYPE
: Es el tipo de búsqueda que se realizará. El valor predeterminado es 0 para la búsqueda de documentos. El otro valor admitido es 1 para la búsqueda de imágenes.FILTER
: Un campo de texto para filtrar tu búsqueda con una expresión de filtro. El valor predeterminado es una string vacía. Para obtener más información sobre el uso del campofilter
, consulta Cómo filtrar la búsqueda en el sitio web.BOOST_SPEC
: es opcional. Es una especificación para aumentar o disminuir la visibilidad de los documentos. Valores:BOOST
: un número de punto flotante en el rango [-1,1]. Cuando el valor es negativo, los resultados se degradan (aparecen más abajo en los resultados). Cuando el valor es positivo, los resultados se promocionan (aparecen más arriba en los resultados).CONDITION
: Es una expresión de filtro de texto para seleccionar los documentos a los que se aplica el refuerzo. El filtro debe evaluarse como un valor booleano. Para obtener información sobre el aumento de la búsqueda estructurada, consulta Aumenta los resultados de la búsqueda.
RESULT_MODE
: Determina si los resultados de la búsqueda se muestran como documentos completos o en fragmentos. Para obtener fragmentos, el almacén de datos debe tener activada la fragmentación de documentos. Los valores aceptados sondocuments
ychunks
. Cuando la fragmentación está activada para un almacén de datos, el valor predeterminado eschunks
. De lo contrario, el valor predeterminado esdocuments
. Para obtener información sobre la división de documentos en fragmentos, consulta Cómo analizar y dividir documentos en fragmentos. Este campo está en versión preliminar pública. Para usarlo, cambiav1
av1alpha
en el comando curl.DATA_STORE_SPEC
: Filtra un almacén de datos específico en el que se realizará la búsqueda. UsadataStoreSpecs
si tu app de búsqueda está conectada a varios almacenes de datos, pero quieres obtener resultados de un almacén de datos específico. Para obtener más información, consulta DataStoreSpec.
C#
Para obtener más información, consulta la documentación de referencia de la API de AI Applications C#.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Java.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Node.js.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para obtener más información, consulta la documentación de referencia de la API de AI Applications PHP.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Python.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Ruby.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Obtén resultados de la búsqueda de una app con datos de sitios web (clave de API)
Si deseas autenticar la llamada de método de búsqueda con una clave de API en lugar de usar OAuth 2.0 a través de una cuenta de servicio o una cuenta de usuario, sigue este procedimiento, que usa el método searchLite
.
El método searchLite
tiene las mismas funciones que el método search
, excepto que solo se puede usar para buscar sitios web públicos.
El método searchLite
es especialmente adecuado en las siguientes condiciones:
Tienes un sitio web estático para el que no es práctico configurar OAuth 2.0 a través de una cuenta de servicio o una cuenta de usuario.
Migraste a Vertex AI Search desde la API de Custom Search Site Restricted JSON del Motor de Búsqueda Programable.
No quieres usar el widget de búsqueda.
Antes de comenzar
Antes de llamar al método servingConfigs.searchLite
, necesitas una clave de API. Si no tienes una clave de API, completa el paso 1 de Implementa la app de búsqueda (clave de API).
Procedimiento
REST
Para usar la API y obtener resultados de la búsqueda de una app con datos de sitios web públicos autenticados con una clave de API, usa el método engines.servingConfigs.searchLite
:
Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.
En la consola de Google Cloud , ve a la página AI Applications.
Ve a Apps.
En la página Apps, busca el nombre de tu app y obtén su ID en la columna ID.
Ejecuta el siguiente comando de curl para obtener resultados de la búsqueda:
curl -X POST -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:searchLite?key=API_KEY" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", }'
Reemplaza lo siguiente:
PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .API_KEY
: Es la cadena de tu clave de API.PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .APP_ID
: Es el ID de la app de Vertex AI Search que deseas consultar.QUERY
: Es el texto de la búsqueda.
Python
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Python.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Obtén resultados de la búsqueda para una app con datos estructurados o no estructurados
Puedes obtener una vista previa de los resultados de la búsqueda desde la consola de Google Cloud o con la API.
Console
Para usar la consola de Google Cloud y obtener una vista previa de los resultados de la búsqueda de una app con datos estructurados o no estructurados, sigue estos pasos:
- Abre la página Preview en la consola.
Escribe una búsqueda.
Si habilitaste el autocompletado, aparecerá una lista de sugerencias debajo de la barra de búsqueda a medida que escribas.
(Opcional) Si conectaste varios almacenes de datos a tu app, pero solo quieres obtener resultados de uno específico, selecciónalo.
Presiona Intro para enviar la consulta.
Debajo de la barra de búsqueda, aparece una lista de resultados.
En el caso de los datos estructurados, se aplican las siguientes condiciones:
Si las asignaciones de atributos no se definen en Configuraciones > Configurar campos en los resultados, los resultados de la búsqueda se muestran como una lista de nombres y valores de atributos sin procesar.
Si se guardó alguna asignación de atributos en Configuraciones > Configurar campos en los resultados, los resultados de la búsqueda se mostrarán de la misma manera que en la vista previa de la página Configuraciones.
Si se especificaron facetas en Configuración > Configuración de facetas, se mostrarán de la misma manera.
REST
Para usar la API y obtener resultados de la búsqueda para una app con datos estructurados o no estructurados, usa el método engines.servingConfigs.search
:
Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.
En la consola de Google Cloud , ve a la página AI Applications.
Ve a Apps.
En la página Apps, busca el nombre de tu app y obtén su ID en la columna ID.
Obtener resultados de la búsqueda
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "userPseudoId": "USER_PSEUDO_ID", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "filter": "FILTER", "boostSpec": "BOOST_SPEC", "facetSpec": "FACET_SPEC", "queryExpansionSpec": "QUERY_EXPANSION_SPEC", "spellCorrectionSpec": "SPELL_CORRECTION_SPEC", "contentSearchSpec": "CONTENT_SEARCH_SPEC", "dataStoreSpecs": [{"DATA_STORE_SPEC"}], }'
Reemplaza lo siguiente:
PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .APP_ID
: Es el ID de la app de Vertex AI Search que deseas consultar.QUERY
: Es el texto de la búsqueda.USER_PSEUDO_ID
: es opcional. Es un identificador seudonimizado para hacer un seguimiento de un visitante de la búsqueda. Google recomienda enfáticamente usar este campo, ya que mejora el rendimiento del modelo y la calidad de la personalización. Puedes usar una cookie HTTP para este campo, que identifica de forma única a un visitante en un solo dispositivo. Este identificador no cambia cuando el visitante accede a un sitio web o sale de él. No establezcas este campo con el mismo identificador para varios usuarios, ya que esto combinaría sus historiales de eventos y degradaría la calidad del modelo. No incluyas información de identificación personal (PII) en este campo.PAGE_SIZE
: Es la cantidad de resultados que muestra la búsqueda. El tamaño de página máximo permitido depende del tipo de datos. Los tamaños de página superiores al valor máximo se fuerzan al valor máximo.- Sitios web con indexación básica: Predeterminado
10
, máximo25
- Sitios web con indexación avanzada: Predeterminado
25
, máximo50
- Otro: Valor predeterminado
50
, máximo100
- Sitios web con indexación básica: Predeterminado
OFFSET
: es opcional. Es el índice inicial de los resultados. El valor predeterminado es 0.Por ejemplo, si el desplazamiento es 2, el tamaño de la página es 10 y hay 15 resultados para devolver, los resultados del 2 al 11 se devuelven en la primera página.
ORDER_BY
: es opcional. Es el orden en el que se organizan los resultados.FILTER
: es opcional. Es un campo de texto para filtrar tu búsqueda con una expresión de filtro. El valor predeterminado es una cadena vacía, lo que significa que no se aplica ningún filtro.Ejemplo:
color: ANY("red", "blue") AND score: IN(*, 100.0e)
Para obtener más información, consulta Cómo filtrar la búsqueda de datos estructurados o no estructurados.
BOOST_SPEC
: es opcional. Es una especificación para potenciar o enterrar documentos. Valores:BOOST
: un número de punto flotante en el rango [-1,1]. Cuando el valor es negativo, los resultados se degradan (aparecen más abajo en los resultados). Cuando el valor es positivo, los resultados se promocionan (aparecen más arriba en los resultados).CONDITION
: Es una expresión de filtro de texto para seleccionar los documentos a los que se aplica el refuerzo. El filtro debe evaluarse como un valor booleano.
Para obtener información sobre el aumento de la búsqueda estructurada, consulta Aumenta los resultados de la búsqueda.
FACET_SPEC
: es opcional. Es una especificación de faceta para realizar una búsqueda por facetas.QUERY_EXPANSION_SPEC
: es opcional. Es una especificación para determinar en qué condiciones debe ocurrir la búsqueda expandida. El valor predeterminado esDISABLED
.SPELL_CORRECTION_SPEC
: es opcional. Es una especificación para determinar en qué condiciones se debe realizar la corrección ortográfica. El valor predeterminado esAUTO
.CONTENT_SEARCH_SPEC
: es opcional. Para obtener resúmenes, respuestas extractivas, segmentos extractivos y resúmenes de búsqueda. Solo para datos no estructurados. Para obtener más información, consulte:DATA_STORE_SPEC
: Filtra un almacén de datos específico en el que se realizará la búsqueda. Se puede usar si tu app de búsqueda está conectada a varios almacenes de datos.Cómo ver los resultados de la búsqueda guiada en la respuesta de búsqueda:
Los resultados de la búsqueda guiada se muestran con las respuestas de búsqueda para la búsqueda estructurada y no estructurada. El resultado de la búsqueda guiada contiene una lista de pares clave-valor de atributos extraídos según los documentos de resultados de la búsqueda. Esto permite que los usuarios definan mejor sus resultados de búsqueda usando algunas claves y valores de atributos como filtros.
En este ejemplo de respuesta, se usó el color verde para definir mejor los resultados de la búsqueda con una nueva solicitud de búsqueda en la que el campo de filtro se especificó como
_gs.color: ANY("green")
:{ "guidedSearchResult": { "refinementAttributes": [ { "attributeKey": "_gs.color", "attributeValue" : "green" }, { "attributeKey": "_gs.category", "attributeValue" : "shoe" } ] } }
C#
Para obtener más información, consulta la documentación de referencia de la API de AI Applications C#.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Java.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Node.js.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para obtener más información, consulta la documentación de referencia de la API de AI Applications PHP.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Python.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Para obtener más información, consulta la documentación de referencia de la API de AI Applications Ruby.
Para autenticarte en AI Applications, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Obtén puntuaciones de relevancia de documentos con los resultados de la búsqueda
Las puntuaciones de relevancia del documento se basan en la similitud de la búsqueda con el documento. Las puntuaciones se colocan en 11 buckets en el rango: 0, 0.1, 0.2… hasta 1.0. Cuanto más alta sea la puntuación, más relevante será el documento.
Considera las puntuaciones de relevancia del documento para los siguientes casos de uso:
Filtrado posterior a la búsqueda basado en la puntuación de relevancia para quitar los resultados irrelevantes
Clasificación posterior a la búsqueda o como entrada para otras aplicaciones
Depuración: Las puntuaciones de relevancia pueden proporcionar información sobre por qué se muestran algunos resultados de la búsqueda.
Para cada resultado de la búsqueda, se puede devolver una puntuación de relevancia:
"results": [ { "id": "DOCUMENT_ID", "document": { ... }, "modelScores": { "relevance_score": { "values": [ DOCUMENT-RELEVANCE-SCORE ] } } }, ...
También consulta el comando de ejemplo en el siguiente procedimiento.
Antes de comenzar: Asegúrate de que la app de búsqueda esté asociada a un almacén de datos estructurados o no estructurados. Es decir, no se pueden devolver las puntuaciones de relevancia del documento para la app de búsqueda de sitios web.
REST
Para solicitar que se muestren las puntuaciones de relevancia del documento con los resultados de la búsqueda, usa el método engines.servingConfigs.search
de la siguiente manera:
Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.
En la consola de Google Cloud , ve a la página AI Applications.
Ve a Apps.
En la página Apps, busca el nombre de tu app y obtén su ID en la columna ID.
Ejecuta el siguiente comando de curl para obtener las puntuaciones que se muestran con los resultados de la búsqueda.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", "relevanceScoreSpec": { "returnRelevanceScore": true } }'
PROJECT_ID
: Es el ID de tu proyecto de Google Cloud .APP_ID
: Es el ID de la app de Vertex AI Search que deseas consultar.QUERY
: Es el texto de la búsqueda.
El resumen de búsquedas varía según el modelo
Si generas resúmenes de búsqueda para tus consultas, es posible que observes que los resúmenes difieren entre los resultados de la consola y los de la API. Si ves este mensaje, es probable que la consola esté usando un modelo de LLM diferente de la API. Los ejemplos de curl y código de esta página usan el modelo de LLM estable.
Para cambiar o ver el modelo de LLM que se usa en la página Preview de la IU (solo se admite para aplicaciones de búsqueda avanzada y aplicaciones de atención médica)
- Ve a la página Configurations de tu app > pestaña UI.
Selecciona un Tipo de búsqueda:
- Selecciona Buscar con una respuesta para mostrar un resumen generativo sobre los resultados de la búsqueda.
- Selecciona Búsqueda con seguimientos para habilitar la búsqueda conversacional con resúmenes generativos y preguntas de seguimiento.
En la sección Modelos de lenguaje grandes para generar resúmenes, selecciona un modelo.
En el caso de las llamadas a métodos, el modelo estable es el predeterminado. Para usar un modelo de LLM que no sea el estable, consulta Cómo especificar el modelo de resumen y Cómo especificar el modelo de respuesta.
Próximos pasos
Usa la API de búsqueda para explorar datos en tus apps de búsqueda genéricas.