Расширение суммирования Looker Dashboard Codelab

1. Прежде чем начать

В этой лаборатории кода (1) вы настроите расширение суммирования панели Looker Dashboard локально, чтобы опробовать его и развивать локально. Затем (2) вы развернете расширение в рабочей среде, чтобы другие пользователи Looker в вашем экземпляре Looker могли его использовать. Наконец, (3) вы можете выполнить дополнительные шаги для точной настройки и улучшения функциональности расширения. Все необязательные разделы следует заполнять в последовательном порядке.

Обзор расширения суммирования Looker Dashboard

Функционально расширение суммирования панели Looker Dashboard отправляет данные панели мониторинга Looker в модель Gemini от Vertex AI. Затем модель Gemini возвращает сводку данных вашей информационной панели и рекомендации по следующим шагам. Расширение отображает сводную информацию и следующие шаги в виде плитки на вашей информационной панели, интегрируя ее в вашу информационную панель. Кроме того, расширение может экспортировать сводку и следующие шаги в Slack или Google Chat. Расширение использует интерфейсное приложение React в сочетании с серверной службой веб-сокетов для отправки и получения данных в модель Gemini от Vertex AI и обратно.

Предварительные условия

  • Базовое знание разработки Node, Docker и Terraform.
  • Знакомство с настройкой проекта Looker LookML.

Что вы узнаете

  • Как настроить и разработать расширение локально
  • Как развернуть расширение в рабочей среде, чтобы его могли использовать другие пользователи Looker в вашем экземпляре Looker.
  • Как дополнительно настроить производительность расширения и расширить его функциональность.
  • Как управлять развернутым расширением в рабочей среде

Что вам понадобится

  • Экземпляр Looker либо по оригинальной лицензии Looker, либо по активной пробной версии Looker Core, либо по активной лицензии Looker Core.
  • разрешения на develop и deploy на вашем экземпляре Looker.
  • Разрешения на редактирование панели мониторинга, которую вы хотели бы опробовать с помощью расширения.
  • Ключ API Looker из вашего экземпляра Looker.
  • Проект Google Cloud, для которого включена оплата.
  • Cloud Run API, Vertex AI API и API реестра артефактов включены в проекте.
  • Доступ к локальной среде с установленным интерфейсом командной строки gcloud. Шаги кодовой лаборатории предполагают среду в стиле Linux.

2. Настройка бэкэнда для локальной разработки

В этом разделе вы настроите серверную службу веб-сокетов, чтобы опробовать ее и разработать локально. Сервис будет иметь доступ к Vertex AI.

  1. Установите Node версии 18 или выше, установленную в вашей локальной среде. Следуйте этим инструкциям , чтобы установить Node.
  2. Клонируйте репозиторий расширения в свой локальный домашний каталог и перейдите в корневой каталог репозитория. Для целей этой лаборатории кода все примеры кода будут предполагать, что ваш клонированный репозиторий находится в вашем локальном домашнем каталоге.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Перейдите в корневой каталог клонированного репозитория и переименуйте файл .env.example в .env чтобы вы могли устанавливать переменные среды в последующих разделах этой лаборатории кода.
cd ~/dashboard-summarization
mv .env.example .env
  1. Перейдите в каталог src серверной части веб-сокета клонированного репозитория. Этот каталог содержит исходный код сервера.
cd ~/dashboard-summarization/websocket-service/src
  1. Установите зависимости службы с помощью NPM .
npm install
  1. Переименуйте файл looker-example.ini в looker.ini .
mv looker-example.ini looker.ini
  1. Внутри обновления файла Looker.ini:
  2. client_id и client_secret соответствуют значениям из вашего ключа API Looker.
  3. base_url с URL-адресом вашего экземпляра Looker в формате: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Текст в скобках (заголовок раздела) с хостом URL-адреса вашего экземпляра Looker.

