AlloyDB'de HTAP ile ajan tabanlı sisteminizi güçlendirme

1. Genel Bakış

1. Bölüm'de, Knowledge Catalog ve DataScan'i kullanarak karmaşık ve yapılandırılmamış PDF'leri BigQuery'de temiz, akıllı ve yapılandırılmış tablolara dönüştürmeyi başardık. Artık güçlü bir veri ambarımız var. 2. bölümde, AlloyDB'yi işlemsel omurgamız olarak ayarladık ve BigQuery tablolarımızı AlloyDB'ye birleştirerek tek bir baytı bile kopyalamadan birleşik bir veri katmanı oluşturduk.

Bugün beyni inşa ediyoruz. Soruları yanıtlamak, alerjenleri kontrol etmek ve canlı siparişleri işlemek için bu veri katmanının üzerinde çalışan "FroyoOS Store Manager" adlı çok agentlı bir uygulama oluşturuyoruz.

Zorluk: Yapay zekayı temsilcinizden ayırma

Veritabanlarıyla iletişim kurması gereken bir yapay zeka temsilcisi oluştururken en yaygın anti-pattern, verileri ve yapay zeka mantığını doğrudan Python uygulamanıza zorla yerleştirmektir. Bu durum, veri mimariniz büyüdükçe uygulamanızı kırılgan, güvensiz ve bakımının inanılmaz derecede zor olmasına neden olur.

Bu sorunu çözmek için Model Context Protocol (MCP) Toolbox'ı kullanıyoruz. MCP Araç Kutusu, birleştirilmiş veri soyutlama katmanımız olarak işlev görür. Veritabanı işlemlerimizi basit bir tools.yaml dosyasında bildirimli olarak tanımlıyoruz. Bu araç kutusunu Google Cloud Run'da güvenli ve sunucusuz bir uç nokta olarak dağıtıyoruz. Yapay Zeka Temsilcimiz bu uç noktaya bağlanıp "place_order" aracını çalıştırır.

***Önemli: 2. bölümü henüz tamamlamadıysanız şimdi tamamlamanız gerekir. Bu bölümde oluşturulan ve burada bu uygulamada kullanılan bazı verilerimiz var.

HTAP'nin Gücü

Aracı oluşturmaya başlamadan önce bu yayının başlığında neden özellikle HTAP'nin (Hibrit İşlemsel/Analitik İşleme) vurgulandığını konuşalım.

Geleneksel bir mimaride, bir yapay zeka aracısının canlı bir kullanıcı siparişini (işlemsel OLTP iş yükü) işlemesi ve binlerce karmaşık içerik eşlemesini (analitik OLAP iş yükü) çapraz referanslaması gerekiyorsa Python uygulamanızın tamamen farklı iki veritabanına bağlantıları yönetmesi gerekirdi. Bu durum, ciddi gecikmeye, güvenlik ek yüküne ve kırılgan durum yönetimine neden olur.

BigQuery veri ambarımızı doğrudan PostgreSQL'e yerel olarak birleştirerek AlloyDB'yi bir HTAP güç merkezine dönüştürdük. Bu HTAP mimarisi sayesinde yapay zeka aracımız bugün yalnızca bir veritabanı uç noktasıyla iletişim kuruyor. Tek bir veri baytını bile kopyalamadan, canlı işlemleri live_orders tablosuna ekleyebilir ve birleşik BigQuery froyo_data veri kümesine karşı aynı anda ağır analiz taramaları çalıştırabilir. Bu motoru yapay zekamıza nasıl sunduğumuza bakalım.

Oluşturmaya başlayalım.

Neler öğreneceksiniz?

• Tek bir tıklamayla AlloyDB kümesi, örneği ve ağ iletişimi nasıl ayarlanır?
• Federasyona hazırlanmak için uzantıyı ayarlama
• BigQuery'den AlloyDB'ye federasyon oluşturma
• Deneyin

Şartlar

• Chrome veya Firefox gibi bir tarayıcı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• SQL hakkında temel düzeyde bilgi sahibi olmanız gerekir.

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.

Bu laboratuvarda, faturalandırma hesabınız olmasa bile deneyebileceğiniz sınırlı sayıda özellik vardır. Bu kapasitede uygulamalı olarak keşfetmek istiyorsanız "FATURALANDIRMA HESABI YOK MU?" nitelikleri kapsamında geçerli notlarınız vardır. Bunlara dikkat edin.

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ında 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ğrulandığını ve projenin proje kimliğinize ayarlandığı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. Kimlik doğrulamak istiyorsanız

