Obtén estadísticas con el agente de Data Insights

El agente de Data Insights es un agente creado por Google. Te brinda estadísticas de datos a partir de tus datos de BigQuery. Con el agente de Data Insights, no necesitas conocimientos previos de SQL. Esto te permite tomar decisiones comerciales fundamentadas y basadas en datos, y libera a los analistas de datos para que se enfoquen en tareas más complejas.

En esta página, se describe cómo un administrador de proyectos Google Cloud puede autorizar, crear y, luego, implementar el agente de Data Insights con la consola deGoogle Cloud y la API de REST. En esta página, también se muestra cómo un usuario final puede usar el agente.

Descripción general

El agente de Data Insights está diseñado para hacer lo siguiente:

  • Comprende la intención del usuario: Analiza el contexto de las fuentes de datos conectadas y la consulta en lenguaje natural del usuario para comprender su objetivo.
  • Generar SQL: En función de esta comprensión, convierte la pregunta del usuario en una consulta en SQL sintáctica y semánticamente correcta.
  • Recupera datos: Luego, ejecuta el código SQL generado para recuperar los datos pertinentes directamente de la fuente de datos conectada, un conjunto de datos de BigQuery.
  • Proporciona estadísticas: Presenta los datos recuperados como visualizaciones, como gráficos y tablas, o como resúmenes basados en texto para responder la búsqueda del usuario.

Ejemplos de preguntas que puedes hacerle al agente de Data Insights

Estos son algunos ejemplos de preguntas que puedes hacerle al agente de Data Insights:

  • Agregación y visualización de datos:
    • "¿Cómo se comparan las ventas del segundo trimestre de este año en la región de Latinoamérica con las del segundo trimestre del año pasado?"
    • "Crea un gráfico de barras que muestre la comparación de cada uno de los 5 países principales de la región".
  • Análisis de tendencias:
    • "¿Cómo varió el volumen de llamadas salientes en los últimos 6 meses, desglosado por ubicación?"
    • "Analiza los patrones de reserva de los hoteles de Lisboa con una calificación superior a 3 estrellas".
  • Minería de datos:
    • "¿Qué factores se correlacionan con el valor total de las ventas cuando un cliente compra algo? Dame un mapa de calor que muestre la relación".
  • Análisis y generación de informes:
    • "Resume la tabla de oportunidades y cuentas, y crea un informe breve en el que se destaquen las tendencias clave".

Antes de comenzar

Para comenzar a usar el agente de Data Insights en Gemini Enterprise, sigue estos pasos:

Otorga acceso a los datos de BigQuery

Para permitir que el agente de Data Insights vea y consulte los datos de BigQuery, otorga los roles de Identity and Access Management (IAM) a los usuarios del agente:

Flujo de trabajo

El flujo de trabajo general para configurar y usar el agente de Data Insights es el siguiente:

Obtén detalles de la autorización

Sigue estos pasos para configurar la autorización. Los detalles que obtienes son necesarios para autorizar al agente de Data Insights a conectarse a los datos de BigQuery.

  1. En la consola de Google Cloud , ve a la página Credenciales en APIs y servicios.

    Ir a Credenciales

  2. Selecciona el proyecto Google Cloud que contiene el conjunto de datos de BigQuery que deseas que consulte el agente.

  3. Haz clic en Crear credenciales y, luego, selecciona ID de cliente OAuth.

  4. En Tipo de aplicación, selecciona Aplicación web.

  5. En la sección URI de redireccionamiento autorizados, agrega los siguientes URI:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Haz clic en Crear.

  7. En el panel Se creó el cliente de OAuth, haz clic en Descargar JSON. El archivo JSON descargado incluye los siguientes detalles del proyectoGoogle Cloud seleccionado. Necesitas estos detalles para crear un recurso de autorización:

    • Client ID: CLIENT_ID
    • URI de autorización: 
      https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    • URI del token: TOKEN_URI
    • Client secret: CLIENT_SECRET

Configura el agente con la consola de Google Cloud

En esta sección, se muestra cómo autorizar, crear y, luego, implementar una instancia del agente de Data Insights con la consola de Google Cloud . También puedes agregar permisos de usuario que determinen quién puede acceder al agente creado.

