AlloyDB'de Üretken Yapay Zeka ve Aracıik Uygulamalarınız İçin Veritabanları İçin MCP Araç Kutusu Yükleme ve Ayarlama

1. Genel Bakış

Veritabanları için MCP Araç Kutusu, Google'ın açık kaynaklı bir sunucusudur. Bu sunucu, veritabanlarıyla etkileşim kurmak için üretken yapay zeka araçları oluşturmayı kolaylaştırır. Bağlantı havuzu oluşturma ve kimlik doğrulama gibi karmaşık işlemleri yöneterek araçları daha kolay, daha hızlı ve daha güvenli bir şekilde geliştirmenizi sağlar. Bu araç, temsilcilerinizin veritabanınızdaki verilere erişmesine olanak tanıyan ü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 daha 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 dağıtın.

Daha iyi performans: Bağlantı havuzu oluşturma ve kimlik doğrulama 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: OpenTelemetry için yerleşik destekle birlikte kullanıma hazır metrikler ve izleme.

Araç kutusu, uygulamanızın düzenleme ç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 sağlayarak araçlarınızın yönetimini basitleştirir. Böylece, araçları temsilciler ve uygulamalar arasında paylaşabilir ve uygulamanızı yeniden dağıtmak zorunda kalmadan bu araçları güncelleyebilirsiniz.

Ne oluşturacaksınız?

Bu laboratuvar kapsamında, aracınızdan veya üretken yapay zeka uygulamasından çağrılabilen basit bir veritabanı (AlloyDB) sorgusu gerçekleştirmek için bir araç kullanan bir uygulama oluşturacaksınız. Bunun için

