Codelab da extensão de resumo do Painel do Looker

1. Antes de começar

Neste codelab, você vai (1) configurar a extensão de resumo do painel do Looker localmente para testar e desenvolver no seu computador. Em seguida, (2) você vai implantar a extensão na produção para que outros usuários do Looker na sua instância possam usá-la. Por fim, (3) siga outras etapas para ajustar e melhorar a funcionalidade da extensão. Todas as seções não opcionais precisam ser preenchidas em ordem sequencial.

Visão geral da extensão de resumo do painel do Looker

Funcionalmente, a extensão de resumo do painel do Looker envia os dados do painel do Looker para o modelo Gemini da Vertex AI. Em seguida, o modelo do Gemini retorna um resumo dos dados do painel e uma prescrição das próximas etapas. A extensão mostra o resumo e as próximas etapas como um bloco no painel, integrando-se à sua experiência. Além disso, a extensão pode exportar o resumo e as próximas etapas para o Slack ou o Google Chat. A extensão usa um aplicativo de front-end React associado a um serviço de back-end websocket para enviar e receber dados do modelo Gemini da Vertex AI.

Pré-requisitos

  • Familiaridade básica com desenvolvimento em Node, Docker e Terraform
  • Conhecimento sobre como configurar um projeto do LookML no Looker

O que você vai aprender

  • Como configurar e desenvolver a extensão localmente
  • Como implantar a extensão na produção para que outros usuários do Looker na sua instância possam usá-la
  • Como ajustar a performance da extensão e ampliar a funcionalidade dela.
  • Como gerenciar sua extensão implantada em produção

O que é necessário

  • Uma instância do Looker, seja por uma licença original do Looker, um teste ativo do Looker Core ou uma licença ativa do Looker Core.
  • Permissões develop e deploy na sua instância do Looker.
  • Permissões para editar um painel que você quer testar com a extensão.
  • Uma chave de API Looker da sua instância do Looker.
  • Ter um projeto na nuvem do Google Cloud com o faturamento ativado.
  • As APIs Cloud Run, Vertex AI e API Artifact Registry ativadas no projeto.
  • Acesso a um ambiente local com a CLI gcloud instalada. As etapas do codelab pressupõem um ambiente de estilo Linux.

2. Configurar o back-end para desenvolvimento local

Nesta seção, você vai configurar o serviço de back-end do WebSocket para testar e desenvolver localmente. O serviço terá acesso à Vertex AI.

  1. Instale a versão 18 ou mais recente do Node no ambiente local. Siga estas instruções para instalar o Node.
  2. Clone o repositório da extensão no seu diretório inicial local e navegue até o diretório raiz do repositório. Para fins deste codelab, todas as amostras de código vão considerar que o repositório clonado está no diretório inicial local.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Navegue até o diretório raiz do repositório clonado e renomeie o arquivo .env.example para .env. Isso permite definir variáveis de ambiente nas seções posteriores deste codelab.
cd ~/dashboard-summarization
mv .env.example .env
  1. Navegue até o diretório src do back-end do WebSocket do repositório clonado. Esse diretório contém o código-fonte do servidor.
cd ~/dashboard-summarization/websocket-service/src
  1. Instale as dependências do serviço com o NPM.
npm install
  1. Renomeie o arquivo looker-example.ini como looker.ini.
mv looker-example.ini looker.ini
  1. No arquivo looker.ini, atualize:
  2. Os client_id e client_secret com os da sua chave de API Looker.
  3. O base_url com o URL da sua instância do Looker no formato: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. O texto entre colchetes (o cabeçalho da seção) com o host do URL da sua instância do Looker.

