Memeriksa fakta pernyataan dengan agen AI ADK dan model Gemini

Tingkat coding: Lanjutan
Durasi: 30 menit
Jenis project: Fungsi kustom

Ringkasan

Fungsi kustom pengecekan fakta untuk Google Spreadsheet yang akan digunakan sebagai project Apps Script terikat yang didukung oleh agen Vertex AI dan model Gemini.

Contoh ini menunjukkan cara menggunakan dua jenis resource AI yang canggih langsung ke spreadsheet Google Spreadsheet Anda:

1. Agen AI untuk kemampuan penalaran multi-langkah dan multi-alat yang canggih menggunakan agen ADK yang di-deploy di Vertex AI Agent Engine.
2. Model AI untuk kemampuan pemahaman, generatif, dan peringkasan tingkat lanjut menggunakan model Gemini dari Vertex AI.

Tujuan

• Pahami fungsi solusi.
• Pahami cara penerapan solusi.
• Deploy agen Vertex AI.
• Siapkan skrip.
• Jalankan skrip.

Tentang solusi ini

Fungsi kustom Spreadsheet diberi nama FACT_CHECK dan beroperasi sebagai solusi end-to-end. Model ini menganalisis pernyataan, mendasarkan responsnya menggunakan informasi web terbaru, dan menampilkan hasilnya dalam format yang Anda butuhkan:

• Penggunaan:
  • =FACT_CHECK("Your statement here") untuk output yang ringkas dan diringkas.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") untuk format output tertentu.
• Alasan: Agen AI ADK Auditor LLM (Contoh Python).
• Pemformatan output: Model Gemini.

Solusi ini meminta Vertex AI REST API menggunakan UrlFetchApp.

Arsitektur

Diagram berikut menunjukkan arsitektur resource Google Workspace dan Google Cloud yang digunakan oleh fungsi kustom.

Prasyarat

Untuk menggunakan sampel ini, Anda memerlukan prasyarat berikut:

• Akun Google (akun Google Workspace mungkin memerlukan persetujuan administrator).

• Browser web dengan akses ke internet.

• Prasyarat agen ADK LLM Auditor

  • Python 3.11+: Untuk penginstalan, ikuti petunjuk di situs Python resmi.
  • Python Poetry: Untuk penginstalan, ikuti petunjuk di situs Poetry resmi.
  • Google Cloud CLI: Untuk penginstalan, ikuti petunjuk di situs Google Cloud resmi.

Menyiapkan lingkungan

Bagian ini menunjukkan cara membuat dan mengonfigurasi project Google Cloud.

Membuat project Google Cloud

Konsol Google Cloud

1. Di konsol Google Cloud, buka Menu > IAM & Admin > Create a Project.

   Buka Buat Project

2. Di kolom Project Name, masukkan nama deskriptif untuk project Anda.

   Opsional: Untuk mengedit Project ID, klik Edit. Project ID tidak dapat diubah setelah project dibuat, jadi pilih ID yang sesuai dengan kebutuhan Anda sepanjang waktu project tersebut.

3. Di kolom Lokasi, klik Jelajah untuk menampilkan potensi lokasi untuk project Anda. Kemudian, klik Select.
   Perhatian: Tidak dapat menemukan organisasi Google Workspace Anda?
   Artinya, Anda tidak login ke akun Google Workspace. Beberapa fitur yang dijelaskan dalam dokumentasi developer Google Workspace hanya tersedia untuk project yang terkait dengan organisasi.
4. Klik Buat. Konsol Google Cloud akan membuka halaman Dasbor dan project Anda akan dibuat dalam beberapa menit.

gcloud CLI

Di salah satu lingkungan pengembangan berikut, akses Google Cloud CLI (gcloud):

• Cloud Shell: Untuk menggunakan terminal online dengan gcloud CLI yang sudah disiapkan, aktifkan Cloud Shell.
  Aktifkan Cloud Shell
