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 localmente. 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 ajustar 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

Desde el punto de vista funcional, la extensión de Resumen del panel de Looker envía los datos de tu panel de Looker al modelo Gemini de Vertex AI. Luego, el modelo de Gemini devuelve un resumen de los datos de tu panel y una sugerencia de los próximos pasos. La extensión muestra el resumen y los próximos pasos como una tarjeta en tu panel, lo que se integra en tu experiencia del panel. Además, la extensión puede exportar el resumen y los próximos pasos a Slack o Google Chat. La extensión usa una aplicación de frontend de React junto con un servicio de backend de WebSocket para enviar y recibir datos hacia y desde el modelo Gemini de Vertex AI.

Requisitos previos

  • Conocimientos básicos sobre el desarrollo de Node, Docker y Terraform
  • Conocimiento de la configuración de 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 ajustar de forma opcional el rendimiento de la extensión y ampliar su funcionalidad
  • Cómo administrar tu extensión implementada en 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
  • Permisos de develop y deploy en tu instancia de Looker
  • Permisos para editar un panel que quieras probar con la extensión
  • Una clave de la API de Looker de tu instancia de Looker
  • Un proyecto de Google Cloud con la facturación habilitada
  • Las APIs de Cloud Run, Vertex AI y Artifact Registry deben estar habilitadas en el proyecto.
  • Acceso a un entorno local con la CLI de gcloud instalada Los pasos del codelab suponen 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 desarrolles de forma local. El servicio tendrá acceso a Vertex AI.

  1. Instala la versión 18 o una posterior de Node 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. Para los fines de este codelab, todas las muestras de código supondrán 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 que puedas 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 WebSocket 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. Dentro de la actualización del archivo looker.ini, haz lo siguiente:
  2. Reemplaza client_id y client_secret por los de tu clave de API de Looker.
  3. El base_url con la URL de tu instancia de Looker en el siguiente 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 de tu proyecto.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI proporciona el modelo Gemini en varias regiones que se indican aquí. Determina desde 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 tu servicio local.
npm start
  1. Tu servicio de backend de WebSocket local se ejecutará en http://localhost:5000.

Ahora terminaste de configurar el servicio de backend de WebSocket en tu entorno local.

El servicio actúa como una interfaz entre tu extensión de frontend y el modelo Gemini de Vertex AI. El servicio tomará los datos del panel y de LookML de tu extensión de frontend con los datos consultados de Looker y le indicará al 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 de 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 del repositorio clonado y, luego, instala las dependencias del servidor de frontend para tu frontend.
cd ~/dashboard-summarization
npm install
  1. Inicia tu servidor de desarrollo local de frontend
npm run develop
  1. Tu servidor de frontend local ahora entrega el 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. Asigna el nombre dashboard-summarization al proyecto. Ahora deberías tener el proyecto de LookML en blanco abierto automáticamente en el IDE de Looker en la pestaña del 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. Sigue estas instrucciones si no sabes cómo hacerlo.
  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. Regresa 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 por el siguiente ejemplo de código. Asegúrate de reemplazar la cadena entre comillas dobles por el nombre de la conexión de la base de datos que elegiste en el paso 9. Guarda los cambios que hiciste en el 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 "Set up a bare repository instead". Selecciona “Crear repositorio”.
  2. Ahora tienes un repositorio básico para almacenar los archivos de tu proyecto de LookML. Para volver al proyecto en el IDE de Looker, selecciona "Volver al proyecto" o navega manualmente.
  3. Selecciona el botón "Validate LookML" en la esquina superior derecha. El botón cambiará a "Confirmar cambios y enviar".
  4. Selecciona el botón "Commit changes and push". Agrega el mensaje que quieras y selecciona “Confirmar”.
  5. Selecciona "Deploy to Production" en la esquina superior derecha del IDE de Looker. Ahora agregaste la extensión a tu instancia de Looker.
  6. Navega a un 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 una tarjeta.
  8. Asegúrate de que el servicio de backend de WebSocket local que configuraste antes se esté ejecutando.