1. MCP Toolbox for Databases'i yükleme
2. Araç Kutusu sunucusunda aracı (AlloyDB'de bir görevi yerine getirmek için tasarlanmıştır) ayarlayın.
3. Veritabanları için MCP Araç Kutusu'nu Cloud Run'da dağıtma
4. Aracı, dağıtılan Cloud Run uç noktasıyla test edin.
5. Araç kutusunu çağırmak için Cloud Run işlevini oluşturun.

Şartlar

• Chrome veya Firefox gibi bir tarayıcı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi (sonraki bölümdeki adımlar).

2. Başlamadan önce

Proje oluşturma

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.
3. 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.

4. 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 edin:

gcloud auth list

5. 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

6. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:

gcloud config set project <YOUR_PROJECT_ID>

7. Cloud Shell terminalinizde aşağıdaki komutları tek tek çalıştırarak gerekli API'leri etkinleştirin:

Aşağıdaki komutları çalıştırmak için tek bir komut da vardır 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ırda bir tane olacak şekilde ayrılır.

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 işlem yapmaktır.

Herhangi bir API atlanırsa 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 tutmak için veritabanı olarak AlloyDB'yi kullanacağız. Veritabanları ve günlükler gibi tüm kaynakları tutmak için kümeler kullanılır. Her kümede, verilere erişim noktası sağlayan bir birincil örnek bulunur. Tablolar gerçek verileri içerir.

E-ticaret veri kümesinin yükleneceği bir AlloyDB kümesi, örneği ve tablosu oluşturalım.

Küme ve örnek oluşturma

1. Cloud Console'da AlloyDB sayfasına gidin.

Cloud Console'daki çoğu sayfayı bulmanın kolay bir yolu, konsolun arama çubuğunu kullanarak arama yapmaktır.

2. Bu sayfada KÜME OLUŞTUR'u seçin:

3. Aşağıdaki gibi 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"
• password: "alloydb"
• PostgreSQL 15 ile uyumlu
• Bölge: "us-central1"
• Ağ: "default"

4. Varsayılan ağı seçtiğinizde aşağıdaki gibi bir ekran görürsünüz. BAĞLANTIYI AYARLA'yı seçin.
   
5. Buradan "Otomatik olarak atanmış bir IP aralığı kullan"ı ve Devam'ı seçin. Bilgileri inceledikten sonra BAĞLANTI OLUŞTUR'u seçin.
6. Ağınız kurulduktan sonra kümenizi oluşturmaya devam edebilirsiniz. Aşağıda gösterildiği gibi küme kurulumunu tamamlamak için KÜME OLUŞTUR'u tıklayın:

Örnek kimliğini "

vector-instance"

.

Küme oluşturma işleminin yaklaşık 10 dakika süreceğini unutmayın. İşlem başarılı olduğunda, yeni oluşturduğunuz kümenizin genel görünümünü gösteren bir ekran görürsünüz.

4. Veri kullanımı

Şimdi de mağazayla ilgili verilerin bulunduğu bir tablo ekleme zamanı. AlloyDB'ye gidin, birincil kümeyi ve ardından AlloyDB Studio'yu seçin:

Örneğinizin oluşturulmasının 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ı yapmak için aşağıdaki verileri kullanın:

• Kullanıcı adı : "postgres"
• Veritabanı : "postgres"
• Şifre : "alloydb"

AlloyDB Studio'da kimliğinizi başarıyla doğruladıktan sonra Düzenleyici'ye SQL komutları girebilirsiniz. Son pencerenin sağındaki artı işaretini kullanarak birden fazla Düzenleyici penceresi ekleyebilirsiniz.

Gerekirse Çalıştır, Biçimlendir ve Temizle seçeneklerini kullanarak AlloyDB için komutları düzenleyici pencerelerine girebilirsiniz.

Uzantıları etkinleştirme

Bu uygulamayı oluşturmak için pgvector ve google_ml_integration uzantılarını kullanacağız. pgvector uzantısı, vektör yerleştirmelerini depolamanıza ve aramanıza olanak tanır. google_ml_integration uzantısı, SQL'de tahmin almak için Vertex AI tahmin uç noktalarına erişmek üzere kullandığınız işlevleri sağlar. 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 istiyorsanız ş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 tablonun veritabanında görüntülenebilmesi gerekir.

Veri alma

Bu laboratuvar için SQL dosyasında yaklaşık 72 kayıttan oluşan 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.

Satırları/ekleme ifadelerini oradan kopyalayın, ardından bu satırları boş bir düzenleyici sekmesine yapıştırıp ÇALIŞTIR'ı seçin.

Tablo içeriklerini görmek için Gezgin bölümünü, giysiler adlı tabloyu görene kadar genişletin. Tabloya sorgu gönderme seçeneğini görmek için üç nokta simgesini (⋮) seçin. SELECT ifadesi yeni bir Düzenleyici sekmesinde açılır.

İzin Ver

embedding işlevinde postgres kullanıcısına 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ısı ROLÜ'nü verme

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şturma

Bilgisayarların sayıları işlemesi, metinleri işlemesinden çok daha kolaydır. Bir yerleştirme sistemi, metni, nasıl ifade edildiğine veya hangi dili kullandığına bakılmaksızın metni temsil etmesi gereken vektör yerleştirmeleri adı verilen bir dizi kayan nokta sayısına dönüştürür.

Örneğin, deniz kenarındaki bir yer "denize sıfır", "sahilde", "odanızdan okyanusa yürüyerek gidebilirsiniz", "sur la mer", "на берегу океана" vb. olarak adlandırılabilir. Bu terimlerin hepsi farklı görünse de anlamsal anlamları veya makine öğrenimi terminolojisindeki yerleştirmeleri birbirine çok yakın olmalıdır.

Veriler ve bağlam hazır olduğuna göre, ürün açıklamasının yerleştirmelerini embedding alanındaki tabloya eklemek için SQL'i çalıştıracağız. 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 textembedding-gecko gibi metin yerleştirme modelinin eski sürümlerini kullanmaya devam etmeniz gerekebilir.

AlloyDB Studio sekmesine dönün ve aşağıdaki DML'yi yazın:

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

Bazı yerleştirmeleri 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 işlem, oyuncak açıklaması için aşağıdaki gibi bir kayan nokta dizisi olan yerleştirme vektörünü döndürmelidir:

Not: Ücretsiz katman kapsamında yeni oluşturulan Google Cloud projeleri, saniye başına yerleştirme modellerine izin verilen yerleştirme isteği sayısı konusunda kota sorunlarıyla karşılaşabilir. Yerleştirme oluştururken kimlik için bir filtre sorgusu kullanmanızı ve ardından 1-5 kayıt seçmenizi öneririz.

6. Vektör araması yapma

Tablo, veriler ve yerleştirmeler hazır olduğuna göre artık kullanıcı arama metni için anlık vektör aramasını gerçekleştirebiliriz.

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,

1. Kullanıcının arama metni: "I want a white plush teddy bear toy with a floral pattern."
2. embedding() yönteminde text-embedding-005 modeli kullanılarak yerleştirmelere dönüştürülüyor. Bu adım, son adımda yerleştirme işlevini tablodaki tüm öğelere uyguladığımız için tanıdık gelecektir.
3. "<=>", KOSİNÜS BENZERLİĞİ uzaklık yönteminin kullanımını gösterir. Kullanılabilen tüm benzerlik ölçülerini pgvector dokümanlarında bulabilirsiniz.
4. 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.
5. LIMIT 5, arama metni için en yakın 5 komşuyu çıkarmak istediğimizi gösterir.

Sonuç şu şekilde görünür:

Sonuçlarınızda da görebileceğ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 Toolbox etkileşimi için hazırlama

Toolbox'ı kurmaya hazırlanırken yeni aracın veritabanına erişebilmesi için AlloyDB örneğimizde herkese açık IP bağlantısını etkinleştirelim.

1. AlloyDB örneğinize gidin, DÜZENLE'yi tıklayın ve birincil örneği düzenleme sayfasına yönlendirilin.
2. Herkese açık IP bağlantısı bölümüne gidin, Herkese açık IP'yi etkinleştir onay kutusunu işaretleyin ve Cloud Shell makinenizin IP adresini girin.
3. Cloud Shell makinenizin IP'sini almak için Cloud Shell terminaline gidip ifconfig yazın. Sonuçtan eth0 inet adresini belirleyin ve son 2 basamağı "/16" maske boyutuyla 0.0 olarak değiştirin. Örneğin, "XX.XX.0.0/16" şeklinde görünür. Burada XX sayılardır.
4. Bu IP'yi, örnek düzenleme sayfasının Yetkili harici ağlar "Ağlar" metin kutusuna yapıştırın.

5. İşlem tamamlandığında ÖRNEĞİ GÜNCELLE'yi tıklayın.

Bu işlemin tamamlanması birkaç dakika sürer.

8. Veritabanları için MCP Araç Kutusu'nu yükleme

1. Araç ayrıntılarını depolamak 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öre gidelim. Cloud Shell Terminali'ne gidin ve projenizin seçili olduğundan ve terminal isteminde gösterildiğinden emin olun. Cloud Shell terminalinizde aşağıdaki komutu çalıştırın:

mkdir toystore

cd toystore

2. 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

3. 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 yerine kendi proje kimliğinizi yazın 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 metnine (özel oyuncak açıklaması) en yakın eşleşmeyi bulup fiyatını döndürüyoruz. Ayrıca, en yakın eşleşen ilk 5 oyuncağın ortalama fiyatını bulmak için de değiştirebilirsiniz:

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;

Araç tanımını tamamladınız.

tools.yaml dosyanızı yapılandırma hakkında daha fazla bilgi için bu belgeye bakın.

4. Cloud Shell terminaline geçin ve araç kutusu sunucusunu araç yapılandırmanızla başlatmak için aşağıdaki komutu girin:

./toolbox --tools_file "tools.yaml"

5. Artık sunucuyu bulutta web önizleme modunda açarsanız get-toy-price. adlı yeni aracınızla birlikte Toolbox sunucusunun çalışır durumda olduğunu görebilirsiniz.

9. Veritabanları için MCP Toolbox'un Cloud Run'a dağıtımı

Bu aracı gerçek hayatta kullanabilmeniz için Cloud Run'a dağıtalım.

1. "Cloud Run'a dağıtma" bölümündeki 3. noktada yer alan gcloud run deploy toolbox komutuna ulaşana kadar bu sayfadaki talimatları tek tek uygulayın. VPC ağı yöntemi kullandığınızda geçerli olan ikinci seçeneği değil, ilk seçeneği kullanmanız gerekir.
2. Başarıyla dağıtıldıktan sonra, araç kutusu sunucunuzun Cloud Run dağıtılmış uç noktasını alırsınız. Bir CURL komutuyla test edin.

İpuçları:

Sayfadaki talimatları dikkatlice uygulayın ve hiçbir adımı atlamayın.

Yeni dağıtılan aracınızı agentic uygulamanızda kullanmaya hazırsınız.

10. Uygulamanızı veritabanları için MCP Toolbox'a bağlama

Bu bölümde, uygulamanın ihtiyaçlarıyla etkileşim kurmak ve yanıt almak için aracınızı test etmenize olanak tanıyan küçük bir uygulama oluşturacağız.

1. Google Colab'e gidin ve yeni bir not defteri açın.
2. Not defterinizde aşağıdakileri ç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)

