Codelab Ekstensi Ringkasan Dasbor Looker

1. Sebelum memulai

Dalam codelab ini (1), Anda akan menyiapkan Ekstensi Ringkasan Dasbor Looker secara lokal untuk dicoba dan dikembangkan secara lokal. Kemudian (2) Anda akan men-deploy ekstensi ke produksi sehingga pengguna Looker lain di instance Looker Anda dapat menggunakannya. Terakhir, (3) Anda dapat mengikuti langkah-langkah tambahan untuk menyempurnakan dan meningkatkan fungsi ekstensi. Semua bagian yang tidak opsional harus diselesaikan secara berurutan.

Ringkasan Ekstensi Ringkasan Dasbor Looker

Secara fungsional, Ekstensi Ringkasan Dasbor Looker mengirimkan data dasbor Looker Anda ke model Gemini Vertex AI. Kemudian, model Gemini akan menampilkan ringkasan data dasbor Anda dan saran langkah berikutnya. Ekstensi ini menampilkan ringkasan dan langkah berikutnya sebagai kartu di dasbor Anda, yang terintegrasi ke dalam pengalaman dasbor Anda. Selain itu, ekstensi dapat mengekspor ringkasan dan langkah berikutnya ke Slack atau Google Chat. Ekstensi ini menggunakan aplikasi frontend React yang dipasangkan dengan layanan backend websocket untuk mengirim dan menerima data ke dan dari model Gemini Vertex AI.

Prasyarat

  • Pemahaman dasar tentang pengembangan Node, Docker, dan Terraform
  • Memahami cara menyiapkan project LookML Looker

Yang akan Anda pelajari

  • Cara menyiapkan dan mengembangkan ekstensi secara lokal
  • Cara men-deploy ekstensi ke produksi sehingga pengguna Looker lain di instance Looker Anda dapat menggunakannya
  • Cara menyetel performa ekstensi dan memperluas fungsinya secara opsional.
  • Cara mengelola ekstensi yang di-deploy dalam produksi

Yang Anda butuhkan

  • Instance Looker, baik melalui Lisensi Asli Looker, Uji Coba Looker Core yang aktif, atau lisensi Looker Core yang aktif.
  • Izin develop dan deploy di instance Looker Anda.
  • Izin untuk mengedit dasbor yang ingin Anda coba dengan ekstensi.
  • Kunci API Looker dari instance Looker Anda.
  • Project Google Cloud yang mengaktifkan penagihan.
  • Cloud Run API, Vertex AI API, dan Artifact Registry API diaktifkan di project.
  • Akses ke lingkungan lokal dengan gcloud CLI yang terinstal. Langkah-langkah codelab mengasumsikan lingkungan gaya Linux.

2. Menyiapkan backend untuk pengembangan lokal

Di bagian ini, Anda akan menyiapkan layanan backend websocket untuk dicoba dan dikembangkan secara lokal. Layanan akan memiliki akses ke Vertex AI.

  1. Instal Node versi 18 atau yang lebih tinggi di lingkungan lokal Anda. Ikuti petunjuk ini untuk menginstal Node.
  2. Buat clone repositori ekstensi ke direktori utama lokal Anda dan buka direktori root repositori. Untuk tujuan codelab ini, semua contoh kode akan mengasumsikan bahwa repositori yang di-clone ada di direktori utama lokal Anda.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Buka direktori root repositori yang di-clone dan ganti nama file .env.example menjadi .env agar Anda dapat menyetel variabel lingkungan di bagian selanjutnya dalam codelab ini.
cd ~/dashboard-summarization
mv .env.example .env
  1. Buka direktori src backend web socket repositori yang di-clone. Direktori ini berisi kode sumber untuk server.
cd ~/dashboard-summarization/websocket-service/src
  1. Instal dependensi layanan dengan NPM.
npm install
  1. Ganti nama file looker-example.ini menjadi looker.ini.
mv looker-example.ini looker.ini
  1. Di dalam file looker.ini, perbarui:
  2. client_id dan client_secret dengan yang ada di kunci API Looker Anda.
  3. base_url dengan URL instance Looker Anda dalam format: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Teks di antara tanda kurung (header bagian) dengan host URL instance Looker Anda.

