Codelab de la extensión de resúmenes del panel de Looker

1. Antes de comenzar

En este codelab (1), configurarás la extensión de resumen de paneles de Looker de forma local para que la pruebes y desarrolles. Luego, (2) implementarás la extensión en producción para que otros usuarios de Looker en tu instancia de Looker puedan usarla. Por último, (3) puedes seguir pasos adicionales para perfeccionar y mejorar la funcionalidad de la extensión. Todas las secciones que no sean opcionales deben completarse en orden secuencial.

Descripción general de la extensión de resumen de paneles de Looker

Funcionalmente, la extensión de resumen de paneles de Looker envía los datos de tu panel de Looker al modelo Gemini de Vertex AI. Luego, el modelo de Gemini muestra un resumen de los datos de tu panel y una prescripción de los próximos pasos. La extensión muestra el resumen y los próximos pasos como una tarjeta en tu panel, que se integra en tu experiencia en el panel. Además, la extensión puede exportar el resumen y los próximos pasos a Slack o Google Chat. La extensión utiliza una aplicación de frontend de React junto con un servicio de backend de websocket para enviar y recibir datos desde y hacia el modelo de Gemini de Vertex AI.

Requisitos previos

  • Conocimientos básicos sobre el desarrollo de nodos, Docker y Terraform
  • Conocimientos para configurar un proyecto de LookML de Looker

Qué aprenderás

  • Cómo configurar y desarrollar la extensión de forma local
  • Cómo implementar la extensión en producción para que otros usuarios de Looker en tu instancia de Looker puedan usarla
  • Cómo, de manera opcional, ajustar el rendimiento de la extensión y extender su funcionalidad
  • Cómo administrar la extensión implementada en la producción

Requisitos

  • Una instancia de Looker, ya sea a través de una licencia original de Looker, una prueba activa de Looker Core o una licencia activa de Looker Core
  • Los permisos develop y deploy en tu instancia de Looker
  • Permisos para editar un panel que quieras probar con la extensión.
  • Una clave de API de Looker de tu instancia de Looker.
  • Un proyecto de Google Cloud con la facturación habilitada
  • Las APIs de Cloud Run, de Vertex AI y de Artifact Registry están habilitadas en el proyecto.
  • Acceso a un entorno local con gcloud CLI instalada. En los pasos del codelab, se da por sentado un entorno de estilo Linux.

2. Configura el backend para el desarrollo local

En esta sección, configurarás el servicio de backend de websocket para que lo pruebes y lo desarrolles de manera local. El servicio tendrá acceso a Vertex AI.

  1. Instala la versión 18 de Node o una posterior en tu entorno local. Sigue estas instrucciones para instalar Node.
  2. Clona el repositorio de la extensión en tu directorio principal local y navega al directorio raíz del repositorio. A los fines de este codelab, en todas las muestras de código se presupone que el repositorio clonado se encuentra en tu directorio principal local.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Navega al directorio raíz del repositorio clonado y cambia el nombre del archivo .env.example a .env para poder establecer variables de entorno en las secciones posteriores de este codelab.
cd ~/dashboard-summarization
mv .env.example .env
  1. Navega al directorio src del backend de socket web del repositorio clonado. Este directorio contiene el código fuente del servidor.
cd ~/dashboard-summarization/websocket-service/src
  1. Instala las dependencias del servicio con NPM.
npm install
  1. Cambia el nombre del archivo looker-example.ini por looker.ini.
mv looker-example.ini looker.ini
  1. Actualización del archivo looker.ini:
  2. Los valores client_id y client_secret con los de tu clave de API de Looker.
  3. El base_url con la URL de tu instancia de Looker en el formato: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. El texto entre corchetes (el encabezado de la sección) con el host de la URL de tu instancia de Looker

Por ejemplo, si tu ID de cliente es ABC123, tu secreto de cliente es XYZ789 y la URL de tu instancia de Looker es https://mycompany.cloud.looker.com, tu archivo looker.ini se verá exactamente de la siguiente manera:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Determina tu ID del proyecto de Google Cloud y configúralo en tu variable de entorno PROJECT. Reemplaza YOUR_PROJECT_ID por el ID del proyecto.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI proporciona el modelo de Gemini en las múltiples regiones que se indican aquí. Determina en qué región tu backend local enviará y recibirá datos del modelo Gemini de Vertex AI. Establece la región en tu variable de entorno REGION. Reemplaza YOUR_VERTEX_REGION por tu región, como us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Ahora, inicia el servicio local.
npm start
  1. Tu servicio de backend de websocket local se ejecutará en http://localhost:5000.