Por exemplo, se o ID do cliente for ABC123, a chave secreta do cliente for XYZ789 e o URL da instância do Looker for https://mycompany.cloud.looker.com, o arquivo looker.ini terá esta aparência:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Determine o ID do projeto na nuvem do Google Cloud e defina-o na variável de ambiente PROJECT. Substitua YOUR_PROJECT_ID pelo ID do projeto.
export PROJECT="YOUR_PROJECT_ID"
  1. A Vertex AI oferece o modelo Gemini em várias regiões listadas aqui. Determine de qual região seu back-end local vai enviar e receber dados do modelo Gemini da Vertex AI. Defina a região na variável de ambiente REGION. Substitua YOUR_VERTEX_REGION pela sua região, como us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Agora, inicie o serviço local.
npm start
  1. O serviço de back-end websocket local será executado em http://localhost:5000.

Você concluiu a configuração do serviço de back-end do websocket no seu ambiente local.

O serviço funciona como uma interface entre sua extensão de front-end e o modelo Gemini da Vertex AI. O serviço vai usar dados do painel e da LookML da sua extensão de front-end com dados consultados do Looker e vai solicitar o modelo Gemini da Vertex AI. Em seguida, o serviço vai transmitir a resposta do Gemini para a extensão de front-end, que será exibida no painel.

Você também pode fazer mudanças no código-fonte do serviço de back-end. Primeiro, pare o processo de serviço, faça mudanças no código e execute npm start novamente.

3. Configurar o front-end para desenvolvimento local

Nesta seção, você vai configurar a extensão de front-end para testar e desenvolver localmente.

  1. No mesmo ambiente local das etapas anteriores, navegue até o diretório raiz do repositório clonado e instale as dependências do servidor de front-end para seu front-end.
cd ~/dashboard-summarization
npm install
  1. Iniciar o servidor de desenvolvimento local do front-end
npm run develop
  1. O servidor de front-end local agora está veiculando o JavaScript da extensão em http://localhost:8080/bundle.js.
  2. Abra um navegador da Web e faça login na sua instância do Looker.
  3. Siga estas instruções para configurar um projeto do LookML em branco. Nomeie o projeto como "dashboard-summarization". O projeto em branco do LookML vai ser aberto automaticamente no IDE do Looker na guia atual do navegador.
  4. Crie um arquivo de manifesto do projeto na raiz do projeto do LookML. O arquivo será chamado de manifest.lkml. Se você não souber como fazer isso, siga estas instruções sobre como adicionar um arquivo a um projeto do LookML.
  5. Substitua o conteúdo do novo arquivo manifest.lkml pelo conteúdo do arquivo manifest.lkml no diretório raiz do repositório fechado. Selecione o botão "Salvar mudanças" no canto superior direito para salvar as alterações no arquivo.
  6. Em uma guia separada do navegador, acesse a lista de conexões de banco de dados na sua instância do Looker. Siga estas instruções se não souber como fazer isso.
  7. Escolha o nome de uma conexão de banco de dados do Looker. Não importa qual conexão você escolher. Se você não tiver permissão para ver as conexões com o banco de dados, entre em contato com o administrador do Looker e peça o nome de uma conexão.
  8. Volte para a guia do navegador com seu projeto do LookML aberto em um ambiente de desenvolvimento integrado do Looker. Crie um arquivo modelo no seu projeto do LookML e nomeie-o como dashboard-summarization.
  9. Substitua o conteúdo do arquivo dashboard-summarization.model.lkml pelo exemplo de código abaixo. Substitua a string entre as aspas duplas pelo nome da conexão de banco de dados escolhido na etapa 9. Salve as alterações no arquivo.
connection: "<YOUR_CONNECTION_NAME>"
  1. Configure um repositório para salvar seu projeto. Selecione o botão "Configurar Git" no canto superior direito. Selecione "Configurar um repositório simples". Selecione "Criar repositório".
  2. Agora você tem um repositório básico para armazenar os arquivos do projeto do LookML. Volte ao projeto no ambiente de desenvolvimento integrado do Looker selecionando "Voltar ao projeto" ou navegando manualmente.
  3. Selecione o botão "Validar LookML" no canto superior direito. O botão vai mudar para "Commit changes and push".
  4. Selecione o botão "Confirmar mudanças e enviar". Adicione a mensagem que quiser e selecione "Confirmar".
  5. Selecione "Implantar na produção" no canto superior direito do IDE do Looker. Agora você adicionou a extensão à sua instância do Looker.
  6. Navegue até um painel do Looker em que você quer adicionar a extensão.
  7. Siga as instruções para adicionar um bloco de extensão ao painel. Adicione a nova extensão ao painel como um bloco.
  8. Verifique se o serviço de back-end websocket local configurado anteriormente está em execução.

Parabéns! Agora você pode testar a extensão de resumo do painel do Looker no seu painel. A extensão vai enviar os metadados do painel para o serviço de back-end websocket local e mostrar a saída do Gemini do serviço de back-end diretamente no bloco da extensão do painel.

Enquanto o servidor de front-end local estiver em execução, você poderá fazer mudanças no código-fonte JavaScript da extensão. O servidor vai criar e disponibilizar as mudanças automaticamente. Será necessário recarregar a extensão ou a página do painel para ver as mudanças.

4. Implantar o back-end na produção

Nesta seção, você vai configurar o serviço de back-end do websocket para atender a todas as instâncias da extensão de resumo do dashboard em qualquer dashboard na sua instância do Looker. Isso permite que outros usuários do Looker testem a extensão nos próprios painéis sem precisar configurar um serviço de back-end. Estas etapas pressupõem que você já tenha implantado o back-end para desenvolvimento local no mesmo ambiente local.

  1. Siga estas instruções para configurar uma credencial padrão de aplicativo no ambiente local com o ID do projeto para as próximas etapas.
  2. Crie um repositório do Artifact Registry para as imagens do Docker do seu serviço de back-end. Substitua YOUR_REGION pela região em que você quer que o repositório esteja.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Navegue até o diretório src do back-end do WebSocket do repositório clonado.
cd ~/dashboard-summarization/websocket-service/src
  1. Edite o arquivo cloudbuild.yaml e substitua todas as instâncias de YOUR_REGION e YOUR_PROJECT_ID pela região e pelo ID do projeto. Salve as alterações no arquivo.
  2. Envie um build usando o Cloud Build que vai criar a imagem Docker do serviço de back-end e enviá-la para o repositório do Artifact Registry que você acabou de criar. Substitua YOUR_REGION pela região em que você quer usar o serviço do Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. O URL da imagem Docker recém-criada é YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Substitua YOUR_PROJECT_ID pelo ID do projeto. Substitua YOUR_REGION pela região da etapa 2 que você usou para criar o repositório do Artifact Registry.
  2. Navegue até o diretório websocket-service/terraform no repositório clonado.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Determine em qual local do Google Cloud Run você quer executar o serviço de back-end do websocket. Escolha um destes locais.
  2. Edite o arquivo variables.tf e substitua YOUR_PROJECT_ID e YOUR_DOCKER_IMAGE_URL pelos valores apropriados. Confira a etapa 6 para ver o URL da imagem do Docker. Substitua YOUR_REGION pela região escolhida na etapa 8 anterior. Salve as alterações no arquivo.
  3. Implante os recursos que seu serviço de back-end vai usar com o Terraform.
terraform init
terraform plan
terraform apply
  1. Salve o endpoint de URL do Cloud Run implantado para a próxima seção.

Parabéns! Você implantou o serviço de back-end do websocket, e ele está sendo executado no Google Cloud Run. Agora, todas as instâncias da extensão de resumo do painel do Looker podem se comunicar com seu serviço de back-end. Recomendamos que você sempre tenha pelo menos uma instância do serviço de back-end do websocket em execução no Cloud Run. A persistência do serviço de back-end mantém a integridade do streaming de dados entre o serviço de back-end do websocket e o front-end da extensão, além de ajudar a manter a sessão de cada usuário enquanto ele usa a extensão.

5. Implantar o front-end na produção