Например, если ваш идентификатор клиента — ABC123 , ваш секрет клиента — XYZ789 , а URL-адрес вашего экземпляра Looker — https://mycompany.cloud.looker.com , ваш файл looker.ini будет выглядеть именно так:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Определите идентификатор своего проекта Google Cloud и установите его в переменной среды PROJECT . Замените YOUR_PROJECT_ID идентификатором вашего проекта.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI предоставляет модель Gemini в нескольких регионах, перечисленных здесь . Определите, в каком регионе ваш локальный бэкэнд будет отправлять и получать данные из модели Vertex AI Gemini. Установите регион в переменной среды REGION . Замените YOUR_VERTEX_REGION своим регионом, например us-central1 .
export REGION="YOUR_VERTEX_REGION"
  1. Теперь запустите локальную службу.
npm start
  1. Ваша локальная серверная служба веб-сокета будет работать по адресу http://localhost:5000.

Вы завершили настройку серверной службы WebSocket в вашей локальной среде!

Служба служит интерфейсом между вашим внешним расширением и моделью Vertex AI Gemini. Служба будет получать данные информационной панели и LookML из вашего внешнего расширения, а также данные, запрашиваемые из Looker, и запрашивать модель Gemini от Vertex AI. Затем служба будет передавать ответ Gemini на расширение внешнего интерфейса, которое будет отображаться на вашей панели управления.

Вы также можете внести изменения в исходный код серверной службы. Вам нужно будет сначала остановить процесс службы, внести изменения в код, а затем снова запустить npm start .

3. Настройка интерфейса для локальной разработки

В этом разделе вы настроите расширение внешнего интерфейса, которое сможете опробовать и разработать локально.

  1. В той же локальной среде, что и на предыдущих шагах, перейдите в корневой каталог клонированного репозитория и установите зависимости внешнего сервера для вашего внешнего интерфейса.
cd ~/dashboard-summarization
npm install
  1. Запустите локальный сервер фронтенд-разработки.
npm run develop
  1. Ваш локальный интерфейсный сервер теперь обслуживает JavaScript расширения по адресу http://localhost:8080/bundle.js.
  2. Откройте веб-браузер и войдите в свой экземпляр Looker.
  3. Следуйте этим инструкциям , чтобы настроить пустой проект LookML. Назовите проект Dashboard-summarization. Теперь пустой проект LookML должен автоматически открыться в Looker IDE на текущей вкладке браузера.
  4. Создайте файл манифеста проекта в корне проекта LookML. Файл будет называться манифест.lkml. Если вы не знаете, как это сделать, следуйте этим инструкциям по добавлению файла в проект LookML.
  5. Замените содержимое нового файла манифеста.lkml содержимым файла манифеста.lkml в корневом каталоге вашего закрытого репозитория. Нажмите кнопку «Сохранить изменения» в правом верхнем углу, чтобы сохранить изменения в файле.
  6. На отдельной вкладке браузера перейдите к списку подключений к базе данных в вашем экземпляре Looker. Следуйте этим инструкциям , если вы не знаете, как это сделать.
  7. Выберите имя одного подключения к базе данных Looker. Не имеет значения, какое соединение вы выберете. Если у вас нет разрешения на просмотр подключений к базе данных, обратитесь к администратору Looker и запросите имя одного подключения к базе данных Looker.
  8. Вернитесь на вкладку браузера с открытым проектом LookML в Looker IDE. Создайте файл модели в своем проекте LookML и назовите его «dashboard-summarization».
  9. Замените содержимое файла Dashboard-summarization.model.lkml приведенным ниже примером кода. Обязательно замените строку в двойных кавычках именем подключения к базе данных, которое вы выбрали на шаге 9. Сохраните изменения в файле.
connection: "<YOUR_CONNECTION_NAME>"
  1. Настройте репозиторий для сохранения вашего проекта. Нажмите кнопку «Настроить Git» в правом верхнем углу. Выберите «Вместо этого создайте пустой репозиторий». Выберите «Создать репозиторий».
  2. Теперь у вас есть базовый репозиторий для хранения файлов проекта LookML. Вернитесь к проекту в Looker IDE, выбрав «Назад к проекту» или вернитесь назад вручную.
  3. Нажмите кнопку «Проверить LookML» в правом верхнем углу. Кнопка изменится на «Зафиксировать изменения и нажать».
  4. Нажмите кнопку «Зафиксировать изменения и нажать». Добавьте любое сообщение и нажмите «Зафиксировать».
  5. Выберите «Развернуть в производство» в правом верхнем углу Looker IDE. Теперь вы добавили расширение в свой экземпляр Looker!
  6. Перейдите к панели управления Looker, в которую вы хотите добавить расширение.
  7. Следуйте инструкциям , чтобы добавить плитку расширения на панель мониторинга. Добавьте новое расширение на свою панель мониторинга в виде плитки.
  8. Убедитесь, что локальная серверная служба веб-сокета, которую вы настроили ранее, работает.