Misalnya, jika ID klien Anda adalah ABC123, rahasia klien Anda adalah XYZ789, dan URL instance Looker Anda adalah https://mycompany.cloud.looker.com, file looker.ini Anda akan terlihat persis seperti ini:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Tentukan project ID Google Cloud Anda dan tetapkan di variabel lingkungan PROJECT. Ganti YOUR_PROJECT_ID dengan project ID Anda.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI menyediakan model Gemini di beberapa region yang tercantum di sini. Tentukan region tempat backend lokal Anda akan mengirim dan menerima data dari model Gemini Vertex AI. Tetapkan region pada variabel lingkungan REGION Anda. Ganti YOUR_VERTEX_REGION dengan region Anda, seperti us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Sekarang mulai layanan lokal Anda.
npm start
  1. Layanan backend websocket lokal Anda akan berjalan di http://localhost:5000.

Anda telah selesai menyiapkan layanan backend websocket di lingkungan lokal.

Layanan ini berfungsi sebagai antarmuka antara ekstensi frontend dan model Gemini Vertex AI. Layanan ini akan mengambil data dasbor dan LookML dari ekstensi frontend Anda dengan data yang dikueri dari Looker dan meminta model Gemini Vertex AI. Kemudian, layanan akan melakukan streaming respons Gemini ke ekstensi frontend untuk ditampilkan di dasbor Anda.

Anda juga dapat membuat perubahan pada kode sumber layanan backend. Anda harus menghentikan proses layanan terlebih dahulu, melakukan perubahan kode, lalu menjalankan npm start lagi.

3. Menyiapkan frontend untuk pengembangan lokal

Di bagian ini, Anda akan menyiapkan ekstensi frontend untuk dicoba dan dikembangkan secara lokal.

  1. Di lingkungan lokal yang sama dari langkah-langkah sebelumnya, buka direktori root repositori yang di-clone dan instal dependensi server frontend untuk frontend Anda.
cd ~/dashboard-summarization
npm install
  1. Mulai server pengembangan frontend lokal
npm run develop
  1. Server frontend lokal Anda kini menayangkan javascript ekstensi di http://localhost:8080/bundle.js.
  2. Buka browser web, lalu login ke instance Looker Anda.
  3. Ikuti petunjuk ini untuk menyiapkan project LookML kosong. Beri nama project dashboard-summarization. Sekarang Anda akan melihat project LookML kosong yang terbuka secara otomatis di Looker IDE pada tab browser Anda saat ini.
  4. Buat file manifes project di root project LookML. File ini akan disebut manifest.lkml. Jika Anda tidak tahu caranya, ikuti petunjuk ini tentang cara menambahkan file ke project LookML.
  5. Ganti konten file manifest.lkml baru dengan konten manifest.lkml di direktori root repositori tertutup Anda. Pilih tombol "Simpan Perubahan" di pojok kanan atas untuk menyimpan perubahan ke file.
  6. Di tab browser terpisah, buka daftar koneksi database di instance Looker Anda. Ikuti petunjuk ini jika Anda tidak tahu caranya.
  7. Pilih Nama salah satu koneksi database Looker. Tidak masalah koneksi mana yang Anda pilih. Jika Anda tidak memiliki izin untuk melihat koneksi database, hubungi admin Looker Anda dan minta nama salah satu koneksi database Looker.
  8. Kembali ke tab browser dengan project LookML Anda yang dibuka di Looker IDE. Buat file model di project LookML Anda dan beri nama file tersebut dashboard-summarization.
  9. Ganti konten file dashboard-summarization.model.lkml Anda dengan contoh kode di bawah. Pastikan untuk mengganti string dalam tanda petik ganda dengan nama koneksi database yang Anda pilih di langkah 9. Simpan perubahan pada file.
connection: "<YOUR_CONNECTION_NAME>"
  1. Siapkan repositori untuk menyimpan project Anda. Pilih tombol "Configure Git" di kanan atas. Pilih "Set up a bare repository instead". Pilih "Create Repository".
  2. Sekarang Anda memiliki repositori kosong dasar untuk menyimpan file project LookML. Kembali ke project di Looker IDE dengan memilih "Kembali ke project" atau kembali secara manual.
  3. Pilih tombol "Validasi LookML" di pojok kanan atas. Tombol akan berubah menjadi "Commit changes and push".
  4. Pilih tombol ""Commit changes and push". Tambahkan pesan yang Anda inginkan, lalu pilih "Commit".
  5. Pilih "Deploy to Production" di pojok kanan atas Looker IDE. Anda kini telah menambahkan ekstensi ke instance Looker Anda.
  6. Buka dasbor Looker yang ingin Anda tambahkan ekstensi.
  7. Ikuti petunjuk untuk menambahkan kartu ekstensi ke dasbor Anda. Tambahkan ekstensi baru Anda ke dasbor sebagai kartu.
  8. Pastikan layanan backend websocket lokal yang Anda siapkan sebelumnya sedang berjalan.

