Codelab Ekstensi Ringkasan Dasbor Looker

1. Sebelum memulai

Dalam codelab ini (1), Anda akan menyiapkan Ekstensi Peringkasan Dasbor Looker secara lokal agar dapat Anda coba dan kembangkan secara lokal. Kemudian (2) Anda akan men-deploy ekstensi ke produksi agar pengguna Looker lain di instance Looker Anda dapat menggunakannya. Terakhir, (3) Anda dapat mengikuti langkah-langkah tambahan untuk menyesuaikan dan meningkatkan fungsi ekstensi. Semua bagian non-opsional harus diselesaikan secara berurutan.

Ringkasan Ekstensi Ringkasan Dasbor Looker

Secara fungsional, Ekstensi Peringkasan Dasbor Looker mengirimkan data dasbor Looker Anda ke model Gemini Vertex AI. Model Gemini kemudian menampilkan ringkasan data dasbor Anda dan resep langkah selanjutnya. Ekstensi menampilkan ringkasan dan langkah berikutnya sebagai kartu di dasbor, yang mengintegrasikan ke dalam pengalaman dasbor Anda. Selain itu, ekstensi tersebut dapat mengekspor ringkasan dan langkah berikutnya ke Slack atau Google Chat. Ekstensi ini menggunakan aplikasi frontend React yang dipadukan 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
• Pemahaman tentang penyiapan project Looker LookML

Yang akan Anda pelajari

• Cara menyiapkan dan mengembangkan ekstensi secara lokal
• Cara men-deploy ekstensi ke produksi agar pengguna Looker lain di instance Looker Anda dapat menggunakannya
• Cara meningkatkan 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 dengan penagihan diaktifkan di dalamnya.
• Cloud Run API, Vertex AI API, dan Artifact Registry API yang diaktifkan pada project.
• Akses ke lingkungan lokal dengan gcloud CLI terinstal. Langkah-langkah codelab mengasumsikan lingkungan gaya Linux.

2. Menyiapkan backend untuk pengembangan lokal

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

1. Instal Node versi 18 atau yang lebih baru di lingkungan lokal Anda. Ikuti petunjuk ini untuk menginstal Node.
2. Clone repositori ekstensi ke direktori utama lokal Anda dan buka direktori root repositori. Untuk tujuan codelab ini, semua contoh kode akan mengasumsikan repositori yang di-clone berada di direktori beranda lokal Anda.

cd ~
git clone [e-mail]:looker-open-source/dashboard-summarization.git

3. Buka direktori utama repositori yang di-clone dan ganti nama file .env.example menjadi .env agar Anda dapat menetapkan variabel lingkungan di bagian selanjutnya dari codelab ini.

cd ~/dashboard-summarization
mv .env.example .env

4. Buka direktori src backend soket web repositori yang di-clone. Direktori ini berisi kode sumber untuk server.

cd ~/dashboard-summarization/websocket-service/src   

5. Instal dependensi layanan dengan NPM.

npm install  

6. Ganti nama file looker-example.ini menjadi looker.ini.

mv looker-example.ini looker.ini  

7. Di dalam pembaruan file Looker.ini:
8. client_id dan client_secret dengan data dari kunci Looker API Anda.
9. base_url dengan URL instance Looker Anda dalam format: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
10. Teks di antara tanda kurung (header bagian) dengan host URL instance Looker Anda.

Misalnya, jika client ID Anda adalah ABC123, rahasia klien adalah XYZ789, dan URL instance Looker 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 

8. Tentukan project ID Google Cloud Anda dan tetapkan pada variabel lingkungan PROJECT. Ganti YOUR_PROJECT_ID dengan ID project Anda.

export PROJECT="YOUR_PROJECT_ID"

9. Vertex AI menyediakan model Gemini di beberapa region yang tercantum di sini. Tentukan region yang akan digunakan oleh backend lokal Anda untuk mengirim dan menerima data dari model Gemini Vertex AI. Tetapkan region pada variabel lingkungan REGION Anda. Ganti YOUR_VERTEX_REGION dengan wilayah Anda, seperti us-central1.

export REGION="YOUR_VERTEX_REGION"

10. Sekarang mulai layanan lokal Anda.

npm start