Nesta última seção, você vai realizar as etapas finais de implantação do front-end da extensão para que ela fique disponível a todos os usuários do Looker na sua instância.

  1. Navegue até o diretório raiz do repositório clonado.
cd ~/dashboard-summarization
  1. Edite o .arquivo env. Substitua YOUR_CLOUD_RUN_URL pelo endpoint do URL do Cloud Run da seção anterior. Salve as mudanças no arquivo. Isso vai apontar o front-end da extensão de produção para o serviço de back-end do WebSocket em execução no Cloud Run.
  2. Crie o JavaScript da extensão. Um diretório dist será gerado automaticamente com um arquivo bundle.js e outros arquivos nele.
npm run build
  1. Abra um navegador da Web e faça login na sua instância do Looker. Abra a navegação à esquerda e ative o botão "Modo de desenvolvimento" na parte de baixo.
  2. Com a navegação à esquerda aberta, selecione "Desenvolver", role para baixo e selecione "dashboard-summarization", o projeto do LookML da sua extensão. Agora você está no ambiente de desenvolvimento integrado do Looker para o projeto do LookML.
  3. Arraste e solte todos os arquivos do diretório "dist" gerado anteriormente no diretório raiz do projeto no "Navegador de arquivos". Siga estas instruções se precisar de mais ajuda.
  4. Abra o arquivo manifest.lkml no ambiente de desenvolvimento integrado do Looker. No arquivo, substitua a linha
url: "http://localhost:8080/bundle.js"

com

file: "bundle.js"

Substitua YOUR_CLOUD_RUN_URL pelo endpoint do URL do Cloud Run do final da última seção. Salve as mudanças no arquivo.

  1. Selecione o botão "Validar LookML" no canto superior direito. O botão vai mudar para "Commit changes and push".
  2. Selecione o botão "Confirmar mudanças e enviar". Adicione a mensagem que quiser e selecione "Confirmar".
  3. Selecione "Implantar na produção" no canto superior direito do IDE do Looker.

Parabéns! Agora, todos os usuários do Looker na sua instância podem adicionar a extensão de resumo do painel do Looker aos próprios painéis. À medida que outros usuários do Looker usam a extensão, todas as instâncias dela fazem chamadas para o serviço de back-end websocket implantado em execução no Google Cloud Run.

Se você fizer alguma mudança no código-fonte, é necessário:

  1. Crie o JavaScript da sua extensão novamente.
  2. Substitua os arquivos gerados que você adicionou ao projeto do LookML pelos arquivos recém-gerados do diretório dist.
  3. Validar, confirmar e implantar as mudanças do projeto do LookML na produção

Teste a extensão de resumo do painel do Looker. Incentivamos você a contribuir com a extensão e ajudar a atender melhor às necessidades da comunidade do Looker. Crie uma solicitação de pull no repositório.

Confira as seções opcionais a seguir para ativar a exportação do Slack/Google Chat, ajustar os resumos e as próximas etapas do Gemini e configurar o registro do Gemini.

6. [Opcional] Configurar recursos de exportação

Agora que você e seus usuários do Looker testaram a extensão de resumo do painel do Looker, vamos compartilhar a análise dela com um público maior. Siga esta seção para permitir que sua extensão envie resumos e próximas etapas para o Google Chat ou o Slack. Você precisa conhecer a configuração do OAuth para continuar com esta seção do codelab.

Ativar a exportação do Google Chat

  1. Ative a API Chat no seu projeto na nuvem do Google Cloud.
  2. Siga a etapa 1 das instruções de configuração do OAuth do Google Workspace. Para escopos, inclua spaces.messages.create.
  3. Siga a etapa 2 das instruções de configuração do OAuth do Google Workspace. Adicione o URL da sua instância do Looker como um URI em "Origens JavaScript autorizadas". Por exemplo, https://mycompany.cloud.looker.com. Anote o ID do cliente gerado.
  4. Determine o ID do espaço do Chat do Google para onde você quer exportar os resumos. Se você não souber como fazer isso, siga estas instruções.
  5. Edite o .arquivo env. Substitua YOUR_GOOGLE_CLIENT_ID pelo ID do cliente. Substitua YOUR_GOOGLE_SPACE_ID pelo ID do espaço do Google Chat. Salve as mudanças no arquivo. Isso vai configurar o front-end da extensão para enviar insights ao espaço do Google Chat que você quer.
  6. Se você estiver executando o front-end da extensão localmente, crie a extensão novamente. Caso contrário, se você estiver implantando o front-end da extensão, faça isso de novo.