Selamat! Sekarang Anda dapat mencoba Ekstensi Ringkasan Dasbor Looker di dasbor. Ekstensi Anda akan mengirimkan metadata dasbor ke layanan backend websocket lokal dan akan menampilkan output Gemini dari layanan backend langsung di kartu ekstensi dasbor.

Saat server frontend lokal Anda berjalan, Anda dapat membuat perubahan pada kode sumber javascript ekstensi dan server akan otomatis membangun serta menayangkan perubahan tersebut. Anda harus memuat ulang halaman ekstensi atau dasbor untuk melihat perubahan.

4. Men-deploy backend ke produksi

Di bagian ini, Anda akan menyiapkan layanan backend websocket untuk menayangkan semua instance ekstensi ringkasan dasbor di dasbor mana pun di instance Looker Anda. Hal ini akan memungkinkan pengguna Looker lain mencoba ekstensi di dasbor mereka sendiri tanpa perlu menyiapkan layanan backend mereka sendiri. Langkah-langkah ini mengasumsikan bahwa Anda telah berhasil men-deploy backend untuk pengembangan lokal di lingkungan lokal yang sama sebelumnya.

  1. Ikuti petunjuk ini untuk menyiapkan Kredensial Default Aplikasi di lingkungan lokal dengan project ID Anda untuk langkah berikutnya.
  2. Buat repositori Artifact Registry untuk image Docker layanan backend Anda. Ganti YOUR_REGION dengan region tempat Anda ingin repositori berada.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Buka direktori src backend web socket repositori yang di-clone.
cd ~/dashboard-summarization/websocket-service/src
  1. Edit file cloudbuild.yaml dan ganti semua instance YOUR_REGION dan YOUR_PROJECT_ID dengan region dan project ID Anda. Simpan perubahan pada file.
  2. Kirimkan build menggunakan Cloud Build yang akan membangun image Docker layanan backend dan mengirimkannya ke repo Artifact Registry yang baru saja Anda buat. Ganti YOUR_REGION dengan region tempat Anda ingin menggunakan layanan Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Ingat, URL image Docker yang baru dibuat ada di YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Ganti YOUR_PROJECT_ID dengan project ID Anda. Ganti YOUR_REGION dengan region dari langkah 2 yang Anda gunakan untuk membuat repositori Artifact Registry.
  2. Buka direktori websocket-service/terraform di repositori yang di-clone.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Tentukan lokasi Google Cloud Run yang ingin Anda gunakan untuk menjalankan layanan backend websocket. Pilih dari lokasi berikut.
  2. Edit file variables.tf dan ganti YOUR_PROJECT_ID dan YOUR_DOCKER_IMAGE_URL dengan nilai yang sesuai. Periksa langkah 6 untuk URL image Docker Anda. Ganti YOUR_REGION dengan region yang Anda pilih di langkah 8 sebelumnya. Simpan perubahan pada file.
  3. Deploy resource yang akan digunakan layanan backend Anda menggunakan terraform.
terraform init
terraform plan
terraform apply
  1. Simpan Endpoint URL Cloud Run yang Di-deploy untuk bagian berikutnya.

Selamat! Anda telah men-deploy layanan backend websocket dan sekarang layanan tersebut berjalan di Google Cloud Run. Sekarang, semua instance ekstensi Ringkasan Dasbor Looker Anda dapat berkomunikasi dengan layanan backend Anda. Sebaiknya Anda selalu menjalankan setidaknya satu instance layanan backend websocket di Cloud Run. Persistensi layanan backend Anda mempertahankan integritas streaming data antara layanan backend websocket dan frontend ekstensi Anda, serta membantu mempertahankan sesi setiap pengguna saat mereka menggunakan ekstensi Anda.

5. Men-deploy frontend ke produksi

Untuk bagian terakhir ini, Anda akan melakukan langkah-langkah terakhir dalam men-deploy frontend ekstensi agar tersedia untuk semua pengguna Looker di instance Looker Anda.

  1. Buka direktori root repositori yang di-clone.