• Shell Lokal: Untuk menggunakan lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI.
  Untuk membuat project Cloud, gunakan perintah gcloud projects create:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan menetapkan ID untuk project yang ingin Anda buat.

Mengaktifkan penagihan untuk project Cloud

Jika tidak dapat menautkan akun penagihan, berarti Anda tidak memiliki izin yang diperlukan untuk melakukan perubahan ini. Untuk mengetahui informasi selengkapnya, lihat Izin yang diperlukan untuk mengaktifkan penagihan.

Konsol Google Cloud

1. Di konsol Google Cloud, buka Penagihan. Klik Menu > Penagihan > Project Saya.

   Buka Penagihan untuk Project Saya

2. Di Pilih organisasi, pilih organisasi yang terkait dengan project Google Cloud Anda.
3. Di baris project, buka menu Tindakan (), klik Ubah penagihan, lalu pilih akun Penagihan Cloud.
4. Klik Tetapkan akun.

gcloud CLI

1. Untuk mencantumkan akun penagihan yang tersedia, jalankan:

   gcloud billing accounts list

2. Tautkan akun penagihan dengan project Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Ganti kode berikut:

   • PROJECT_ID adalah Project ID untuk project Cloud yang penagihannya ingin Anda aktifkan.
   • BILLING_ACCOUNT_ID adalah ID akun penagihan yang akan ditautkan dengan project Google Cloud.

Mengaktifkan Vertex AI API

Konsol Google Cloud

1. Di Konsol Google Cloud, aktifkan Vertex AI API.

   Aktifkan API

2. Pastikan Anda mengaktifkan Vertex AI API di project Cloud yang benar, lalu klik Berikutnya.

3. Pastikan Anda mengaktifkan API yang benar, lalu klik Aktifkan.

gcloud CLI

1. Jika perlu, tetapkan project Cloud saat ini ke project yang Anda buat dengan perintah gcloud config set project:

   gcloud config set project PROJECT_ID

   Ganti PROJECT_ID dengan Project ID dari project Cloud yang Anda buat.

2. Aktifkan Vertex AI API dengan perintah gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

Membuat akun layanan di konsol Google Cloud

Buat akun layanan baru dengan peran Vertex AI User dengan mengikuti langkah-langkah berikut:

Konsol Google Cloud

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Klik Create service account.
3. Isi detail akun layanan, lalu klik Buat dan lanjutkan.
   Catatan: Secara default, Google membuat ID akun layanan yang unik. Jika Anda ingin mengubah ID, ubah ID di kolom ID akun layanan.
4. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.
5. Klik Lanjutkan.
6. Opsional: Masukkan pengguna atau grup yang dapat mengelola dan melakukan tindakan dengan akun layanan ini. Untuk mengetahui detail selengkapnya, lihat Mengelola peniruan identitas akun layanan.
7. Klik Selesai. Catat alamat email untuk akun layanan.

gcloud CLI

1. Buat akun layanan:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.

Akun layanan akan muncul di halaman akun layanan. Selanjutnya, buat kunci pribadi untuk akun layanan.

Buat kunci pribadi

Peringatan: Contoh ini menggunakan kunci akun layanan yang diekspor agar lebih mudah. Mengekspor kunci pribadi tidak direkomendasikan dalam produksi karena kunci tersebut tidak boleh disimpan di lokasi yang tidak aman, seperti kontrol sumber.

Untuk mempelajari lebih lanjut penerapan akun layanan yang aman dan praktik terbaik, lihat Memilih waktu penggunaan akun layanan.

Untuk membuat dan mendownload kunci pribadi untuk akun layanan, ikuti langkah-langkah berikut:

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Pilih akun layanan Anda.
3. Klik Keys > Add key > Create new key.
4. Pilih JSON, lalu klik Buat.

   Pasangan kunci umum/pribadi baru Anda dibuat dan didownload ke komputer Anda sebagai file baru. Simpan file JSON yang didownload sebagai credentials.json di direktori kerja Anda. File ini adalah satu-satunya salinan kunci ini. Untuk mengetahui informasi tentang cara menyimpan kunci Anda dengan aman, lihat Mengelola kunci akun layanan.