gcloud auth login

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

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>

8. Gerekli API'leri etkinleştirin: Gerekli tüm API'leri etkinleştirmek için şu komutu çalıştırın:

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com

Dikkat Edilmesi Gerekenler ve Sorun Giderme

"Hayalet Proje" Sendromu	gcloud config set project komutunu çalıştırdınız ancak Console kullanıcı arayüzünde aslında farklı bir projeye bakıyorsunuz. Sol üstteki açılır listede proje kimliğini kontrol edin.
Faturalandırma Barikatı	Projeyi etkinleştirdiniz ancak faturalandırma hesabını unuttunuz. AlloyDB yüksek performanslı bir motordur. "Yakıt deposu" (faturalandırma) boşsa çalışmaz.
API Yayılımı Gecikmesi	"API'leri etkinleştir"i tıkladınız ancak komut satırında hâlâ Service Not Enabled yazıyor. 60 saniye bekleyin. Bulutun nöronlarını uyandırması biraz zaman alabilir.
Kota Quags	Yeni bir deneme hesabı kullanıyorsanız AlloyDB örnekleri için bölgesel kotaya ulaşabilirsiniz. us-central1 başarısız olursa us-east1'ı deneyin.

3. Verileri hazırlama

Yapılandırılmamış PDF'lerden ayıkladığımız yapılandırılmış verilerin BigQuery'de kullanılabilir olduğundan ve BigQuery verilerinin AlloyDB federasyonunun oluşturulup test edildiğinden emin olun. Bu adımları tamamlamadıysanız buradan ve buradan 1. ve 2. bölümdeki basit adımları uygulamanın tam zamanı.

Not:

Bu codelab'i deniyorsanız 2. bölümdeki temizleme adımını (küme ve örnek silme adımı) uygulamamalısınız. Çünkü burada gösterilen yapay zeka destekli sistemimiz için AlloyDB düzenlemesine ihtiyacımız var.

2. bölümde oluşturduğumuz verilere ek olarak AlloyDB örneğinde bir tablo daha oluşturmamız gerekiyor. Bağlantıyı kullanarak AlloyDB Studio'ya gidin:

https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio

Farklı bir küme kullanıyorsanız yukarıdaki bağlantıda küme adını değiştirin.

AlloyDB Studio'da yeni bir Sorgu Düzenleyici sekmesinde aşağıdaki ifadeyi çalıştırın:

CREATE TABLE live_orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100),
    product_id VARCHAR(100),
    quantity INT,
    order_status VARCHAR(50) DEFAULT 'Pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Bu işlem, veritabanınızda live_orders tablosunu oluşturmalıdır.

4. Soyutlamayı tanımlama (tools.yaml)

İlk olarak, veritabanı işlemlerimizi resmi olarak kaydederiz. Ajanımızın hem işlemsel hem de analitik verileri (BigQuery federasyonundan alınan analitik veriler) içeren AlloyDB ile nasıl etkileşim kurduğunu tanımlayan bir tools.yaml dosyası oluştururuz.

1. Cloud Shell terminalinize gidin. Düzenleyici moduna geçin.
2. Kök dizininizde "froyo-agent" adlı yeni bir klasör oluşturun.
3. Klasörün içinde bir tools.yaml dosyası oluşturun ve aşağıdaki içeriği yapıştırın (proje, küme, örnek ve şifre için kendi değerlerinizle değiştirin):

# tools.yaml
sources:
    alloydb-source:
        kind: "alloydb-postgres"
        project: "*******"
        region: "us-central1"
        cluster: "my-alloydb-cluster"
        instance: "my-primary-inst"
        database: "postgres"
        user: "postgres"
        password: "*******"
        ipType: "private"


