1. Giriş
Bu codelab, AlloyDB için Google Cloud MCP sunucusunu kullanmaya başlama, bunu yapay zeka aracısının araç setinin bir parçası olarak etkinleştirme ve uygulamada kullanma hakkında bir kılavuz sunar.
Ön koşullar
- Google Cloud ve konsol hakkında temel düzeyde bilgi sahibi olmak
- Komut satırı arayüzü ve Cloud Shell'de temel beceriler
Neler öğreneceksiniz?
- AlloyDB kümesi oluşturma ve örnek verileri içe aktarma
- AlloyDB Veri Erişimi API'sini etkinleştirme
- AlloyDB NL için Google Cloud MCP'yi etkinleştirme
- AlloyDB için Google Cloud MCP'yi ADK aracınıza ekleme
- Uygulamada AlloyDB için Google Cloud MCP'yi kullanma
- Analiz için AlloyDBMCP ile aracıları kullanma
Gerekenler
- Google Cloud hesabı ve Google Cloud projesi
- Google Cloud Console ve Cloud Shell'i destekleyen Chrome gibi bir web tarayıcısı
2. Kurulum ve Gereksinimler
Proje Kurulumu
- Google Cloud Console'da oturum açın. Gmail veya Google Workspace hesabınız yoksa hesap oluşturmanız gerekir.
İş veya okul hesabı yerine kişisel hesap kullanıyorsanız.
- Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Google Cloud Console'da yeni bir proje oluşturmak için üstbilgide bir pop-up pencere açacak olan Proje seç düğmesini tıklayın.
Proje seçin penceresinde Yeni Proje düğmesini tıklayın. Bu işlem, yeni proje için bir iletişim kutusu açar.
İletişim kutusunda tercih ettiğiniz proje adını girin ve konumu seçin.
- Proje adı, bu projenin katılımcıları için görünen addır. Proje adı, Google API'leri tarafından kullanılmaz ve istediğiniz zaman değiştirilebilir.
- Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve sabittir (ayarlandıktan sonra değiştirilemez). Google Cloud Console, benzersiz bir kimliği otomatik olarak oluşturur ancak bu kimliği özelleştirebilirsiniz. Oluşturulan kimliği beğenmediyseniz başka bir rastgele kimlik oluşturabilir veya kendi kimliğinizi girerek kullanılabilirliğini kontrol edebilirsiniz. Çoğu codelab'de, genellikle PROJECT_ID yer tutucusuyla tanımlanan proje kimliğinize başvurmanız gerekir.
- Bazı API'lerin kullandığı üçüncü bir değer olan Proje Numarası da vardır. Bu üç değer hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.
Faturalandırmayı etkinleştirme
Kişisel faturalandırma hesabı oluşturma
Faturalandırmayı Google Cloud kredilerini kullanarak ayarladıysanız bu adımı atlayabilirsiniz.
Kişisel faturalandırma hesabı oluşturmak için Cloud Console'da faturalandırmayı etkinleştirmek üzere buraya gidin.
Bazı Notlar:
- Bu laboratuvarı tamamlamak için 3 ABD dolarından daha az tutarda bulut kaynağı kullanmanız gerekir.
- Daha fazla ücret ödememek için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
- Yeni kullanıcılar 300 ABD doları değerinde ücretsiz deneme sürümünden yararlanabilir.
Cloud Shell'i başlatma
Google Cloud, dizüstü bilgisayarınızdan uzaktan çalıştırılabilir ancak bu codelab'de Cloud'da çalışan bir komut satırı ortamı olan Google Cloud Shell'i kullanacaksınız.
Google Cloud Console'da sağ üstteki araç çubuğunda Cloud Shell simgesini tıklayın:
Alternatif olarak G ve ardından S tuşuna basabilirsiniz. Bu sıra, Google Cloud Console'da veya bu bağlantıyı kullanıyorsanız Cloud Shell'i etkinleştirir.
Ortamın temel hazırlığı ve bağlantı kurulması yalnızca birkaç dakikanızı alır. İşlem tamamlandığında aşağıdakine benzer bir ekranla karşılaşırsınız:
Bu sanal makine, ihtiyaç duyacağınız tüm geliştirme araçlarıyla birlikte gelir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud üzerinde çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde güçlenir. Bu codelab'deki tüm çalışmalarınızı tarayıcıda yapabilirsiniz. Herhangi bir şey yüklemeniz gerekmez.
3. Başlamadan önce
API'yi etkinleştirme
AlloyDB, Compute Engine, ağ hizmetleri ve Vertex AI'ı kullanmak için Google Cloud projenizde ilgili API'leri etkinleştirmeniz gerekir.
Cloud Shell terminalinde proje kimliğinizin ayarlandığından emin olun:
gcloud config get-value project
Google proje kimliğiniz döndürülmelidir.
PROJECT_ID ortam değişkenini ayarlayın:
PROJECT_ID=$(gcloud config get-value project)
Gerekli tüm hizmetleri etkinleştirin:
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Beklenen çıktı
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
4. AlloyDB'yi dağıtma
AlloyDB kümesi ve birincil örnek oluşturun. Gerekli tüm kaynakları dağıtacak şekilde hazırlanmış bir komut dosyası kullanarak dağıtabilir veya dokümanları takip ederek adım adım kendiniz yapabilirsiniz.
Otomatik komut dosyası kullanarak AlloyDB'yi dağıtma
Bu yaklaşımda, AlloyDB kümesini dağıtmak için otomatik bir komut dosyası kullanılır ve dağıtılan kaynaklarla çalışmaya başlamak için gerekli bilgiler sağlanır.
Cloud Shell terminalinde, dağıtım komut dosyasını depodan klonlamak için komutu çalıştırın.
REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"
git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR
Dağıtım komut dosyasını çalıştırın.
./deploy_alloydb.sh
Komut dosyasının çalışması biraz zaman alır (genellikle yaklaşık 5-7 dakika). Ardından, çıkış olarak dağıtılan AlloyDB kümeniz hakkında bilgi sağlamalıdır. Şifrenizin farklı olacağını lütfen unutmayın. Şifreyi ileride kullanmak üzere bir yere kaydedin.
... <redacted> ... Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster) Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715 Creating instance...done. ---------------------------------------- Deployment Process Completed Cluster: alloydb-aip-01 (TRIAL) Instance: alloydb-aip-01-pr Region: us-central1 Initial Password: JBBoDTgixzYwYpkF (if new cluster) ----------------------------------------
Yeni kümeyi ve birincil örneği web konsolunda da görebilirsiniz.
5. Veritabanını Hazırlama
Yapay zeka işlevlerini ve operatörlerini kullanmak için Vertex AI entegrasyonunu etkinleştirmeniz, veri erişimi API'sini etkinleştirmeniz ve örnek veri kümesi için bir veritabanı oluşturmanız gerekir.
AlloyDB'ye Gerekli İzinleri Verme
AlloyDB hizmet aracısına Vertex AI izinleri ekleyin.
En üstteki "+" işaretini kullanarak başka bir Cloud Shell sekmesi açın.
Yeni Cloud Shell sekmesinde şunu çalıştırın:
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"
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/discoveryengine.viewer"
Beklenen konsol çıkışı:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project) Your active configuration is: [cloudshell-11039] student@cloudshell:~ (test-project-001-402417)$ 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" Updated IAM policy for project [test-project-001-402417]. bindings: - members: - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com role: roles/aiplatform.user - members: ... < redacted > etag: BwYIEbe_Z3U= version: 1
Veri Erişimi API'sini etkinleştirme
execute_sql gibi MCP araçlarını kullanabilmek için AlloyDB kümesinde Data Access API'yi etkinleştirmeniz gerekir.
Aynı terminal sekmesinde yürütün.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
Örnek İşaretlerini Güncelleme
AlloyDB'de gelişmiş yapay zeka işlevlerini kullanmak için bazı veritabanı işaretlerini etkinleştirmemiz gerekir. Veri Erişim API'si etkinleştirildikten sonra, örneğin bir sonraki değişikliklere hazır olduğunu göstermesi birkaç dakika sürebilir. Yeşil onay işaretinin göründüğünden emin olmak için lütfen konsolda örneğin durumunu kontrol edin.
Aynı terminal sekmesinde yürütün.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
--database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
--region=$REGION \
--cluster=$ADBCLUSTER \
--project=$PROJECT_ID \
--update-mode=FORCE_APPLY
MCP'yi etkinleştirme
Bir sonraki adım, projenizde AlloyDB için Google Cloud MCP sunucusunu etkinleştirmektir. MCP varsayılan olarak etkin değildir ve IAM kimlik doğrulama ve yetkilendirme, veri erişimi API'si ve kümenizdeki roller dahil olmak üzere birden fazla koruma katmanından biridir.
Aynı terminal sekmesinde yürütün.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
--project=$PROJECT_ID
Sekmede "exit" komutunu çalıştırarak sekmeyi kapatın:
exit
AlloyDB Studio'ya bağlanma
Aşağıdaki bölümlerde, veritabanına bağlantı gerektiren tüm SQL komutları AlloyDB Studio'da yürütülebilir. T
Postgres için AlloyDB'deki Kümeler sayfasına gidin.
Birincil örneği tıklayarak AlloyDB kümeniz için web konsolu arayüzünü açın.
Ardından sol taraftaki AlloyDB Studio'yu tıklayın:
Postgres veritabanını ve postgres kullanıcısını seçin, ardından küme oluşturulurken not edilen şifreyi girin. Ardından "Kimlik doğrulama" düğmesini tıklayın.
Şifre çalışmıyorsa veya şifreyi not almayı unuttuysanız şifreyi değiştirebilirsiniz. Bunun nasıl yapılacağını öğrenmek için dokümanları inceleyin.
AlloyDB Studio arayüzü açılır. Veritabanındaki komutları çalıştırmak için sağdaki "Untitled Query" (Adsız Sorgu) sekmesini tıklayın.
SQL komutlarını çalıştırabileceğiniz bir arayüz açılır.
Veritabanı Oluşturma
Veritabanı oluşturma hızlı başlangıç kılavuzu.
AlloyDB Studio Düzenleyici'de aşağıdaki komutu çalıştırın.
Veritabanı oluşturma:
CREATE DATABASE quickstart_db
Beklenen çıktı:
Statement executed successfully
quickstart_db'ye bağlanma
Veritabanınıza bağlanarak oluşturulup oluşturulmadığını kontrol edin. Kullanıcı/veritabanı değiştirme düğmesini kullanarak stüdyoya yeniden bağlanın.
Açılır listeden yeni quickstart_db veritabanını seçin ve daha önce kullandığınız kullanıcı ile şifreyi kullanın.
quickstart_db veritabanındaki nesnelerle çalışabileceğiniz yeni bir bağlantı açılır. Burada, içe aktarılan şemanızı ve verilerinizi inceleyebilirsiniz.
6. Örnek Veriler
Şimdi veritabanında nesneler oluşturmanız ve verileri yüklemeniz gerekiyor. Kurgusal bir Cymbal Shipping şirketi veri kümesini kullanacaksınız. Bu veri kümesinde, kurgusal sürücülerle birlikte mallar, kamyonlar, istekler ve kamyon yolculukları hakkında kurgusal veriler yer alır.
Storage paketi oluşturma
Klonlanmış depomuzdaki verileri AlloyDB veritabanına aktarmak için Google SDK'sını (gcloud) kullanacaksınız. Bu işlem için bir depolama paketi oluşturmanız ve AlloyDB hizmet hesabına erişim izni vermeniz gerekir. Alternatif olarak, belgelerde açıklandığı gibi web konsolunu kullanarak da yapmayı deneyebilirsiniz.
Google Cloud Shell terminalinde şunu çalıştırın:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer
Veri Yükleme
Bir sonraki adım, verileri yüklemektir. SQL dökümümüz, klonlanmış depo klasöründe bulunur. Aşağıdaki komutta, AlloyDB kümesi oluştururken önceki adımda depoyu klonladığınızda başlangıç noktası olarak ana dizininizi kullandığınız varsayılır.
Sıkıştırılmış SQL dökümünü yeni depolama paketine kopyalayın:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz gs://$PROJECT_ID-import
Ardından verileri quickstart_db veritabanına yükleyin:
PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql
Komut, örnek veri kümesini quickstart_db veritabanına yükler. AlloyDB Studio'yu kullanarak tabloları ve kayıtları doğrulayabilirsiniz.
7. Veri Temsilcisi ile çalışma
Python için Google ADK kullanılarak oluşturulan örnek bir yapay zeka aracısından başlayıp AlloyDB için Google Cloud MCP sunucusuyla çalışacak şekilde nasıl yapılandırılacağını gösterelim.
Aracı kaynak kodunu kontrol etme
Klonlanan depoda, Google Cloud Shell düzenleyicisini kullanarak aracı kodunu inceleyin.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py
Aracımızda AlloyDB için Google Cloud MCP sunucusu bölümü olduğunu görebilirsiniz. MCP_SERVER_URL olarak bir uç nokta, kimlik doğrulama ve proje kimliği sağlarız ve bunu MCP araç setine ekleriz.
# Google Cloud MCP Server for AlloyDB
MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
creds.refresh(GoogleAuthRequest())
print(f"Authenticated as project: {project_id}")
# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
"Authorization": f"Bearer {creds.token}",
"X-Goog-User-Project": project_id
}
connection_params = StreamableHTTPConnectionParams(
url=MCP_SERVER_URL,
headers=headers,
timeout=300.0,
sse_read_timeout=600.0
)
mcp_toolset = McpToolset(connection_params=connection_params)
Ajan kodunda ise MCP araç seti, ajan için tools parametresi olarak yer alır. Ayrıca, küme ve örnek adları, bölge ve veritabanı da aracı istemi için değişken olarak kullanılabilir.
MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"
# Agent configuration
root_agent = Agent(
model=MODEL_ID,
name='root_agent',
description='A helpful assistant for analyst requests.',
instruction=f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
""",
tools=[mcp_toolset],
)
AlloyDB için Google Cloud MCP hizmetinde önceden tanımlanmış bir araç seti bulunur. Kullanılabilir tüm araçları listelemek istiyorsanız Cloud Shell konsol terminalinden curl komutunu aşağıdaki komutu kullanarak kullanabilirsiniz. Ayrıca, Google Cloud MCP sunucusunun AlloyDB'deki en son referansını dokümanlarda her zaman kontrol edebilirsiniz.
curl -s -X POST http://alloydb.googleapis.com/mcp \
-H "Content-Type: application/json" \
-d @- <<EOF | jq -r '.result.tools[].name'
{
"id": "my_id_01",
"jsonrpc": "2.0",
"method": "tools/list"
}
EOF
Aracıyı başlatma
Artık Google ADK web arayüzünü kullanarak etkileşimli modda aracı başlatabilirsiniz. ADK web arayüzü, aracıların iş akışlarını test etmek ve sorunlarını gidermek için kullanışlı bir yöntem sunar.
Öncelikle, uv paket yöneticisini kullanarak Python için gerekli tüm paketleri yükleyelim.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync
Tüm paketler yüklendikten sonra, temsilciyi yapay zeka modelleriyle tüm iletişimlerde Vertex AI'ı kullanmaya yönlendirmek için temsilci dizinine bir .env dosyası eklemeniz gerekir.
echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env
Ardından, temsilciyi başlatabilirsiniz.
uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Şuna benzer bir çıkış görmelisiniz: http://127.0.0.1:8000 .
Cloud Shell'de bu URL'yi tıkladığınızda ayrı bir tarayıcı sekmesinde önizleme penceresi açılır. Burada, soldaki açılır listeden data_agent simgesini seçersiniz.
ADK web arayüzünde sorularınızı sağ alt kısımdan gönderebilir ve her adımın izlerini de içeren tam yürütme akışını sağ tarafta görebilirsiniz.
8. AlloyDB MCP'yi Agent ile test etme
Aracı, doğal dil kullanarak serbest biçimde soru sormanıza olanak tanır. Araç, soruları yanıtlamak için AlloyDB'nin Google Cloud MCP sunucusunu kullanır. Sorular sağ altta yayınlanır ve araçlara yapılan tüm çağrıları içeren yanıt en üstte görünür.
Kargo şirketinin operasyonel verileriyle çalışıyorsunuz. Bu verilerde kargo talepleri, kamyonlar, sürücüler ve sürücülerin yaptığı yolculuklarla ilgili bilgiler yer alıyor. İlk soru, Şubat 2026'da gerçekleştirilen yolculukların sayısı ile ilgilidir.
Sağ alttaki giriş alanına aşağıdakileri yazıp Enter tuşuna basın.
Hello, can you tell me how many trips we've done in February this year?
Aracı, doğru verileri almak için doğru SQL ifadesini yürütmeden önce şemadaki doğru tabloları ve tablo yapısını belirlemek üzere birden fazla araç çağrısı yürüterek çalışır.
Sonunda, uygun sorguyu oluşturup veritabanında yürüttükten sonra sonucu üretir.
Veritabanımızdaki kayıtlara göre, Şubat 2026'da 108 gezi tamamlandı.
Araç yürütmesini tıklayarak her araç çağrısının ne yaptığını görebilirsiniz. Örneğin, sonuçlarımızı almak için yürütülen sorgu aşağıda verilmiştir.
Şimdi sonuçları önceki ayla karşılaştırmasını isteyerek talebi daha karmaşık hale getirin.
How is it in comparison in numbers and mileage with the January?
Sonuçları analiz eden ve gezi sayısı ile mesafede fark sağlayan farklı sorgular yürüterek sonucu döndürür.
In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage: January 2026: 114 trips with a total mileage of 185,597 km. February 2026: 108 trips with a total mileage of 177,893 km. This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.
ADK web arayüzünü kullanarak diğer basit istekleri deneyin ve sonuçlara ulaşmak için farklı sorguları nasıl yürüttüğünü görün.
Terminalde ctrl+c tuşuna basarak aracı durdurun. ADK web arayüzünün bulunduğu tarayıcı sekmesini kapatabilirsiniz.
Artık örnek bir uygulamayı deneyebilir ve bu uygulamanın veri analistleri için nasıl bir araç olarak kullanılabileceğini görebilirsiniz.
9. Örnek Uygulama
Aynı klonlanmış depoda, Cymbol Logistic şirketimiz için örnek bir uygulama var. Uygulama, Google Mesop Python çerçevesini kullanıyor .
Uygulama kodunu, Cloud Shell düzenleyicisinde app.py dosyasını açarak analiz edebilirsiniz.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py
Kodda, değişkenlerle yeni bir istemi veri aracımıza iletmek için bir işlev kullanıyoruz. Bunun nedeni, farklı bir veritabanı veya örnek çağırmaya karar verirsek arayüzde yapılandırabilmektir. İşlev tanımı ve istem aşağıda verilmiştir.
def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
local_runner = FrontendRunner()
instruction = f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
"""
...
Kodu inceledikten sonra uygulamamızı başlatıp test etmek için "terminal" düğmesine basın. Uygulama, 8080 numaralı bağlantı noktasında başlatılır. Bağlantı noktasını değiştirmek istiyorsanız bağlantı noktası değerini değiştirerek komutu ayarlayın.
Cloud Shell'de çalıştırın.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080
Ardından, http://localhost:8080 adresini tıklayarak Google Cloud Shell'de web önizlemeyi kullanın.
Tarayıcıda uygulama arayüzünün bulunduğu yeni bir sekme açılır.
Sağ üstteki "Enable Debug Output" (Hata Ayıklama Çıkışını Etkinleştir) onay kutusunu tıklayın ve aşağıdaki gibi bir soru yazın.
What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.
Ardından Submit Request düğmesine basın.
Temsilci, arka planda çalışacak ve MCP araç setimiz tarafından yürütülen tüm sorgularla çıkış ve hata ayıklama bilgilerini üretecektir. İş akışını görmek için sorguları kontrol edin.
Farklı analiz soruları deneyerek aracıları ve uygulama özelliklerini test edebilirsiniz.
Şimdiye kadar MCP ile birlikte aracıyı kullanarak bazı temel analizler ve keşifler yapabiliyordunuz. Bir sonraki bölümde, daha gelişmiş AlloyDB özelliklerini kullanmayı deneyeceksiniz.
10. AlloyDB AI işlevleri
AlloyDB AI işlevleri, metin ve çok formatlı verilerde (özellikle görseller) akıllı filtreleme ve sıralama yapmanıza olanak tanır ve Gemini'ın gücünü sorgularınıza getirir. Özellikle AlloyDB AI işlevleri AI.IF ve AI.RANK, geleneksel SQL operatörleriyle (filtreler, birleştirmeler, toplama vb.) birlikte SQL ifadelerinde görünebilir.
Yapay zeka işlevlerini kullanmadan önce, "klasik" yöntemleri kullanarak bir aramayı ve toplamaları inceleriz. Aşağıdaki istemi deneyin.
Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.
Müşteri geri bildirimlerinin yer aldığı tablodaki "puan" sütununu bulabilir ve en iyi puanı alan sürücüleri belirlemek için bu sütunu kullanabilir. Ardından, sürücüler hakkında daha fazla bilgi edinmek için bu bilgileri kullandı.
SELECT
d.first_name || ' ' || d.last_name as driver_name,
SUM(sr.distance_km) as total_distance,
d.experience_years,
COUNT(cf.feedback_id) as positive_feedback_count
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
WHERE tt.arrival_time >= '2025-12-01'
AND tt.arrival_time < '2026-05-01'
AND cf.rating >= 4
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY positive_feedback_count DESC, total_distance DESC
LIMIT 5;
Ancak derecelendirme, değerlendirmek istediğimiz tüm parametreleri teknik olarak içerebilir veya içermeyebilir. Bunun için AlloyDB AI işlevlerini kullanabiliriz.
AI.RANK operatörleri
ai.rank() işlevi, bir dokümanın belirli bir sorguyu ne kadar iyi yanıtladığına göre puan verir. Sorgunun sonuçlarını sıralamak veya yeniden sıralamak için kullanılabilir. Operatörler hakkında daha fazla bilgiyi dokümanlarda bulabilirsiniz.
İsteği değiştirin ve sürücüleri performanslarına ve profesyonelliklerine göre değerlendirmek için analiz sırasında AI.RANK'in kullanılmasını açıkça isteyin.
Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function? Give me top drivers names, distance, years of experience and rank for each driver.
Ajanın AI.RANK işlevini nasıl kullanacağını bulması, verileri alması ve bilgileri buna göre sıralamak için AI.RANK işlevini uygulaması gerektiğinden komutun tamamlanması biraz daha uzun sürebilir. Sonunda, modele göre sıralanmış sürücülerin listesini ve yürütülen sorguların listesini alırsınız.
Bu sorgunun yürütülmesi, modelin seçtiği yola bağlı olarak biraz zaman alabilir. Sürücülerle ilgili bilgileri almak için yürütülen sorguyu hata ayıklama penceresinde görebilirsiniz.
WITH fastest_drivers AS (
SELECT
d.driver_id,
d.first_name || ' ' || d.last_name as driver_name,
d.experience_years,
SUM(sr.distance_km) as total_distance,
AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
LEFT
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
WHERE tt.arrival_time >= '2026-04-04'
AND tt.arrival_time IS NOT NULL
AND tt.departure_time IS NOT NULL
AND tt.arrival_time > tt.departure_time
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY avg_speed DESC
LIMIT 5
)
SELECT
f.driver_name,
f.total_distance,
f.experience_years,
f.avg_speed,
f.feedbacks,
(SELECT r.score
FROM ai.rank(
'semantic-ranker-fast-004',
'excellent customer service, professional, friendly, fast,
and reliable delivery reviews',
ARRAY[f.feedbacks],
1
) r
LIMIT 1) as feedback_score
FROM fastest_drivers f
ORDER BY feedback_score DESC;
Uygulamayı test etmeye ve aracının nihai sonuçlara nasıl ulaştığını görmek için sorguları incelemeye devam edebilirsiniz.
Laboratuvarımızın sonuna geldik. Umarım tüm örnekleri inceleyip AlloyDB için Google Cloud MCP hizmetini nasıl kullanacağınızı öğrenmişsinizdir. MCP'nin kurumsal düzeyde çalışmasını sağlamak için MCP'yi AlloyDB belgelerinde açıklanan AlloyDB NL2SQL özellikleriyle birleştirmek mantıklıdır. AlloyDB için SQL ifadeleri oluşturma codelab'ini kullanarak bu özelliği deneyebilirsiniz.
11. Ortamı temizleme
Beklenmedik ücretleri önlemek için geçici kaynakları temizlemek iyi bir uygulamadır. En güvenilir yöntem, iş akışını test ettiğiniz projeyi silmektir. Ancak isteğe bağlı olarak AlloyDB gibi tek tek kaynakları silerek kendinizi sınırlayabilirsiniz.
Laboratuvarı tamamladığınızda AlloyDB örneklerini ve kümeyi yok edin.
AlloyDB kümesini ve tüm örnekleri silme
AlloyDB'nin deneme sürümünü kullandıysanız Deneme kümesini kullanarak diğer laboratuvarları ve kaynakları test etmeyi planlıyorsanız deneme kümesini silmeyin. Aynı projede başka bir deneme kümesi oluşturamazsınız.
Küme, zorlama seçeneğiyle yok edilir. Bu seçenek, kümeye ait tüm örnekleri de siler.
Bağlantınız kesildiyse ve önceki tüm ayarlar kaybolduysa Cloud Shell'de proje ve ortam değişkenlerini tanımlayın:
gcloud config set project <your project id>
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)
Kümeyi silme:
gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
Beklenen konsol çıkışı:
student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force All of the cluster data will be lost when the cluster is deleted. Do you want to continue (Y/n)? Y Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f Deleting cluster...done.
AlloyDB Yedeklemelerini Silme
Kümenin tüm AlloyDB yedeklerini silin:
for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Beklenen konsol çıkışı:
student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f Deleting backup...done.
12. Tebrikler
Codelab'i tamamladığınız için tebrikler.
İşlediğimiz konular
- AlloyDB kümesi oluşturma ve örnek verileri içe aktarma
- AlloyDB Veri Erişimi API'sini etkinleştirme
- AlloyDB NL için Google Cloud MCP'yi etkinleştirme
- AlloyDB için Google Cloud MCP'yi ADK aracınıza ekleme
- Uygulamada AlloyDB için Google Cloud MCP'yi kullanma
- Analiz için AlloyDBMCP ile aracıları kullanma
13. Anket
Çıkış: