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 del panel de Looker de forma local para que la pruebes y desarrolles de forma local. 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 no opcionales deben completarse en orden secuencial.

Descripción general de la extensión de resumen del panel de Looker

De forma funcional, la extensión de resumen del panel de Looker envía los datos del panel de Looker al modelo de Gemini de Vertex AI. Luego, el modelo de Gemini devuelve un resumen de los datos de tu panel y una receta de los próximos pasos. La extensión muestra el resumen y los próximos pasos como un mosaico en tu panel, que se integra en tu experiencia de 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 manera 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 quieres 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 del 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 a 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 los 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á 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 qué región enviará y recibirá datos del backend local del modelo de Gemini de Vertex AI. Configura 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 tu 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á datos del panel y de LookML de tu extensión de frontend con datos consultados desde Looker y mostrará el modelo de Gemini de Vertex AI. Luego, el servicio transmitirá la respuesta de Gemini a la extensión de 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 denominará 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 con el contenido de manifest.lkml en el directorio raíz de tu repositorio cerrado. Selecciona "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 bases de datos, comunícate con el administrador de Looker y pídele el nombre de una conexión de 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 nombra el archivo de resumen del panel.
  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 en el que guardar tu proyecto. Selecciona el comando "Configurar Git" botón en la esquina superior derecha. Selecciona “Set up a bare repository Buscar”. 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 navegar hacia atrás de forma manual.
  3. Selecciona “Validar LookML”. en la esquina superior derecha. El botón cambiará a “Confirmar cambios y enviar”.
  4. Selecciona el comando “Confirmar cambios y enviar”. . Agrega el mensaje que quieras y selecciona "Confirmar".
  5. Selecciona “Implementar en producción” (Deploy to Production). en la esquina superior derecha del IDE de Looker. Acabas de agregar 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 a tu panel como un mosaico.
  8. Asegúrate de que se ejecute 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 tu servidor de frontend local, puedes realizar cambios en el código fuente JavaScript de la extensión, y el servidor creará 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 paneles en cualquier panel de tu instancia de Looker. Esto permitirá que otros usuarios de Looker prueben la extensión en sus paneles sin necesidad de configurar su propio servicio de backend. En estos pasos, se da por sentado que ya implementaste correctamente el backend para el desarrollo local en el mismo entorno local antes.

  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 del proyecto. Guarda los cambios al archivo.
  2. Envía una compilación con Cloud Build que compile la imagen de Docker del servicio de backend y la envíe 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 acabas de compilar se encuentra en YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Reemplaza YOUR_PROJECT_ID por el ID del 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 qué ubicación de Google Cloud Run quieres que ejecute 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 la extensión Looker Dashboard Summarization 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 la 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 apuntará 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.
npm run build
  1. Abre un navegador web y accede a tu instancia de Looker. Abre el panel de navegación izquierdo y activa el "Modo de desarrollo" botón de activación 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 para el proyecto de LookML.
  3. Arrastra y suelta todos los archivos del directorio dist generado anteriormente en el directorio raíz del proyecto en el "File Browser". 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 “Validar LookML”. en la esquina superior derecha. El botón cambiará a “Confirmar cambios y enviar”.
  2. Selecciona el comando “Confirmar cambios y enviar”. . Agrega el mensaje que quieras y selecciona "Confirmar".
  3. Selecciona “Implementar en producción” (Deploy to Production). en la esquina superior derecha del IDE de Looker.

¡Felicitaciones! Ya habilitaste a todos los usuarios de Looker en tu instancia de Looker para que 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 esta realizarán llamadas al servicio de backend de websocket implementado que se ejecuta en Google Cloud Run.

Ten en cuenta que, si realizas algún cambio en el código fuente, deberás 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 con los archivos generados recientemente desde el directorio dist.
  3. Validar, confirmar e implementar los cambios del proyecto de LookML en producción

Prueba la extensión de resúmenes del panel de Looker. Te recomendamos que contribuyas a la extensión para que pueda 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 capacidades 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 la extensión para enviar resúmenes y los próximos pasos a Google Chat o Slack. Para continuar con esta sección del codelab, debes estar familiarizado con la configuración de OAuth.

Habilitar la exportación a Google Chat

  1. Habilitar la API de Chat en tu proyecto de Google Cloud
  2. Sigue el paso 1 de las instrucciones de configuración de OAuth para 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 autorizados de JavaScript”, 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 elArchivo 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 poder enviar sus estadísticas al espacio de Google Chat que desees.
  6. 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.

Habilitar 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 alcances, 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 quieres exportar los resúmenes.
  3. Edita elArchivo env. Reemplaza YOUR_SLACK_CLIENT_ID por el ID de cliente. Reemplaza YOUR_SLACK_CLIENT_SECRET por el secreto del cliente. Reemplaza YOUR_SLACK_CHANNEL_ID por el ID del canal. Guarda los cambios en tu 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 codificado o a un canal de Slack específico. 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] Optimiza el resumen y los próximos pasos

La extensión le indica al modelo Gemini todos los metadatos del panel y los datos de consultas. 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 del panel. Esto ayudará a informar al LLM el contexto general del panel.
  • Sigue estas instrucciones para agregar notas a la tarjeta de cada 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.

Mientras 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 que incluya metadatos de panel adicionales en la instrucción para el 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, la extensión llamará a Vertex AI por cada consulta en el panel y una última llamada para darles formato a todos los resúmenes. Sigue esta sección para registrar las llamadas de Vertex AI que realiza tu extensión y, así, 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 en Cloud Run del servicio de backend de websocket implementado.
  2. Sigue estas instrucciones para configurar un receptor de registros que enrutará los registros a BigQuery. El destino del receptor debería ser BigQuery. Configura el filtro de inclusión con la siguiente muestra de código y reemplaza YOUR_CLOUD_RUN_LOCATION 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 Looker Dashboard Summarization de forma local para que la pruebes. 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 potenciados por Gemini y los próximos pasos directamente desde tus paneles.

10. ¿Qué sigue?