Autoriza y crea una instancia del agente

Para autorizar y crear una instancia del agente de Data Insights, sigue estos pasos:

  1. En la consola de Google Cloud , ve a Gemini Enterprise.

    Ir a Gemini Enterprise

  2. Selecciona una app en la que quieras crear el agente.

  3. En el menú, haz clic en Agentes.

    En la página Agentes, se muestran los agentes existentes.

  4. Haz clic en Agregar agente.

  5. En el panel Create agent, haz clic en Create en la tarjeta Data agent.

  6. En Autorizaciones, haz clic en Agregar autorización y, luego, ingresa los detalles de la autorización. Para obtener más información, consulta Cómo obtener autorización.

  7. Haz clic en Listo.

  8. Haz clic en Siguiente.

  9. Configura tu agente de la siguiente manera:

    1. Ingresa el nombre y la descripción del agente.
    2. En Conjunto de datos de BigQuery, haz clic en Explorar y realiza una de las siguientes acciones:
      • Selecciona un conjunto de datos disponible y haz clic en Seleccionar.
      • Ingresa la ruta de acceso al conjunto de datos de BigQuery requerido, haz clic en Buscar, selecciónalo y, luego, selecciona Seleccionar.

    3. Opcional: Haz clic en Mostrar más para ver las opciones avanzadas.

    4. Selecciona las opciones de acceso a la tabla correctas. Si deseas imponer una lista de entidades permitidas o una lista de bloqueo, especifica las rutas de acceso a las tablas restringidas.

    5. Opcional: Define la configuración de la consulta en lenguaje natural para proporcionar personalizaciones específicas de una traducción de lenguaje natural a código SQL o Python. También puedes proporcionar un ejemplo de SQL con una consulta en lenguaje natural, su resultado esperado en SQL y su respuesta esperada. Esto mejora la calidad de los resultados del agente.

      • Descripción del esquema: Es una cadena en lenguaje natural que describe el esquema del conjunto de datos de BigQuery.
      • Instrucción de consulta de lenguaje natural a SQL: Es una consulta en lenguaje natural transformada en una instrucción en SQL.
      • Instrucción de consulta de lenguaje natural a Python: Es una consulta en lenguaje natural que se transforma en una instrucción de Python.

    6. Opcional: Agrega ejemplos de consultas en lenguaje natural transformadas en consultas de SQL:

      • Consulta: Es un ejemplo de una consulta en lenguaje natural que se debe convertir en una consulta en SQL. Por ejemplo, "¿Cuáles son los nombres y las direcciones de correo electrónico de los clientes que se encuentran en California?".
      • SQL esperado: Es una cadena que ilustra un ejemplo de consulta en SQL que corresponde a la consulta en lenguaje natural. Por ejemplo, supongamos que tienes una tabla de BigQuery llamada customers. Luego, tu consulta en SQL esperada puede ser SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Respuesta esperada: Es una cadena que proporciona la respuesta esperada para la búsqueda ejecutando la consulta en SQL esperada. Por ejemplo:
      Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  10. Haz clic en Crear.

    La instancia del agente de Data Insights aparece en la lista Agents.
    Para comenzar a trabajar con el agente, espera hasta que la columna Estado del agente muestre Habilitado para tu instancia.

Configura el agente con la API de REST

En esta sección, se describe cómo autorizar, crear y, luego, implementar una instancia del agente de Data Insights con la API de REST.

Autoriza el agente

Como administrador, crea un recurso de autorización en Gemini Enterprise. Esto permite que el agente de Data Insights acceda a los datos de BigQuery.

  1. Crea el recurso de autorización.

    REST

    En el siguiente ejemplo, se muestra cómo crear un recurso de autorización con el método authorizations.create.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "TOKEN_URI"
}
}'

    Reemplaza lo siguiente:

    • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
    • LOCATION: La ubicación de tu proyecto de Google Cloud
    • AUTHORIZATION_ID: Es un ID que debes proporcionar para identificar el recurso de autorización.
    • CLIENT_ID: Es el ID de cliente que obtuviste en el paso anterior.
    • CLIENT_SECRET: Es el secreto del cliente que obtuviste en el paso anterior.
    • AUTHORIZATION_URI: Es el URI de autorización que obtuviste en el paso anterior.
    • TOKEN_URI: Es el URI del token que obtuviste en el paso anterior.