tools:
  check_allergens:
    kind: postgres-sql
    source: alloydb-source
    description: Queries the federated BigQuery tables to find allergens for a product.
    statement: |
      SELECT a.allergen_name
      FROM consistsof c
      INNER JOIN product p ON c.product_id = p.product_id
      INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
      INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
      WHERE UPPER(p.product_name) LIKE UPPER($1)
    parameters:
      - name: product_name
        type: string
        description: The name of the product to check. (e.g., '%Midnight%')


  place_order:
    kind: postgres-sql
    source: alloydb-source
    description: Inserts a new live transaction into the native AlloyDB orders table.
    statement: |
      INSERT INTO live_orders (customer_name, product_id, quantity)
      VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
    parameters:
      - name: customer_name
        type: string
        description: The name of the customer placing the order.
      - name: product_name
        type: string
        description: The name of the product being ordered.
      - name: quantity
        type: integer
        description: The quantity of the product being ordered.


toolsets:
  alloydb_tools:
    - check_allergens
    - place_order

Temsilci özelliklerimizi 2 araçla sınırladık: alerjenleri kontrol etme ve sipariş verme.

5. Araç kutusunu Cloud Run'a dağıtma

Bunu uygulamamızda kullanabilmek için gcloud CLI'yı kullanarak araç kutusunu güvenli bir şekilde dağıtırız. Bu, soyutlama katmanı uç noktamızı oluşturur.

4. Cloud Shell Terminali'ne geçin ve şu komutu çalıştırarak çalışma dizinine gidin:

cd froyo-agent

5. tools.yaml dosyasını "tools-froyo" adlı bir sır olarak kaydedin:

gcloud secrets create tools-froyo --data-file=tools.yaml

6. MCP Toolbox container'ını Cloud Run'a dağıtma

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy toolbox-froyo \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools-froyo:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network easy-alloydb-vpc \
    --subnet easy-alloydb-subnet \
    --allow-unauthenticated \
    --vpc-egress private-ranges-only

2. Bölümdeki codelab'de yapılandırdığımız değerlerden farklı değerler kullandıysanız "network" ve "subnet" değerlerinin değiştirilmesi gerekir.

7. Elde edilen Cloud Run URL'sini (ör. https://toolbox-froyo-xxx.run.app) not edin.

6. Ajan tabanlı arka uç (app.py)

Veritabanımız soyutlandığı için Python kodumuz tamamen düzenleme ve muhakemeye odaklanabilir.

Flask ile birlikte Agent Development Kit (ADK)'yı kullanıyoruz. ADK, kurumsal düzeyde oturum belleği (InMemorySessionService) sağlar. Bu sayede aracımız, görüşmenin bağlamını hatırlar. Araçlarımızı Cloud Run'dan sorunsuz bir şekilde çekmek için ToolboxSyncClient ile yerel olarak entegre olur.

app.py dosyanız:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py

Basit Python Flask uygulaması, ADK aracısını Araç Kutumuzda tanımladığımız araçlara bağlar. Bu araçlar da AlloyDB (ve BigQuery birleştirilmiş verileri) ile etkileşime girip kullanıcıya yanıt verir.

FATURALANDIRMA HESABINIZ YOK MU?

Bu codelab'i faturalandırma hesabı olmadan pratik ve üst düzey bir şekilde gözden geçiriyorsanız büyük olasılıkla Datascan işini ayarlayamamış, Knowledge Catalog çıkarımını veya AlloyDB federasyonunu gerçekleştirememişsinizdir. 1. ve 2. codelab'leri kaçırdıysanız mimariyi ve uygulamayı deneyimleyebilmeniz için veriler hazır olarak sunulmuştur:

Verileri faturalandırma hesabıyla deneyimlemeye devam etme adımları:

A.Projenizin kök klasöründe, depodan şu dosyaları indirin:

1. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.allergen.csv
2. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.consistsof.csv
3. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.containsallergen.csv
4. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.froyo_data_materialized.csv
5. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.ingredient.csv
6. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.product.csv
7. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.suppliedby.csv
8. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.supplier.csv

Bu dosyalar, app.py dosyanızla aynı klasörde bulunmalıdır.

B. app-nobill.py adlı Python dosyasını aynı yolda oluşturun.

1. Proje kök klasöründe app-nobill.py adlı bir dosya oluşturun ve şu adresteki içeriği kopyalayın: https://github.com/AbiramiSukumaran/froyo-data/blob/main/app-nobill.py

C. Laboratuvarda belirtilen diğer tüm dosyalar bu sürümde de bozulmamış olmalıdır (yalnızca app.py dosyasının yürütülmesine gerek yoktur).

FATURALANDIRMA HESABINIZ YOK MU?

