Obtener estadísticas con el agente Estadísticas de datos

El agente Estadísticas de datos es un agente creado por Google. Te ofrece estadísticas de datos a partir de tus datos de BigQuery. Con el agente Estadísticas de datos, no necesitas tener conocimientos previos de SQL. De esta forma, podrás tomar decisiones empresariales fundamentadas y basadas en datos, y los analistas de datos podrán centrarse en tareas más complejas.

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

Información general

El agente Estadísticas de datos se ha diseñado para hacer lo siguiente:

  • Entender 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: a partir de esta información, convierte la pregunta del usuario en una consulta SQL correcta desde el punto de vista sintáctico y semántico.
  • Recuperar datos: a continuación, ejecuta el código SQL generado para obtener los datos relevantes directamente de la fuente de datos conectada, que es un conjunto de datos de BigQuery.
  • Proporcionar estadísticas: presenta los datos obtenidos como visualizaciones, como gráficos y tablas, o como resúmenes de texto para responder a la consulta del usuario.

Ejemplos de consultas que puedes hacer al agente de Estadísticas de datos

Aquí tienes algunos ejemplos de consultas que puedes hacerle al agente Estadísticas de datos:

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

Antes de empezar

Para empezar a usar el agente Estadísticas de datos en Gemini Enterprise, sigue estos pasos:

Conceder acceso a datos de BigQuery

Para que el agente de Estadísticas de Datos pueda ver y consultar los datos de BigQuery, asigna los roles de Gestión de Identidades y Accesos (IAM) a los usuarios del agente:

Flujo de trabajo

El flujo de trabajo general para configurar y usar el agente de Estadísticas de datos es el siguiente:

Obtener los detalles de la autorización

Sigue estos pasos para configurar la autorización. Los detalles que obtengas son necesarios para autorizar al agente de Estadísticas de datos a conectarse a los datos de BigQuery.

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

    Ir a Credenciales

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

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

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

  5. En la sección URIs de redirección autorizados, añade los siguientes URIs:

    • 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 Cliente de OAuth creado, haz clic en Descargar JSON. El archivo JSON descargado incluye los siguientes detalles del proyectoGoogle Cloud seleccionado. Necesitarás estos datos para crear un recurso de autorización:

    • ID de cliente: 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
    • Secreto de cliente: CLIENT_SECRET

Configurar el agente con la Google Cloud consola

En esta sección se muestra cómo autorizar, crear y desplegar una instancia del agente de estadísticas de datos mediante la consola de Google Cloud . También puedes añadir permisos de usuario que determinen quién puede acceder al agente creado.

Autorizar y crear una instancia de agente

Autoriza y crea una instancia del agente de Estadísticas de datos siguiendo estos pasos:

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

    Ir a Gemini Enterprise

  2. Selecciona la aplicación en la que quieras crear el agente.

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

    En la página Agentes se muestran los agentes que ya tienes.

  4. Haz clic en Añadir agente.

  5. En el panel Crear agente, haz clic en Crear en la tarjeta Agente de datos.

  6. En Autorizaciones, haz clic en Añadir autorización e introduce los detalles de la autorización. Para obtener más información, consulta el artículo Obtener autorización.

  7. Haz clic en Listo.

  8. Haz clic en Siguiente.

  9. Configura tu agente de la siguiente manera:

    1. Introduce el nombre y la descripción del agente.
    2. En Conjunto de datos de BigQuery, haga clic en Buscar y siga uno de estos pasos:
      • Selecciona un conjunto de datos disponible y haz clic en Seleccionar.
      • Introduce la ruta al conjunto de datos de BigQuery que necesites, haz clic en Buscar, selecciónalo y, a continuación, selecciona Seleccionar.

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

    4. Selecciona las opciones de acceso a la tabla correctas. Si quieres imponer una lista de permitidos o una lista de bloqueados, especifica las rutas 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 mediante una consulta en lenguaje natural, su salida de SQL esperada y su respuesta esperada. De esta forma, se mejora la calidad de las respuestas del agente.

      • Descripción del esquema: una cadena en lenguaje natural que describe el esquema del conjunto de datos de BigQuery.
      • Petición de consulta en lenguaje natural a SQL: una consulta en lenguaje natural transformada en una instrucción de SQL.
      • Consulta en lenguaje natural a petición de Python: una consulta en lenguaje natural transformada en una instrucción de Python.

    6. Opcional: Añade ejemplos de consultas en lenguaje natural transformadas en consultas de SQL:

      • Consulta: ejemplo de una consulta en lenguaje natural que debe convertirse en una consulta de SQL. Por ejemplo, "¿Cuáles son los nombres y las direcciones de correo de los clientes de California?"
      • SQL esperado: una cadena que muestra un ejemplo de consulta de SQL correspondiente a la consulta en lenguaje natural. Por ejemplo, supongamos que tienes una tabla de BigQuery llamada customers. En ese caso, la consulta de SQL esperada puede ser SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Respuesta esperada: una cadena que proporciona la respuesta esperada a la consulta ejecutando la consulta de 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 Estadísticas de datos aparece en la lista Agentes.
    Para empezar a trabajar con el agente, espera hasta que en la columna Estado del agente se muestre el valor Habilitado en tu instancia.

Configurar el agente mediante la API REST

En esta sección se describe cómo autorizar, crear e implementar una instancia de agente de Estadísticas de Datos mediante la API REST.

Autorizar al agente

Como administrador, crea un recurso de autorización en Gemini Enterprise. De esta forma, el agente de Estadísticas de datos puede acceder 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 mediante 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"
}
}'

    Haz los cambios siguientes:

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