Crea una instancia del agente

Como Google Cloud administrador del proyecto, puedes crear una instancia del agente de Data Insights. Para ello, se requiere el ID del proyecto y el ID del conjunto de datos de los datos de BigQuery que deseas consultar con tu agente.

REST

En el siguiente ejemplo, se muestra cómo crear una instancia del agente de Data Insights con el método agents.create. Para obtener información sobre los campos avanzados que puedes agregar a esta muestra, consulta Cómo agregar configuraciones avanzadas para el agente.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu app de Gemini Enterprise.
  • APP_ID: ID de la app.
  • AGENT_DISPLAY_NAME: Es el nombre de tu instancia del agente de Data Insights.
  • AGENT_ICON_URI: Es un campo opcional para proporcionar un URI del ícono del agente.
  • AGENT_DESCRIPTION: Es una descripción de tu instancia del agente de Data Insights que indica el propósito del agente o los detalles de su fuente de datos de BigQuery.
  • BIGQUERY_PROJECT_ID: Es el ID del proyecto deGoogle Cloud que contiene el conjunto de datos de BigQuery.
  • BIGQUERY_DATASET_ID: Es el ID del conjunto de datos de BigQuery que contiene los datos que se consultarán.
  • AUTHORIZATION_RESOURCE_NAME: Es el nombre del recurso de autorización que obtuviste en la sección anterior.

Agrega configuraciones avanzadas para el agente

De manera opcional, puedes definir el campo nlQueryConfig para proporcionar personalizaciones específicas de la traducción de lenguaje natural a código SQL o Python. También puedes proporcionar un ejemplo de SQL con una consulta en lenguaje natural, su resultado esperado en SQL y su respuesta esperada. Esto mejora la calidad de las respuestas del agente. En el siguiente fragmento de código, se muestra cómo puedes configurar estos campos avanzados:

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

Reemplaza lo siguiente:

  • NL_TO_SQL_INSTRUCTIONS: Una consulta en lenguaje natural transformada en una instrucción de SQL.
  • NL_TO_PYTHON_INSTRUCTIONS: Es una consulta en lenguaje natural transformada en una instrucción de Python.
  • EXAMPLE_NL_QUERY: Es un ejemplo de una búsqueda en lenguaje natural que se debe convertir en una consulta en SQL. Por ejemplo, "¿Cuáles son los nombres y las direcciones de correo electrónico de los clientes que se encuentran en California?".
  • EXPECTED_SQL_QUERY: Es una cadena que ilustra un ejemplo de consulta en SQL que corresponde a la consulta en lenguaje natural. Por ejemplo, supongamos que tienes una tabla de BigQuery llamada customers. Luego, la consulta en SQL esperada puede ser "SELECT customer_name, email FROM customers WHERE state = 'California'".

  • EXPECTED_SQL_RESPONSE: Es una cadena que proporciona la respuesta esperada para la búsqueda y la consulta en SQL esperada. Por ejemplo:

    Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  • NL_DESCRIPTION_OF_BQ_DATASET: Es una cadena en lenguaje natural que describe el esquema del conjunto de datos de BigQuery.

Implementa la instancia

Después de crear la instancia del agente de Data Insights, como administrador, puedes implementarla para que los usuarios finales puedan usarla.

REST

  1. Implementa el agente. En el siguiente ejemplo, se muestra cómo implementar el agente creado con el método agents.deploy. La implementación del agente es una operación de larga duración (LRO).

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'

    Reemplaza lo siguiente:

    • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
    • AGENT_RESOURCE_NAME: Es el nombre del recurso del agente que obtuviste en la sección anterior cuando creaste el agente.

  2. Obtén el estado de la operación de implementación. En el siguiente ejemplo, se muestra cómo obtener el estado del método de operación de implementación operations.get.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"

    Reemplaza DEPLOY_OPERATION_NAME por el nombre del LRO que obtuviste en el paso anterior cuando implementaste el agente.

    En la respuesta, si el valor del campo done es true, se completó la implementación. Si el valor del campo done es false, la implementación está en curso.