Acabas de configurar el servicio de backend de websocket en tu entorno local.

El servicio funciona como una interfaz entre tu extensión de frontend y el modelo de Gemini de Vertex AI. El servicio tomará los datos de panel y LookML de tu extensión de frontend con datos consultados desde Looker y le solicitará al modelo Gemini de Vertex AI. Luego, el servicio transmitirá la respuesta de Gemini a la extensión del frontend para que se muestre en tu panel.

También puedes realizar cambios en el código fuente del servicio de backend. Primero, deberás detener el proceso del servicio, realizar cambios en el código y, luego, volver a ejecutar npm start.

3. Configura el frontend para el desarrollo local

En esta sección, configurarás la extensión de frontend para que la pruebes y desarrolles de forma local.

  1. En el mismo entorno local de los pasos anteriores, navega al directorio raíz de tu repositorio clonado y, luego, instala las dependencias del servidor de frontend para el frontend.
cd ~/dashboard-summarization
npm install
  1. Inicia tu servidor de desarrollo de frontend local
npm run develop
  1. Tu servidor de frontend local ahora entrega el código JavaScript de la extensión en http://localhost:8080/bundle.js.
  2. Abre un navegador web y accede a tu instancia de Looker.
  3. Sigue estas instrucciones para configurar un proyecto de LookML en blanco. Nombra el resumen del panel del proyecto. Ahora deberías tener el proyecto en blanco de LookML abierto automáticamente en el IDE de Looker en la pestaña de tu navegador actual.
  4. Crea un archivo de manifiesto del proyecto en la raíz del proyecto de LookML. El archivo se llamará manifest.lkml. Si no sabes cómo hacerlo, sigue estas instrucciones para agregar un archivo a un proyecto de LookML.
  5. Reemplaza el contenido del nuevo archivo manifest.lkml por el contenido de manifest.lkml en el directorio raíz de tu repositorio cerrado. Selecciona el botón "Guardar cambios" en la esquina superior derecha para guardar los cambios en el archivo.
  6. En otra pestaña del navegador, navega a la lista de conexiones de bases de datos en tu instancia de Looker. Si no sabes cómo hacerlo, sigue estas instrucciones.
  7. Elige el nombre de una conexión de base de datos de Looker. No importa qué conexión elijas. Si no tienes permiso para ver las conexiones de la base de datos, comunícate con tu administrador de Looker y pídele el nombre de una conexión de la base de datos de Looker.
  8. Vuelve a la pestaña del navegador con tu proyecto de LookML abierto en un IDE de Looker. Crea un archivo de modelo en tu proyecto de LookML y asígnale el nombre dashboard-summarization.
  9. Reemplaza el contenido de tu archivo dashboard-summarization.model.lkml con la siguiente muestra de código. Asegúrate de reemplazar la cadena entre comillas dobles por el nombre de conexión de base de datos que elegiste en el paso 9. Guarda los cambios al archivo.
connection: "<YOUR_CONNECTION_NAME>"
  1. Configura un repositorio para guardar tu proyecto. Selecciona el botón “Configurar Git” en la parte superior derecha. Selecciona "Configurar un repositorio sin procesar". Selecciona “Crear repositorio”.
  2. Ahora tienes un repositorio básico básico en el que puedes almacenar los archivos de tus proyectos de LookML. Vuelve al proyecto en el IDE de Looker. Para ello, selecciona “Volver al proyecto” o navega hacia atrás de forma manual.
  3. Selecciona el botón "Validar LookML" en la esquina superior derecha. El botón cambiará a "Confirmar cambios y enviar".
  4. Selecciona el botón “Confirmar cambios y enviar”. Agrega el mensaje que quieras y selecciona "Confirmar".
  5. Selecciona "Deploy to Production" en la esquina superior derecha del IDE de Looker. Ya agregaste la extensión a tu instancia de Looker.
  6. Navega hasta el panel de Looker al que quieras agregar la extensión.
  7. Sigue las instrucciones para agregar una tarjeta de extensión a tu panel. Agrega tu nueva extensión al panel como tarjeta.
  8. Asegúrate de que se esté ejecutando el servicio de backend de websocket local que configuraste antes.