cd ~/dashboard-summarization
  1. Edit .File env. Ganti YOUR_CLOUD_RUN_URL dengan Endpoint URL Cloud Run dari bagian sebelumnya. Simpan perubahan file Anda. Tindakan ini akan mengarahkan frontend ekstensi produksi ke layanan backend websocket yang berjalan di Cloud Run.
  2. Buat javascript ekstensi. Direktori dist akan otomatis dibuat dengan file bundle.js dan file lainnya di dalamnya.
npm run build
  1. Buka browser web, lalu login ke instance Looker Anda. Buka menu navigasi kiri samping dan aktifkan tombol "Mode Pengembangan" di bagian bawah.
  2. Dengan nav kiri samping terbuka, pilih "Develop", lalu scroll ke bawah dan pilih "dashboard-summarization", project LookML ekstensi Anda. Sekarang Anda akan berada di IDE Looker untuk project LookML.
  3. Tarik lalu lepas semua file di direktori dist yang dibuat sebelumnya ke direktori root project di "File Browser". Ikuti petunjuk ini jika Anda memerlukan bantuan lebih lanjut.
  4. Buka file manifest.lkml di dalam Looker IDE. Di dalam file, ganti baris
url: "http://localhost:8080/bundle.js"

dengan

file: "bundle.js"

Ganti YOUR_CLOUD_RUN_URL dengan Endpoint URL Cloud Run dari akhir bagian terakhir. Simpan perubahan pada file.

  1. Pilih tombol "Validasi LookML" di pojok kanan atas. Tombol akan berubah menjadi "Commit changes and push".
  2. Pilih tombol ""Commit changes and push". Tambahkan pesan yang Anda inginkan, lalu pilih "Commit".
  3. Pilih "Deploy to Production" di pojok kanan atas Looker IDE.

Selamat! Sekarang Anda telah mengizinkan semua pengguna Looker di instance Looker Anda untuk menambahkan Ekstensi Ringkasan Dasbor Looker ke dasbor mereka. Saat pengguna Looker lain menggunakan ekstensi, semua instance ekstensi akan melakukan panggilan ke layanan backend websocket yang di-deploy dan berjalan di Google Cloud Run.

Perlu diingat, jika Anda melakukan perubahan pada kode sumber, Anda harus:

  1. Bangun ulang javascript ekstensi Anda
  2. Ganti file yang dihasilkan yang telah Anda tambahkan ke project LookML dengan file yang baru dihasilkan dari direktori dist.
  3. Memvalidasi, melakukan, dan men-deploy perubahan project LookML ke produksi

Coba Ekstensi Ringkasan Dasbor Looker. Sebaiknya Anda berkontribusi pada ekstensi ini dan membantu memenuhi kebutuhan komunitas Looker dengan lebih baik. Jangan ragu untuk membuat permintaan pull di repositori.

Lihat bagian opsional berikut untuk mengaktifkan ekspor Slack/Google Chat, menyempurnakan ringkasan dan langkah berikutnya dari Gemini, serta menyiapkan logging Gemini.

6. [Opsional] Menyiapkan kemampuan ekspor

Setelah Anda dan pengguna Looker Anda mencoba ekstensi Ringkasan Dasbor Looker, mari bagikan insight ekstensi ini kepada audiens yang lebih luas. Ikuti bagian ini untuk mengaktifkan ekstensi Anda agar dapat mengirim ringkasan dan langkah berikutnya ke Google Chat atau Slack. Anda harus memahami penyiapan OAuth untuk melanjutkan bagian codelab ini.

Mengaktifkan ekspor Google Chat

  1. Aktifkan Chat API di project Google Cloud Anda.
  2. Ikuti langkah 1 petunjuk penyiapan OAuth Google Workspace. Untuk cakupan, Anda harus menyertakan spaces.messages.create.
  3. Ikuti langkah 2 petunjuk penyiapan OAuth Google Workspace. Tambahkan URL instance Looker Anda sebagai URI di bagian "Authorized JavaScript origins", misalnya https://mycompany.cloud.looker.com. Catat ID Klien yang dihasilkan.
  4. Tentukan ID ruang Google Chat yang ingin Anda gunakan sebagai tujuan ekspor ringkasan. Jika Anda tidak yakin caranya, ikuti petunjuk ini.
  5. Edit .File env. Ganti YOUR_GOOGLE_CLIENT_ID dengan ID Klien. Ganti YOUR_GOOGLE_SPACE_ID dengan ID ruang Google Chat. Simpan perubahan file Anda. Tindakan ini akan mengonfigurasi frontend ekstensi Anda agar dapat mengirimkan insight-nya ke ruang Google Chat yang Anda inginkan.
  6. Jika Anda menjalankan frontend ekstensi secara lokal, bangun kembali ekstensi Anda. Atau, jika Anda men-deploy frontend ekstensi, deploy ulang frontend ekstensi.