Agregar o modificar usuarios y sus permisos

Sigue estos pasos para agregar o modificar principales en tu instancia del agente de Data Insights y asígnarles roles específicos de Identity and Access Management (IAM):

Console

  1. En la consola de Google Cloud , ve a Gemini Enterprise.

    Ir a Gemini Enterprise

  2. Selecciona una app que contenga tu instancia del agente de Data Insights.

  3. En el menú, haz clic en Agentes.

    En la página Agentes, se muestran los agentes existentes.

  4. Haz clic en el agente para el que deseas agregar o modificar usuarios.

    De forma predeterminada, un agente recién creado no tiene usuarios.

  5. En la tabla Usuarios con permiso, haz clic en Agregar usuario.

  6. Selecciona un Tipo de miembro de la lista disponible.

  7. Ingresa la identidad del miembro según el tipo y asígnale uno o más roles.

    • En el caso de un usuario, un grupo o una cuenta de servicio, la cadena de miembro es un correo electrónico.
    • En el caso de un dominio, la cadena de miembro es un nombre de dominio válido.
    • Para un principal, la cadena de miembro es un principal válido. Por ejemplo, principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1.
    • Para un conjunto de principales, la cadena de miembro es un conjunto de principales válido. Por ejemplo, principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1.
    • En el caso de los dominios y los conjuntos de principales, a todas las identidades y los grupos de usuarios dentro de esos dominios y conjuntos de principales se les asignan los mismos roles. Para un acceso seguro al agente, selecciona grupos individuales y dominios controlados o conjuntos de principales, y asígnales roles con privilegio mínimo.

  8. Haz clic en Guardar.

    Se actualiza la política de IAM y se agrega el usuario a la lista de usuarios con permiso.

  9. Para modificar los permisos asignados, haz clic en Acciones, selecciona Modificar y realiza una de las siguientes acciones:

    • Modificar los roles asignados
    • Agregar un rol diferente
    • Haz clic en Borrar para quitar un rol. Debes asignar al menos un rol a un usuario.

Cambia el estado de funcionamiento de la instancia

Después de crear la instancia del agente de Data Insights, el agente se habilita de forma predeterminada. Puedes cambiar su estado de funcionamiento a Inhabilitado, Suspendido, Habilitado o Borrado siguiendo estos pasos:

Console

  1. En la consola de Google Cloud , ve a Gemini Enterprise.

    Ir a Gemini Enterprise

  2. Selecciona una app que contenga tu instancia del agente de Data Insights.

  3. En el menú, haz clic en Agentes.

    En la página Agentes, se muestran los agentes existentes.

  4. Haz clic en Acciones para tus agentes y selecciona una de las siguientes opciones:

    • Suspendido: Para que el agente no esté disponible temporalmente para su uso. Sin embargo, los usuarios con cualquier grado de permiso para el agente de acceso aún pueden verlo.
    • Inhabilitado: Para que el agente no esté disponible para todos los usuarios, excepto el usuario que lo creó.
    • Habilitado: Para que el agente esté disponible para todos los usuarios con cualquier grado de permiso para acceder al agente.
    • Borrar: Para borrar la instancia del agente.

Cómo usar el agente

Sigue estos pasos para obtener estadísticas de datos con tu agente:

App

  1. En el menú de navegación de la app, haz clic en Agentes.

  2. Haz clic en View all agents.

  3. Selecciona tu instancia del agente de Data Insights.

  4. Si tu agente requiere autorización adicional, haz clic en Autorizar y proporciona los detalles de autorización.

  5. Haz clic en Agregar archivos para incluir archivos como fuentes de datos adicionales con las que el agente puede trabajar.

  6. Haz clic en Fuentes para seleccionar las fuentes que el agente debe incluir para proporcionar las estadísticas de datos más relevantes.

  7. Ingresa tus preguntas o instrucciones y presiona Intro o haz clic en Enviar.