Ativar a exportação para o Slack

  1. Siga as etapas 1 e 2 da documentação oficial para desenvolvedores do Slack e configure um aplicativo OAuth. Para escopos, inclua chat:write e channels:read. Anote o ID do cliente e a chave secreta do cliente gerados.
  2. Determine o ID do canal do Slack para onde você quer exportar os resumos.
  3. Edite o .arquivo env. Substitua YOUR_SLACK_CLIENT_ID pelo ID do cliente. Substitua YOUR_SLACK_CLIENT_SECRET pela chave secreta do cliente. Substitua YOUR_SLACK_CHANNEL_ID pelo ID do canal. Salve as mudanças no arquivo. Isso vai configurar o front-end da extensão para enviar insights ao canal do Slack que você quer.
  4. Se você estiver executando o front-end da extensão localmente, crie a extensão novamente. Caso contrário, se você estiver implantando o front-end da extensão, faça isso de novo.

Agora, a extensão pode exportar os resumos diretamente para o Slack ou o Google Chat. A extensão só pode enviar resumos para um espaço específico do Google Chat ou um canal do Slack. Você pode adicionar outros escopos do OAuth e modificar o código para buscar e mostrar uma lista de espaços e canais para enviar resumos.

7. [Opcional] Ajustar o resumo e as próximas etapas

A extensão solicita ao modelo do Gemini todos os metadados do painel e consulta os dados. Para melhorar a precisão, o detalhe e a profundidade dos resumos e das etapas prescritivas, adicione o máximo possível de metadados e contexto ao próprio painel. Siga estas etapas para cada painel de que sua extensão faz parte:

  • Siga estas instruções para adicionar detalhes ao painel. Isso vai ajudar a informar ao LLM o contexto geral do painel.
  • Siga estas instruções para adicionar observações ao bloco de cada painel. Isso vai ajudar a informar à LLM o contexto de cada consulta individual no painel. As pequenas observações contextuais serão consideradas nos resumos gerados.

Quanto mais informações você adicionar aos seus painéis, melhores serão os resumos e as próximas etapas da extensão. Você pode modificar o código para incluir mais metadados do painel no comando para o modelo do Gemini.

8. [Opcional] Configurar o registro em registros do modelo do Gemini

Sempre que um usuário pede para a extensão criar resumos de um painel, ela faz uma chamada para a Vertex AI para cada consulta no painel, além de uma chamada final para formatar todos os resumos. Siga esta seção para registrar as chamadas da Vertex AI feitas pela sua extensão e estimar e monitorar os custos e o tráfego da Vertex AI. Siga estas instruções apenas se você tiver implantado o serviço de back-end do WebSocket.

  1. Determine o local do Cloud Run do serviço de back-end websocket implantado.
  2. Siga estas instruções para configurar um coletor de registros que vai encaminhar os registros para o BigQuery. O destino do coletor precisa ser o BigQuery. Defina o filtro de inclusão com o exemplo de código a seguir, substituindo YOUR_CLOUD_RUN_LOCATION pelo local do Cloud Run da etapa 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. Parabéns!

Você configurou a extensão de resumo do painel do Looker localmente para testar. Você também implantou a extensão no Google Cloud para que outros usuários possam testá-la. Agora você e outros usuários podem acessar resumos e próximas etapas gerados pelo Gemini diretamente nos painéis.

10. A seguir