11. Layanan backend websocket lokal Anda akan berjalan di http://localhost:5000.

Anda kini telah selesai menyiapkan layanan backend websocket di lingkungan lokal Anda.

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

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

Catatan: Layanan backend websocket lokal Anda akan melakukan panggilan ke Vertex AI.

3. Menyiapkan frontend untuk pengembangan lokal

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

1. Di lingkungan lokal yang sama dari langkah sebelumnya, buka direktori root repositori yang di-clone dan instal dependensi server frontend untuk frontend Anda.

cd ~/dashboard-summarization
npm install

2. Memulai server pengembangan frontend lokal

npm run develop

3. Server frontend lokal Anda sekarang menyajikan JavaScript ekstensi di http://localhost:8080/bundle.js.
4. Buka browser web, lalu login ke instance Looker Anda.
5. Ikuti petunjuk ini untuk menyiapkan project LookML kosong. Beri nama ringkasan dasbor proyek. Sekarang, project LookML kosong akan terbuka secara otomatis di Looker IDE pada tab browser Anda saat ini.
6. Buat file manifes project di root project LookML. File akan disebut manifest.lkml. Jika Anda tidak tahu caranya, ikuti petunjuk ini tentang cara menambahkan file ke project LookML.
7. Ganti konten file manifest.lkml baru dengan konten manifest.lkml di direktori utama repositori tertutup Anda. Pilih "Simpan Perubahan" di sudut kanan atas untuk menyimpan perubahan pada {i>file<i}.
8. Di tab browser terpisah, buka daftar koneksi database di instance Looker Anda. Ikuti petunjuk ini jika Anda tidak tahu caranya.
9. 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.
10. Kembali ke tab browser dengan project LookML Anda yang terbuka di Looker IDE. Buat file model di project LookML Anda dan beri nama ringkasan dasbor file.
11. Ganti konten file dasbor-summarization.model.lkml dengan contoh kode di bawah. Pastikan untuk mengganti {i>string<i} dalam tanda kutip ganda dengan nama koneksi {i>database<i} yang Anda pilih pada langkah 9. Simpan perubahan pada file.

connection: "<YOUR_CONNECTION_NAME>"

Catatan: Koneksi database yang Anda tentukan dalam project ini tidak menentukan database yang akan dikueri oleh ekstensi ringkasan dasbor Anda. Saat ekstensi ditambahkan ke dasbor, ekstensi tersebut akan mengkueri database yang terkait dengan dasbor tersebut.

12. Siapkan repositori untuk menyimpan project Anda. Pilih "Configure Git" di kanan atas. Pilih "Set up a bare repository". Pilih "Create Repository".
13. Anda sekarang memiliki repositori sederhana untuk menyimpan file project LookML. Kembali ke project di Looker IDE dengan memilih "Kembali ke project" atau menavigasi kembali secara manual.
14. Pilih "Validasi LookML" di sudut kanan atas. Tombol akan berubah menjadi "Commit changes and push".
15. Pilih ""Commit changes and push" tombol. Tambahkan pesan apa pun yang Anda inginkan dan pilih "Commit".
16. Pilih "Deploy to Production" di sudut kanan atas Looker IDE. Sekarang Anda telah menambahkan ekstensi ke instance Looker.
17. Buka dasbor Looker yang ingin Anda tambahi ekstensi.
18. Ikuti petunjuk untuk menambahkan kartu ekstensi ke dasbor Anda. Tambahkan ekstensi baru Anda ke dasbor sebagai kartu.
19. Pastikan layanan backend websocket lokal yang Anda siapkan sebelumnya sudah berjalan.

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

Sewaktu server frontend lokal berjalan, Anda dapat membuat perubahan pada kode sumber JavaScript ekstensi dan server akan otomatis membangun dan menyalurkan perubahan tersebut. Anda harus memuat ulang halaman dasbor atau ekstensi untuk melihat perubahannya.

Catatan: Anda dapat mengikuti bagian opsional di akhir codelab ini untuk mengaktifkan ekstensi agar dapat mengekspor ringkasan dan langkah berikutnya ke Slack atau Gchat.

Catatan: Anda juga dapat meningkatkan akurasi, detail, dan kedalaman ringkasan ekstensi dan langkah berikutnya dengan bagian opsional di akhir codelab ini.