3. Sonuç şu şekilde olmalıdır:

Bu, araç kitini kullanan bir Python uygulamasında açıkça çağrılan araçtır. toolbox-langchain.

4. Bu aracı kullanmak ve LangGraph ile entegre bir uygulamadaki bir aracıya bağlamak istiyorsanız bunu langgraph araç setiyle kolayca yapabilirsiniz.
5. Bunun için kod snippet'lerine bakın.

11. Take it to Cloud!!!

Bu Python kod snippet'ini sunucusuz hale getirmek için Cloud Run Functions'a saralım.

1. Bunu Cloud Functions'a aktarmak için kod deposu klasöründen kaynağı kopyalayın.
2. Cloud Run Functions konsoluna gidip CREATE FUNCTION'ı (İşlev Oluştur) tıklayın.
3. Demo uygulaması için kimlik doğrulama yapmayın ve sonraki sayfada Python 3.11 çalışma zamanını seçin.
4. 1. adımda paylaşılan kaynak depodaki main.py ve requirements.txt dosyalarını kopyalayıp ilgili dosyalara yapıştırın.
5. main.py dosyasındaki sunucu URL'sini kendi sunucu URL'nizle değiştirin.
6. İşlevi dağıtın. Böylece, oyuncak mağazası web uygulamasında erişilebilecek fiyat tahmini aracı için bir REST uç noktası elde edersiniz.
7. Uç noktanız aşağıdaki gibi görünmelidir:

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

2. TESTING sekmesine gidip istek girişi olarak aşağıdakileri girerek işlevi doğrudan Cloud Functions konsolunda test edebilirsiniz:

{

           "search": "White plush toy"

}

3. TEST THE FUNCTION'ı (İŞLEVİ TEST ET) tıklayın veya Cloud Shell Terminal'de kullanmayı tercih ettiğiniz şeyi çalıştırın. Sonucu sağ tarafta "Çıkış" başlığı altında görmeniz gerekir:

12. Tebrikler

Tebrikler! Temsilci tabanlı uygulamanızı oluşturmanıza yardımcı olmak için veritabanları, platformlar ve üretken yapay zeka düzenleme çerçeveleri arasında etkileşim kurabilen sağlam ve gerçekten modüler bir aracı başarıyla oluşturdunuz.