¡Felicitaciones! Ahora puedes probar la extensión de resumen del panel de Looker en tu panel. La extensión enviará los metadatos de tu panel al servicio de backend de WebSocket local y mostrará el resultado de Gemini del servicio de backend directamente en la tarjeta de la 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 entregar cualquier instancia de la extensión de resumen del 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 de WebSocket 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 que hiciste en el 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 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 de tu proyecto. Reemplaza YOUR_REGION por la región del paso 2 que usaste para crear tu repositorio de Artifact Registry.
  2. Navega al directorio websocket-service/terraform en el 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 entre estas ubicaciones.
  2. Edita el archivo variables.tf y reemplaza YOUR_PROJECT_ID y YOUR_DOCKER_IMAGE_URL por los valores adecuados. Consulta el paso 6 para obtener la URL de tu imagen de Docker. Reemplaza YOUR_REGION por la región que elegiste en el paso 8 anterior. Guarda los cambios realizados 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 próxima sección.

¡Felicitaciones! Implementaste tu servicio de backend de WebSocket y ahora se ejecuta en Google Cloud Run. Ahora, cualquier instancia de tu extensión de Resumen del panel 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 el frontend de tu extensión, y ayuda a mantener la sesión de cada usuario mientras usa tu extensión.

5. Implementa el frontend en producción

En esta última sección, realizarás los pasos finales para implementar el frontend de la extensión y 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 el .Archivo env. Reemplaza YOUR_CLOUD_RUN_URL por el extremo de URL de Cloud Run de la sección anterior. Guarda los cambios en el 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 lateral izquierdo abierto, selecciona "Develop", 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 "Explorador de archivos". Sigue estas instrucciones si necesitas más ayuda.
  4. Abre el archivo manifest.lkml en el 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 "Validate LookML" en la esquina superior derecha. El botón cambiará a "Confirmar cambios y enviar".
  2. Selecciona el botón "Commit changes and push". 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 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 la extensión harán llamadas a tu 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, 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. Valida, confirma y, luego, implementa los cambios del proyecto de LookML en producción

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

Consulta las siguientes secciones opcionales para habilitar la exportación de Slack o 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 de Resumen del panel de Looker, compartamos la información de la extensión con un público más amplio. Sigue esta sección para habilitar tu extensión y enviar resúmenes y próximos pasos a Google Chat o Slack. Debes conocer la configuración de OAuth para continuar con esta sección del codelab.

Cómo habilitar 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 de Google Workspace. Agrega la URL de tu instancia de Looker como un URI en "Orígenes JavaScript autorizados", por ejemplo, https://mycompany.cloud.looker.com. Toma nota del 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 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 el 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 la documentación oficial para desarrolladores de Slack y configura una aplicación de OAuth. Para los permisos, debes incluir chat:write y channels:read. Anota el ID de cliente y el secreto del cliente generados.
  2. Determina el ID del canal de Slack al que deseas exportar los resúmenes.
  3. Edita el .Archivo 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 el archivo. Esto configurará el frontend de tu extensión para que pueda enviar sus estadísticas al canal de Slack que desees.
  4. 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.

Ahora tu 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 un canal de Slack específicos codificados. Puedes agregar permisos de OAuth adicionales y modificar el código para recuperar y mostrar una lista de espacios y canales a los que se enviarán resúmenes.

7. [Opcional] Ajusta 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 agregando la mayor cantidad posible de 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 sobre el contexto general del panel.
  • Sigue estas instrucciones para agregar notas a cada tarjeta del panel. Esto ayudará a informar al LLM sobre el contexto de cada búsqueda individual en el panel. Las pequeñas notas contextuales se tendrán en cuenta en los resúmenes generados.

Cuanta 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 adicionales del panel en la instrucción para el modelo de Gemini.

8. [Opcional] Configura el registro del modelo de Gemini

Cada vez que un usuario le indica a la extensión que cree resúmenes para un panel, la extensión realizará una llamada a Vertex AI para cada consulta 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 el siguiente código de muestra, en el 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 del panel de Looker 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 y los próximos pasos potenciados por Gemini directamente desde los paneles.

10. ¿Qué sigue?