Mengaktifkan ekspor Slack

  1. Ikuti langkah 1 dan 2 dokumentasi developer Slack resmi untuk menyiapkan Aplikasi OAuth. Untuk cakupan, Anda harus menyertakan chat:write dan channels:read. Catat client ID dan rahasia klien yang dihasilkan.
  2. Tentukan ID saluran Slack yang ingin Anda ekspor ringkasannya.
  3. Edit .File env. Ganti YOUR_SLACK_CLIENT_ID dengan ID Klien. Ganti YOUR_SLACK_CLIENT_SECRET dengan Rahasia Klien. Ganti YOUR_SLACK_CHANNEL_ID dengan channel ID. Simpan perubahan file Anda. Tindakan ini akan mengonfigurasi frontend ekstensi Anda agar dapat mengirimkan insight-nya ke saluran Slack yang Anda inginkan.
  4. Jika Anda menjalankan frontend ekstensi secara lokal, bangun kembali ekstensi Anda. Atau, jika Anda men-deploy frontend ekstensi, deploy ulang frontend ekstensi.

Sekarang, ekstensi Anda dapat mengekspor ringkasannya langsung ke Slack atau Google Chat. Perlu diingat bahwa ekstensi hanya dapat mengirim ringkasan ke ruang chat Google atau saluran Slack tertentu yang dikodekan secara permanen. Anda dapat menambahkan cakupan Oauth lain dan mengubah kode untuk mengambil dan menampilkan daftar ruang dan channel untuk mengirim ringkasan.

7. [Opsional] Sesuaikan ringkasan dan langkah selanjutnya

Ekstensi ini akan meminta model Gemini dengan semua metadata dasbor dan mengkueri data. Anda dapat meningkatkan akurasi, detail, dan kedalaman ringkasan serta langkah-langkah preskriptif dengan menambahkan sebanyak mungkin metadata dan konteks ke dasbor itu sendiri. Coba langkah-langkah berikut untuk setiap dasbor tempat ekstensi Anda berada:

  • Ikuti petunjuk berikut untuk menambahkan detail dasbor ke dasbor. Hal ini akan membantu memberi tahu LLM tentang konteks umum dasbor.
  • Ikuti petunjuk ini untuk menambahkan catatan ke setiap kartu dasbor. Tindakan ini akan membantu memberi tahu LLM tentang konteks setiap kueri individual di dasbor. Catatan kontekstual kecil akan diperhitungkan dalam ringkasan yang dihasilkan.

Semakin banyak informasi yang dapat Anda tambahkan ke dasbor, semakin baik ringkasan dan langkah berikutnya dari ekstensi. Anda dapat mengubah kode untuk menyertakan metadata dasbor tambahan dalam perintah ke model Gemini.

8. [Opsional] Menyiapkan logging model Gemini

Setiap kali pengguna meminta ekstensi untuk membuat ringkasan dasbor, ekstensi akan melakukan panggilan ke Vertex AI untuk setiap kueri di dasbor ditambah satu panggilan terakhir untuk memformat semua ringkasan. Ikuti bagian ini untuk mencatat panggilan Vertex AI yang dilakukan ekstensi Anda sehingga Anda dapat memperkirakan dan memantau biaya dan traffic Vertex AI. Anda hanya boleh mengikuti petunjuk ini jika telah men-deploy layanan backend websocket.

  1. Tentukan lokasi Cloud Run untuk layanan backend websocket yang di-deploy.
  2. Ikuti petunjuk ini untuk menyiapkan sink log yang akan merutekan log ke BigQuery. Tujuan sink harus berupa BigQuery. Tetapkan filter penyertaan dengan contoh kode berikut dengan YOUR_CLOUD_RUN_LOCATION diganti dengan lokasi Cloud Run dari langkah sebelumnya.
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. Selamat!

Anda telah menyiapkan ekstensi Ringkasan Dasbor Looker secara lokal untuk Anda coba. Anda juga telah men-deploy ekstensi ke Google Cloud sehingga pengguna lain juga dapat mencobanya. Sekarang Anda dan pengguna lain dapat mengakses ringkasan dan langkah selanjutnya yang didukung Gemini langsung dari dalam dasbor Anda.

10. Langkah berikutnya