Menginstal dan Menyiapkan Toolbox untuk Aplikasi AI Generatif & Agentik di AlloyDB

1. Ringkasan

Gen AI Toolbox for Databases adalah server open source dari Google yang mempermudah pembuatan alat AI Generatif untuk berinteraksi dengan database. Dengan demikian, Anda dapat mengembangkan alat dengan lebih mudah, lebih cepat, dan lebih aman dengan menangani kompleksitas seperti penggabungan koneksi, autentikasi, dan lainnya. Alat ini membantu Anda membuat alat AI Generatif yang memungkinkan agen mengakses data di database Anda. Toolbox menyediakan:

Pengembangan yang disederhanakan: Mengintegrasikan alat ke agen Anda dalam kurang dari 10 baris kode, menggunakan kembali alat di antara beberapa agen atau framework, dan men-deploy versi baru alat dengan lebih mudah.

Performa yang lebih baik: Praktik terbaik seperti penggabungan koneksi, autentikasi, dan lainnya.

Keamanan yang ditingkatkan: Autentikasi terintegrasi untuk akses yang lebih aman ke data Anda.

Kemampuan observasi menyeluruh: Metrik dan pelacakan siap pakai dengan dukungan bawaan untuk OpenTelemetry.

Toolbox berada di antara framework orkestrasi aplikasi dan database Anda, yang menyediakan platform kontrol yang digunakan untuk mengubah, mendistribusikan, atau memanggil alat. Alat ini menyederhanakan pengelolaan alat dengan menyediakan lokasi terpusat untuk menyimpan dan mengupdate alat, sehingga Anda dapat membagikan alat antar-agen dan aplikasi serta mengupdate alat tersebut tanpa harus men-deploy ulang aplikasi.

Yang akan Anda build

Sebagai bagian dari lab ini, Anda akan mem-build aplikasi yang menggunakan alat untuk menjalankan kueri database (AlloyDB) sederhana yang dapat dipanggil dari agen atau aplikasi AI generatif. Untuk melakukannya, Anda akan

  1. Menginstal Toolbox
  2. Menyiapkan alat (yang dirancang untuk melakukan tugas di AlloyDB) di server Toolbox
  3. Men-deploy Toolbox di Cloud Run
  4. Menguji alat dengan endpoint Cloud Run yang di-deploy
  5. Mem-build Fungsi Cloud Run untuk memanggil Toolbox

Persyaratan

  • Browser, seperti Chrome atau Firefox
  • Project Google Cloud yang mengaktifkan penagihan (langkah-langkah di bagian berikutnya).

2. Sebelum memulai

Membuat project

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.
  3. Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Aktifkan Cloud Shell di bagian atas konsol Google Cloud.

Gambar tombol Aktifkan Cloud Shell

  1. Setelah terhubung ke Cloud Shell, periksa apakah Anda sudah diautentikasi dan apakah project ditetapkan ke project ID yang benar menggunakan perintah berikut:
gcloud auth list
  1. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
  1. Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:
gcloud config set project <YOUR_PROJECT_ID>
  1. Aktifkan API yang diperlukan dengan menjalankan perintah berikut satu per satu di Terminal Cloud Shell Anda:

Ada juga satu perintah untuk menjalankan perintah di bawah, tetapi jika Anda adalah pengguna akun uji coba, Anda mungkin mengalami masalah kuota saat mencoba mengaktifkannya secara massal. Itulah sebabnya perintah dipilih satu per baris.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

Alternatif untuk perintah gcloud adalah melalui konsol dengan menelusuri setiap produk atau menggunakan link ini.

Jika ada API yang terlewat, Anda dapat mengaktifkannya kapan saja selama proses penerapan.

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.

3. Penyiapan database

Di lab ini, kita akan menggunakan AlloyDB sebagai database untuk menyimpan data retail. Layanan ini menggunakan cluster untuk menyimpan semua resource, seperti database dan log. Setiap cluster memiliki instance utama yang menyediakan titik akses ke data. Tabel akan menyimpan data sebenarnya.

Mari kita buat cluster, instance, dan tabel AlloyDB tempat set data e-commerce akan dimuat.

Membuat cluster dan instance

  1. Buka halaman AlloyDB di Cloud Console.

Cara mudah untuk menemukan sebagian besar halaman di Cloud Console adalah dengan menelusurinya menggunakan kotak penelusuran konsol.

  1. Pilih BUAT CLUSTER dari halaman tersebut:

f76ff480c8c889aa.png

  1. Anda akan melihat layar seperti di bawah. Buat cluster dan instance dengan nilai berikut (Pastikan nilainya cocok jika Anda meng-clone kode aplikasi dari repo):
  • cluster id: "vector-cluster"
  • sandi: "alloydb"
  • Kompatibel dengan PostgreSQL 15
  • Region: "us-central1"
  • Jaringan: "default"

538dba58908162fb.png

  1. Saat memilih jaringan default, Anda akan melihat layar seperti di bawah ini. Pilih SIAPAKAN KONEKSI.
    7939bbb6802a91bf.png
  2. Dari sana, pilih "Gunakan rentang IP yang dialokasikan secara otomatis" dan Lanjutkan. Setelah meninjau informasi, pilih BUAT KONEKSI. 768ff5210e79676f.png
  3. Setelah jaringan disiapkan, Anda dapat terus membuat cluster. Klik CREATE CLUSTER untuk menyelesaikan penyiapan cluster seperti yang ditunjukkan di bawah:

e06623e55195e16e.png

Pastikan untuk mengubah ID instance menjadi "

vector-instance"

.

Perhatikan bahwa pembuatan Cluster akan memerlukan waktu sekitar 10 menit. Setelah berhasil, Anda akan melihat layar yang menampilkan ringkasan cluster yang baru saja Anda buat.

4. Penyerapan data

Sekarang saatnya menambahkan tabel dengan data tentang toko. Buka AlloyDB, pilih cluster utama, lalu AlloyDB Studio:

847e35f1bf8a8bd8.png

Anda mungkin perlu menunggu hingga instance selesai dibuat. Setelah selesai, login ke AlloyDB menggunakan kredensial yang Anda buat selama pembuatan cluster. Gunakan data berikut untuk mengautentikasi ke PostgreSQL:

  • Nama pengguna : "postgres"
  • Database : "postgres"
  • Sandi : "alloydb"

Setelah Anda berhasil diautentikasi ke AlloyDB Studio, perintah SQL dapat dimasukkan di Editor. Anda dapat menambahkan beberapa jendela Editor menggunakan tanda plus di sebelah kanan jendela terakhir.

91a86d9469d499c4.png

Anda dapat memasukkan perintah untuk AlloyDB di jendela editor, menggunakan opsi Run, Format, dan Clear sesuai kebutuhan.

Mengaktifkan Ekstensi

Untuk mem-build aplikasi ini, kita akan menggunakan ekstensi pgvector dan google_ml_integration. Ekstensi pgvector memungkinkan Anda menyimpan dan menelusuri embedding vektor. Ekstensi google_ml_integration menyediakan fungsi yang Anda gunakan untuk mengakses endpoint prediksi Vertex AI guna mendapatkan prediksi di SQL. Aktifkan ekstensi ini dengan menjalankan DDL berikut:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Jika Anda ingin memeriksa ekstensi yang telah diaktifkan di database, jalankan perintah SQL ini:

select extname, extversion from pg_extension;

Membuat tabel

Buat tabel menggunakan pernyataan DDL di bawah:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Setelah berhasil menjalankan perintah di atas, Anda akan dapat melihat tabel di database.

Menyerap data

Untuk lab ini, kita memiliki data pengujian sekitar 72 data dalam file SQL ini. Isinya adalah kolom id, name, description, quantity, price, image_url. Kolom lainnya akan diisi nanti di lab.

Salin baris/sisipkan pernyataan dari sana, lalu tempel baris tersebut di tab editor kosong dan pilih RUN.

Untuk melihat konten tabel, luaskan bagian Penjelajah hingga Anda dapat melihat tabel bernama apparels. Pilih titik tiga (⋮) untuk melihat opsi Buat kueri tabel. Pernyataan SELECT akan terbuka di tab Editor baru.

cfaa52b717f9aaed.png

Berikan Izin

Jalankan pernyataan di bawah untuk memberikan hak eksekusi pada fungsi embedding kepada pengguna postgres:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Memberikan PERAN Pengguna Vertex AI ke akun layanan AlloyDB

Buka terminal Cloud Shell dan berikan perintah berikut:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. Membuat penyematan untuk konteks

Komputer jauh lebih mudah memproses angka daripada memproses teks. Sistem penyematan mengubah teks menjadi serangkaian bilangan floating point, yang disebut penyematan vektor, yang harus mewakili teks, terlepas dari bagaimana kata-katanya, bahasa yang digunakan, dll.