5. Klik Tutup.

Untuk mengetahui informasi selengkapnya tentang akun layanan, lihat akun layanan dalam dokumentasi Google Cloud IAM.

Men-deploy Agen AI ADK LLM Auditor

1. Jika belum melakukannya, lakukan autentikasi dengan akun Google Cloud Anda dan konfigurasi Google Cloud CLI untuk menggunakan project Google Cloud Anda.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Ganti PROJECT_ID dengan ID project Cloud yang Anda buat.

2. Download repositori GitHub ini

   Download

3. Di lingkungan pengembangan lokal pilihan Anda, ekstrak file arsip yang didownload dan buka direktori adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Buat bucket Cloud Storage baru yang dikhususkan untuk agen ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Ganti kode berikut:

   1. CLOUD_STORAGE_BUCKET_NAME dengan nama bucket unik yang ingin Anda gunakan.
   2. PROJECT_ID dengan ID project Cloud yang Anda buat.
   3. PROJECT_LOCATION dengan lokasi project Cloud yang Anda buat.

5. Tetapkan variabel lingkungan berikut:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Ganti kode berikut:

   1. CLOUD_STORAGE_BUCKET_NAME dengan nama bucket yang Anda buat.
   2. PROJECT_ID dengan ID project Cloud yang Anda buat.
   3. PROJECT_LOCATION dengan lokasi project Cloud yang Anda buat.

6. Instal dan deploy agen ADK dari lingkungan virtual.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Ambil ID agen, Anda akan memerlukannya nanti untuk mengonfigurasi fungsi kustom.

   python3 deployment/deploy.py --list

Meninjau kode contoh

Atau, sebelum membuat spreadsheet baru, luangkan waktu untuk meninjau dan memahami kode contoh yang dihosting di GitHub.

Lihat di GitHub

Membuat dan mengonfigurasi di spreadsheet baru

1. Klik tombol berikut dan buat salinan lengkap spreadsheet Google Sheet contoh, termasuk project Apps Script yang terikat dengan penampungnya.

   Menyalin spreadsheet Google Spreadsheet

2. Di spreadsheet yang baru dibuat, buka Ekstensi > Apps Script.

3. Di project Apps Script, buka Project Settings, klik Edit script properties, lalu klik Add script property untuk menambahkan properti skrip berikut:

   1. LOCATION dengan lokasi project Google Cloud yang dibuat pada langkah sebelumnya, seperti us-central1.
   2. GEMINI_MODEL_ID dengan model Gemini yang ingin Anda gunakan, seperti gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID dengan ID Agen ADK Auditor LLM yang di-deploy pada langkah sebelumnya seperti 1234567890.
   4. SERVICE_ACCOUNT_KEY dengan kunci JSON dari akun layanan yang didownload pada langkah sebelumnya, seperti { ... }.

4. Klik Simpan properti skrip

Menguji fungsi kustom

1. Buka spreadsheet yang baru dibuat.
2. Ubah pernyataan di kolom A.
3. Formula di kolom B dijalankan, lalu menampilkan hasil cek fakta.

Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, sebaiknya hapus project Cloud tersebut.

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tutorial ini, saat menghapusnya, Anda juga akan menghapus pekerjaan lain yang telah dilakukan dalam project tersebut.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang masih ingin Anda gunakan pada masa mendatang. Untuk mempertahankan URL yang menggunakan project ID tersebut, seperti URL di appspot.com, hapus resource yang dipilih di dalam project, alih-alih menghapus seluruh project.

Jika Anda berencana mempelajari beberapa tutorial dan panduan memulai, menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

1. Di Konsol Google Cloud, buka halaman Manage resources. Klik Menu > IAM & Admin > Kelola Resource.

   Buka Resource Manager

2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Hapus .
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Langkah berikutnya

• Fungsi kustom di Google Spreadsheet
• Memperluas Google Spreadsheet