¡Felicitaciones! Ahora puedes probar la extensión de resúmenes del panel de Looker en tu panel. La extensión enviará los metadatos del panel a tu servicio de backend websocket local y mostrará el resultado de Gemini de tu servicio de backend directamente en la tarjeta de extensión del panel.

Mientras se ejecuta el servidor de frontend local, puedes realizar cambios en el código fuente de JavaScript de la extensión, y el servidor compilará y publicará los cambios automáticamente. Deberás volver a cargar la extensión o la página del panel para ver los cambios.

4. Implementa el backend en producción

En esta sección, configurarás el servicio de backend de websocket para que entregue cualquier instancia de tu extensión de resumen de panel en cualquier panel de tu instancia de Looker. Esto permitirá que otros usuarios de Looker prueben la extensión en sus propios paneles sin necesidad de configurar su propio servicio de backend. En estos pasos, se supone que ya implementaste correctamente el backend para el desarrollo local en el mismo entorno local.

  1. Sigue estas instrucciones para configurar una credencial predeterminada de la aplicación en tu entorno local con el ID de tu proyecto para los próximos pasos.
  2. Crea un repositorio de Artifact Registry para las imágenes de Docker de tu servicio de backend. Reemplaza YOUR_REGION por la región en la que deseas que se encuentre tu repositorio.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Navega al directorio src del backend del socket web del repositorio clonado.
cd ~/dashboard-summarization/websocket-service/src
  1. Edita el archivo cloudbuild.yaml y reemplaza todas las instancias de YOUR_REGION y YOUR_PROJECT_ID por tu región y el ID de tu proyecto. Guarda los cambios al archivo.
  2. Envía una compilación con Cloud Build que compilará la imagen de Docker del servicio de backend y la enviará al repositorio de Artifact Registry que acabas de crear. Reemplaza YOUR_REGION por la región en la que deseas usar el servicio de Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Recuerda que la URL de la imagen de Docker que compilaste recientemente se encuentra en YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Reemplaza YOUR_PROJECT_ID por el ID de tu proyecto. Reemplaza YOUR_REGION por la región del paso 2 que usaste para crear el repositorio de Artifact Registry.
  2. Navega al directorio websocket-service/terraform en tu repositorio clonado.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Determina en qué ubicación de Google Cloud Run deseas ejecutar tu servicio de backend de websocket. Elige una de estas ubicaciones.
  2. Edita el archivo variables.tf y reemplaza YOUR_PROJECT_ID y YOUR_DOCKER_IMAGE_URL por los valores adecuados. Verifica el paso 6 para la URL de tu imagen de Docker. Reemplaza YOUR_REGION por la región que elegiste en el paso 8 anterior. Guarda los cambios en el archivo.
  3. Implementa los recursos que usará tu servicio de backend con Terraform.
terraform init
terraform plan
terraform apply
  1. Guarda el extremo de URL de Cloud Run implementado para la siguiente sección.

¡Felicitaciones! Implementaste tu servicio de backend de websocket y ahora se está ejecutando en Google Cloud Run. Ahora, cualquier instancia de tu extensión de resumen de paneles de Looker puede comunicarse con tu servicio de backend. Te recomendamos que siempre tengas al menos una instancia de tu servicio de backend de websocket en ejecución en Cloud Run. La persistencia de tu servicio de backend mantiene la integridad de la transmisión de datos entre tu servicio de backend de websocket y tu frontend de extensión, y ayuda a mantener la sesión de cada usuario a medida que usa tu extensión.

5. Implementa el frontend en producción

En esta última sección, seguirás los últimos pasos para implementar el frontend de la extensión de modo que esté disponible para todos los usuarios de Looker en tu instancia de Looker.

  1. Navega al directorio raíz del repositorio clonado.