4. Men-deploy backend ke produksi

Di bagian ini, Anda sekarang akan menyiapkan layanan backend websocket untuk menyalurkan instance ekstensi ringkasan dasbor di dasbor mana pun dalam instance Looker Anda. Dengan ini, pengguna Looker lain dapat mencoba ekstensi di dasbor mereka sendiri tanpa perlu menyiapkan layanan backend 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 Anda 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 menyimpan repositori.

gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \

3. Buka direktori src backend soket web repositori yang di-clone.

cd ~/dashboard-summarization/websocket-service/src

4. Edit file cloudbuild.yaml dan ganti semua instance YOUR_REGION dan YOUR_PROJECT_ID dengan region dan project ID Anda. Simpan perubahan pada file.
5. Kirim build menggunakan Cloud Build yang akan membangun image Docker layanan backend dan mengirimnya 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

6. Ingat, URL image Docker yang baru dibuat berada di YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Ganti YOUR_PROJECT_ID dengan ID project Anda. Ganti YOUR_REGION dengan region dari langkah 2 yang Anda gunakan untuk membuat repositori Artifact Registry.
7. Buka direktori websocket-service/terraform di repositori yang Anda clone.

cd ~/dashboard-summarization/websocket-service/terraform

8. Tentukan lokasi Google Cloud Run yang Anda inginkan untuk menjalankan layanan backend websocket. Pilih dari lokasi ini.
9. Edit file variables.tf dan ganti YOUR_PROJECT_ID dan YOUR_DOCKER_IMAGE_URL dengan nilai yang sesuai. Periksa langkah 6 untuk URL gambar Docker Anda. Ganti YOUR_REGION dengan wilayah yang Anda pilih di langkah 8 sebelumnya. Simpan perubahan Anda pada file tersebut.
10. Deploy resource yang akan digunakan layanan backend Anda menggunakan terraform.

terraform init
terraform plan
terraform apply

11. Simpan Endpoint URL Cloud Run yang Di-deploy untuk bagian berikutnya.

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

Catatan: Layanan backend websocket yang di-deploy ke cloud run dalam codelab ini ditampilkan secara publik.

Catatan: Setiap kali pengguna memberi tahu frontend ekstensi agar membuat ringkasan untuk dasbor, layanan backend akan melakukan panggilan ke Vertex AI untuk setiap kueri di dasbor, ditambah satu panggilan terakhir untuk memformat semua ringkasan. Anda dapat mencatat panggilan Vertex AI yang dilakukan layanan backend untuk membantu memperkirakan dan memantau biaya. Lihat halaman "Menyiapkan logging model Gemini" bagian opsional codelab ini untuk melihat caranya.

5. Men-deploy frontend ke produksi

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

1. Buka direktori utama repositori yang di-clone.

cd ~/dashboard-summarization

2. Edit file .File env. Ganti YOUR_CLOUD_RUN_URL dengan Cloud Run URL Endpoint dari bagian sebelumnya. Simpan perubahan file Anda. Tindakan ini akan mengarahkan frontend ekstensi produksi ke layanan backend websocket Anda yang berjalan di Cloud Run.
3. Buat JavaScript ekstensi. Direktori dist akan otomatis dibuat dengan file bundle.js dan file lain di dalamnya.

npm run build

4. Buka browser web, lalu login ke instance Looker Anda. Buka navigasi sebelah kiri dan aktifkan "Development Mode" tombol di bagian bawah.
5. Dengan navigasi sebelah kiri terbuka, pilih "Develop", lalu scroll ke bawah dan pilih "dashboard-summarization", project LookML ekstensi Anda. Sekarang Anda seharusnya berada di Looker IDE untuk project LookML.
6. Tarik lalu lepas semua file dalam direktori dist yang dihasilkan sebelumnya ke direktori utama project di "File Browser". Ikuti petunjuk ini jika Anda memerlukan bantuan lebih lanjut.
7. Buka file manifest.lkml di dalam Looker IDE. Di dalam file, ganti barisnya

url: "http://localhost:8080/bundle.js"

dengan

file: "bundle.js"

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

