Menginstal dan Menyiapkan Toolbox MCP untuk Database bagi Gen AI &Aplikasi Agentic Anda di AlloyDB

1. Ringkasan

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

Pengembangan yang disederhanakan: Integrasikan alat ke agen Anda dengan kurang dari 10 baris kode, gunakan kembali alat di antara beberapa agen atau framework, dan 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 langsung dengan dukungan bawaan untuk OpenTelemetry.

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

Yang akan Anda build

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

  1. Menginstal MCP Toolbox for Databases
  2. Siapkan alat (yang dirancang untuk melakukan tugas di AlloyDB) di server Toolbox
  3. Men-deploy MCP Toolbox for Databases di Cloud Run
  4. Uji alat dengan endpoint Cloud Run yang di-deploy
  5. Membangun Fungsi Cloud Run untuk memanggil Toolbox

Persyaratan

  • Browser, seperti Chrome atau Firefox
  • Project Google Cloud dengan penagihan diaktifkan (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 Activate Cloud Shell di bagian atas konsol Google Cloud.

Gambar tombol Activate Cloud Shell

  1. Setelah terhubung ke Cloud Shell, periksa apakah Anda sudah diautentikasi dan apakah project disetel 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 mengaktifkan perintah ini secara massal. Itulah sebabnya perintah-perintah tersebut dipisahkan 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 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. Cloud SQL 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 Konsol Cloud.

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

  1. Pilih CREATE CLUSTER dari halaman tersebut:

f76ff480c8c889aa.png

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

538dba58908162fb.png

  1. Saat Anda memilih jaringan default, Anda akan melihat layar seperti di bawah. Pilih SIAPKAN KONEKSI.
    7939bbb6802a91bf.png
  2. Dari sana, pilih "Gunakan rentang IP yang dialokasikan secara otomatis", lalu Lanjutkan. Setelah meninjau informasi, pilih BUAT KONEKSI. 768ff5210e79676f.png
  3. Setelah jaringan disiapkan, Anda dapat melanjutkan pembuatan 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 melakukan autentikasi 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 membangun 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 Anda, 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 rekaman dalam file SQL ini. Berisi kolom id, name, description, quantity, price, image_url. Kolom lainnya akan diisi nanti di lab.

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

Untuk melihat isi tabel, luaskan bagian Explorer hingga Anda dapat melihat tabel bernama apparels. Pilih tiga titik (⋮) untuk melihat opsi 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 Vertex AI User 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 embedding untuk konteks

Komputer jauh lebih mudah memproses angka daripada memproses teks. Sistem embedding mengonversi teks menjadi serangkaian bilangan floating point, yang disebut embedding vektor, yang harus merepresentasikan teks, terlepas dari cara penyusunannya, bahasa yang digunakan, dll.

Misalnya, lokasi di tepi laut dapat disebut "di atas 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, embeddingnya harus sangat dekat satu sama lain.

Setelah data dan konteks siap, kita akan menjalankan SQL untuk menambahkan embedding 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 sematan yang sama di seluruh project.

Catatan: Jika Anda 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 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 embedding, 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 rekaman secara selektif dan seterusnya, saat membuat penyematan.

6. Melakukan penelusuran Vektor

Setelah tabel, data, dan embedding siap, mari 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 akan mengonversinya menjadi embedding dalam metode embedding() menggunakan model: text-embedding-005. Langkah ini akan terlihat familiar setelah langkah terakhir, saat kita menerapkan fungsi penyematan ke semua item dalam tabel.
  3. "<=>" menunjukkan penggunaan metode jarak COSINE SIMILARITY. Anda dapat menemukan semua ukuran kemiripan yang tersedia di dokumentasi pgvector.
  4. Kita mengonversi hasil metode embedding 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 di hasil Anda, kecocokannya cukup dekat dengan teks penelusuran. Coba ubah teks untuk melihat perubahan hasilnya.

7. Mempersiapkan AlloyDB untuk Interaksi Toolbox

Sebagai persiapan untuk menyiapkan Toolbox, mari aktifkan konektivitas IP publik di instance AlloyDB kita 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 Enable public IP, lalu masukkan alamat IP mesin Cloud Shell Anda.
  3. Untuk mendapatkan IP mesin Cloud Shell Anda, buka Terminal Cloud Shell dan masukkan ifconfig. Dari hasilnya, 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" pada Jaringan eksternal yang diizinkan di halaman edit instance.

5f6e60e8dec2cea1.png

  1. Klik PERBARUI INSTANS setelah selesai.

Proses ini akan memerlukan waktu beberapa menit.

8. Penginstalan MCP Toolbox for Databases

  1. Anda dapat membuat folder project untuk menyimpan detail alat. Dalam kasus ini, karena kita sedang mengerjakan data toko mainan, mari 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
  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. Beralih 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 5 mainan 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. Beralih 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 berjalan dengan alat baru Anda yang bernama get-toy-price.

9. Deployment Cloud Run MCP Toolbox for Databases

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

  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 yang di-deploy Cloud Run dari server Toolbox Anda. Uji dengan perintah CURL.

Tips:

Ikuti petunjuk di halaman dengan cermat dan jangan sampai terlewat.

Anda sudah siap menggunakan alat yang baru di-deploy di aplikasi agentik Anda.

10. Menghubungkan Aplikasi Anda dengan MCP Toolbox for Databases

Di bagian ini, kita akan membuat aplikasi kecil untuk menguji alat Anda dalam 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-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)
  1. Hasilnya akan terlihat seperti ini:

5074f209a86c4f15.png

Alat ini 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 hal ini.

11. Bawa ke Cloud!!!

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

  1. Salin sumber dari folder repositori kode untuk mengirimkannya ke Cloud Functions.
  2. Buka konsol Cloud Run Functions, lalu klik CREATE FUNCTION.
  3. Biarkan tidak diautentikasi 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, lalu tempelkan ke file masing-masing.
  5. Ganti URL server di main.py dengan URL server Anda.
  6. Deploy fungsi dan Anda akan mendapatkan endpoint REST untuk alat prediksi harga yang dapat diakses di aplikasi web toko mainan.
  7. 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 TESTING dan memasukkan berikut sebagai input permintaan:

{

           "search": "White plush toy"

}

  1. Klik TEST THE FUNCTION atau jalankan di Terminal Cloud Shell, mana pun yang ingin Anda gunakan. Anda akan melihat hasilnya di sebelah kanan di bagian judul "Output":

d7ba57cf5e5ca553.png

12. Selamat

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