cd ~/dashboard-summarization
  1. Edita elArchivo env. Reemplaza YOUR_CLOUD_RUN_URL por el extremo de URL de Cloud Run de la sección anterior. Guarda los cambios en tu archivo. Esto dirigirá el frontend de la extensión de producción a tu servicio de backend de websocket que se ejecuta en Cloud Run.
  2. Compila el código JavaScript de la extensión. Se generará automáticamente un directorio dist con un archivo bundle.js y otros archivos en él.
npm run build
  1. Abre un navegador web y accede a tu instancia de Looker. Abre el panel de navegación lateral izquierdo y activa el botón de activación "Modo de desarrollo" en la parte inferior.
  2. Con el panel de navegación izquierdo abierto, selecciona “Develop”, luego desplázate hacia abajo y selecciona “dashboard-summarization”, el proyecto de LookML de tu extensión. Ahora deberías estar en el IDE de Looker del proyecto de LookML.
  3. Arrastra y suelta todos los archivos del directorio dist generado anteriormente en el directorio raíz del proyecto en el "Explorador de archivos". Sigue estas instrucciones si necesitas más ayuda.
  4. Abre el archivo manifest.lkml dentro del IDE de Looker. Dentro del archivo, reemplaza la línea
url: "http://localhost:8080/bundle.js"

con

file: "bundle.js"

Reemplaza YOUR_CLOUD_RUN_URL por el extremo de URL de Cloud Run del final de la última sección. Guarda los cambios en el archivo.

  1. Selecciona el botón "Validar LookML" en la esquina superior derecha. El botón cambiará a “Confirmar cambios y enviar”.
  2. Selecciona el botón “Confirmar cambios y enviar”. Agrega el mensaje que quieras y selecciona "Confirmar".
  3. Selecciona “Deploy to Production” en la esquina superior derecha del IDE de Looker.

¡Felicitaciones! Ahora habilitaste que todos los usuarios de Looker en tu instancia de Looker agreguen la extensión de resumen del panel de Looker a sus paneles. A medida que otros usuarios de Looker usen la extensión, todas las instancias de la extensión realizarán llamadas a tu servicio de backend de websocket implementado que se ejecuta en Google Cloud Run.

Ten en cuenta que, si realizas cambios en el código fuente, debes hacer lo siguiente:

  1. Vuelve a compilar el código JavaScript de tu extensión
  2. Reemplaza los archivos generados que agregaste al proyecto de LookML por los archivos recién generados del directorio dist.
  3. Validar, confirmar e implementar los cambios del proyecto de LookML en producción

Prueba la extensión de resumen de paneles de Looker. Te recomendamos que contribuyas con la extensión y la ayudes a satisfacer mejor las necesidades de la comunidad de Looker. Puedes crear una solicitud de extracción en el repositorio.

Consulta las siguientes secciones opcionales para habilitar la exportación a Slack/Google Chat, ajustar los resúmenes y los próximos pasos de Gemini y configurar el registro de Gemini.

6. [Opcional] Configura las funciones de exportación

Ahora que tú y tus usuarios de Looker probaron la extensión Looker Dashboard Summarization, puedes compartir la información de la extensión con un público más amplio. Sigue esta sección para habilitar tu extensión para que envíe resúmenes y los próximos pasos a Google Chat o Slack. Debes estar familiarizado con la configuración de OAuth para continuar con esta sección del codelab.

Habilita la exportación de Google Chat

  1. Habilita la API de Chat en tu proyecto de Google Cloud.
  2. Sigue el paso 1 de las instrucciones de configuración de OAuth de Google Workspace. Para los permisos, debes incluir spaces.messages.create.
  3. Sigue el paso 2 de las instrucciones de configuración de OAuth para Google Workspace. Agrega la URL de tu instancia de Looker como un URI en "Orígenes de JavaScript autorizados", por ejemplo, https://mycompany.cloud.looker.com. Anota el ID de cliente generado.
  4. Determina el ID del espacio de Google Chat al que quieres exportar los resúmenes. Si no sabes cómo hacerlo, sigue estas instrucciones.
  5. Edita el archivo .Archivo env. Reemplaza YOUR_GOOGLE_CLIENT_ID por el ID de cliente. Reemplaza YOUR_GOOGLE_SPACE_ID por el ID del espacio de Google Chat. Guarda los cambios en tu archivo. Esto configurará el frontend de tu extensión para que pueda enviar sus estadísticas al espacio de Google Chat que desees.
  6. Si ejecutas el frontend de tu extensión de forma local, vuelve a compilar la extensión. De lo contrario, si implementas el frontend de tu extensión, vuelve a implementarlo.