8. Pilih "Validasi LookML" di sudut kanan atas. Tombol akan berubah menjadi "Commit changes and push".
9. Pilih ""Commit changes and push" tombol. Tambahkan pesan apa pun yang Anda inginkan dan pilih "Commit".
10. Pilih "Deploy to Production" di sudut kanan atas Looker IDE.

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

Perhatikan, jika Anda membuat perubahan pada kode sumber, Anda harus:

1. Membuat kembali 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 commit, dan men-deploy perubahan project LookML ke produksi

Coba Ekstensi Peringkasan Dasbor Looker. Kami mendorong Anda untuk berkontribusi pada ekstensi 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, meningkatkan kualitas ringkasan Gemini dan langkah berikutnya, serta menyiapkan logging Gemini.

6. [Opsional] Menyiapkan kemampuan ekspor

Setelah Anda dan pengguna Looker mencoba ekstensi Peringkasan Dasbor Looker, mari bagikan insight ekstensi kepada audiens yang lebih banyak. Ikuti bagian ini untuk mengaktifkan ekstensi Anda agar dapat mengirim ringkasan dan langkah berikutnya ke Google Chat atau Slack. Anda harus sudah memahami penyiapan Oauth untuk melanjutkan ke 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 pencari Anda sebagai URI di bagian "Authorized JavaScript origin", misalnya https://mycompany.cloud.looker.com. Catat Client-ID yang dibuat.
4. Tentukan ID ruang Google Chat yang ingin Anda jadikan tujuan ekspor ringkasan. Jika Anda tidak mengetahui caranya, ikuti petunjuk ini.
5. Edit file .File env. Ganti YOUR_GOOGLE_CLIENT_ID dengan Client-ID. 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 ulang ekstensi Anda. Selain itu, jika Anda men-deploy frontend ekstensi, deploy ulang frontend ekstensi Anda.

Mengaktifkan ekspor Slack

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

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 di-hardcode. Anda dapat menambahkan cakupan Oauth tambahan dan mengubah kode untuk mengambil dan menampilkan daftar ruang dan saluran yang akan dikirimi ringkasan.

7. [Opsional] Menyesuaikan ringkasan dan langkah berikutnya

Ekstensi ini memberi tahu model Gemini dengan semua metadata dan data kueri dasbor. Anda dapat meningkatkan akurasi, detail, dan kedalaman ringkasan serta langkah preskriptif dengan menambahkan sebanyak mungkin metadata dan konteks ke dasbor itu sendiri. Coba langkah-langkah berikut untuk setiap dasbor yang mencakup ekstensi Anda:

• Ikuti petunjuk ini 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 ubin dasbor. Hal ini akan membantu memberi tahu LLM tentang konteks setiap kueri individu di dasbor. Catatan kontekstual kecil akan diperhitungkan dalam ringkasan yang dihasilkan.

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

8. [Opsional] Siapkan logging model Gemini

Setiap kali pengguna memberi tahu ekstensi agar membuat ringkasan untuk 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 dibuat ekstensi Anda sehingga Anda dapat memperkirakan dan memantau biaya dan traffic Vertex AI. Anda hanya perlu 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 Big Query. Tujuan sink harus berupa BigQuery. Tetapkan filter penyertaan menggunakan contoh kode berikut dengan YOUR_CLOUD_RUN_LOCATION yang diganti dengan lokasi Cloud Run pada 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 Peringkasan Dasbor Looker secara lokal untuk Anda coba. Anda juga telah men-deploy ekstensi ke Google Cloud sehingga pengguna lain dapat mencobanya juga. Sekarang Anda dan pengguna lain dapat mengakses ringkasan dan langkah selanjutnya yang didukung Gemini langsung dari dasbor Anda.

10. Langkah berikutnya

• Ubah codebase ekstensi Anda untuk menyesuaikan fungsinya dengan kebutuhan organisasi Anda.
• Berkontribusilah pada repositori ekstensi serta tingkatkan kualitas ekstensi untuk Anda dan komunitas Looker Anda.
• Mengembangkan ekstensi Anda sendiri untuk meningkatkan pengalaman Looker Anda
• Integrasikan ekstensi Anda ke dasbor sebagai kartu untuk meningkatkan pengalaman dasbor Anda.