7. Kullanıcı Arayüzü ve Uygulamayı Çalıştırma

Mağaza Yöneticilerimize uygun bir deneyim sunmak için canlı ürün kataloğu kenar çubuğu ve etkileşimli sohbet arayüzü içeren şık bir glassmorphic kullanıcı arayüzü (templates/index.html) oluşturduk.

index.html dosyasını depo dosyasında şu konumda bulabilirsiniz:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html

Uygulamayı çalıştırmadan önce, aşağıdaki içeriğe sahip requirements.txt dosyasını oluşturarak bağımlılıklarınızı yüklediğinizden emin olun:

Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv

ve .env dosyanız doldurulmuş olmalıdır:

GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***

Cloud Shell terminalinde, proje klasöründe olduğunuzdan emin olarak aşağıdaki komutları tek tek çalıştırın:

Bağımlılıkları yükleyin:

pip install -r requirements.txt

Python dosyasını yürütme:

python app.py

FATURALANDIRMA HESABINIZ YOK MU?

Bu durumda, app.py adlı python dosyasını çalıştırmak yerine aşağıdakileri çalıştırın:

python app-nobill.py

FATURALANDIRMA HESABINIZ YOK MU?

Terminalde gösterilen bağlantıyı tıklayın veya http://localhost:8080 adresini açın.

8. The Ultimate Test

Temsilciye soru sormak için katalogdan bir ürünü tıklayalım:

Does Midnight Swirl have any allergens?

Yanıtı görürsünüz:

Kamera arkası:

1. ADK Agent, istemi alır ve check_allergens aracını kullanmaya karar verir.
2. Cloud Run'daki MCP Toolbox'u güvenli bir şekilde çağırır.
3. Araç kutusu, sorguyu AlloyDB'de yürütür. Bu sorgu, 1. bölümde oluşturduğumuz karmaşık ilişkileri taramak için anında BigQuery'ye birleştirilir.
4. Veritabanı "Soy" yanıtını döndürür. Bu yanıt, aracı tarafından kullanıcı arayüzünde düzgün bir şekilde özetlenir.

Ardından şunları söylüyoruz:

Order 2 Midnight Swirls for Alice.

Aracı, "Midnight Swirl" dizesini araç kutusuna iletir. Temel SQL, dizeyi BigQuery aracılığıyla dinamik olarak bir tam sayı kimliğine dönüştürür, canlı siparişi AlloyDB'ye ekler ve işlemi onaylar.

Code Repo

https://github.com/AbiramiSukumaran/froyo-data

9. Temizleme

Bu laboratuvar tamamlandıktan sonra AlloyDB kümesini ve örneğini silmeyi unutmayın.

https://console.cloud.google.com/alloydb/clusters adresine gidin. Yanındaki üç nokta simgesini tıklayarak silmek istediğiniz grubu seçin ve SİL'i tıklayın.

Küme, örnekleriyle birlikte temizlenmelidir.

10. Temsilciniz için tebrikler!

Şu ana kadar başardıklarımızı düşünün:

İyi düzenlenmiş ajan sistemimiz yalnızca veritabanları için MCP Toolbox ile etkileşime girer. Bu arka plan işlemi, araç çağrısını ve verileri uygulamamızın yapay zeka mantığına aktararak akışı basit tutar:

1. İşlem uygulamamız (AlloyDB'de çalışır) hızlı ve eşzamanlı kullanıcı oturumlarını işleyebilir.
2. Yoğun analitik veriye veya geçmiş bağlama (ör. tedarikçi ayrıntıları ya da karmaşık içerik eşlemeleri) ihtiyaç duyduğunda BigQuery froyo_dataschema'yı sorgular.
3. Zero ETL. Veri ardışık düzenleri bozulmaz. Senkronize olmayan veritabanı yok. Verileri bir kez (BQ'da) depolar ve ihtiyaç duyduğumuz yerde hesaplarız.

Hem analitik hem de işlemsel olan aracı ve veri temellerimiz tamamlandığına göre bir sonraki bölüme geçebiliriz.

Sırada ne var?

Ajanımız, mutlu yolda mükemmel bir şekilde çalışır. 4. Bölüm'de, temsilci sistemimizin geçerliliğini, temellendirmesini ve performansını titizlikle test etmek için bir Temsilci Değerlendirme ardışık düzeni oluşturacağız. Orada görüşmek üzere.