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

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

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

Обзор расширения Looker Dashboard Summarization Extension

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

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

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

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

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

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

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

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

В этом разделе вы настроите серверную часть на основе WebSocket для тестирования и локальной разработки. Сервис будет иметь доступ к 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 в нескольких регионах, перечисленных здесь . Определите, в каком регионе ваш локальный бэкэнд будет отправлять и получать данные от модели Gemini от Vertex AI. Укажите регион в переменной среды REGION . Замените YOUR_VERTEX_REGION на ваш регион, например, us-central1 . 
export REGION="YOUR_VERTEX_REGION"
  1. Теперь запустите свою местную службу. 
npm start
  1. Ваш локальный сервер веб-сокетов будет работать по адресу http://localhost:5000.

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

Этот сервис служит интерфейсом между вашим расширением для внешнего интерфейса и моделью Gemini от Vertex AI. Сервис будет получать данные с панели мониторинга и 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 должен автоматически открыться в IDE Looker в текущей вкладке браузера.
  4. Создайте файл манифеста проекта в корневой директории проекта LookML. Файл будет называться manifest.lkml. Если вы не знаете, как это сделать, следуйте этим инструкциям по добавлению файла в проект LookML.
  5. Замените содержимое нового файла manifest.lkml содержимым файла manifest.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, выбрав «Назад к проекту» или вернувшись назад вручную.
  3. Выберите кнопку «Проверить LookML» в правом верхнем углу. Кнопка изменится на «Зафиксировать изменения и отправить».
  4. Выберите кнопку «Зафиксировать изменения и отправить». Добавьте любое желаемое сообщение и нажмите «Зафиксировать».
  5. Выберите «Развернуть в продакшн» в правом верхнем углу среды разработки Looker. Теперь расширение добавлено в ваш экземпляр Looker!
  6. Перейдите на панель управления Looker, в которую вы хотите добавить расширение.
  7. Следуйте инструкциям , чтобы добавить плитку расширения на панель управления. Добавьте новое расширение на панель управления в виде плитки.
  8. Убедитесь, что локально настроенная вами ранее служба веб-сокетов запущена.

Поздравляем! Теперь вы можете опробовать расширение Looker Dashboard Summarization Extension на своей панели управления. Ваше расширение будет отправлять метаданные вашей панели управления в локальный бэкэнд по протоколу WebSocket и отображать вывод Gemini из вашего бэкэнда прямо в плитке расширения вашей панели управления.

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

4. Разверните бэкэнд в продакшене.

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

  1. Следуйте этим инструкциям , чтобы настроить учетные данные приложения по умолчанию в вашей локальной среде, указав идентификатор вашего проекта для дальнейших шагов.
  2. Создайте репозиторий Artifact Registry для образов 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 для серверной части и загрузит его в только что созданный репозиторий Artifact Registry. Замените 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, который вы использовали для создания репозитория Artifact Registry.
  2. Перейдите в каталог websocket-service/terraform в клонированном репозитории. 
cd ~/dashboard-summarization/websocket-service/terraform
  1. Определите, в каком из следующих расположений Google Cloud Run вы хотите запустить свой бэкэнд-сервис на основе веб-сокетов. Выберите одно из перечисленных расположений .
  2. Отредактируйте файл variables.tf и замените YOUR_PROJECT_ID и YOUR_DOCKER_IMAGE_URL соответствующими значениями. Проверьте шаг 6, чтобы узнать URL-адрес вашего образа Docker. Замените YOUR_REGION на регион, который вы выбрали на предыдущем шаге 8. Сохраните изменения в файле.
  3. Разверните ресурсы, которые будет использовать ваш бэкэнд-сервис, с помощью Terraform. 
terraform init
terraform plan
terraform apply
  1. Сохраните конечную точку URL-адреса развернутого облачного сервера для следующего раздела.

Поздравляем! Вы развернули свой бэкэнд-сервис на основе веб-сокетов, и теперь он работает в Google Cloud Run. Теперь любые экземпляры вашего расширения Looker Dashboard Summarization могут взаимодействовать с вашим бэкэнд-сервисом. Мы рекомендуем всегда иметь хотя бы один запущенный экземпляр вашего бэкэнд-сервиса на основе веб-сокетов в 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. Откройте боковое меню слева, выберите «Разработка», затем прокрутите вниз и выберите «dashboard-summarization» — проект 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 Dashboard Summarization Extension на свои панели мониторинга. По мере того, как другие пользователи Looker будут использовать расширение, все экземпляры расширения будут отправлять вызовы к развернутой вами службе веб-сокетов, работающей на Google Cloud Run.

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

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

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

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

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

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

Включить экспорт в Google Чат

  1. Включите API чата в своем проекте Google Cloud.
  2. Следуйте шагу 1 инструкций по настройке OAuth в Google Workspace. Для областей действия необходимо указать spaces.messages.create .
  3. Выполните шаг 2 инструкций по настройке OAuth в Google Workspace. Добавьте URL-адрес вашего экземпляра Looker в качестве 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. Для настройки приложения OAuth выполните шаги 1 и 2 из официальной документации Slack для разработчиков. В качестве областей действия (scopes) необходимо указать chat:write и channels:read . Запишите сгенерированные идентификатор клиента (client ID) и секретный ключ клиента (client secret).
  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 понять контекст каждого отдельного запроса на панели мониторинга. Небольшие контекстные заметки будут учитываться при создании сводных отчетов.

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

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

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

  1. Определите местоположение развернутой вами службы бэкэнда WebSocket в 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 Summarization локально, чтобы протестировать его. Вы также развернули расширение в Google Cloud, чтобы другие пользователи тоже могли его попробовать! Теперь вы и другие пользователи можете получать доступ к сводкам и дальнейшим шагам, созданным с помощью Gemini, прямо из своих панелей мониторинга.

10. Что дальше?