Поздравляем! Теперь вы можете опробовать расширение суммирования Looker Dashboard на своей информационной панели. Ваше расширение отправит метаданные вашей панели мониторинга в локальную серверную службу веб-сокета и отобразит выходные данные Gemini из вашей внутренней службы прямо на плитке расширения панели мониторинга.

Пока ваш локальный интерфейсный сервер работает, вы можете вносить изменения в исходный код javascript расширения, и сервер автоматически создаст и обработает эти изменения. Вам нужно будет перезагрузить страницу расширения или панели управления, чтобы увидеть изменения.

4. Развертывание серверной части в рабочей среде

В этом разделе вы настроите серверную службу веб-сокета для обслуживания любых экземпляров расширения сводной панели вашей информационной панели на любой информационной панели в вашем экземпляре Looker. Это позволит другим пользователям Looker опробовать расширение на своих информационных панелях без необходимости настраивать собственную серверную службу. В этих шагах предполагается, что вы уже успешно развернули серверную часть для локальной разработки в той же локальной среде.

  1. Следуйте этим инструкциям , чтобы настроить учетные данные приложения по умолчанию в вашей локальной среде с идентификатором вашего проекта для следующих шагов.
  2. Создайте репозиторий реестра артефактов для образов Docker вашей серверной службы. Замените YOUR_REGION на регион, в котором вы хотите разместить свой репозиторий.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Перейдите в каталог src серверной части веб-сокета вашего клонированного репозитория.
cd ~/dashboard-summarization/websocket-service/src
  1. Отредактируйте файл cloudbuild.yaml и замените все экземпляры YOUR_REGION и YOUR_PROJECT_ID на свой регион и идентификатор проекта. Сохраните изменения в файле.
  2. Отправьте сборку с помощью Cloud Build, которая создаст образ Docker серверной службы и поместит его в только что созданный репозиторий реестра артефактов. Замените YOUR_REGION на регион, в котором вы хотите использовать сервис Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Помните, что ваш новый URL-адрес образа Docker находится по адресу YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest . Замените YOUR_PROJECT_ID идентификатором вашего проекта. Замените YOUR_REGION регионом из шага 2, который вы использовали для создания репозитория реестра артефактов.
  2. Перейдите в каталог websocket-service/terraform в вашем клонированном репозитории.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Определите, в каком месте Google Cloud Run вы хотите запустить серверную службу веб-сокета. Выбирайте из этих мест .
  2. Отредактируйте файлvariable.tf и замените YOUR_PROJECT_ID и YOUR_DOCKER_IMAGE_URL соответствующими значениями. Проверьте шаг 6, чтобы узнать URL-адрес вашего образа Docker. Замените YOUR_REGION на регион, который вы выбрали на предыдущем шаге. 8. Сохраните изменения в файле.
  3. Разверните ресурсы, которые будет использовать ваша серверная служба, с помощью terraform.
terraform init
terraform plan
terraform apply
  1. Сохраните конечную точку развернутого URL-адреса Cloud Run для следующего раздела.

Поздравляю! Вы развернули серверную службу веб-сокета, и теперь она работает в Google Cloud Run. Теперь любые экземпляры вашего расширения суммирования Looker Dashboard могут взаимодействовать с вашей серверной службой. Мы рекомендуем всегда иметь хотя бы один экземпляр серверной службы веб-сокета, работающий в Cloud Run. Постоянство вашей серверной службы поддерживает целостность потоковой передачи данных между вашей серверной службой веб-сокета и внешним интерфейсом вашего расширения и помогает поддерживать сеанс каждого пользователя, когда он использует ваше расширение.

5. Развертывание интерфейса в рабочей среде

В этом последнем разделе вы выполните заключительные шаги по развертыванию внешнего интерфейса расширения, который будет доступен всем пользователям Looker в вашем экземпляре Looker.

  1. Перейдите в корневой каталог вашего клонированного репозитория.
