Incorpora Looker con Conversational Analytics

1. Antes de comenzar

En este codelab, se te guiará para integrar un panel de Looker incorporado con un chat impulsado por Conversational Analytics para crear una experiencia de datos unificada basada en lenguaje natural. Para obtener el máximo valor, debes estar familiarizado con la incorporación de Looker, Conversational Analytics, JavaScript y React.

Qué aprenderás

Después de seguir este codelab, habrás aprendido lo siguiente:

• Cómo configurar la aplicación de referencia de Looker Embed de forma local
• Cómo crear un componente de chat de React con la biblioteca de componentes de Looker
• Cómo enviar el filtro del panel incorporado como contexto a Conversational Analytics
• Cómo habilitar el chat impulsado por Conversational Analytics para controlar los filtros del panel incorporado

Requisitos

Para completar este codelab, necesitarás lo siguiente:

• Una instancia de Looker con el bloque de Looker de datos demográficos de ASC instalado y la incorporación de SSO habilitada
• Acceso a la API y para desarrolladores a tu instancia de Looker
• Un entorno local con Node v18, yarn, Git y gcloud instalados
• Un proyecto de Cloud con estos roles de IAM configurados para tu cuenta de usuario:
• roles/bigquery.dataViewer Visualizador de datos de BigQuery
• roles/bigquery.user Usuario de BigQuery
• roles/looker.instanceUser Usuario de la instancia de Looker

2. Configura Conversational Analytics

Configuraremos el agente de datos de Conversational Analytics que usará el chat del panel incorporado para responder preguntas en lenguaje natural.

Autenticación con gcloud

1. Autentícate con tu cuenta de usuario en tu entorno local:

gcloud auth login

2. Establece las credenciales predeterminadas de la aplicación (ADC) y el proyecto de facturación en tu gcloud:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Habilita las APIs de Conversational Analytics

3. Habilita las APIs del proyecto de Cloud. Reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Crea el agente de datos

4. Abre Google Colab.
5. Dentro de Google Colab, carga este notebook desde el repositorio de Looker Embed Reference.
6. Ejecuta todos los pasos del notebook. Necesitarás el ID de tu proyecto de Cloud y el URI de tu instancia de Looker con una barra diagonal final, como "https://my.looker.app/". Deberías obtener un resultado exitoso al final del notebook.

Ahora tienes un agente de datos de Conversational Analytics disponible y listo para aceptar mensajes de chat, consultar las exploraciones de Looker en tu panel de Looker incorporado y mostrar resultados y visualizaciones.

3. Configura Looker Embed Reference

Configuraremos la aplicación de referencia de Looker Embed en tu entorno local para que puedas probar el ejemplo de integración del chat de Conversational Analytics con un panel de Looker incorporado.

Clona el repositorio

1. Clona el repositorio de GitHub en tu entorno local. Consulta el siguiente comando de ejemplo:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Navega al directorio LookerEmbedReference que clonaste:

cd LookerEmbedReference

Configura y ejecuta el servidor de frontend local

3. Instala las dependencias en el directorio Frontend.

cd Frontend
yarn install

4. Configura un archivo .env en la raíz del directorio Frontend con credenciales. YOUR_LOOKER_INSTANCE_URI debe ser el URI de tu instancia de Looker sin barra diagonal final. El contenido del archivo debe ser el siguiente:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Puedes usar el siguiente comando de ejemplo para crear el archivo:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Ejecuta el servidor de desarrollo de frontend:

yarn run dev

Configura y ejecuta el servidor de backend de forma local

6. Abre un shell, una terminal, una consola o una pestaña nuevos. Navega al directorio Backend-Node y luego instala las dependencias. Asegúrate de mantener el shell o la terminal anterior con el servidor de frontend en ejecución.

cd ../Backend-Node
yarn install

7. Configura un archivo .env en la raíz del directorio Backend-Node con credenciales:

• YOUR_LOOKER_CLIENT_ID es tu ID de cliente de Looker.
• YOUR_LOOKER_CLIENT_SECRET es tu secreto de cliente de Looker.
• YOUR_LOOKER_EMBED_SECRET es tu secreto de incorporación.
• YOUR_PROJECT_ID es el ID del proyecto de Cloud.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH es el URI de tu instancia de Looker con una barra diagonal final.
• YOUR_LOOKER_INSTANCE_URI es el URI de tu instancia de Looker sin barra diagonal final.

El contenido del archivo debe ser el siguiente:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Puedes usar el siguiente comando de ejemplo para crear el archivo. Reemplaza todas las credenciales según corresponda:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Ejecuta el servidor de desarrollo de backend:

yarn run dev

Ahora tienes el servidor de desarrollo de frontend en ejecución, que entrega el código JavaScript para la aplicación web. También tienes el servidor de desarrollo de backend en ejecución para ocuparte de las solicitudes de URL de incorporación de SSO y las solicitudes de proxy a los extremos de Conversational Analytics.

4. Prueba el ejemplo

Probemos tu aplicación web que ahora se ejecuta de forma local en tu entorno.

Cómo iniciar una conversación

1. Abre la dirección https://localhost:3001 en el navegador que elijas.
2. Navega a la página Panel incorporado con chat en la navegación principal de la izquierda.
3. Una vez que se cargue el componente de chat de la derecha, escribe: "Hola, ¿quién eres?".
4. Observa la respuesta.

La aplicación creó automáticamente un objeto de conversación de Conversational Analytics para hacer un seguimiento del historial de chat y cargó la interfaz de chat. Cuando le hiciste una pregunta a la interfaz de chat, el frontend envió un mensaje de usuario a tu servidor de backend de Node local. Luego, envió la solicitud al extremo de chat de Conversational Analytics y la respuesta de este.

Filtra el panel incorporado

Ahora familiarízate con el panel incorporado e interactúa con él.

5. Desplázate por el panel incorporado. Observa que abarca datos del censo en varias dimensiones y métricas.
6. Puedes filtrar el panel en Estado y Condado en la parte superior izquierda del panel. Establece el filtro en el filtro del panel en Texas. Luego, selecciona el botón de flecha circular resaltado en azul para volver a ejecutar el panel.
7. Observa cómo se filtran todos los datos de visualizaciones en el estado de Texas.

Haz una pregunta con el contexto del panel

Ahora que filtramos el panel, sigamos investigando los datos en el panel.

8. Envía "Dime los 5 condados principales con el alquiler más bajo" en el chat.
9. Observa que tu instrucción para Conversational Analytics ahora contiene palabras adicionales: "Filtrar por la dimensión 'state.state_name' que es Texas".
10. Ahora, observa que la consulta y los datos de la respuesta se filtran en el estado de Texas.
11. Además, después de que se mostraron los resultados de los datos, se volvió a ejecutar el panel incorporado con su filtro de Condado establecido en los 5 condados definidos en los datos del resultado.

Ahora puedes seguir investigando los datos del censo, con los 5 condados filtrados de forma conveniente para ti.

¡Felicitaciones! Configuraste y probaste un ejemplo simple de un panel incorporado integrado con un chat de Conversational Analytics.

5. Crea un componente de chat

Para comprender qué sucede en segundo plano, primero exploremos el componente Chat. Suponemos que entiendes cómo incorporar un panel de Looker con el SDK de Looker Embed.

Usa la biblioteca de componentes de Looker

1. Abre el archivo del componente Chat en Frontend/src/components/EmbedChat/components/chat.js en tu IDE favorito o en tu terminal.
2. El componente Chat se compila con componentes de React de la IU de Looker estándar del paquete de la biblioteca de componentes de Looker .

La biblioteca de componentes de Looker permite una integración perfecta entre el contenido de Looker y tu aplicación, ya que proporciona componentes de React precompilados que se alinean con los estilos y componentes de un panel de Looker incorporado.

Envía un mensaje de usuario

La interfaz de chat debe enviar la instrucción de un usuario a Conversational Analytics.

3. Cerca de la parte inferior del archivo del componente Chat, el componente Chat contiene el subcomponente ChatInput, que proporciona el campo de entrada para la instrucción de un usuario.
4. Cuando se envía, el método showAndSendUserPrompt envía la instrucción del usuario a Conversational Analytics (a través de tu backend de Node).

Transmite y muestra mensajes del sistema

Después de que el usuario le envíe un mensaje a Conversational Analytics, debemos mostrar su respuesta.

5. Cerca de la parte inferior del archivo del componente Chat, el componente Chat contiene el subcomponente MessageList, que contiene la lógica para mostrar los mensajes de Conversational Analytics según el tipo de mensaje.
6. El método streamAndParseResponse controla la respuesta, ya que intenta constantemente analizar mensajes del sistema válidos de la respuesta JSON de transmisión. Cada vez que se analiza correctamente un mensaje del sistema válido, se muestra en MessageList.

Te recomendamos que muestres los mensajes del sistema de Conversational Analytics en cuanto lleguen para ofrecer una experiencia del usuario más responsiva.

