Bu codelab hakkında
1. Genel Bakış
Veritabanları için MCP Araç Kutusu, veritabanlarıyla etkileşime geçmek için üretken yapay zeka araçları oluşturmayı kolaylaştıran açık kaynak bir Google sunucusudur. Bağlantı havuzu oluşturma, kimlik doğrulama ve daha birçok karmaşıklığı ele alarak araçları daha kolay, daha hızlı ve daha güvenli bir şekilde geliştirmenize olanak tanır. Temsilcilerinizin veritabanınızdaki verilere erişmesini sağlayan üretken yapay zeka araçları oluşturmanıza yardımcı olur. Araç Kutusu şunları sağlar:
Basitleştirilmiş geliştirme: Araçları 10 satırdan az kodla aracınıza entegre edin, araçları birden fazla aracı veya çerçeve arasında yeniden kullanın ve araçların yeni sürümlerini daha kolay bir şekilde dağıtın.
Daha iyi performans: Bağlantı havuzu oluşturma, kimlik doğrulama ve daha fazlası gibi en iyi uygulamalar.
Gelişmiş güvenlik: Verilerinize daha güvenli erişim için entegre kimlik doğrulama.
Uçtan uca gözlemlenebilirlik: Yerleşik OpenTelemetry desteğiyle kullanıma hazır metrikler ve izleme.
Araç Kutusu, uygulamanızın orkestrasyon çerçevesi ile veritabanınız arasında yer alır ve araçları değiştirmek, dağıtmak veya çağırmak için kullanılan bir kontrol düzlemi sağlar. Araçları depolamak ve güncellemek için merkezi bir konum sunarak araçlarınızın yönetimini basitleştirir. Böylece, araçları aracılar ve uygulamalar arasında paylaşabilir ve uygulamanızı yeniden dağıtmadan bu araçları güncelleyebilirsiniz.
Neler oluşturacaksınız?
Bu laboratuvar kapsamında, aracınızdan veya üretken yapay zeka uygulamasından çağrılabilecek basit bir veritabanı (AlloyDB) sorgusu gerçekleştirmek için araç kullanan bir uygulama derleyeceksiniz. Bunun için
- Veritabanları için MCP Araç Kutusu Yükleme
- Aracı (AllyDB'deki bir görevi gerçekleştirmek için tasarlanmıştır) Araç Kutusu sunucusunda kurma
- Cloud Run'da Veritabanları İçin MCP Araç Kutusu Dağıtma
- Aracı dağıtılmış Cloud Run uç noktasıyla test etme
- Araç Kutusu'nu çağırmak için Cloud Run İşlevini derleme
Şartlar
2. Başlamadan önce
Proje oluşturma
- Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
- Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin.
- Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
- Cloud Shell'e bağlandıktan sonra, aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin doğru proje kimliğine ayarlanıp ayarlanmadığını kontrol etmek için aşağıdaki komutu kullanın:
gcloud auth list
- gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
- Projeniz ayarlanmadıysa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
- Aşağıdaki komutları Cloud Shell terminalinizde tek tek çalıştırarak gerekli API'leri etkinleştirin:
Aşağıdakileri tek bir komutla çalıştırabilirsiniz. Ancak deneme hesabı kullanıcısıysanız bunları toplu olarak etkinleştirmeye çalışırken kota sorunlarıyla karşılaşabilirsiniz. Bu nedenle komutlar her satıra bir tane gelecek şekildedir.
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
gcloud komutunun alternatifi, her ürünü arayarak veya bu bağlantıyı kullanarak konsol üzerinden kullanılabilir.
Atlanan bir API varsa uygulama sırasında istediğiniz zaman etkinleştirebilirsiniz.
gcloud komutları ve kullanımı için belgelere bakın.
3. Veritabanı kurulumu
Bu laboratuvarda perakende verilerini saklamak için veritabanı olarak AlloyDB'yi kullanacağız. Veritabanları ve günlükler gibi tüm kaynakları barındırmak için kümeler kullanır. Her kümenin, verilere erişim noktası sağlayan bir birincil örneği vardır. Tablolar gerçek verileri tutacaktır.
E-ticaret veri kümesinin yükleneceği bir AlloyDB kümesi, örnek ve tablo oluşturalım.
Küme ve örnek oluşturma
- Cloud Console'daki AlloyDB sayfasına gidin.
Cloud Console'daki çoğu sayfayı bulmanın kolay bir yolu, konsolun arama çubuğunu kullanarak sayfaları aramaktır.
- İlgili sayfadan KÜME OLUŞTUR'u seçin:
- Aşağıdakine benzer bir ekran görürsünüz. Aşağıdaki değerlerle bir küme ve örnek oluşturun (Uygulama kodunu depodan klonluyorsanız değerlerin eşleştiğinden emin olun):
- küme kimliği: "
vector-cluster" - şifre: "
alloydb" - PostgreSQL 15 uyumlu
- Bölge: "
us-central1" - Ağ iletişimi: "
default"
- Varsayılan ağı seçtiğinizde aşağıdaki gibi bir ekran görürsünüz. BAĞLANTI KURUN'u seçin.
- Buradan "Otomatik olarak atanmış bir IP aralığı kullan"ı seçip Devam'ı tıklayın. Bilgileri inceledikten sonra BAĞLANTI OLUŞTURUN'u seçin.
- Ağınız ayarlandıktan sonra kümenizi oluşturmaya devam edebilirsiniz. Kümenin kurulumunu aşağıda gösterildiği gibi tamamlamak için OLUŞTUR'u tıklayın:
Örnek kimliğini "
vector-instance"
.
Küme oluşturmanın yaklaşık 10 dakika süreceğini unutmayın. Başarılı olduğunda, az önce oluşturduğunuz kümenize genel bakışı gösteren bir ekran görürsünüz.
4. Veri kullanımı
Şimdi sıra mağazayla ilgili verileri içeren bir tablo eklemeye geldi. AlloyDB'ye gidin, birincil kümeyi ve ardından AlloyDB Studio'yu seçin:
Örneğinizin oluşturulma işleminin tamamlanmasını beklemeniz gerekebilir. İşlem tamamlandıktan sonra, küme oluşturma sırasında oluşturduğunuz kimlik bilgilerini kullanarak AlloyDB'de oturum açın. PostgreSQL'de kimlik doğrulaması için aşağıdaki verileri kullanın:
- Kullanıcı adı: "
postgres" - Veritabanı : "
postgres" - Şifre: "
alloydb"
AlloyDB Studio'da kimlik doğrulaması başarıyla tamamlandıktan sonra Editor'a SQL komutları girilebilir. Son pencerenin sağındaki artı işaretini kullanarak birden fazla Düzenleyici penceresi ekleyebilirsiniz.
Gerektiğinde Çalıştır, Biçim ve Temizle seçeneklerini kullanarak AlloyDB komutlarını düzenleyici pencerelerine girebilirsiniz.
Uzantıları Etkinleştir
Bu uygulamayı oluşturmak için pgvector ve google_ml_integration uzantılarını kullanacağız. pgvector uzantısı, vektör yerleştirmeleri depolamanıza ve aramanıza olanak tanır. google_ml_integration uzantısı, SQL'de tahmin almak amacıyla Vertex AI tahmin uç noktalarına erişirken kullandığınız işlevleri sunar. Aşağıdaki DDL'leri çalıştırarak bu uzantıları etkinleştirin:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Veritabanınızda etkinleştirilen uzantıları kontrol etmek isterseniz şu SQL komutunu çalıştırın:
select extname, extversion from pg_extension;
Tablo oluşturma
Aşağıdaki DDL ifadesini kullanarak bir tablo oluşturun:
CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;
Yukarıdaki komut başarıyla yürütüldüğünde tabloyu veritabanında görüntüleyebilmeniz gerekir.
Verileri besleme
Bu laboratuvara özel olarak, bu SQL dosyasında yaklaşık 72 kaydın test verileri bulunmaktadır. id, name, description, quantity, price, image_url alanlarını içerir. Diğer alanlar laboratuvarın ilerleyen bölümlerinde doldurulacaktır.
Buradan satırları/insert ifadelerini kopyalayıp bu satırları boş bir düzenleyici sekmesine yapıştırıp ÇALIŞTIR'ı seçin.
Tablo içeriğini görmek için giysiler adlı tabloyu görene kadar Gezgin bölümünü genişletin. Tabloyu sorgulama seçeneğini görmek için üç nokta işaretini (⋮) seçin. Yeni bir Editor sekmesinde bir SELECT ifadesi açılır.
İzin Ver
postgres kullanıcısına embedding işlevinde yürütme hakları vermek için aşağıdaki ifadeyi çalıştırın:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
AlloyDB hizmet hesabına Vertex AI Kullanıcı ROLÜ atama
Cloud Shell terminaline gidip aşağıdaki komutu verin:
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. Bağlam için yerleştirmeler oluşturun.
Bilgisayarların sayıları işlemek, metinleri işlemekten çok daha kolaydır. Yerleştirme sistemi, metni vektör yerleştirme adı verilen bir kayan nokta dizisine dönüştürür. Bu sayı, metnin nasıl yazıldığından ve hangi dilde kullanıldığına bakılmaksızın metni temsil etmelidir.
Örneğin, deniz kıyısındaki bir yer "suda", "sahil", "odanızdan okyanusa doğru yürüyün", "sur la mer", "vа кереке акеала" vb. olarak adlandırılabilir. Bu terimlerin tümü farklı görünse de anlamları veya makine öğrenimi terminolojisinde yerleştirilmiş öğeler birbirine çok yakın olmalıdır.
Veriler ve bağlamlar hazır olduğuna göre artık SQL'i çalıştırıp embedding alanındaki ürün açıklamasının yerleştirmelerini tabloya ekleyeceğiz. Kullanabileceğiniz çeşitli yerleştirme modelleri vardır. Vertex AI'dan text-embedding-005 kullanıyoruz. Proje boyunca aynı yerleştirme modelini kullandığınızdan emin olun.
Not: Eski bir Google Cloud projesi kullanıyorsanız metin yerleştirme modelinin eski sürümlerini (textembedding-gecko gibi) kullanmaya devam etmeniz gerekebilir.
AlloyDB Studio sekmesine dönün ve şu DML'yi yazın:
UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);
Yerleştirilmiş bazı öğeleri görmek için toys tablosuna tekrar bakın. Değişiklikleri görmek için SELECT ifadesini yeniden çalıştırdığınızdan emin olun.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Bu, aşağıda gösterildiği gibi oyuncak açıklaması için, kayan noktalı bir dizi gibi görünen yerleştirme vektörünü döndürmelidir:
Not: Ücretsiz katman kapsamında yeni oluşturulan Google Cloud projelerinde, Yerleştirme modellerinde saniye başına izin verilen yerleştirme isteği sayısı söz konusu olduğunda kota sorunlarıyla karşılaşabilir. Kimlik için bir filtre sorgusu kullanmanızı ve ardından yerleştirmeyi oluştururken seçerek 1-5 arası kayıt seçmenizi öneririz.
6. Vektör araması yap
Artık tablo, veriler ve yerleştirmeler hazır olduğuna göre, kullanıcı arama metni için gerçek zamanlı vektör araması yapalım.
Kullanıcının şu soruyu sorduğunu varsayalım:
"I want a white plush teddy bear toy with a floral pattern."
Aşağıdaki sorguyu çalıştırarak bununla ilgili eşleşmeleri bulabilirsiniz:
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;
Bu sorguyu ayrıntılı olarak inceleyelim:
Bu sorguda
- Kullanıcının arama metni: "
I want a white plush teddy bear toy with a floral pattern." text-embedding-005modeli kullanarak bunu,embedding()yönteminde yerleştirmelere dönüştürüyoruz. Tablodaki tüm öğelere yerleştirme işlevi uyguladığımız son adımdan sonra bu adım size tanıdık gelecektir.- "
<=>", COSINE BENZERLİK mesafe yönteminin kullanımını gösterir. Tüm benzerlik ölçülerini pgvector belgelerinde bulabilirsiniz. - Yerleştirme yönteminin sonucunu, veritabanında depolanan vektörlerle uyumlu hale getirmek için vektör türüne dönüştürüyoruz.
- SINIR 5, arama metni için en yakın 5 komşuyu ayıklamak istediğimizi gösterir.
Sonuç şuna benzer:
Sonuçlarınızda gözlemleyebileceğiniz gibi, eşleşmeler arama metnine oldukça yakındır. Sonuçların nasıl değiştiğini görmek için metni değiştirmeyi deneyin.
7. AlloyDB'yi Araç Kutusu Etkileşimi için hazırlama
Araç Kutusu kurulumuna hazırlanırken yeni aracın veritabanına erişebilmesi için AlloyDB örneğimizde genel IP bağlantısını etkinleştirelim.
- AlloyDB örneğinize gidin, DÜZENLE'yi tıklayın ve "Edit birincil örneği düzenle" sayfasına gidin.
- Genel IP bağlantısı bölümüne gidin, Genel IP'yi etkinleştir onay kutusunu işaretleyin ve Cloud Shell makinenizin IP adresini girin.
- Cloud Shell makinenizin IP'sini almak için Cloud Shell Terminal'e gidin ve ifconfig yazın. Sonuçtan eth0 inet adresini belirleyin ve son 2 basamağı 0.0 yerine maske boyutu "/16" olarak değiştirin. Örneğin, "XX.XX.0.0/16" şeklinde görünür, burada XX sayı sayıdır.
- Bu IP'yi, örnek düzenleme sayfasının Yetkili harici ağlar "Ağlar" metin kutusuna yapıştırın.
- İşlem tamamlandığında ÖRNEĞİ GÜNCELLE'yi tıklayın.
İşlemin tamamlanması birkaç dakika sürer.
8. Veritabanları Yükleme için MCP Araç Kutusu
- Araç ayrıntılarını saklamak için bir proje klasörü oluşturabilirsiniz. Bu örnekte, oyuncak mağazası verileri üzerinde çalıştığımız için "toystore" adlı bir klasör oluşturup bu klasörün içine gidelim. Cloud Shell Terminal'e gidin ve projenizin seçili olduğundan ve terminalin isteminde gösterildiğinden emin olun. Cloud Shell terminalinizden aşağıdaki komutu çalıştırın:
mkdir toystore
cd toystore
- Araç kutusunu yeni klasörünüze indirip yüklemek için aşağıdaki komutu çalıştırın:
# 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
- Cloud Shell Düzenleyici'ye geçin. Yeni oluşturulan "toystore" klasörünü genişletin ve Tools.yaml adlı yeni bir dosya oluşturun. Aşağıdaki içeriği kopyalayın. YOUR_PROJECT_ID değerini değiştirin ve diğer tüm bağlantı ayrıntılarının doğru olup olmadığını kontrol edin.
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;
Bu araçta, kullanıcının arama metniyle (özel oyuncak açıklaması) en yakın eşleşmeyi bulup fiyatı iade ediyoruz. İsterseniz en iyi eşleşen 5 oyuncağın ortalama fiyatını da bulabilirsiniz:
select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) fiyat olarak;
Araç tanımını tamamladınız.
Tools.yaml dosyanızı yapılandırma hakkında daha fazla bilgi edinmek için bu dokümanlara bakın.
- Cloud Shell terminaline geçin ve aşağıdaki komutu girerek araç kutusu sunucusunu araç yapılandırmanızla başlatın:
./toolbox --tools_file "tools.yaml"
- Şimdi sunucuyu bulutta web önizleme modunda açarsanız araç kutusu sunucusunun
get-toy-price.adlı yeni aracınızla çalıştığını görebilirsiniz.
9. Veritabanları için MCP Araç Kutusu'nun Cloud Run Dağıtımı
Bu aracı gerçekten kullanabilmeniz için aracı Cloud Run'a dağıtalım.
- "Cloud Run'a dağıt" bölümünün altında 3. noktadaki
gcloud run deploy toolboxkomutuna ulaşana kadar bu sayfadaki talimatları tek tek uygulayın. VPC ağ yöntemi kullanırken geçerli olan ikinci seçeneğe değil, ilk seçeneğe ihtiyacınız vardır. - Başarıyla dağıtıldıktan sonra Araç Kutusu sunucunuzun Cloud Run dağıtılmış uç noktasını alırsınız. CURL komutuyla test edin.
İpuçları:
Bu sayfadaki talimatları dikkatli bir şekilde uygulayın ve talimatları gözden geçirin.
Yeni dağıtılan aracınızı aracı uygulamanızda kullanmaya hazırsınız.
10. Uygulamanızı Veritabanları için MCP Araç Kutusu ile Bağlama
Bu bölümde, uygulamanızın ihtiyaçlarıyla etkileşim kurmak ve yanıt almak için aracınızı test etmek amacıyla küçük bir uygulama geliştireceğiz.
- Google Colab'e gidip yeni bir not defteri açın.
- Not defterinizde aşağıdaki komutu çalıştırın
!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)
- Sonuç şöyle olmalıdır:
Bu, toolbox-langchain. araç setini kullanan bir Python uygulamasında açıkça çağrılan araçtır
- Bu aracı kullanmak ve LangGraph ile entegre bir uygulama içindeki bir aracıya bağlamak isterseniz,
langgrapharaç setini kullanarak bunu kolayca yapabilirsiniz. - Bunun için kod snippet'lerine bakın.
11. Cloud'a taşıyın!
Bu Python kod snippet'ini bir Cloud Run Functions'a sarmalayarak sunucusuz hale getirelim.
- Bu kaynağı Cloud Functions'a aktarmak için kod deposu klasöründen kaynağı kopyalayın.
- Cloud Run Functions konsoluna gidin ve İŞLEV OLUŞTUR'u tıklayın.
- Demo uygulama için kimliği doğrulanmamış tutun ve sonraki sayfada Python 3.11 çalışma zamanını seçin.
- 1. adımda paylaşılan kaynak depodan
main.pyverequirements.txtdosyalarını kopyalayıp ilgili dosyaları yapıştırın. - main.py dosyasındaki sunucu URL'sini sunucu URL'nizle değiştirin.
- İşlevi dağıttığınızda, oyuncak mağazası web uygulamasında fiyat tahmin aracına erişmek için bir REST uç noktası oluşturmuş olursunuz.
- Uç noktanız şu şekilde görünmelidir:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- TEST sekmesine gidip istek girişi olarak şunu girerek işlevi doğrudan Cloud Functions konsolunda test edebilirsiniz:
{
"search": "White plush toy"
}
- İŞLEVİ TEST ET'i tıklayın veya kullanmayı tercih ettiğiniz şekilde Cloud Shell Terminal'de çalıştırın. Sonucu sağda "Çıkış" başlığının altında görürsünüz:
12. Tebrikler
Tebrikler! Aracı uygulamanızı oluşturmanıza yardımcı olmak için veritabanları, platformlar ve üretken yapay zeka düzenleme çerçeveleri arasında etkileşime geçebilen sağlam ve tam anlamıyla modüler bir aracı başarıyla oluşturdunuz.