Misalnya, lokasi tepi pantai mungkin disebut "di tepi air", "di tepi pantai", "berjalan dari kamar Anda ke laut", "sur la mer", "на берегу океана", dll. Semua istilah ini terlihat berbeda, tetapi makna semantiknya atau dalam terminologi machine learning, penyematan mereka harus sangat mirip satu sama lain.

Setelah data dan konteks siap, kita akan menjalankan SQL untuk menambahkan penyematan deskripsi produk ke tabel di kolom embedding. Ada berbagai model penyematan yang dapat Anda gunakan. Kita menggunakan text-embedding-005 dari Vertex AI. Pastikan untuk menggunakan model penyematan yang sama di seluruh project.

Catatan: Jika menggunakan Project Google Cloud lama, Anda mungkin perlu terus menggunakan model penyematan teks versi lama seperti textembedding-gecko.

Kembali ke tab AlloyDB Studio dan ketik DML berikut:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Lihat kembali tabel toys untuk melihat beberapa penyematan. Pastikan untuk menjalankan ulang pernyataan SELECT untuk melihat perubahan.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Tindakan ini akan menampilkan vektor penyematan, yang terlihat seperti array float, untuk deskripsi mainan seperti yang ditunjukkan di bawah ini:

7d32f7cd7204e1f3.png

Catatan: Project Google Cloud yang baru dibuat dalam paket gratis mungkin mengalami masalah kuota terkait jumlah permintaan penyematan yang diizinkan per detik ke model Penyematan. Sebaiknya gunakan kueri filter untuk ID, lalu pilih 1-5 data secara selektif dan seterusnya, saat membuat penyematan.

6. Melakukan penelusuran Vektor

Setelah tabel, data, dan penyematan siap, mari kita lakukan penelusuran vektor real-time untuk teks penelusuran pengguna.

Misalkan pengguna bertanya:

"I want a white plush teddy bear toy with a floral pattern".

Anda dapat menemukan kecocokan untuk hal ini dengan menjalankan kueri di bawah:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Mari kita lihat kueri ini secara mendetail:

Dalam kueri ini,

  1. Teks penelusuran pengguna adalah: "I want a white plush teddy bear toy with a floral pattern."
  2. Kita mengonversinya menjadi penyematan dalam metode embedding() menggunakan model: text-embedding-005. Langkah ini akan terlihat familier setelah langkah terakhir, saat kita menerapkan fungsi penyematan ke semua item dalam tabel.
  3. "<=>" mewakili penggunaan metode jarak COSINE SIMILARITY. Anda dapat menemukan semua ukuran kesamaan yang tersedia di dokumentasi pgvector.
  4. Kita mengonversi hasil metode penyematan ke jenis vektor agar kompatibel dengan vektor yang disimpan dalam database.
  5. LIMIT 5 menunjukkan bahwa kita ingin mengekstrak 5 tetangga terdekat untuk teks penelusuran.

Hasilnya akan terlihat seperti ini:

fa7f0fc3a4c68804.png

Seperti yang dapat Anda amati dalam hasil, kecocokannya cukup dekat dengan teks penelusuran. Coba ubah teks untuk melihat perubahan hasilnya.

7. Menyiapkan AlloyDB untuk Interaksi Toolbox

Sebagai persiapan untuk menyiapkan Toolbox, mari kita aktifkan konektivitas IP publik di instance AlloyDB agar alat baru dapat mengakses database.

  1. Buka instance AlloyDB Anda, klik EDIT, lalu buka halaman Edit instance utama.
  2. Buka bagian Konektivitas IP publik, centang kotak Aktifkan IP publik, lalu masukkan alamat IP mesin Cloud Shell Anda.
  3. Untuk mendapatkan IP komputer Cloud Shell, buka Terminal Cloud Shell dan masukkan ifconfig. Dari hasil tersebut, identifikasi alamat inet eth0 dan ganti 2 digit terakhir dengan 0.0 dengan ukuran mask '/16'. Misalnya, akan terlihat seperti "XX.XX.0.0/16" dengan XX adalah angka.
  4. Tempelkan IP ini di kotak teks "Jaringan" Jaringan eksternal yang diizinkan di halaman edit instance.

5f6e60e8dec2cea1.png

  1. Klik UPDATE INSTANCE setelah selesai.

Proses ini akan memerlukan waktu beberapa menit.

8. Penginstalan Toolbox

  1. Anda dapat membuat folder project untuk menyimpan detail alat. Dalam hal ini, karena kita sedang mengerjakan data toko mainan, mari kita buat folder bernama "toystore" dan buka folder tersebut. Buka Terminal Cloud Shell dan pastikan project Anda dipilih dan ditampilkan di perintah terminal. Jalankan perintah di bawah dari Terminal Cloud Shell Anda:
mkdir toystore

cd toystore
  1. Jalankan perintah di bawah untuk mendownload dan menginstal toolbox di folder baru Anda:
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  1. Alihkan ke Cloud Shell Editor. Luaskan folder "toystore" yang baru dibuat dan buat file baru bernama tools.yaml. Salin konten di bawah. Ganti YOUR_PROJECT_ID dan periksa apakah semua detail koneksi lainnya sudah akurat.
sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

Dalam alat ini, kita hanya menemukan kecocokan terdekat dengan teks penelusuran pengguna (deskripsi mainan kustom) dan menampilkan harganya. Anda juga dapat mengubahnya untuk menemukan harga rata-rata dari 5 mainan teratas yang paling cocok:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

Anda sudah siap dengan definisi alat.

Untuk mengetahui detail selengkapnya tentang cara mengonfigurasi tools.yaml, lihat dokumentasi ini.

  1. Alihkan ke Terminal Cloud Shell dan masukkan perintah berikut untuk memulai server toolbox dengan konfigurasi alat Anda:
./toolbox --tools_file "tools.yaml"
  1. Sekarang, jika Anda membuka server dalam mode pratinjau web di cloud, Anda akan dapat melihat server Toolbox yang sudah siap dan berjalan dengan alat baru bernama get-toy-price.

9. Deployment Cloud Run Toolbox

Mari kita deploy ke Cloud Run agar Anda dapat menggunakan alat ini.

  1. Ikuti petunjuk di halaman ini satu per satu hingga Anda mencapai perintah gcloud run deploy toolbox yang ada di poin ke-3 di bagian "Deploy to Cloud Run". Anda memerlukan opsi pertama, bukan opsi kedua yang digunakan saat Anda menggunakan metode jaringan VPC.
  2. Setelah berhasil di-deploy, Anda akan menerima endpoint server Toolbox yang di-deploy Cloud Run. Uji dengan perintah CURL.

Anda siap menggunakan alat yang baru di-deploy di aplikasi agen Anda.

10. Menghubungkan Aplikasi dengan Toolbox

Di bagian ini, kita akan mem-build aplikasi kecil untuk menguji alat Anda agar berinteraksi dengan kebutuhan aplikasi dan mengambil respons.

  1. Buka Google Colab dan buka notebook baru.
  2. Jalankan kode berikut di notebook Anda
pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)
  1. Hasilnya akan terlihat seperti ini:

5074f209a86c4f15.png

Ini adalah alat yang dipanggil secara eksplisit dalam aplikasi Python yang menggunakan toolkit toolbox-langchain.

  1. Jika ingin menggunakan alat ini dan mengikatnya ke agen dalam aplikasi terintegrasi LangGraph, Anda dapat melakukannya dengan mudah menggunakan toolkit langgraph.
  2. Lihat cuplikan kode untuk ini.

11. Bawa ke Cloud!!!

Mari kita gabungkan cuplikan kode Python ini dalam Cloud Run Functions agar menjadi serverless.

  1. Salin sumber dari folder repo kode untuk mengirimkannya ke Cloud Functions.
  2. Buka konsol Cloud Run Functions, lalu klik CREATE FUNCTION.
  3. Jangan autentikasi untuk aplikasi demo dan pilih runtime Python 3.11 di halaman berikutnya.
  4. Salin file main.py dan requirements.txt dari repo sumber yang dibagikan di langkah 1 dan tempel di file masing-masing.
  5. Deploy fungsi dan Anda akan mendapatkan endpoint REST untuk alat prediksi harga yang akan diakses di aplikasi web toko mainan.
  6. Endpoint Anda akan terlihat seperti ini:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

  1. Anda dapat mengujinya langsung di konsol Cloud Functions dengan membuka tab PENGUJIAN dan memasukkan hal berikut sebagai input permintaan:

{

               "`search`"`:` "`White plush toy`"

}

  1. Klik UJI FUNGSI atau jalankan di Terminal Cloud Shell apa pun yang Anda pilih untuk digunakan. Anda akan melihat hasilnya di sebelah kanan pada judul "Output":

d7ba57cf5e5ca553.png

12. Selamat

Selamat! Anda telah berhasil membuat alat yang andal dan benar-benar modular yang dapat berinteraksi di seluruh database, platform, dan framework orkestrasi AI Generatif untuk membantu membuat aplikasi agen Anda.