La respuesta de Conversational Analytics a una instrucción del usuario consta de varios mensajes del sistema, que abarcan las fuentes de datos consultadas, la consulta, los resultados, las visualizaciones y mucho más. Esperar a que lleguen todos los mensajes del sistema puede hacer que el usuario suponga que hay problemas de rendimiento o de la aplicación.

Ahora exploraste cómo el componente Chat, compilado con la biblioteca de componentes de Looker, envía un mensaje de usuario y transmite la respuesta.

6. Envía filtros del panel a Conversational Analytics

Ahora comprendamos cómo incluir los filtros del panel en la instrucción de un usuario para que Conversational Analytics pueda filtrar su consulta con el contexto del panel (sus filtros).

Escucha el evento de cambio de filtro del panel

1. Abre el archivo del componente EmbedChat en Frontend/src/components/EmbedChat/EmbedChat.js, que representa la página de la aplicación que contiene el panel incorporado integrado con el componente Chat explorado anteriormente.
2. El componente EmbedChat escucha el evento "dashboard:filters:changed" del panel incorporado con el método .on(...) del SDK de Embed. Luego, el componente almacena los filtros actuales en su estado de filtro.

Envía el estado del filtro a Conversational Analytics

3. El componente EmbedChat pasa los filtros al componente Chat, que convierte cada filtro en una cadena como "Filter on dimension '...' being ..." en el método showAndSendUserPrompt para que se agregue a la instrucción del usuario.

El nombre o la clave del filtro de un panel no son necesariamente los mismos que el nombre de la dimensión real. Debes asignar la clave del filtro al nombre de la dimensión real para que Conversational Analytics comprenda en qué dimensiones filtrar.

En este caso, por ejemplo, en el componente Chat, su objeto FIELD_FILTER_MAP asigna el nombre de la dimensión "state.state_name" a la clave del filtro "State 📍". Luego, el método showAndSendUserPrompt usa el mapa para determinar el nombre de la dimensión en la que se debe filtrar.

7. Controla los filtros del panel desde el chat

Por último, veamos cómo habilitar el componente Chat para controlar los filtros del panel incorporado.

Determina qué filtros establecer

1. El método streamAndParseResponse del componente Chat siempre busca un mensaje del sistema con los resultados de los datos de Conversational Analytics.
2. Cada vez que el método streamAndParseResponse analiza un mensaje del sistema con resultados de datos, verifica si alguna dimensión de los datos corresponde a las dimensiones de los filtros.
3. Si es así, el método streamAndParseResponse convierte las columnas de datos en filtros del panel. Esta vez, el método vuelve a usar FIELD_FILTER_MAP, pero a la inversa, convirtiendo del nombre de la dimensión a la clave del filtro. Los valores del filtro son los valores de la columna de datos.

Envía el evento de cambio de filtro al panel incorporado

4. Con los filtros del panel deseados, el método streamAndParseResponse llama al método setFilters del componente Chat con los filtros deseados.
5. Esto llama al método setDashboardFilters del componente EmbedChat, que envía dos eventos, "dashboard:filters:update" con los filtros y "dashboard:run" al panel incorporado en sucesión inmediata con el método send del SDK de Embed.
6. El evento "dashboard:filters:update" cambia los filtros del panel incorporado, mientras que el evento "dashboard:run" vuelve a ejecutar las consultas del panel con los filtros nuevos.

Debes enviar "dashboard:run" después del evento "dashboard:filters:update". El evento "dashboard:filters:update" no vuelve a ejecutar automáticamente las consultas del panel.

8. Conclusión y aspectos clave

Configuraste tu propio ejemplo de funcionamiento de un panel de Looker incorporado integrado con el chat de Conversational Analytics. Aprendiste a habilitar la exploración de datos basada en lenguaje natural con tu panel de Looker incorporado y Conversational Analytics.

• Creaste un componente de chat con la biblioteca de componentes de Looker.
• Pasaste el contexto del panel de Looker incorporado a Conversational Analytics para facilitar la exploración de datos.
• Habilitaste Conversational Analytics para controlar los filtros del panel incorporado y mejorar el contexto mientras exploras los datos.

Próximos pasos

• Obtén más información sobre las capacidades de Conversational Analytics.
• Actualiza tu app de ejemplo de Looker Embed Reference para que funcione con tus propios paneles de Looker incorporados.
• Prueba los otros casos de uso de incorporación disponibles en tu app de ejemplo de Looker Embed Reference que se ejecuta de forma local.