1. Genel Bakış
Günümüzün gezginleri, sohbet deneyimi bekliyor. Karmaşık kullanıcı arayüzü filtrelerinde gezinmek yerine "Köpeğimi Boston'a giden saat 9 otobüsüne götürebilir miyim?" diye sormak istiyorlar. Bu işlem için yapılandırılmamış veriler (PDF politikaları) ve yapılandırılmış veriler (SQL planları) arasında akıl yürütebilen bir aracı gerekir.
Bu laboratuvarda, Cymbal Transit Agent'ı oluşturmak için şunları kullanacağız:
- LangChain4j: Yapay zeka düzenlemesi için önde gelen Java çerçevesi.
- AlloyDB: Yüksek performanslı, PostgreSQL uyumlu bir veritabanı.
- MCP Toolbox Java SDK: Java aracılarını harici araçlara ve veri kaynaklarına bağlamanın standartlaştırılmış bir yoludur.
Ne oluşturacaksınız?
Cymbal Bus Agent, aşağıdakilerden oluşan bir Java Spring Boot uygulamasıdır:
- AlloyDB veritabanı ve MCP Toolbox Java SDK'sı (aracıların araç düzenlemesi için).
- Araç kutusu dağıtımı ve uygulaması için Cloud Run (aracı dağıtımı).
- Java 17 ile Spring Boot uygulamasında aracı ve LLM çerçevesi için LangChain4J kitaplığı.
Neler öğreneceksiniz?
- LangChain4J'yi kullanarak, MCP Toolbox for Databases Java SDK ile düzenlenmiş özel aracılar ve alt aracılar oluşturma
- Veri ve yapay zeka için AlloyDB'yi ayarlama ve kullanma
- Aracıları AlloyDB veri araçlarına bağlamak için MCP Toolbox'ı kullanma
- Çözümü Cloud Run kullanarak dağıtma veya yerel olarak çalıştırma
Mimari
- AlloyDB for PostgreSQL: Rota, politikalar ve rezervasyon kayıtlarımızı içeren yüksek performanslı operasyonel veritabanı olarak hizmet verir. Vektör arama ve alma işlemlerini destekler.
- MCP Toolbox for Databases Java SDK: "Orchestration Maestro" olarak işlev görür ve AlloyDB verilerini, temsilcilerin çağırabileceği yürütülebilir araçlar olarak kullanıma sunar.
MCP Toolbox Java SDK, kurumsal düzeydeki uygulamalar için aracıları veritabanı araçlarınızla kolayca düzenlemenizi sağlar.
- LangChain4J: Büyük dil modellerinin (LLM'ler) Java uygulamalarına entegrasyonunu basitleştiren açık kaynaklı bir Java kitaplığıdır. Chatbot'lar, temsilciler ve veriyle artırılmış üretim (RAG) sistemleri dahil olmak üzere yapay zeka destekli uygulamalar oluşturmak için araçlar ve soyutlamalar sağlar.
- Cloud Run: Herhangi bir dilde, kitaplıkta ve ikili programda uygulamaları veya web sitelerini hızlıca ve kolayca oluşturup dağıtmanıza olanak tanıyan, tümüyle yönetilen bir SUNUCUSUZ platformdur. En sevdiğiniz dili, çerçeveyi ve kitaplıkları kullanarak kod yazabilir, bunu bir kapsayıcı olarak paketleyebilir, "gcloud run deploy" komutunu çalıştırabilir ve uygulamanızın üretimde çalışması için gereken her şey sağlanarak yayına alınabilir. Kapsayıcı oluşturmak tamamen isteğe bağlıdır. Go, Node.js, Python, Java, .NET Core veya Ruby kullanıyorsanız kullandığınız dil için en iyi uygulamaları kullanarak sizin için kapsayıcıyı oluşturan kaynak tabanlı dağıtım seçeneğini kullanabilirsiniz.
Ş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ı kontrol etmeyi öğ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ğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:
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 ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
- Gerekli API'leri etkinleştirin: Bağlantıyı takip ederek API'leri etkinleştirin.
Alternatif olarak, bu işlem için gcloud komutunu kullanabilirsiniz. gcloud komutları ve kullanımı için belgelere bakın.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Hayalet Proje" Sendromu |
|
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 Yayma Gecikmesi | "API'leri etkinleştir"i tıkladınız ancak komut satırında hâlâ |
Kota Quags | Yeni bir deneme hesabı kullanıyorsanız AlloyDB örnekleri için bölgesel kotaya ulaşabilirsiniz. |
"Gizli" Hizmet Aracısı | Bazen AlloyDB hizmet aracısına |
3. Veritabanı kurulumu
Uygulamamızın temelinde AlloyDB for PostgreSQL yer alıyor. 50.000'den fazla SCM kaydı için yerleştirmeler oluşturmak üzere güçlü vektör özelliklerinden ve entegre sütun motorundan yararlandık. Bu sayede, anlık vektör analizi yapılabiliyor ve temsilcilerimiz, saniyeler içinde büyük veri kümelerindeki envanter anormalliklerini veya lojistik risklerini belirleyebiliyor.
Bu laboratuvarda, test verileri 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.
Test veri kümesinin yükleneceği bir AlloyDB kümesi, örneği ve tablosu oluşturalım.
- Google Cloud Console kullanıcısının oturumunun açık olduğu tarayıcıda aşağıdaki bağlantıyı kopyalayın veya düğmeyi tıklayın.
Alternatif olarak, faturalandırma hesabını kullandığınız projenizden Cloud Shell Terminal'e gidebilir, GitHub deposunu klonlayabilir ve aşağıdaki komutları kullanarak projeye gidebilirsiniz:
git clone https://github.com/AbiramiSukumaran/easy-alloydb-setup
cd easy-alloydb-setup
- Bu adım tamamlandıktan sonra depo yerel Cloud Shell düzenleyicinize klonlanır ve aşağıdaki komutu proje klasöründen çalıştırabilirsiniz (proje dizininde olduğunuzdan emin olmanız önemlidir):
sh run.sh
- Şimdi kullanıcı arayüzünü kullanın (terminaldeki bağlantıyı veya terminaldeki "web'de önizleme" bağlantısını tıklayarak).
- Başlamak için proje kimliği, küme ve örnek adlarıyla ilgili ayrıntılarınızı girin.
- Günlükler kayarken kahve almaya gidebilirsiniz. Bu işlemin arka planda nasıl yapıldığı hakkında bilgi edinmek için burayı ziyaret edebilirsiniz.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Sabır" Sorunu | Veritabanı kümeleri ağır altyapılardır. Sayfayı yenilerseniz veya "takılmış gibi göründüğü" için Cloud Shell oturumunu sonlandırırsanız kısmen sağlanan ve manuel müdahale olmadan silinmesi mümkün olmayan bir "hayalet" örneğiniz olabilir. |
Bölge Uyuşmazlığı | API'lerinizi |
Zombi Kümeleri | Daha önce bir küme için aynı adı kullandıysanız ve bu adı silmediyseniz komut dosyası, küme adının zaten mevcut olduğunu söyleyebilir. Küme adları, proje içinde benzersiz olmalıdır. |
Cloud Shell Zaman Aşımı | Kahve molanız 30 dakika sürerse Cloud Shell uyku moduna geçebilir ve |
4. Şema Sağlama
AlloyDB kümeniz ve örneğiniz çalıştıktan sonra yapay zeka uzantılarını etkinleştirmek ve şemayı sağlamak için AlloyDB Studio SQL düzenleyicisine gidin.
Örneğinizin oluşturulma işleminin tamamlanmasını beklemeniz gerekebilir. Bu işlem tamamlandıktan sonra, kümeyi oluştururken 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" (veya oluşturma sırasında ayarladığınız şifre)
AlloyDB Studio'da kimliğinizi başarıyla doğruladıktan sonra SQL komutları Düzenleyici'ye girilir. Son pencerenin sağındaki artı işaretini kullanarak birden fazla Editor penceresi ekleyebilirsiniz.
Gerekli durumlarda Çalıştır, Biçimlendir ve Temizle seçeneklerini kullanarak AlloyDB için komutları düzenleyici pencerelerine gireceksiniz.
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;
İzin Ver
"embedding" işlevinde yürütme izni 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
Google Cloud IAM Console'dan AlloyDB hizmet hesabına (service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com şeklinde görünür) "Vertex AI Kullanıcısı" rolüne erişim izni verin. PROJECT_NUMBER, proje numaranızı içerir.
Alternatif olarak aşağıdaki komutu Cloud Shell Terminali'nden çalıştırabilirsiniz:
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"
Tablo oluşturma
AlloyDB Studio'da aşağıdaki DDL ifadesini kullanarak bir tablo oluşturabilirsiniz:
DROP TABLE IF EXISTS transit_policies;
DROP TABLE IF EXISTS bus_schedules;
DROP TABLE IF EXISTS bookings;
-- Table 1: Transit Policies (Unstructured Data for RAG)
CREATE TABLE transit_policies (
policy_id SERIAL PRIMARY KEY,
category VARCHAR(50),
policy_text TEXT,
policy_embedding vector(768)
);
-- Table 2: Intercity Bus Schedules (Structured Data)
CREATE TABLE bus_schedules (
trip_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
origin_city VARCHAR(100),
destination_city VARCHAR(100),
departure_time TIMESTAMP,
arrival_time TIMESTAMP,
available_seats INT DEFAULT 50,
ticket_price DECIMAL(6,2)
);
-- Table 3: Booking Ledger (Transactional Action Data)
CREATE TABLE bookings (
booking_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
trip_id UUID REFERENCES bus_schedules(trip_id),
passenger_id VARCHAR(100),
status VARCHAR(20) DEFAULT 'CONFIRMED',
booking_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
policy_embedding sütunu, bazı metin alanlarının vektör değerlerinin depolanmasına olanak tanır.
Veri Kullanımı
Kayıtları ilgili tablolara toplu olarak eklemek için aşağıdaki SQL ifadeleri grubunu çalıştırın:
- Yapılandırılmamış politikaları ekleyin ve AlloyDB'de yerel olarak GERÇEK GÖMÜLÜLER OLUŞTURUN
-- 1. Insert Unstructured Policies and GENERATE REAL EMBEDDINGS natively in AlloyDB
INSERT INTO transit_policies (category, policy_text, policy_embedding)
VALUES
('Pets', 'Service animals are always welcome. Small pets (under 25 lbs) are allowed in secure carriers for a $25 fee. Large dogs are not permitted on standard coaches.', embedding('text-embedding-005', 'Service animals are always welcome. Small pets (under 25 lbs) are allowed in secure carriers for a $25 fee. Large dogs are not permitted on standard coaches.')),
('Luggage', 'Each passenger is allowed one carry-on (up to 15 lbs) and two stowed bags (up to 50 lbs each) free of charge. Additional bags cost $15 each.', embedding('text-embedding-005', 'Each passenger is allowed one carry-on (up to 15 lbs) and two stowed bags (up to 50 lbs each) free of charge. Additional bags cost $15 each.')),
('Refunds', 'Tickets are fully refundable up to 24 hours before departure. Within 24 hours, tickets can be exchanged for travel credit only.', embedding('text-embedding-005', 'Tickets are fully refundable up to 24 hours before departure. Within 24 hours, tickets can be exchanged for travel credit only.'));
- generate_series kullanarak 7 gün için 200'den fazla gerçekçi program oluşturma
-- 2. Generate 200+ Realistic Schedules for the Next 7 Days using generate_series
INSERT INTO bus_schedules (origin_city, destination_city, departure_time, arrival_time, ticket_price, available_seats)
SELECT
origin,
destination,
-- Generate departures every 4 hours starting from tomorrow
(CURRENT_DATE + 1) + (interval '4 hours' * seq) AS dep_time,
(CURRENT_DATE + 1) + (interval '4 hours' * seq) + interval '4.5 hours' AS arr_time,
ROUND((RANDOM() * 30 + 25)::numeric, 2) AS price, -- Random price between $25 and $55
FLOOR(RANDOM() * 50 + 1) AS seats -- Random seats between 1 and 50
FROM
(VALUES
('New York', 'Boston'), ('Boston', 'New York'),
('Philadelphia', 'Washington DC'), ('Washington DC', 'Philadelphia'),
('Seattle', 'Portland'), ('Portland', 'Seattle')
) AS routes(origin, destination)
CROSS JOIN generate_series(1, 40) AS seq; -- 6 routes * 40 time slots = 240 distinct trips ingested!
Yerleştirilmiş Öğeler Oluşturma
Yerleştirmeler, "embedding('text-embedding-005', '<<policytext>>')" işlevi kullanılarak transit_policies tablosuna ekleme ifadesinde otomatik olarak ele alınır.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Parola Unutma" Döngüsü | "Tek Tıklama" kurulumunu kullandıysanız ve şifrenizi hatırlamıyorsanız konsoldaki örnek temel bilgileri sayfasına gidip "Düzenle"yi tıklayarak |
"Uzantı Bulunamadı" Hatası |
|
IAM Yayma Sorunları |
|
Vektör Boyutu Uyuşmazlığı |
|
Proje Kimliği Yazım Hatası |
|
5. Araçlar ve Araç Kutusu Kurulumu
MCP Toolbox for Databases, veritabanları için açık kaynaklı bir MCP sunucusudur. Bağlantı havuzu oluşturma, kimlik doğrulama gibi karmaşık işlemleri yöneterek araçları daha kolay, hızlı ve güvenli bir şekilde geliştirmenizi sağlar. Daha fazla bilgi Araç kutusu, temsilcilerinizin veritabanınızdaki verilere erişmesine olanak tanıyan üretken yapay zeka araçları oluşturmanıza yardımcı olur.
"Orkestra şefi" olarak Model Context Protocol (MCP) Toolbox for Databases'i kullanırız. Temsilcilerimiz ve AlloyDB arasında standartlaştırılmış bir ara yazılım görevi görür. tools.yaml yapılandırması tanımlayarak araç kutusu, karmaşık veritabanı işlemlerini otomatik olarak find-bus-schedules and routes veya query-schedules for specific routes gibi temiz ve yürütülebilir araçlar olarak kullanıma sunar ve book-ticket gibi bağımsız işlemleri yürütür. Bu sayede, aracı mantığında manuel bağlantı havuzu oluşturma veya standart SQL kullanma ihtiyacı ortadan kalkar.
Araç kutusu sunucusunu yükleme
Cloud Shell terminalinizden, yeni araçlar YAML dosyanızı ve araç kutusu ikili dosyasını kaydetmek için bir klasör oluşturun:
mkdir cymbal-bus-toolbox
cd cymbal-bus-toolbox
Bu yeni klasörün içinden aşağıdaki komut grubunu çalıştırın:
# see releases page for other versions
export VERSION=0.27.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Ardından, Cloud Shell Düzenleyici'ye giderek yeni klasörün içinde tools.yaml dosyasını oluşturun ve bu repo dosyasının içeriğini tools.yaml dosyasına kopyalayın.
... (Refer to entire file in the repo)
tools:
find-bus-schedules:
kind: postgres-sql
source: alloydb
description: Find all available bus schedules.
statement: |
SELECT CAST(trip_id AS TEXT) trip_id, departure_time, arrival_time, ticket_price, available_seats , origin_city, destination_city
FROM bus_schedules;
query-schedules:
kind: postgres-sql
source: alloydb
description: Find available bus schedules between an origin and destination city.
parameters:
- name: origin
type: string
description: The departure city name.
- name: destination
type: string
description: The arrival city name.
statement: |
SELECT CAST(trip_id AS TEXT) trip_id, departure_time, arrival_time, ticket_price, available_seats
FROM bus_schedules
WHERE lower(origin_city) = lower($1)
AND lower(destination_city) = lower($2)
AND available_seats > 0
ORDER BY departure_time ASC
LIMIT 5;
book-ticket:
kind: postgres-sql
source: alloydb
description: Books a ticket for a specific trip, decrementing available seats and generating a confirmed booking record.
parameters:
- name: trip_id
type: string
description: The UUID of the trip schedule to book.
- name: passenger_name
type: string
description: Name or ID of the passenger (Bound securely via backend or AuthToken).
authServices:
- name: google_auth
field: sub
statement: |
WITH updated_schedule AS (
UPDATE bus_schedules
SET available_seats = available_seats - 1
WHERE trip_id = CAST($1 AS UUID) AND available_seats > 0
RETURNING trip_id
)
INSERT INTO bookings (trip_id, passenger_id)
SELECT trip_id, $2
FROM updated_schedule
RETURNING CAST(booking_id as TEXT) as booking_id, trip_id, passenger_id, status, booking_time;
search-policies:
kind: postgres-sql
source: alloydb
description: Semantic search for transit policies regarding luggage, pets, refunds, and general rules.
parameters:
- name: search_query
type: string
description: The user's question about transit policies to be embedded and searched.
statement: |
SELECT category, policy_text
FROM transit_policies
ORDER BY policy_embedding <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
LIMIT 2;
Not:
- tools.yaml kurulumunda, alloydb kaynak yapılandırmasına ipType: "private" ifadesini eklemeyi unutmayın.
- Ayrıca, authServices yapılandırması için clientId parametresine MCP Toolbox hizmet URL'sini eklemeyi unutmayın. Bağlantıyı yalnızca ilk dağıtımdan sonra alabilirsiniz. Bu nedenle, kimliği doğrulanmış araçlar kullanım alanının çalıştığından emin olmak için dağıtım adımlarını iki kez çalıştırmanız gerekir.
- AlloyDB bağlantınız özel olarak ayarlanmışsa araç kutusunu yerel olarak test etmek için aşağıdaki seçenekler çalışmaz. Yerel olarak test etmek için bağlantıyı herkese açık hale getirmeniz veya bağlantı için proxy kullanmanız gerekir. Ancak bu durum endişe etmenizi gerektirmez. Bu örnekte, doğrudan Cloud Run'a dağıtıp test edeceğiz.
Yerel sunucudaki tools.yaml dosyasını test etmek için:
./toolbox --tools-file "tools.yaml"
Alternatif olarak, kullanıcı arayüzünde de test edebilirsiniz:
./toolbox --ui
Şimdi bunu Cloud Run'da aşağıdaki şekilde dağıtalım.
Cloud Run Deployment
- PROJECT_ID ortam değişkenini ayarlayın:
export PROJECT_ID="my-project-id"
- gcloud CLI'yı başlatın:
gcloud init
gcloud config set project $PROJECT_ID
- Aşağıdaki API'lerin etkinleştirilmiş olması gerekir:
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
- Henüz bir arka uç hizmet hesabınız yoksa oluşturun:
gcloud iam service-accounts create toolbox-identity
- Secret Manager'ı kullanma izinleri verme:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
- Hizmet hesabına, AlloyDB kaynağımıza özgü ek izinler verin (roles/alloydb.client ve roles/serviceusage.serviceUsageConsumer).
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/alloydb.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/serviceusage.serviceUsageConsumer
- tools.yaml dosyasını gizli olarak yükleyin:
gcloud secrets create tools-cymbal-transit --data-file=tools.yaml
- Zaten bir gizli anahtarınız varsa ve gizli anahtar sürümünü güncellemek istiyorsanız aşağıdakileri yürütün:
gcloud secrets versions add tools-cymbal-transit --data-file=tools.yaml
- Cloud Run için kullanmak istediğiniz container görüntüsüne bir ortam değişkeni ayarlayın:
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
- Aşağıdaki komutu kullanarak Toolbox'ı Cloud Run'a dağıtın:
AlloyDB örneğinizde herkese açık erişimi etkinleştirdiyseniz Cloud Run'a dağıtım için aşağıdaki komutu uygulayın:
gcloud run deploy toolbox-cymbal-transit \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-cymbal-transit:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
VPC ağı kullanıyorsanız aşağıdaki komutu kullanın:
gcloud run deploy toolbox-cymbal-transit \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-cymbal-transit:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--network <<YOUR_NETWORK_NAME>> \
--subnet <<YOUR_SUBNET_NAME>> \
--allow-unauthenticated
Not: Dağıtım tamamlandıktan sonra Cloud Run hizmet listesine gidin ve ilgili hizmetin güvenlik sekmesinde "Herkese açık erişime izin ver"in seçili olduğundan emin olun.
6. Aracı Uygulaması Kurulumu
Bu depoyu projenize klonlayın ve inceleyelim.
Bunu klonlamak için Cloud Shell terminalinizde (kök dizinde veya bu projeyi oluşturmak istediğiniz herhangi bir yerden) aşağıdaki komutu çalıştırın:
git clone https://github.com/googleapis/mcp-toolbox-sdk-java
Yukarıdaki komut, mcp-toolbox-sdk-java'nın tamamını kopyalar. Yalnızca örnek projeye ihtiyacımız var. Bu nedenle, depodaki projenin kök dizinine gidin:
cd mcp-toolbox-sdk-java/demo-applications/cymbal-transit
- Bu işlem projeyi oluşturur ve Cloud Shell Düzenleyici'de bunu doğrulayabilirsiniz.
- CymbalTransitController.java dosyasını açın ve ortam değişkenlerini ayarlayın:
- GCP_PROJECT_ID
- GCP_REGION
- GEMINI_MODEL_NAME
- MCP_TOOLBOX_URL
Alternatif olarak (yalnızca geliştirme amacıyla) ilgili yedek değer yer tutucularını da değiştirebilirsiniz.
7. Kod Açıklaması
CymbalTransitController, Cloud Run hizmetimizin giriş noktası olarak işlev görür. Bu işlev, görüşme akışını yönetir ve temsilcinin kullanıcının mevcut isteğine erişebilmesini sağlar.
Uygulama, yapay zeka düzenlemesini, araç köprülemeyi ve düşük düzeyli MCP iletişimini ayıran katmanlı bir mimariyi takip eder.
1. Yapay Zeka Aracısı Yapılandırması (AgentConfiguration)
Bu sınıf, yapay zeka bileşenlerini başlatmak için Spring'in @Configuration özelliğini kullanır. VertexAiGeminiChatModel'i başlatır ve Agent arayüzümüze bağlar.
@Bean
ChatLanguageModel geminiChatModel() {
return VertexAiGeminiChatModel.builder()
.project(projectId)
.location(region)
.modelName(modelName)
.build();
}
@Bean
TransitAgent transitAgent(ChatLanguageModel chatLanguageModel, TransitAgentTools tools) {
return AiServices.builder(TransitAgent.class)
.chatLanguageModel(chatLanguageModel)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(20))
.tools(tools)
.build();
}
Önem: AiServices, arayüzü LLM'ye bağlar. MessageWindowChatMemory, aracının tek bir oturumda 20 iletiye kadar kullanıcı tercihlerini (ör. daha önce bahsedilen evcil hayvan taşıma çantası) hatırlamasını sağlar.
2. Yapay Zeka Ajanı Arayüzü (TransitAgent)
@SystemMessage ek açıklaması, "Karakter" ve operasyonel kısıtlamaları (özellikle Yönlendirme Stratejisi) tanımlar.
@SystemMessage({
"You are the Cymbal Transit Concierge.",
"CRITICAL INSTRUCTION: On your very first interaction, you MUST use the 'findAllSchedules' tool to fetch and memorize the broad bus routes.",
"ONLY if the user asks a specifically narrowed-down question... should you route to the specific tools like 'querySchedules', 'bookTicket', 'searchPolicies'.",
"Don't show any asterisks while listing results. Keep it formatted and numbered or bulleted."
})
String chat(@MemoryId String sessionId, @UserMessage String userMessage);
Önem: Bu strateji gecikmeyi en aza indirir. Ajan, önce geniş kapsamlı verileri getirerek gereksiz arka uç çağrıları yapmadan genel yönlendirme sorularını kendi içindeki bağlamı kullanarak yanıtlayabilir.
3. Araç Kutusu Köprüsü (TransitAgentTools)
Bu hizmet, aracının "elleri" gibi davranarak LangChain4j araç çağrılarını yürütme mantığına çevirir.
@Tool("Fetches the initial, broad dataset of all available bus schedules and routes.")
public String findAllSchedules() {
return mcpService.findAllSchedules().join();
}
@Tool("Book a ticket for a passenger using a specific trip ID.")
public String bookTicket(String tripId, String passengerName) {
return mcpService.bookTicket(tripId, passengerName).join();
}
Eşzamanlı Yürütme: MCP çağrıları eşzamansız olsa da (CompletableFuture döndürür) LLM, "düşünme" sürecine devam edebilmek için bir sonuç gerektirir. Aracıya eşzamanlı sonuçlar sağlamak için .join() kullanırız.
4. MCP Toolbox Hizmeti (McpToolboxService)
Bu, AlloyDB arka ucuyla etkileşim kurmak için MCP Toolbox Java SDK'sını kullanan iletişim katmanıdır.
// Identity Management: Fetching OIDC ID Token for Auth
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
this.idToken = ((IdTokenProvider) credentials)
.idTokenWithAudience(targetUrl, Collections.emptyList())
.getTokenValue();
// Dynamic Invocation: Executing a tool by name
public CompletableFuture<String> findAllSchedules() {
return mcpClient.invokeTool("find-bus-schedules", Collections.emptyMap()).thenApply(result -> {
return result.content().stream()
.map(content -> content.text())
.collect(Collectors.joining(", ", "[", "]"));
});
}
Önemi: McpToolboxClient, JSON-RPC iletişimiyle ilgili ağır işleri halleder. bookTicket yöntemi, SDK'nın karmaşık parametreleri dinamik olarak bağlama özelliğini özellikle gösterir.
5. REST denetleyicisi (TransitAgentController)
LangChain4j durumu ve mantığı yönettiği için nihai uç nokta önemli ölçüde basitleştirilmiştir.
@PostMapping("/chat")
public ResponseEntity<String> handleUserChat(@RequestBody String userMessage, HttpSession session) {
String sessionId = session.getId();
String agentResponse = transitAgent.chat(sessionId, userMessage);
return ResponseEntity.ok(agentResponse);
}
Önem: HttpSession kimliğini @MemoryId ile eşleyerek farklı kullanıcıların seyahat planlarının karışmamasını sağlarız. Bu sırada denetleyici kodunu temiz ve okunabilir tutarız.
8. MCP Araç Kutusu: Önem ve Java SDK'sı
MCP nedir?
Model Context Protocol'ü (MCP) yapay zeka için evrensel bir çevirmen olarak düşünebilirsiniz. Yapay zeka modellerinin harici araçlara ve veri kümelerine bağlanma şeklini standartlaştırmak için oluşturulan MCP, özel ve parçalanmış entegrasyon komut dosyalarını güvenli ve evrensel bir protokolle değiştirir. Aracınızın işlemsel bir SQL sorgusu yürütmesi, binlerce politika belgesinde arama yapması veya bir REST API'yi tetiklemesi gerekse de MCP tek ve birleşik bir arayüz sağlar.
Veritabanları için MCP Araç Kutusu
Mühendislik ekipleri, görev açısından kritik öneme sahip veritabanlarıyla doğrudan etkileşime giren temsilci sistemler oluşturmak için basit chatbot'ların ötesine geçiyor. Ancak bu kurumsal temsilcileri oluşturmak genellikle özel yapıştırıcı kod, kırılgan API'ler ve karmaşık veritabanı mantığı gibi bir entegrasyon duvarına çarpmak anlamına gelir.
Bu sabit kodlu darboğazları güvenli ve birleşik bir kontrol düzlemiyle değiştirmek için Veritabanları için Model Context Protocol (MCP) Toolbox'ın Java SDK'sını duyurmaktan heyecan duyuyoruz. Bu sürüm, dünyanın en yaygın kullanılan kurumsal ekosistemine birinci sınıf, tür güvenli aracı düzenleme özelliği getiriyor. Java'nın olgun mimarisi, bu zorlu talepler için özel olarak tasarlanmıştır. Üretimde görev açısından kritik öneme sahip yapay zeka aracılarını güvenli bir şekilde ölçeklendirmek için gereken yüksek eşzamanlılığı, katı işlemsel bütünlüğü ve sağlam durum yönetimini sağlar.
Neden Java SDK?
MCP Toolbox Java SDK, Java geliştiricilerin şunları yapmasına olanak tanır:
- Consume Tools: Bir MCP sunucusuna (ör. AlloyDB için MCP Toolbox) bağlanın ve özelliklerini LangChain4j'in anlayabileceği Java yöntemlerine otomatik olarak dönüştürün.
- Tür Güvenliği: Araç parametreleri için Java'nın güçlü tür yazma özelliğinden yararlanarak araç çağrılarında çalışma zamanı "halüsinasyon" hatalarını azaltın.
- Kurumsal kullanıma hazır olma: Spring Boot, Quarkus, Micronaut vb. ile kolayca entegre edin.
- Kolayca Bağlanın: Ortak metin JSON-RPC kodu yazmaktan kaçının.
- Kimlik Doğrulamayı Standartlaştırma: Google Cloud OIDC jetonları için yerel destek, araçların güvenli bir şekilde yürütülmesini sağlar.
ve çok daha fazlası.
Bağımlılıklar: pom.xml Yapılandırması
En yeni MCP Toolbox Java SDK'yı eklemek için Maven projenize aşağıdaki bağımlılığı ekleyin:
<dependency>
<groupId>com.google.cloud.mcp</groupId>
<artifactId>mcp-toolbox-sdk-java</artifactId>
<version>0.2.0</version>
</dependency>
LangChain4j yapısını eklemek için Maven projenize aşağıdaki bağımlılığı ekleyin:
<!-- LangChain4j Core & Gemini -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
<version>0.35.0</version>
</dependency>
İşte bu!!! Projeyi başarıyla klonladık ve aracı, MCP Toolbox Java SDK'sı ve bağlamın ayrıntılarını inceledik.
9. Yerel olarak çalıştırma
Temsilciyi makinenizde test etmek için dağıtılmış MCP Toolbox sunucunuza yönlendirmeniz gerekir.
- Ortam değişkenlerini ayarlayın:
export GCP_PROJECT_ID="<<YOUR_PROJECT_ID>>"
export GCP_REGION="us-central1"
export GEMINI_MODEL_NAME="gemini-2.5-flash"
export MCP_TOOLBOX_URL="<<YOUR_TOOLBOX_ENDPOINT_URL>>/mcp"
- Maven ile çalıştırma:
mvn compile
mvn spring-boot:run
Bu işlem, aracınızı yerel olarak başlatır ve test edebilirsiniz.
10. Cloud Run'a dağıtalım
Projeyi klonladığınız Cloud Shell terminalinden aşağıdaki komutu çalıştırarak Cloud Run'da dağıtın ve projenin kök klasöründe olduğunuzdan emin olun.
MEVCUT PROJEMİZİN KÖK KLASÖRÜNDE DEĞİLSENİZ Cloud Shell terminalinizde şunu çalıştırın:
cd cymbal-transit
Zaten cymbal-transit kök dizinindeyseniz uygulamayı doğrudan Cloud Run'a dağıtmak için aşağıdaki komutu çalıştırın:
gcloud run deploy cymbal-transit --source . --set-env-vars GCP_PROJECT_ID=<<YOUR_PROJECT_ID>>,GCP_REGION=us-central1,GEMINI_MODEL_NAME=gemini-2.5-flash,MCP_TOOLBOX_URL=<<YOUR_MCP_TOOLBOX_URL>> --allow-unauthenticated
Yer tutucuların değerlerini değiştirin <<YOUR_PROJECT>> and <<YOUR_MCP_TOOLBOX_URL>>
Komut tamamlandığında bir hizmet URL'si oluşturulur. Kopyalayın.
Cloud Run hizmet hesabına AlloyDB İstemcisi rolünü verin.Bu, sunucusuz uygulamanızın veritabanına güvenli bir şekilde tünel oluşturmasına olanak tanır.
Cloud Shell terminalinizde şunu çalıştırın:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
Not: Dağıtım tamamlandıktan sonra Cloud Run hizmet listesine gidin ve ilgili hizmetin güvenlik sekmesinde "Herkese açık erişime izin ver"in seçili olduğundan emin olun.
Şimdi hizmet URL'sini (daha önce kopyaladığınız Cloud Run uç noktası) kullanarak uygulamayı test edin.
Not: Bir hizmet sorunuyla karşılaşırsanız ve bunun nedeni olarak bellek gösteriliyorsa sorunu test etmek için ayrılan bellek sınırını 1 GiB'ye yükseltmeyi deneyin.
11. Demo
Ajana sorun: "Yarın sabah New York'tan Boston'a gitmem gerekiyor. Golden Retriever cinsi köpeğimi getirebilir miyim?" Temsilcinin:
- Büyük köpekler için politikaları arar.
- Belirli programları bulur.
- En hızlı geziyi, gezi kimliğiyle özetler.
- Ayrıca, bu işlem isteğini takip ederseniz bilet de ayırtır.
12. Temizleme
Bu laboratuvar tamamlandıktan sonra AlloyDB kümesini ve örneğini silmeyi unutmayın.
Küme, örnekleriyle birlikte temizlenmelidir.
13. Tebrikler
Gelişmiş bir Java tabanlı geçiş aracısını başarıyla oluşturdunuz. Orkestrasyon için LangChain4j'yi, veri bağlantısı için MCP Toolbox Java SDK'sını kullanarak aracılar, araçlar ve veri kaynakları arasında akıl yürütebilen bir sistem oluşturdunuz. Veritabanları için MCP Toolbox ile birden fazla veritabanında, hatta platformlar arasında bile yapay zeka destekli uygulamalarınızı düzenlemeye başlamak istiyorsanız hemen Java SDK'yı kullanmaya başlayın. Kitaplık hakkında daha ayrıntılı bilgi veren lansman duyurusu blogunu buradan inceleyebilirsiniz. Bu tür uygulamaları ücretsiz olarak kendi hızınızda ve eğitmen rehberliğinde uygulamalı olarak geliştirmek istiyorsanız https://codevipassana.dev adresinden Code Vipassana'ya kaydolun.