cd ~/dashboard-summarization
  1. Отредактируйте файл . env файл. Замените YOUR_CLOUD_RUN_URL конечной точкой URL-адреса Cloud Run из предыдущего раздела. Сохраните изменения файла. Это укажет интерфейс производственного расширения на вашу серверную службу веб-сокета, работающую в Cloud Run.
  2. Создайте JavaScript расширения. Каталог dist будет автоматически создан с файлом bundle.js и другими файлами в нем.
npm run build
  1. Откройте веб-браузер и войдите в свой экземпляр Looker. Откройте боковую левую панель навигации и включите переключатель «Режим разработки» внизу.
  2. Открыв боковую левую панель навигации, выберите «Разработка», затем прокрутите вниз и выберите «Сводная панель», проект LookML вашего расширения. Теперь вы должны находиться в Looker IDE для проекта LookML.
  3. Перетащите все файлы из ранее созданного каталога dist в корневой каталог проекта в «Браузере файлов». Следуйте этим инструкциям , если вам нужна дополнительная помощь.
  4. Откройте файл manifest.lkml в Looker IDE. Внутри файла замените строку
url: "http://localhost:8080/bundle.js"

с

file: "bundle.js"

Замените YOUR_CLOUD_RUN_URL конечной точкой URL-адреса Cloud Run из конца последнего раздела. Сохраните изменения в файле.

  1. Нажмите кнопку «Проверить LookML» в правом верхнем углу. Кнопка изменится на «Зафиксировать изменения и нажать».
  2. Нажмите кнопку «Зафиксировать изменения и нажать». Добавьте любое сообщение и нажмите «Зафиксировать».
  3. Выберите «Развернуть в производство» в правом верхнем углу Looker IDE.

Поздравляю! Теперь вы разрешили всем пользователям Looker в вашем экземпляре Looker добавлять расширение суммирования панели мониторинга Looker на свои панели мониторинга. Поскольку другие пользователи Looker используют расширение, все экземпляры расширения будут выполнять вызовы к вашей развернутой серверной службе веб-сокета, работающей в Google Cloud Run.

Имейте в виду, что если вы вносите какие-либо изменения в исходный код, вы должны:

  1. Снова создайте JavaScript вашего расширения.
  2. Замените сгенерированные файлы, которые вы добавили в проект LookML, вновь сгенерированными файлами из каталога dist .
  3. Проверка, фиксация и развертывание изменений проекта LookML в рабочей среде.

Попробуйте расширение суммирования Looker Dashboard! Мы призываем вас внести свой вклад в расширение и помочь ему лучше удовлетворять потребности сообщества Looker. Пожалуйста, не стесняйтесь создавать запрос на включение в репозиторий .

Ознакомьтесь со следующими дополнительными разделами, чтобы включить экспорт Slack/Google Chat, точно настроить сводки Gemini и следующие шаги, а также настроить ведение журнала Gemini.

6. [Необязательно] Настройка возможностей экспорта

Теперь, когда вы и ваши пользователи Looker опробовали расширение Looker Dashboard Summarization, давайте поделимся информацией о расширении с большей аудиторией. Следуйте этому разделу, чтобы разрешить вашему расширению отправлять сводки и дальнейшие действия в Google Chat или Slack. Чтобы продолжить работу с этим разделом лаборатории кода, вы должны быть знакомы с настройкой Oauth.

Включить экспорт Google Chat

  1. Включите Chat API в своем проекте Google Cloud.
  2. Выполните шаг 1 инструкций по настройке Google Workspace OAuth . Для областей действия необходимо включить spaces.messages.create .
  3. Выполните шаг 2 инструкций по настройке Google Workspace OAuth . Добавьте URL-адрес экземпляра средства просмотра в качестве URI в разделе «Авторизованные источники JavaScript», например https://mycompany.cloud.looker.com . Обратите внимание на сгенерированный идентификатор клиента.
  4. Определите идентификатор пространства Google Chat, в которое вы хотите экспортировать сводки. Если вы не знаете, как это сделать, следуйте этим указаниям .
  5. Отредактируйте файл . env файл. Замените YOUR_GOOGLE_CLIENT_ID на идентификатор клиента. Замените YOUR_GOOGLE_SPACE_ID на идентификатор пространства Google Chat. Сохраните изменения файла. Это позволит настроить внешний интерфейс вашего расширения таким образом, чтобы он мог отправлять свои аналитические данные в нужное вам пространство Google Chat.
  6. Если вы используете интерфейс вашего расширения локально, пересоберите расширение. В противном случае, если вы развертываете интерфейс вашего расширения, повторно разверните интерфейс вашего расширения.

