Tentang codelab ini
1. Ringkasan
Toolbox MCP untuk Database adalah server open source dari Google yang mempermudah pembangunan 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. Solusi ini membantu Anda membangun alat AI Generatif yang memungkinkan agen mengakses data di database Anda. Toolbox menyediakan:
Pengembangan yang disederhanakan: Integrasikan alat ke agen Anda dalam kurang dari 10 baris kode, gunakan kembali alat antara beberapa agen atau framework, dan deploy versi alat baru dengan lebih mudah.
Performa yang lebih baik: Praktik terbaik seperti penggabungan koneksi, autentikasi, dan lainnya.
Keamanan yang disempurnakan: Autentikasi terintegrasi untuk akses yang lebih aman ke data Anda.
Kemampuan observasi end-to-end: Metrik dan pelacakan yang 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 membangun aplikasi yang menggunakan alat untuk melakukan kueri database sederhana (AlloyDB) yang dapat dipanggil dari agen Anda atau aplikasi AI generatif. Untuk hal ini Anda akan
- Menginstal Toolbox MCP untuk Database
- Menyiapkan alat (yang dirancang untuk melakukan tugas di AlloyDB) di server Toolbox
- Men-deploy Toolbox MCP untuk Database di Cloud Run
- Menguji alat dengan endpoint Cloud Run yang di-deploy
- Membuat Cloud run Function untuk memanggil Toolbox
Persyaratan
2. Sebelum memulai
Membuat project
- Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
- Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.
- Anda akan menggunakan Cloud Shell, yakni lingkungan command line yang berjalan di Google Cloud. Klik Aktifkan Cloud Shell di bagian atas konsol Google Cloud.
- Setelah terhubung ke Cloud Shell, periksa apakah Anda sudah diautentikasi dan apakah project sudah ditetapkan ke project ID yang benar menggunakan perintah berikut:
gcloud auth list
- Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
- Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:
gcloud config set project <YOUR_PROJECT_ID>
- Aktifkan API yang diperlukan dengan menjalankan perintah berikut satu per satu di Terminal Cloud Shell Anda:
Anda juga dapat menggunakan satu perintah untuk menjalankan perintah di bawah. Namun, jika Anda adalah pengguna akun uji coba, Anda mungkin mengalami masalah kuota saat mencoba mengaktifkannya secara massal. Itulah mengapa 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. Halaman 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 aktual.
Mari kita buat cluster, instance, dan tabel AlloyDB tempat set data e-commerce akan dimuat.
Membuat cluster dan instance
- Buka halaman AlloyDB di Konsol Cloud.
Cara mudah untuk menemukan sebagian besar halaman di Cloud Console adalah dengan menelusurinya menggunakan kotak penelusuran konsol.
- Pilih BUAT CLUSTER dari halaman tersebut:
- Anda akan melihat layar seperti di bawah ini. Buat cluster dan instance dengan nilai berikut (Pastikan nilainya sama jika Anda meng-clone kode aplikasi dari repo):
- id cluster: "
vector-cluster" - sandi: "
alloydb" - Kompatibel dengan PostgreSQL 15
- Wilayah: "
us-central1" - Jaringan: "
default"
- Saat memilih jaringan default, Anda akan melihat layar seperti di bawah ini. Pilih SIAPKAN KONEKSI.
- Dari sana, pilih "{i>Use an automatically allocated IP range<i}" dan {i>Continue<i}. Setelah meninjau informasi, pilih BUAT HUBUNGAN.
- Setelah jaringan disiapkan, Anda dapat melanjutkan pembuatan cluster. Klik CREATE CLUSTER untuk menyelesaikan penyiapan cluster seperti yang ditunjukkan di bawah ini:
Pastikan untuk mengubah ID instance menjadi "
vector-instance"
.
Perlu diperhatikan bahwa pembuatan Cluster akan memerlukan waktu sekitar 10 menit. Setelah berhasil, Anda akan melihat layar yang menampilkan ringkasan cluster yang baru saja dibuat.
4. Penyerapan data
Sekarang saatnya menambahkan tabel dengan data tentang toko tersebut. Buka AlloyDB, pilih cluster utama, lalu AlloyDB Studio:
Anda mungkin perlu menunggu hingga instance selesai dibuat. Setelah selesai, login ke AlloyDB menggunakan kredensial yang Anda buat saat pembuatan cluster. Gunakan data berikut untuk mengautentikasi ke PostgreSQL:
- Nama pengguna : "
postgres" - Database: "
postgres" - Sandi: "
alloydb"
Setelah Anda berhasil mengautentikasi ke AlloyDB Studio, perintah SQL dapat dimasukkan di Editor. Anda dapat menambahkan beberapa jendela Editor menggunakan tanda tambah di sebelah kanan jendela terakhir.
Anda dapat memasukkan perintah untuk AlloyDB di jendela editor, menggunakan opsi Run, Format, dan Clear sesuai kebutuhan.
Aktifkan Ekstensi
Untuk membuat aplikasi ini, kita akan menggunakan ekstensi pgvector dan google_ml_integration. Ekstensi pgvector memungkinkan Anda untuk 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 ingin memeriksa ekstensi yang telah diaktifkan pada database Anda, jalankan perintah SQL ini:
select extname, extversion from pg_extension;
Membuat tabel
Buat tabel menggunakan pernyataan DDL di bawah ini:
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 perintah di atas berhasil dieksekusi, Anda seharusnya dapat melihat tabel di {i>database<i}.
Menyerap data
Untuk lab ini, kami memiliki data uji sekitar 72 record dalam file SQL ini. Isinya adalah kolom id, name, description, quantity, price, image_url. Kolom lain akan diisi nanti di lab.
Salin baris/sisipkan pernyataan dari sana lalu tempel baris tersebut di tab editor kosong dan pilih RUN.
Untuk melihat isi tabel, luaskan bagian Penjelajah hingga Anda dapat melihat tabel bernama pakaian. Pilih tanda titik tiga (⋮) untuk melihat opsi Kueri tabel. Pernyataan SELECT akan terbuka di tab Editor baru.
Berikan Izin
Jalankan pernyataan di bawah untuk memberikan hak eksekusi fungsi embedding kepada pengguna postgres:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Berikan ROLE 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 embeddings untuk konteks
Jauh lebih mudah bagi komputer untuk memproses angka daripada memproses teks. Sistem embedding mengubah teks menjadi serangkaian bilangan floating point, yang disebut penyematan vektor, yang harus mewakili teks, terlepas dari susunan katanya, bahasa yang digunakan, dll.
Misalnya, lokasi tepi laut mungkin disebut "di atas air", "tepi pantai", "berjalan dari kamar Anda menuju lautan", "sur la mer", "на privasii, "sur la mer" dll. Semua istilah ini terlihat berbeda, tetapi arti semantiknya atau dalam terminologi machine learning, embeddings tersebut harus sangat dekat satu sama lain.
Setelah data dan konteks siap, kita akan menjalankan SQL untuk menambahkan embeddings deskripsi produk ke tabel di kolom embedding. Ada berbagai model penyematan yang dapat Anda gunakan. Kami menggunakan text-embedding-005 dari Vertex AI. Pastikan untuk menggunakan model embedding 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 tabel toys lagi untuk melihat beberapa embedding. Pastikan untuk menjalankan kembali pernyataan SELECT untuk melihat perubahannya.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Tindakan ini akan menampilkan vektor embeddings, yang terlihat seperti array float, untuk deskripsi mainan seperti yang ditunjukkan di bawah ini:
Catatan: Project Google Cloud yang baru dibuat dengan paket gratis mungkin mengalami masalah kuota terkait jumlah permintaan penyematan yang diizinkan per detik untuk model Embedding. Sebaiknya gunakan kueri filter untuk ID, lalu pilih 1-5 catatan secara selektif dan seterusnya, sambil menghasilkan penyematan.
6. Melakukan penelusuran Vektor
Setelah tabel, data, dan embedding sudah siap, mari kita lakukan penelusuran vektor real-time untuk teks penelusuran pengguna.
Misalnya pengguna bertanya:
"I want a white plush teddy bear toy with a floral pattern".
Anda dapat menemukan kecocokan ini dengan menjalankan kueri di bawah ini:
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 detail:
Dalam kueri ini,
- Teks penelusuran pengguna adalah: "
I want a white plush teddy bear toy with a floral pattern." - Kita mengonversinya menjadi penyematan dalam metode
embedding()menggunakan model:text-embedding-005. Langkah ini akan terlihat familier setelah langkah terakhir, di mana kita menerapkan fungsi embedding ke semua item dalam tabel. - "
<=>" mewakili penggunaan metode jarak COSINE similarITY. Anda dapat menemukan semua ukuran kesamaan yang tersedia di dokumentasi pgvector. - Kita mengonversi hasil metode embedding ke jenis vektor agar kompatibel dengan vektor yang disimpan dalam database.
- LIMIT 5 mewakili bahwa kita ingin mengekstrak 5 tetangga terdekat untuk teks pencarian.
Hasilnya akan terlihat seperti ini:
Seperti yang dapat Anda amati dalam hasil Anda, kecocokannya cukup mirip 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 kita agar alat baru dapat mengakses database.
- Buka instance AlloyDB Anda, klik EDIT, lalu buka halaman Edit instance utama.
- Buka bagian Public IPConnectivity, centang kotak Enable public IP, lalu masukkan alamat IP mesin Cloud Shell Anda.
- Untuk mendapatkan IP mesin Cloud Shell Anda, buka Terminal Cloud Shell dan masukkan ifconfig. Dari hasil tersebut identifikasikan alamat inet eth0 dan ganti 2 digit terakhir dengan 0.0 dengan ukuran mask '/16'. Misalnya, kodenya akan terlihat seperti "XX.XX.0.0/16" di mana XX adalah angka.
- Tempel IP ini di kotak teks "Jaringan" yang diotorisasi pada halaman edit instance.
- Klik UPDATE INSTANCE setelah selesai.
Proses ini akan memerlukan waktu beberapa menit.
8. Toolbox MCP untuk Penginstalan Database
- 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 Cloud Shell Terminal dan pastikan project Anda dipilih dan ditampilkan di perintah terminal. Jalankan perintah di bawah dari Terminal Cloud Shell Anda:
mkdir toystore
cd toystore
- Jalankan perintah di bawah ini untuk mengunduh 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
- Alihkan ke Cloud Shell Editor. Luaskan folder yang baru dibuat "toystore" dan buat file baru bernama tools.yaml. Salin konten di bawah. Ganti ANDA_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, kami hanya menemukan yang paling cocok dengan teks penelusuran pengguna (deskripsi mainan kustom) dan menampilkan harganya. Anda juga dapat mengubahnya untuk menemukan harga rata-rata 5 mainan terdekat yang cocok:
select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) sebagai harga;
Anda sudah siap dengan definisi alat{i>.<i}
Untuk detail selengkapnya tentang mengonfigurasi tools.yaml, lihat dokumentasi ini.
- Beralihlah ke Terminal Cloud Shell dan masukkan perintah berikut untuk memulai server toolbox dengan konfigurasi alat Anda:
./toolbox --tools_file "tools.yaml"
- Sekarang, jika Anda membuka server dalam mode pratinjau web di cloud, Anda akan dapat melihat server Toolbox aktif dan berjalan dengan alat baru bernama
get-toy-price.
9. Deployment Cloud Run untuk Toolbox MCP untuk Database
Mari kita deploy alat ke Cloud Run agar Anda dapat menerapkan alat ini ke penggunaan sebenarnya.
- Ikuti petunjuk di halaman ini satu per satu hingga Anda mencapai perintah
gcloud run deploy toolboxyang ada di titik ke-3 pada bagian "Deploy to Cloud Run". Anda memerlukan opsi pertama dan bukan opsi kedua saat menggunakan metode jaringan VPC. - Setelah berhasil di-deploy, Anda akan menerima endpoint yang di-deploy Cloud Run dari server Toolbox Anda. Uji dengan perintah CURL.
Tips:
Ikuti petunjuk di halaman dengan cermat dan jangan lewatkan.
Anda sudah siap untuk menggunakan alat yang baru di-deploy di aplikasi agen.
10. Menghubungkan Aplikasi dengan Toolbox MCP untuk Database
Di bagian ini, kita akan membangun aplikasi kecil untuk menguji alat Anda guna berinteraksi dengan kebutuhan aplikasi dan mengambil respons.
- Buka Google Colab dan buka notebook baru.
- Jalankan perintah berikut di notebook Anda
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- Hasilnya akan seperti ini:
Ini adalah alat yang dipanggil secara eksplisit dalam aplikasi Python yang menggunakan toolkit toolbox-langchain.
- Jika ingin menggunakan alat ini dan mengikatnya ke agen dalam aplikasi terintegrasi LangGraph, Anda dapat melakukannya dengan mudah menggunakan toolkit
langgraph. - Lihat cuplikan kode untuk hal ini.
11. Beralihlah ke Cloud!!!
Mari kita gabungkan cuplikan kode Python ini dalam Cloud Run Functions untuk membuatnya tanpa server.
- Salin sumber dari folder repo kode untuk memindahkan resource ini ke Cloud Functions.
- Buka konsol Cloud Run Functions dan klik CREATE FUNCTION.
- Biarkan tidak diautentikasi untuk aplikasi demo dan pilih runtime Python 3.11 di halaman berikutnya.
- Salin file
main.pydanrequirements.txtdari repo sumber yang dibagikan di langkah 1 dan tempelkan di file masing-masing. - Ganti URL server di main.py dengan URL server Anda.
- Deploy fungsi dan Anda akan mendapatkan endpoint REST untuk alat prediksi harga yang dapat diakses di aplikasi web toystore.
- Endpoint Anda akan terlihat seperti ini:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- Anda dapat mengujinya langsung di konsol Cloud Functions dengan membuka tab TESTING dan memasukkan hal berikut sebagai input permintaan:
{
"search": "White plush toy"
}
- Klik UJI FUNGSI atau jalankan di Cloud Shell Terminal apa pun yang Anda pilih untuk digunakan. Anda akan melihat hasilnya di sebelah kanan di bawah judul "Output":
12. Selamat
Selamat! Anda telah berhasil membuat alat yang tangguh dan benar-benar modular yang dapat berinteraksi di berbagai database, platform, dan framework orkestrasi AI Generatif untuk membantu membuat aplikasi agen.