Crear una instancia de agente

Como Google Cloud administrador de un proyecto, puedes crear una instancia del agente de Estadísticas de datos. Para ello, se necesitan el ID del proyecto y el ID del conjunto de datos de BigQuery que quieras consultar con tu agente.

REST

En el siguiente ejemplo se muestra cómo crear una instancia de agente de Estadísticas de datos mediante el método agents.create. Para obtener información sobre los campos avanzados que puedes añadir a esta muestra, consulta Añadir 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"
      ]
    }
  }'

Haz los cambios siguientes:

  • PROJECT_NUMBER: el número de tu proyecto de Google Cloud .
  • LOCATION: la ubicación de tu aplicación Gemini Enterprise.
  • APP_ID: el ID de la aplicación.
  • AGENT_DISPLAY_NAME: el nombre de tu instancia del agente Data Insights.
  • AGENT_ICON_URI: campo opcional para proporcionar un URI del icono del agente.
  • AGENT_DESCRIPTION: una descripción de tu agente de Estadísticas de datos que indique el propósito del agente o los detalles de su fuente de datos de BigQuery.
  • BIGQUERY_PROJECT_ID: el ID del proyecto que contiene el conjunto de datos de BigQuery. Google Cloud
  • BIGQUERY_DATASET_ID: el ID del conjunto de datos de BigQuery que contiene los datos que se van a consultar.
  • AUTHORIZATION_RESOURCE_NAME: el nombre del recurso de autorización que has obtenido en la sección anterior.

Añadir configuraciones avanzadas para el agente

También puedes definir el campo nlQueryConfig para proporcionar personalizaciones específicas de la traducción del lenguaje natural a código SQL o Python. También puedes proporcionar un ejemplo de SQL con una consulta en lenguaje natural, su salida de SQL esperada y su respuesta esperada. De esta forma, se mejora la calidad de las respuestas del agente. En el siguiente fragmento de código se muestra cómo 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"
  }
}

Haz los cambios siguientes:

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

  • EXPECTED_SQL_RESPONSE: cadena que proporciona la respuesta esperada de la consulta y la consulta de 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: una cadena en lenguaje natural que describe el esquema del conjunto de datos de BigQuery.

Desplegar la instancia

Una vez que hayas creado la instancia del agente de Estadísticas de datos, 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 mediante el método agents.deploy. El despliegue del agente es una operación de larga duración.

    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"
 }'

    Haz los cambios siguientes:

    • PROJECT_NUMBER: el número de tu proyecto de Google Cloud .
    • AGENT_RESOURCE_NAME: el nombre del recurso del agente que has obtenido en la sección anterior al crear el agente.

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

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

    Sustituye DEPLOY_OPERATION_NAME por el nombre de la operación de larga duración que obtuviste en el paso anterior al implementar el agente.

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

Añadir o modificar usuarios y sus permisos

Para añadir o modificar principales en tu instancia del agente Data Insights y asignarles roles de Gestión de Identidades y Accesos (IAM) específicos, sigue estos pasos:

Consola

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

    Ir a Gemini Enterprise

  2. Selecciona una aplicación que contenga tu instancia del agente Data Insights.

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

    En la página Agentes se muestran los agentes que ya tienes.

  4. Haz clic en el agente al que quieras añadir o modificar usuarios.

    De forma predeterminada, los agentes recién creados no tienen usuarios.

  5. En la tabla Usuarios con permiso, haz clic en Añadir usuario.

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

  7. Introduce la identidad del miembro en función del tipo y asigna uno o varios roles.

    • En el caso de los usuarios, los grupos o las cuentas 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.
    • En el caso de 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.
    • En el caso de 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 entidades principales, se asignan los mismos roles a todas las identidades y grupos de usuarios de esos dominios y conjuntos de entidades principales. Para proporcionar acceso seguro al agente, selecciona grupos individuales y dominios o conjuntos de principales controlados, y asígnales roles con los mínimos privilegios.

  8. Haz clic en Guardar.

    La política de gestión de identidades y accesos se actualiza y el usuario se añade a la lista de usuarios con permiso.

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

    • Modifica los roles asignados.
    • Añade otro rol.
    • Haz clic en Eliminar para quitar un rol. Debes asignar al menos un rol a un usuario.

Cambiar el estado de trabajo de la instancia

Una vez que hayas creado la instancia del agente de Estadísticas de datos, el agente se habilitará de forma predeterminada. Para cambiar su estado a Inhabilitado, Suspendido, Habilitado o Eliminado, sigue estos pasos:

Consola

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

    Ir a Gemini Enterprise

  2. Selecciona una aplicación que contenga tu instancia del agente Data Insights.

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

    En la página Agentes se muestran los agentes que ya tienes.

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

    • Suspendido: para que el agente no esté disponible temporalmente. Sin embargo, los usuarios con cualquier nivel de permiso para el agente de acceso podrán seguir viendo el agente.
    • Inhabilitado: para que el agente no esté disponible para todos los usuarios, excepto para 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.
    • Eliminar: para eliminar la instancia del agente.

Usar el agente

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

Aplicación

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

  2. Haz clic en Ver todos los agentes.

  3. Selecciona tu instancia de agente de Estadísticas de datos.

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

  5. Haz clic en Añadir archivos para incluir archivos como fuentes de datos adicionales con las que pueda trabajar el agente.

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

  7. Escribe tus preguntas o peticiones y pulsa Intro o haz clic en Enviar.