Включить экспорт в Slack

  1. Выполните шаги 1 и 2 официальной документации для разработчиков Slack, чтобы настроить приложение OAuth . Для областей действия необходимо включить chat:write и channels:read . Запишите сгенерированный идентификатор клиента и секрет клиента.
  2. Определите идентификатор канала Slack, в который вы хотите экспортировать сводки.
  3. Отредактируйте файл . env файл. Замените YOUR_SLACK_CLIENT_ID на идентификатор клиента. Замените YOUR_SLACK_CLIENT_SECRET секретом клиента. Замените YOUR_SLACK_CHANNEL_ID на идентификатор канала. Сохраните изменения файла. Это настроит внешний интерфейс вашего расширения на отправку аналитических данных на нужный вам канал Slack.
  4. Если вы используете интерфейс вашего расширения локально, пересоберите расширение. В противном случае, если вы развертываете интерфейс вашего расширения, повторно разверните интерфейс вашего расширения.

Теперь ваше расширение может экспортировать свои сводки непосредственно в Slack или Google Chat. Имейте в виду, что расширение может отправлять сводки только в определенное жестко запрограммированное пространство чата Google или канал Slack. Вы можете добавить дополнительные области Oauth и изменить код для получения и отображения списка пространств и каналов для отправки сводок.

7. [Необязательно] Настройте сводку и следующие шаги.

Расширение запрашивает модель Gemini со всеми метаданными панели мониторинга и данными запросов. Вы можете повысить точность, детализацию и глубину сводок и инструкций, добавив как можно больше метаданных и контекста в саму панель мониторинга. Попробуйте выполнить эти действия для каждой информационной панели, частью которой является ваше расширение:

  • Следуйте этим инструкциям , чтобы добавить детали информационной панели на информационную панель. Это поможет информировать LLM об общем контексте информационной панели.
  • Следуйте этим инструкциям , чтобы добавить примечания к каждой плитке панели мониторинга. Это поможет проинформировать LLM о контексте каждого отдельного запроса на информационной панели. Небольшие контекстные заметки будут учитываться при составлении резюме.

Чем больше информации вы можете добавить на свои информационные панели, тем лучше будет сводка расширения и последующие шаги. Вы можете изменить код, чтобы включить дополнительные метаданные информационной панели в приглашение к модели Gemini.

8. [Необязательно] Настройка ведения журнала модели Gemini

Каждый раз, когда пользователь сообщает расширению о создании сводных данных для информационной панели, расширение будет вызывать Vertex AI для каждого запроса на информационной панели, а также один последний вызов для форматирования всех сводных данных. Следуйте этому разделу, чтобы регистрировать вызовы Vertex AI, совершаемые вашим внутренним номером, чтобы вы могли оценить и отслеживать затраты и трафик Vertex AI. Вам следует следовать этим указаниям только в том случае, если вы развернули серверную службу веб-сокета.

  1. Определите местоположение Cloud Run для развернутой серверной службы веб-сокета.
  2. Следуйте этим инструкциям , чтобы настроить приемник журналов, который будет направлять журналы в Big Query. Назначением приемника должен быть BigQuery. Установите фильтр включения, используя следующий пример кода, в котором YOUR_CLOUD_RUN_LOCATION заменен местоположением Cloud Run из предыдущего шага. 
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. Поздравляем!

Вы настроили расширение суммирования Looker Dashboard локально, чтобы опробовать его. Вы также развернули расширение в Google Cloud, чтобы другие пользователи тоже могли его опробовать! Теперь вы и другие пользователи можете получить доступ к сводным данным на базе Gemini и следующим шагам прямо со своих информационных панелей.

10. Что дальше