Habilita la exportación a Slack

  1. Sigue los pasos 1 y 2 de los documentos oficiales para desarrolladores de Slack a fin de configurar una aplicación de OAuth. Para los permisos, debes incluir chat:write y channels:read. Anota el ID de cliente generado y el secreto del cliente.
  2. Determina el ID del canal de Slack al que deseas exportar los resúmenes.
  3. Edita el archivo .Archivo env. Reemplaza YOUR_SLACK_CLIENT_ID por el ID de cliente. Reemplaza YOUR_SLACK_CLIENT_SECRET por el Secreto de cliente. Reemplaza YOUR_SLACK_CHANNEL_ID por el ID del canal. Guarda los cambios en el archivo. Esta acción configurará el frontend de tu extensión para poder enviar sus estadísticas al canal de Slack que desees.
  4. Si ejecutas el frontend de tu extensión de manera local, vuelve a compilar la extensión. De lo contrario, si implementas el frontend de tu extensión, vuelve a implementarlo.

Ahora la extensión puede exportar sus resúmenes directamente a Slack o Google Chat. Ten en cuenta que la extensión solo puede enviar resúmenes a un espacio de chat de Google o a un canal de Slack codificados de forma específica. Puedes agregar permisos de OAuth adicionales y modificar el código para recuperar y mostrar una lista de espacios y canales a los que enviar resúmenes.

7. [Opcional] Define mejor el resumen y los próximos pasos

La extensión le solicita al modelo de Gemini todos los metadatos del panel y consulta los datos. Puedes mejorar la precisión, el detalle y la profundidad de los resúmenes y los pasos prescriptivos si agregas tantos metadatos y contexto al panel. Prueba estos pasos para cada panel del que forma parte tu extensión:

  • Sigue estas instrucciones para agregar detalles al panel. Esto ayudará a informar al LLM el contexto general del panel.
  • Sigue estas instrucciones para agregar notas a cada tarjeta del panel. Esto ayudará a informar al LLM el contexto de cada consulta individual en el panel. Las pequeñas notas contextuales se incluirán en los resúmenes generados.

Cuanto más información puedas agregar a tus paneles, mejores serán los resúmenes y los próximos pasos de la extensión. Puedes modificar el código para incluir metadatos de panel adicionales en la instrucción del modelo de Gemini.

8. Configura el registro del modelo de Gemini (opcional)

Cada vez que un usuario le indique a la extensión que cree resúmenes para un panel, esta realizará una llamada a Vertex AI para cada búsqueda del panel, además de una llamada final para dar formato a todos los resúmenes. Sigue esta sección para registrar las llamadas a Vertex AI que realiza tu extensión, de modo que puedas estimar y supervisar los costos y el tráfico de Vertex AI. Solo debes seguir estas instrucciones si implementaste el servicio de backend de websocket.

  1. Determina la ubicación de Cloud Run de tu servicio de backend de websocket implementado.
  2. Sigue estas instrucciones para configurar un receptor de registros que enrute los registros a BigQuery. El destino del receptor debe ser BigQuery. Establece el filtro de inclusión con la siguiente muestra de código en la que YOUR_CLOUD_RUN_LOCATION se reemplaza por la ubicación de Cloud Run del paso anterior.
resource.type = "cloud_run_revision"
resource.labels.service_name = "websocket-service"
resource.labels.location = "YOUR_CLOUD_RUN_LOCATION"
 severity>=DEFAULT
jsonPayload.component="dashboard-summarization-logs"

9. ¡Felicitaciones!

Configuraste la extensión de resumen de paneles de Looker de forma local para probarla. También implementaste la extensión en Google Cloud para que otros usuarios también puedan probarla. Ahora tú y otros usuarios pueden acceder a los resúmenes y los próximos pasos potenciados por Gemini desde sus paneles.

10. ¿Qué sigue?