Sobre este codelab
1. Antes de começar
Neste codelab, você vai configurar a extensão de resumo do painel do Looker localmente para testar e desenvolver. Depois (2) você vai implantar a extensão na produção para que outros usuários do Looker na sua instância do Looker possam usá-la. Por fim, (3) você pode seguir etapas adicionais para ajustar e aprimorar a funcionalidade da extensão. Todas as seções não opcionais precisam ser preenchidas em sequência.
Informações gerais 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. O modelo do Gemini retorna um resumo dos dados do seu 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 à experiência do painel. 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 do React aliado a um serviço de back-end do websocket para enviar e receber dados do modelo Gemini da Vertex AI.
Pré-requisitos
- Conhecimento básico de desenvolvimento do Node, Docker e Terraform
- Familiaridade com a configuração de um projeto do LookML do 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 o desempenho da extensão e estender a funcionalidade dela.
- Como gerenciar a extensão implantada na produção
O que é necessário
- Uma instância do Looker, seja por uma licença original do Looker, um teste do Looker Core ativo ou uma licença ativa do Looker Core.
- permissões
develop
edeploy
na sua instância do Looker. - Permissões para editar um painel que você quer testar com a extensão.
- Uma chave da API Looker da sua instância do Looker.
- Um projeto do Google Cloud com o faturamento ativado.
- API Cloud Run, API Vertex AI e API Artifact Registry ativadas no projeto.
- Acesso a um ambiente local com a CLI gcloud instalada. As etapas do codelab consideram um ambiente no estilo Linux.
2. Configurar back-end para desenvolvimento local
Nesta seção, você configurará o serviço de back-end do websocket para experimentar e desenvolver localmente. O serviço terá acesso à Vertex AI.
- Instale a versão 18 ou mais recente do Node no seu ambiente local. Siga estas instruções para instalar o Node.
- Clone o repositório da extensão no diretório principal local e navegue até o diretório raiz. Para este codelab, todos os exemplos de código vão presumir que o repositório clonado está no diretório inicial local.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
- Navegue até o diretório raiz do repositório clonado e renomeie o arquivo
.env.example
como.env
para permitir que você defina variáveis de ambiente nas próximas seções deste codelab.
cd ~/dashboard-summarization
mv .env.example .env
- Navegue até o diretório
src
do back-end do soquete da Web do repositório clonado. Esse diretório contém o código-fonte do servidor.
cd ~/dashboard-summarization/websocket-service/src
- Instale as dependências do serviço com o NPM.
npm install
- Renomeie o arquivo
looker-example.ini
comolooker.ini
.
mv looker-example.ini looker.ini
- Na atualização do arquivo looker.ini:
- O
client_id
e oclient_secret
com os da sua chave de API Looker. - O
base_url
com o URL da instância do Looker no formato:https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
- O texto entre colchetes (o cabeçalho da seção) com o host do URL da 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
vai ficar assim:
[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
- Determine o ID do projeto do Google Cloud e defina-o na variável de ambiente
PROJECT
. SubstituaYOUR_PROJECT_ID
pelo ID do projeto.
export PROJECT="YOUR_PROJECT_ID"
- A Vertex AI oferece o modelo Gemini em várias regiões listadas aqui. Determinar 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
. SubstituaYOUR_VERTEX_REGION
pela sua região, comous-central1
.
export REGION="YOUR_VERTEX_REGION"
- Agora, inicie o serviço local.
npm start
- Seu serviço de back-end de Websocket local será executado em http://localhost:5000.
Você terminou de configurar o serviço de back-end do websocket no seu ambiente local.
O serviço funciona como uma interface entre a extensão de front-end e o modelo Gemini da Vertex AI. O serviço vai usar dados do painel e do LookML da sua extensão de front-end com dados consultados do Looker e 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á mostrada no painel.
Também é possível fazer mudanças no código-fonte do serviço de back-end. Primeiro, interrompa o processo de serviço, faça mudanças no código e, em seguida, execute npm start
novamente.
3. Configure o front-end para desenvolvimento local
Nesta seção, você vai configurar a extensão de front-end para testar e desenvolver localmente.
- No mesmo ambiente local das etapas anteriores, acesse o diretório raiz do repositório clonado e instale as dependências do servidor de front-end para o front-end.
cd ~/dashboard-summarization
npm install
- Inicie seu servidor de desenvolvimento front-end local
npm run develop
- Seu servidor de front-end local agora está exibindo o JavaScript da extensão em http://localhost:8080/bundle.js.
- Abra um navegador da Web e faça login na sua instância do Looker.
- Siga estas instruções para configurar um projeto do LookML em branco. Nomeie o painel de resumo do projeto. O projeto em branco do LookML deve ser aberto automaticamente no ambiente de desenvolvimento integrado do Looker na guia atual do navegador.
- 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 para adicionar um arquivo a um projeto do LookML.
- Substitua o conteúdo do novo arquivo manifest.lkml pelo conteúdo de manifest.lkml no diretório raiz do repositório fechado. Clique no botão "Save Changes" no canto superior direito para salvar as mudanças no arquivo.
- Em outra guia do navegador, acesse a lista de conexões de banco de dados na instância do Looker. Caso não saiba como fazer isso, siga estas instruções.
- 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 consultar as conexões do banco de dados, entre em contato com o administrador do Looker e peça o nome de uma conexão de banco de dados.
- Volte para a guia do navegador com o projeto do LookML aberto em um ambiente de desenvolvimento integrado do Looker. Crie um arquivo de modelo no seu projeto LookML e nomeie-o como "dashboard-summarization".
- Substitua o conteúdo do arquivo dashboard-summarization.model.lkml pelo exemplo de código abaixo. Lembre-se de substituir a string entre aspas duplas pelo nome da conexão do banco de dados que você escolheu na etapa 9. Salve as alterações no arquivo.
connection: "<YOUR_CONNECTION_NAME>"
- Configure um repositório para salvar seu projeto. Selecione o botão "Configure Git" no canto superior direito. Selecione "Configurar um repositório raiz em vez disso". Selecione "Criar repositório".
- Agora você tem um repositório básico para armazenar arquivos de projeto do LookML. Navegue de volta ao projeto no ambiente de desenvolvimento integrado do Looker selecionando "Voltar ao projeto" ou navegando manualmente de volta.
- Selecione o botão "Validar LookML" no canto superior direito. O botão vai mudar para "Commit changes and push".
- Selecione o botão "Commit changes and push". Adicione a mensagem que quiser e selecione "Confirmar".
- Selecione "Deploy to Production" no canto superior direito do Looker IDE. Você adicionou a extensão à sua instância do Looker.
- Acesse um painel do Looker em que você quer adicionar a extensão.
- Siga as instruções para adicionar um bloco de extensão ao seu painel. Adicione sua nova extensão ao painel como um bloco.
- Verifique se o serviço de back-end do WebSocket local que você configurou 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 no bloco de extensão do painel.
Enquanto o servidor de front-end local estiver em execução, você poderá fazer alterações no código-fonte JavaScript da extensão, e o servidor vai criar e veicular as mudanças automaticamente. Será necessário recarregar a extensão ou a página do painel para ver as alterações.
4. Implantar o back-end na produção
Nesta seção, você vai configurar o serviço de back-end do websocket para exibir todas as instâncias da sua extensão de resumo do painel em qualquer painel da instância do Looker. Assim, outros usuários do Looker poderão testar a extensão nos próprios painéis sem precisar configurar um serviço de back-end próprio. Estas etapas pressupõem que você já tenha implantado o back-end para desenvolvimento local no mesmo ambiente.
- Siga estas instruções para configurar uma credencial padrão do aplicativo no seu ambiente local com o ID do projeto para as próximas etapas.
- Crie um repositório do Artifact Registry para as imagens 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 \
- Navegue até o diretório
src
do back-end do WebSocket do repositório clonado.
cd ~/dashboard-summarization/websocket-service/src
- Edite o arquivo
cloudbuild.yaml
e substitua todas as instâncias deYOUR_REGION
eYOUR_PROJECT_ID
pelo ID da região e do projeto. Salve as alterações no arquivo. - Envie um build usando o Cloud Build para criar a imagem do 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
- O URL da imagem Docker recém-criada está em
YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest
. SubstituaYOUR_PROJECT_ID
pelo ID do projeto. SubstituaYOUR_REGION
pela região da etapa 2 que você usou para criar o repositório do Artifact Registry. - Navegue até o diretório
websocket-service/terraform
no repositório clonado.
cd ~/dashboard-summarization/websocket-service/terraform
- Determine em qual local do Google Cloud Run você quer executar o serviço de back-end do WebSocket. Escolha um destes locais.
- Edite o arquivo variables.tf e substitua
YOUR_PROJECT_ID
eYOUR_DOCKER_IMAGE_URL
pelos valores apropriados. Verifique o URL da imagem do Docker na etapa 6. SubstituaYOUR_REGION
pela região que você escolheu na etapa 8 anterior. Salve as alterações no arquivo. - Implante os recursos que o serviço de back-end vai usar com o Terraform.
terraform init
terraform plan
terraform apply
- Salve o endpoint do URL do Cloud Run implantado para a próxima seção.
Parabéns! Você implantou seu serviço de back-end do websocket e agora ele está em execução no Google Cloud Run. Agora, todas as instâncias da extensão de resumo do painel do Looker podem se comunicar com o serviço de back-end. Recomendamos que você sempre tenha pelo menos uma instância do seu 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 fluxo 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 à medida que usam sua 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 para todos os usuários do Looker na sua instância.
- Navegue até o diretório raiz do repositório clonado.
cd ~/dashboard-summarization
- Edite o arquivo .arquivo
env
. SubstituaYOUR_CLOUD_RUN_URL
pelo endpoint do URL do Cloud Run da seção anterior. Salve as alterações no arquivo. Isso vai apontar o front-end da extensão de produção para seu serviço de back-end do WebSocket em execução no Cloud Run. - Crie o JavaScript da extensão. Um diretório
dist
será gerado automaticamente com um arquivobundle.js
e outros arquivos.
npm run build
- Abra um navegador da Web e faça login na sua instância do Looker. Abra a navegação lateral esquerda e ative a opção "Modo de Desenvolvimento" na parte inferior.
- Com a navegação lateral esquerda aberta, selecione "Desenvolver", role para baixo e selecione "dashboard-summarization", o projeto do LookML da sua extensão. Você deve estar no IDE do Looker para o projeto do LookML.
- Arraste e solte todos os arquivos no diretório dist gerado anteriormente no diretório raiz do projeto no "File Browser". Se precisar de mais ajuda, siga estas instruções.
- Abra o arquivo
manifest.lkml
dentro do Looker IDE. 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 no fim da seção anterior. Salve as alterações no arquivo.
- Selecione o botão "Validar LookML" no canto superior direito. O botão será alterado para "Confirmar alterações e enviar".
- Selecione o botão "Commit changes and push". Adicione a mensagem que quiser e selecione "Confirmar".
- Selecione "Deploy to Production" no canto superior direito do Looker IDE.
Parabéns! Você ativou que todos os usuários do Looker na sua instância do Looker adicionem a extensão de resumo do painel do Looker aos 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 do WebSocket implantado no Google Cloud Run.
Se você fizer alterações no código-fonte, é necessário:
- Crie o JavaScript da sua extensão novamente
- Substitua os arquivos gerados que você adicionou ao projeto do LookML pelos novos arquivos gerados no diretório
dist
. - Valide, confirme e implante as alterações do projeto LookML na produção
Teste a extensão de resumo do painel do Looker. Recomendamos que você contribua com a extensão para atender melhor às necessidades da comunidade do Looker. Fique à vontade para criar uma solicitação de envio 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 a geração de registros 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 os insights da extensão com um público maior. Siga esta seção para ativar sua extensão para enviar resumos e as próximas etapas ao Google Chat ou ao Slack. Para continuar com esta seção do codelab, você precisa ter familiaridade com a configuração do OAuth.
Ativar a exportação do Google Chat
- Ative a API Chat no projeto do Google Cloud.
- Siga a etapa 1 das instruções de configuração do OAuth do Google Workspace. Para escopos, inclua
spaces.messages.create
. - Siga a etapa 2 das instruções de configuração do OAuth do Google Workspace. Adicione o URL da instância do Looker como um URI em "Origens JavaScript autorizadas", por exemplo,
https://mycompany.cloud.looker.com
. Anote o ID do cliente gerado. - Determine o ID do espaço do Google Chat para onde você quer exportar os resumos. Se você não souber como fazer isso, siga estas instruções.
- Edite o .arquivo
env
. SubstituaYOUR_GOOGLE_CLIENT_ID
pelo ID do cliente. SubstituaYOUR_GOOGLE_SPACE_ID
pelo ID do espaço do Google Chat. Salve as alterações no arquivo. Isso vai configurar o front-end da sua extensão para enviar os insights ao espaço do Google Chat. - Se você estiver executando o front-end da sua extensão localmente, recrie-a. Caso contrário, se você estiver implantando o front-end da sua extensão, reimplante o front-end dela.
Ativar a exportação do Slack
- Siga as etapas 1 e 2 da documentação oficial para desenvolvedores do Slack e configure um aplicativo OAuth. Para escopos, inclua
chat:write
echannels:read
. Anote o ID e a chave secreta do cliente gerados. - Determine o ID do canal do Slack para onde você quer exportar os resumos.
- Edite o arquivo .arquivo
env
. SubstituaYOUR_SLACK_CLIENT_ID
pelo ID do cliente. SubstituaYOUR_SLACK_CLIENT_SECRET
pela chave secreta do cliente. SubstituaYOUR_SLACK_CHANNEL_ID
pelo ID do canal. Salve as alterações no arquivo. Isso vai configurar o front-end da sua extensão para enviar insights ao canal do Slack que você quer. - Se você estiver executando o front-end da sua extensão localmente, recrie-a. Caso contrário, se você estiver implantando o front-end da sua extensão, reimplante o front-end dela.
Agora sua extensão pode exportar os resumos diretamente para o Slack ou o Google Chat. Lembre-se de que a extensão só pode enviar resumos para um espaço de chat do Google ou canal do Slack fixado no código. 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 envia ao modelo Gemini todos os metadados e dados de consultas do painel. É possível melhorar a precisão, os detalhes e a profundidade dos resumos e das etapas prescritivas adicionando o máximo 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 do dashboard ao dashboard. Isso ajuda 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 o LLM sobre 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. É possível modificar o código para incluir outros metadados do painel no comando para o modelo do Gemini.
8. [Opcional] Configurar o registro de modelos 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 extensão e estimar e monitorar os custos e o tráfego da Vertex AI. Siga estas instruções apenas se tiver implantado o serviço de back-end do websocket.
- Determine o local do Cloud Run do seu serviço de back-end do websocket implantado.
- Siga estas instruções para configurar um coletor de registros que encaminha 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. Substitua
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 também possam testá-la. Agora você e outros usuários podem acessar os resumos e as próximas etapas gerados pelo Gemini diretamente nos seus painéis.
10. A seguir
- Modifique a base de código da sua extensão para adaptar a funcionalidade às necessidades da sua organização.
- Contribua com o repositório da extensão e aprimore-a para você e sua comunidade do Looker.
- Desenvolva sua própria extensão para melhorar sua experiência com o Looker.
- Integre sua extensão em um painel como um bloco para melhorar a experiência no painel.