Bu codelab hakkında
1. Genel Bakış
Farklı sektörlerde bağlama dayalı arama, uygulamaların temelini oluşturan kritik bir işlevdir. Üretken yapay zeka destekli arama mekanizmalarıyla, Retrieval Augmented Generation (Arama Aşamasında Güçlendirilmiş Üretim) uzun süredir bu önemli teknolojik evrimin önemli bir itici gücü olmuştur. Üretken modeller, geniş bağlam pencereleri ve etkileyici çıkış kalitesiyle yapay zekayı dönüştürüyor. RAG, yapay zeka uygulamalarına ve temsilcilerine bağlam eklemenin sistematik bir yolunu sunar. Bu bağlam, yapılandırılmış veritabanlarına veya çeşitli medyalardan alınan bilgilere dayanır. Bu bağlamsal veriler, doğruluğun netliği ve çıktının doğruluğu açısından çok önemlidir ancak bu sonuçlar ne kadar doğrudur? İşletmeniz büyük ölçüde bu bağlamsal eşleşmelerin doğruluğuna ve alaka düzeyine mi bağlı? O zaman bu proje tam size göre.
Şimdi, üretken modellerin gücünden yararlanıp bağlam açısından kritik öneme sahip bu tür bilgilerle desteklenen ve gerçeğe dayalı otonom kararlar alabilen etkileşimli temsilciler oluşturabilseydik ne olurdu bir düşünün. Bugün bunu yapacağız. Bir patent analizi uygulaması için AlloyDB'deki gelişmiş RAG tarafından desteklenen Agent Development Kit'i kullanarak uçtan uca bir yapay zeka aracısı uygulaması oluşturacağız.
Patent Analizi Asistanı, kullanıcıya arama metniyle bağlamsal olarak alakalı patentleri bulma konusunda yardımcı olur ve istendiğinde, seçilen bir patent için net ve kısa bir açıklama ve gerekirse ek ayrıntılar sağlar. Nasıl yapıldığını öğrenmeye hazır mısınız? Başlayalım.
Hedef
Hedefimiz basit. Kullanıcının metin açıklamasına göre patent aramasına izin verin ve ardından arama sonuçlarından belirli bir patentin ayrıntılı açıklamasını alın. Tüm bunları Java ADK, AlloyDB, Vektör Arama (gelişmiş dizinlerle), Gemini ve Cloud Run'da sunucusuz olarak dağıtılan uygulamanın tamamıyla birlikte geliştirilmiş bir yapay zeka aracısı kullanarak yapın.
Ne oluşturacaksınız?
Bu laboratuvarda şunları yapacaksınız:
- AlloyDB örneği oluşturma ve Patents Public Dataset verilerini yükleme
- ScaNN ve Recall eval özelliklerini kullanarak AlloyDB'de gelişmiş vektör araması uygulama
- Java ADK'yi kullanarak temsilci oluşturma
- Java sunucusuz Cloud Functions'da veritabanı sunucu tarafı mantığını uygulama
- Cloud Run'da aracıyı dağıtma ve test etme
Aşağıdaki diyagram, veri akışını ve uygulamayla ilgili adımları gösterir.
High level diagram representing the flow of the Patent Search Agent with AlloyDB & ADK
Ş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. Projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin .
- Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
- Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığı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 ayarlanmadıysa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
- Gerekli API'leri etkinleştirin. Cloud Shell terminalinde gcloud komutunu kullanabilirsiniz:
gcloud services enable alloydb.googleapis.com compute.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com run.googleapis.com cloudbuild.googleapis.com cloudfunctions.googleapis.com aiplatform.googleapis.com
gcloud komutunun alternatifi, her ürünü arayarak veya bu bağlantıyı kullanarak konsoldan geçmektir.
gcloud komutları ve kullanımı için belgelere bakın.
3. Veritabanı kurulumu
Bu laboratuvarda, patent verileri için veritabanı olarak AlloyDB'yi kullanacağız. Veritabanları ve günlükler gibi tüm kaynakları tutmak için kümeler kullanır. Her kümenin, verilere erişim noktası sağlayan bir birincil örneği vardır. Tablolar gerçek verileri içerir.
Patent veri kümesinin yükleneceği bir AlloyDB kümesi, örneği ve tablosu oluşturalım.
Küme ve örnek oluşturma
- 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.
- Bu sayfada KÜME OLUŞTUR'u seçin:
- Aşağıdakine benzer bir ekran görürsünüz. Aşağıdaki değerlerle bir küme ve örnek oluşturun (Repo'dan uygulama kodunu klonluyorsanız değerlerin eşleştiğinden emin olun):
- küme kimliği: "
vector-cluster" - password: "
alloydb" - PostgreSQL 15 / en son sürüm önerilir
- Bölge: "
us-central1" - Ağ: "
default"
- Varsayılan ağı seçtiğinizde aşağıdaki gibi bir ekran görürsünüz.
BAĞLANTI KUR'u seçin.
- Buradan "Otomatik olarak atanmış bir IP aralığı kullan"ı seçip Devam'ı tıklayın. Bilgileri inceledikten sonra BAĞLANTI OLUŞTUR'u seçin.
- Ağınız oluşturulduktan sonra kümenizi oluşturmaya devam edebilirsiniz. Kümenin ayarlanmasını tamamlamak için aşağıda gösterildiği gibi KÜME OLUŞTUR'u tıklayın:
Örnek kimliğini (küme / örnek yapılandırması sırasında bulabilirsiniz) şununla değiştirin:
vector-instance. Değiştiremiyorsanız sonraki tüm referanslarda örnek kimliğinizi kullanmayı unutmayın.
Küme oluşturma işleminin yaklaşık 10 dakika süreceğini unutmayın. İşlem başarıyla tamamlandığında, yeni oluşturduğunuz kümenize genel bakış sunan bir ekran görürsünüz.
4. Veri kullanımı
Şimdi, mağazayla ilgili verileri içeren 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. 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ğrulama için aşağıdaki verileri kullanın:
- Kullanıcı adı : "
postgres" - Veritabanı : "
postgres" - Şifre : "
alloydb"
AlloyDB Studio'da kimlik doğrulamayı başarıyla tamamladıktan sonra Düzenleyici'ye SQL komutları girilir. Son pencerenin sağındaki artı işaretini kullanarak birden fazla Düzenleyici penceresi ekleyebilirsiniz.
Gerektiği gibi Çalıştır, Biçimlendir ve Temizle seçeneklerini kullanarak AlloyDB komutlarını düzenleyici pencerelerine girersiniz.
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ında etkinleştirilen uzantıları kontrol etmek istiyorsanız aşağıdaki SQL komutunu çalıştırın:
select extname, extversion from pg_extension;
Tablo oluşturma
AlloyDB Studio'da aşağıdaki DDL ifadesini kullanarak tablo oluşturabilirsiniz:
CREATE TABLE patents_data ( id VARCHAR(25), type VARCHAR(25), number VARCHAR(20), country VARCHAR(2), date VARCHAR(20), abstract VARCHAR(300000), title VARCHAR(100000), kind VARCHAR(5), num_claims BIGINT, filename VARCHAR(100), withdrawn BIGINT, abstract_embeddings vector(768)) ;
abstract_embeddings sütunu, metnin vektör değerlerinin depolanmasına olanak tanır.
İ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ı ROLÜ verme
Google Cloud IAM konsolunda 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, Cloud Shell Terminal'den aşağıdaki komutu da ç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"
Patent verilerini veritabanına yükleme
BigQuery'deki Google Patentler Herkese Açık Veri Kümeleri veri kümemiz olarak kullanılacaktır. Sorgularımızı çalıştırmak için AlloyDB Studio'yu kullanacağız. Veriler bu insert_scripts.sql dosyasına alınır ve patent verilerini yüklemek için bu dosyayı çalıştırırız.
- Google Cloud Console'da AlloyDB sayfasını açın.
- Yeni oluşturduğunuz kümeyi seçin ve örneği tıklayın.
- AlloyDB gezinme menüsünde AlloyDB Studio'yu tıklayın. Kimlik bilgilerinizle oturum açın.
- Sağ taraftaki Yeni sekme simgesini tıklayarak yeni bir sekme açın.
- Yukarıda belirtilen
insert_scripts.sqlkomut dosyasındaninsertsorgu ifadesini düzenleyiciye kopyalayın. Bu kullanım alanının hızlı bir demosu için 10-50 insert ifadesi kopyalayabilirsiniz. - Çalıştır'ı tıklayın. Sorgunuzun sonuçları Sonuçlar tablosunda görünür.
5. Patent verileri için gömmeler oluşturma
Öncelikle aşağıdaki örnek sorguyu çalıştırarak yerleştirme işlevini test edelim:
SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');
Bu işlem, sorgudaki örnek metin için kayan nokta dizisi gibi görünen embedding vektörünü döndürür. Şu şekilde görünür:
abstract_embeddings vektör alanını güncelleme
Tablodaki patent özetlerini ilgili yerleştirmelerle güncellemek için aşağıdaki DML'yi çalıştırın:
UPDATE patents_data set abstract_embeddings = embedding( 'text-embedding-005', abstract);
6. Vektör araması yapma
Tablo, veriler ve yerleştirmeler hazır olduğuna göre kullanıcı arama metni için gerçek zamanlı vektör araması gerçekleştirelim. Aşağıdaki sorguyu çalıştırarak bunu test edebilirsiniz:
SELECT id || ' - ' || title as title FROM patents_data ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;
Bu sorguda,
- Kullanıcının aradığı metin: "Duygu Analizi".
- Metni, embedding() yönteminde text-embedding-005 modelini kullanarak yerleştirmelere dönüştürüyoruz.
- "<=>", KOSİNÜS BENZERLİĞİ mesafe yönteminin kullanıldığını gösterir.
- 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.
- LIMIT 10, arama metnine en yakın 10 eşleşmeyi seçtiğimizi gösterir.
AlloyDB, Vektör Arama RAG'yi bir üst seviyeye taşır:
Çok sayıda yeni özellik kullanıma sunuldu. Geliştirici odaklı olanlardan ikisi şunlardır:
- Satır içi filtreleme
- Hatırlanabilirlik Değerlendiricisi
Satır içi filtreleme
Daha önce geliştirici olarak Vector Search sorgusunu gerçekleştirmeniz ve filtreleme ve yeniden çağırma ile uğraşmanız gerekiyordu. AlloyDB sorgu optimize edicisi, filtre içeren bir sorgunun nasıl yürütüleceğiyle ilgili seçimler yapar. Satır içi filtreleme, AlloyDB sorgu optimizatörünün hem meta veri filtreleme koşullarını hem de vektör aramayı değerlendirmesine olanak tanıyan, meta veri sütunlarındaki vektör dizinlerinden ve dizinlerden yararlanan yeni bir sorgu optimizasyon tekniğidir. Bu sayede, geliştiriciler AlloyDB'nin sunduğu özelliklerden yararlanarak hatırlama performansını artırabilir.
Satır içi filtreleme, orta düzeyde seçiciliğe sahip durumlar için en iyi seçenektir. AlloyDB, vektör dizini içinde arama yaparken yalnızca meta veri filtreleme koşullarıyla eşleşen vektörlerin mesafelerini hesaplar (bir sorgudaki işlevsel filtreleriniz genellikle WHERE yan tümcesinde işlenir). Bu, son filtreleme veya önceden filtreleme avantajlarını tamamlayarak bu sorguların performansını büyük ölçüde artırır.
- pgvector uzantısını yükleme veya güncelleme
CREATE EXTENSION IF NOT EXISTS vector WITH VERSION '0.8.0.google-3';
pgvector uzantısı zaten yüklüyse geri çağırma değerlendirmesi özelliklerinden yararlanmak için vektör uzantısını 0.8.0.google-3 veya sonraki bir sürüme yükseltin.
ALTER EXTENSION vector UPDATE TO '0.8.0.google-3';
Bu adımın yalnızca vektör uzantınız <0.8.0.google-3 ise uygulanması gerekir.
Önemli not: Satır sayınız 100'den azsa ScaNN dizini daha az satır için geçerli olmadığından bu dizini oluşturmanız gerekmez. Bu durumda lütfen aşağıdaki adımları atlayın.
- ScaNN dizini oluşturmak için alloydb_scann uzantısını yükleyin.
CREATE EXTENSION IF NOT EXISTS alloydb_scann;
- Öncelikle, dizini ve satır içi filtreyi etkinleştirmeden Vector Search sorgusunu çalıştırın:
SELECT id || ' - ' || title as title FROM patents_data
WHERE num_claims >= 15
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;
Sonuç şuna benzer:
- Bu üzerinde Explain Analyze'i çalıştırın: (dizin veya satır içi filtreleme olmadan)
Yürütme süresi 2,4 ms
- Buna göre filtre uygulayabilmek için num_claims alanında normal bir dizin oluşturalım:
CREATE INDEX idx_patents_data_num_claims ON patents_data (num_claims);
- Patent Arama uygulamamız için ScaNN dizinini oluşturalım. AlloyDB Studio'nuzda aşağıdakileri çalıştırın:
CREATE INDEX patent_index ON patents_data
USING scann (abstract_embeddings cosine)
WITH (num_leaves=32);
Önemli not: (num_leaves=32), 1.000'den fazla satırlık toplam veri kümemiz için geçerlidir. Satır sayınız 100'den azsa daha az satır için geçerli olmayacağından öncelikle bir dizin oluşturmanız gerekmez.
- ScaNN dizininde satır içi filtrelemeyi etkinleştirin:
SET scann.enable_inline_filtering = on
- Şimdi aynı sorguyu filtre ve vektör araması içerecek şekilde çalıştıralım:
SELECT id || ' - ' || title as title FROM patents_data
WHERE num_claims >= 15
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;
Gördüğünüz gibi, aynı Vektör Arama için yürütme süresi önemli ölçüde azaltılmıştır. Vektör aramasında satır içi filtrelemeyle desteklenen ScaNN dizini bunu mümkün kıldı.
Ardından, bu ScaNN özellikli vektör aramasının geri çağırma oranını değerlendirelim.
Hatırlanabilirlik Değerlendiricisi
Benzerlik aramasında geri çağırma, bir aramadan alınan alakalı örneklerin yüzdesidir (doğru pozitif sayısı). Bu, arama kalitesini ölçmek için kullanılan en yaygın metriktir. Hatırlama kaybının bir kaynağı, yaklaşık en yakın komşu araması (aNN) ile k (tam) en yakın komşu araması (kNN) arasındaki farktır. AlloyDB'nin ScaNN gibi vektör dizinleri, aNN algoritmalarını uygular. Bu sayede, hatırlamada küçük bir ödün karşılığında büyük veri kümelerinde vektör aramasını hızlandırabilirsiniz. Artık AlloyDB, bu dengeyi doğrudan veritabanında tek tek sorgular için ölçmenize ve zaman içinde sabit kalmasını sağlamanıza olanak tanır. Daha iyi sonuçlar ve performans elde etmek için bu bilgilere göre sorgu ve dizin parametrelerini güncelleyebilirsiniz.
evaluate_query_recall işlevini kullanarak belirli bir yapılandırma için vektör dizininde bir vektör sorgusunun geri çağırmasını bulabilirsiniz. Bu işlev, istediğiniz vektör sorgu hatırlama sonuçlarını elde etmek için parametrelerinizi ayarlamanıza olanak tanır. Arama kalitesi için kullanılan anımsama, döndürülen sonuçların sorgu vektörlerine objektif olarak en yakın olanlarının yüzdesi olarak tanımlanır. evaluate_query_recall işlevi varsayılan olarak etkindir.
Önemli Not:
Aşağıdaki adımlarda HNSW dizininde izin reddedildi hatasıyla karşılaşırsanız şimdilik bu hatırlama değerlendirmesi bölümünün tamamını atlayın. Bu kod laboratuvarı belgelenirken yeni kullanıma sunulduğu için bu durum şu anda erişim kısıtlamalarıyla ilgili olabilir.
- ScaNN dizini ve HNSW dizininde Dizin Taramasını Etkinleştir işaretini ayarlayın:
SET scann.enable_indexscan = on
SET hnsw.enable_index_scan = on
- AlloyDB Studio'da aşağıdaki sorguyu çalıştırın:
SELECT
*
FROM
evaluate_query_recall($$
SELECT
id || ' - ' || title AS title,
abstract
FROM
patents_data
where num_claims >= 15
ORDER BY
abstract_embeddings <=> embedding('text-embedding-005',
'sentiment analysis')::vector
LIMIT 25 $$,
'{"scann.num_leaves_to_search":1, "scann.pre_reordering_num_neighbors":10}',
ARRAY['scann']);
evaluate_query_recall işlevi, sorguyu parametre olarak alır ve geri çağırma oranını döndürür. Performansı kontrol etmek için kullandığım sorguyu işlev giriş sorgusu olarak kullanıyorum. Dizin yöntemi olarak SCaNN'i ekledim. Daha fazla parametre seçeneği için dokümanlara bakın.
Kullandığımız bu Vektör Arama sorgusunun geri çağırma oranı:
İADE oranının %70 olduğunu görüyorum. Şimdi bu bilgileri kullanarak dizin parametrelerini, yöntemleri ve sorgu parametrelerini değiştirebilir ve bu Vektör Arama için geri çağırmamı iyileştirebilirim.
Sonuç kümesindeki satır sayısını 7 olarak değiştirdim (önceki 10'dan). RECALL değerinin biraz iyileştiğini görüyorum (%86).
Bu sayede, eşleşmelerin alaka düzeyini kullanıcıların arama bağlamına göre iyileştirmek için kullanıcılarımın göreceği eşleşmelerin sayısını anlık olarak değiştirebilirim.
Tamam. Veritabanı mantığını dağıtma ve temsilciye geçme zamanı!!!
7. Veritabanı mantığını sunucusuz olarak web'e taşıma
Bu uygulamayı web'e taşımaya hazır mısınız? Aşağıdaki adımları uygulayın:
- Yeni bir Cloud Run işlevi OLUŞTURMAK için Google Cloud Console'daki Cloud Run İşlevleri'ne gidin veya https://console.cloud.google.com/functions/add bağlantısını kullanın.
- Ortam olarak "Cloud Run işlevi"ni seçin. "patent-search" işlev adını girin ve Bölge olarak "us-central1"i seçin. Kimlik doğrulamayı "Kimliği doğrulanmayan çağrılara izin ver" olarak ayarlayın ve İLERİ'yi tıklayın. Çalışma zamanı olarak Java 17'yi, kaynak kod için Satır İçi Düzenleyici'yi seçin.
- Varsayılan olarak Giriş Noktası "gcfv2.HelloHttpFunction" olarak ayarlanır. Cloud Run işlevinizin HelloHttpFunction.java ve pom.xml dosyalarındaki yer tutucu kodunu sırasıyla "PatentSearch.java" ve "pom.xml" dosyalarındaki kodla değiştirin. Sınıf dosyasının adını PatentSearch.java olarak değiştirin.
- Java dosyasındaki ************* yer tutucusunu ve AlloyDB bağlantı kimlik bilgilerini kendi değerlerinizle değiştirmeyi unutmayın. AlloyDB kimlik bilgileri, bu codelab'in başında kullandığımız kimlik bilgileridir. Farklı değerler kullandıysanız lütfen Java dosyasında da aynı değişiklikleri yapın.
- Dağıt'ı tıklayın.
ÖNEMLİ ADIM:
Dağıtıldıktan sonra, Cloud Functions'in AlloyDB veritabanı örneğimize erişmesine izin vermek için VPC bağlayıcısını oluşturacağız.
Dağıtım işlemini başlattıktan sonra işlevleri Google Cloud Run Functions konsolunda görebilirsiniz. Yeni oluşturulan işlevi (patent-search) arayın, tıklayın ve ardından DÜZENLE VE YENİ DÜZELTMELERİ DAHA SONRA DAĞIT'ı (Cloud Run Functions konsolunun üst kısmındaki DÜZENLE simgesine (kalem) göre tanımlanır) tıklayın ve aşağıdakileri değiştirin:
- Ağ iletişimi sekmesine gidin:
- "Giden trafik için VPC'ye bağlan"ı ve ardından "Sunucusuz VPC Erişimi bağlayıcılarını kullan"ı seçin.
- Ağ açılır menüsünde, ayarlar bölümünde Ağ açılır menüsünü tıklayın ve "Yeni VPC Bağlantısı Ekle" seçeneğini belirleyin (varsayılan bağlantıyı henüz yapılandırmadıysanız) ve açılan iletişim kutusunda gördüğünüz talimatları uygulayın:
- VPC bağlayıcısı için bir ad girin ve bölgenin örneğinizle aynı olduğundan emin olun. Ağ değerini varsayılan olarak bırakın ve Alt Ağ'ı, 10.8.0.0 IP aralığı veya kullanılabilir benzer bir değerle Özel IP Aralığı olarak ayarlayın.
- YÜKSEK ÇÖZÜNÜRLÜKLÜ AYARLARI GÖSTER'i genişletin ve yapılandırmayı tam olarak aşağıdaki şekilde ayarladığınızdan emin olun:
- OLUŞTUR'u tıklayın. Bu bağlayıcı artık çıkış ayarlarında listelenir.
- Yeni oluşturulan bağlayıcıyı seçin.
- Tüm trafiğin bu VPC bağlayıcısı üzerinden yönlendirilmesini tercih edin.
- SONRAKİ'yi ve ardından DAĞIT'ı tıklayın.
- Güncellenen Cloud Functions işlevi dağıtıldıktan sonra uç noktanın oluşturulduğunu görürsünüz. Bu değeri kopyalayıp aşağıdaki komutta değiştirin:
PROJECT_ID=$(gcloud config get-value project)
curl -X POST <<YOUR_ENDPOINT>> \
-H 'Content-Type: application/json' \
-d '{"search":"Sentiment Analysis"}'
İşte bu kadar. AlloyDB verilerinde Embeddings modelini kullanarak gelişmiş bir bağlamsal benzerlik vektör araması yapmak bu kadar basittir.
8. Java ADK ile aracı oluşturalım
Öncelikle düzenleyicide Java projesine başlayalım.
- Cloud Shell Terminal'e gitme
https://shell.cloud.google.com/?fromcloudshell=true&show=ide%2Cterminal
- İstendiğinde yetkilendirme
- Cloud Shell konsolunun üst kısmındaki düzenleyici simgesini tıklayarak Cloud Shell Düzenleyici'ye geçin.
- Açılış Cloud Shell düzenleyici konsolunda yeni bir klasör oluşturun ve klasörü "adk-agents" olarak adlandırın.
Cloud Shell'inizin kök dizininde yeni klasör oluştur'u tıklayın (aşağıda gösterildiği gibi):
"adk-agents" olarak adlandırın:
- Aşağıdaki klasör yapısını ve aşağıdaki yapıdaki ilgili dosya adlarına sahip boş dosyaları oluşturun:
adk-agents/
└—— pom.xml
└—— src/
└—— main/
└—— java/
└—— agents/
└—— App.java
- GitHub deposunu ayrı bir sekmede açın ve App.java ile pom.xml dosyalarının kaynak kodunu kopyalayın.
- Düzenleyiciyi sağ üst köşedeki "Yeni sekmede aç" simgesini kullanarak yeni bir sekmede açtıysanız terminali sayfanın alt kısmında açabilirsiniz. Hem düzenleyiciyi hem de terminali paralel olarak açarak özgürce çalışabilirsiniz.
- Klonlandıktan sonra Cloud Shell Düzenleyici konsoluna geri dönün
- Cloud Run işlevini zaten oluşturduğumuzdan, depo klasöründeki Cloud Run işlev dosyalarını kopyalamanız gerekmez.
ADK Java SDK'sını kullanmaya başlama
Oldukça basittir. Klonlama adımınızda öncelikle aşağıdakilerin yer aldığından emin olmanız gerekir:
- Bağımlılık ekleme:
google-adk ve google-adk-dev (Web kullanıcı arayüzü için) yapılarını pom.xml dosyanıza ekleyin.
<!-- The ADK core dependency -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>0.1.0</version>
</dependency>
<!-- The ADK dev web UI to debug your agent -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-dev</artifactId>
<version>0.1.0</version>
</dependency>
Uygulamanın çalışabilmesi için gereken başka bağımlılık ve yapılandırmalar olduğundan kaynak deposundaki pom.xml dosyasına referans verdiğinizden emin olun.
- Projenizi yapılandırın:
Java sürümünüzün (17 ve üzeri önerilir) ve Maven derleyici ayarlarınızın pom.xml dosyanızda doğru şekilde yapılandırıldığından emin olun. Projenizi aşağıdaki yapıya uygun olacak şekilde yapılandırabilirsiniz:
adk-agents/
└—— pom.xml
└—— src/
└—— main/
└—— java/
└—— agents/
└—— App.java
- Temsilciyi ve Araçları (App.java) Tanımlama:
ADK Java SDK'sının asıl gücü burada ortaya çıkar. Temsilcimizi, yeteneklerini (talimatlar) ve kullanabileceği araçları tanımlarız.
Ana temsilci sınıfının birkaç kod snippet'inin basitleştirilmiş sürümünü burada bulabilirsiniz. Projenin tamamı için buradaki proje deposuna bakın.
// App.java (Simplified Snippets)
package agents;
import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
// ... other imports
public class App {
static FunctionTool searchTool = FunctionTool.create(App.class, "getPatents");
static FunctionTool explainTool = FunctionTool.create(App.class, "explainPatent");
public static BaseAgent ROOT_AGENT = initAgent();
public static BaseAgent initAgent() {
return LlmAgent.builder()
.name("patent-search-agent")
.description("Patent Search agent")
.model("gemini-2.0-flash-001") // Specify your desired Gemini model
.instruction(
"""
You are a helpful patent search assistant capable of 2 things:
// ... complete instructions ...
""")
.tools(searchTool, explainTool)
.outputKey("patents") // Key to store tool output in session state
.build();
}
// --- Tool: Get Patents ---
public static Map<String, String> getPatents(
@Schema(name="searchText",description = "The search text for which the user wants to find matching patents")
String searchText) {
try {
String patentsJson = vectorSearch(searchText); // Calls our Cloud Run Function
return Map.of("status", "success", "report", patentsJson);
} catch (Exception e) {
// Log error
return Map.of("status", "error", "report", "Error fetching patents.");
}
}
// --- Tool: Explain Patent (Leveraging InvocationContext) ---
public static Map<String, String> explainPatent(
@Schema(name="patentId",description = "The patent id for which the user wants to get more explanation for, from the database")
String patentId,
@Schema(name="ctx",description = "The list of patent abstracts from the database from which the user can pick the one to get more explanation for")
InvocationContext ctx) { // Note the InvocationContext
try {
// Retrieve previous patent search results from session state
String previousResults = (String) ctx.session().state().get("patents");
if (previousResults != null && !previousResults.isEmpty()) {
// Logic to find the specific patent abstract from 'previousResults' by 'patentId'
String[] patentEntries = previousResults.split("\n\n\n\n");
for (String entry : patentEntries) {
if (entry.contains(patentId)) { // Simplified check
// The agent will then use its instructions to summarize this 'report'
return Map.of("status", "success", "report", entry);
}
}
}
return Map.of("status", "error", "report", "Patent ID not found in previous search.");
} catch (Exception e) {
// Log error
return Map.of("status", "error", "report", "Error explaining patent.");
}
}
public static void main(String[] args) throws Exception {
InMemoryRunner runner = new InMemoryRunner(ROOT_AGENT);
// ... (Session creation and main input loop - shown in your source)
}
}
Vurgulanan temel ADK Java kodu bileşenleri:
- LlmAgent.builder(): Temsilcinizi yapılandırmak için Fluent API.
- .instruction(...): Hangi aracın ne zaman kullanılacağı da dahil olmak üzere LLM için temel istemi ve yönergeleri sağlar.
- FunctionTool.create(App.class, "methodName"): Java yöntemlerinizi, aracının çağırabileceği araçlar olarak kolayca kaydeder. Yöntem adı dizesi, gerçek bir herkese açık statik yöntemle eşleşmelidir.
- @Schema(description = ...): Araç parametrelerine ek açıklama ekleyerek LLM'nin her aracın hangi girişleri beklediğini anlamasına yardımcı olur. Bu açıklama, doğru araç seçimi ve parametre doldurma için çok önemlidir.
- InvocationContext ctx: Oturum durumuna (ctx.session().state()), kullanıcı bilgilerine ve daha fazlasına erişim sağlayan, araç yöntemlerine otomatik olarak iletilir.
- .outputKey("patents"): Bir araç veri döndürdüğünde ADK, bu verileri otomatik olarak bu anahtar altında oturum durumunda saklayabilir. explainPatent, getPatents işlevindeki sonuçlara bu şekilde erişebilir.
- VECTOR_SEARCH_ENDPOINT: Bu, patent araması kullanım alanındaki kullanıcı için bağlama dayalı soru-cevap özelliğinin temel işlevsel mantığını içeren bir değişkendir.
- Buradaki işlem öğesi: Önceki bölümdeki Java Cloud Run işlevi adımını uyguladıktan sonra güncellenmiş bir dağıtılmış uç nokta değeri ayarlamanız gerekir.
- searchTool: Kullanıcının arama metni için patent veritabanından bağlamsal olarak alakalı patent eşleşmelerini bulmak üzere kullanıcıyla etkileşim kurar.
- explainTool: Kullanıcıdan ayrıntılı incelemek istediği belirli bir patenti seçmesi istenir. Ardından, patent özetini özetler ve sahip olduğu patent ayrıntılarına göre kullanıcının diğer sorularını yanıtlayabilir.
Önemli Not: VECTOR_SEARCH_ENDPOINT değişkenini dağıtılan CRF uç noktanızla değiştirdiğinizden emin olun.
Durum bilgisi içeren etkileşimler için InvocationContext'ten yararlanma
Faydalı temsilciler oluşturmak için önemli özelliklerden biri, bir sohbetin birden fazla dönüşünde durumu yönetmektir. ADK'nın InvocationContext özelliği bunu kolaylaştırır.
App.java dosyamızda:
- initAgent() tanımlandığında .outputKey("patents") kullanılır. Bu, ADK'ye bir araç (getPatents gibi) rapor alanında veri döndürdüğünde bu verilerin oturum durumunda "patents" anahtarı altında depolanması gerektiğini bildirir.
- explainPatent araç yönteminde InvocationContext ctx'yi enjekte ederiz:
public static Map<String, String> explainPatent(
@Schema(description = "...") String patentId, InvocationContext ctx) {
String previousResults = (String) ctx.session().state().get("patents");
// ... use previousResults ...
}
Bu sayede explainPatent aracı, önceki bir turda getPatents aracı tarafından getirilen patent listesine erişebilir. Böylece sohbet duruma duyarlı ve tutarlı hale gelir.
9. Yerel KSA Testi
Ortam değişkenlerini tanımlama
İki ortam değişkenini dışa aktarmanız gerekir:
- AI Studio'dan alabileceğiniz bir Gemini anahtarı:
Bunu yapmak için https://aistudio.google.com/apikey adresine gidin ve bu uygulamayı uyguladığınız etkin Google Cloud projeniz için API anahtarınızı alın ve anahtarı bir yere kaydedin:
- Anahtarı aldıktan sonra Cloud Shell Terminal'i açın ve aşağıdaki komutu çalıştırarak yeni oluşturduğunuz adk-agents dizinine gidin:
cd adk-agents
- Bu sefer Vertex AI'ı kullanmadığımızı belirtmek için kullanılan bir değişken.
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=AIzaSyDF...
- KSA'da ilk temsilcinizi çalıştırma
Bu ilk aracıyı başlatmak için terminalinizde aşağıdaki Maven komutunu kullanın:
mvn compile exec:java -DmainClass="agents.App"
Temsilcinin etkileşimli yanıtını terminalinizde görürsünüz.
10. Cloud Run'a dağıtma
ADK Java aracınızı Cloud Run'a dağıtmak, diğer Java uygulamalarını dağıtmaya benzer:
- Dockerfile: Java uygulamanızı paketlemek için bir Dockerfile oluşturun.
- Docker görüntüsünü derleyip gönderme: Google Cloud Build ve Artifact Registry'yi kullanın.
- Yukarıdaki adımı gerçekleştirip Cloud Run'a tek bir komutla dağıtabilirsiniz:
gcloud run deploy --source . --set-env-vars GOOGLE_API_KEY=<<Your_Gemini_Key>>
Benzer şekilde, Java Cloud Run işlevinizi (gcfv2.PatentSearch) dağıtırsınız. Alternatif olarak, veritabanı mantığı için Java Cloud Run işlevini doğrudan Cloud Run işlevi konsolundan oluşturabilir ve dağıtabilirsiniz.
11. Web kullanıcı arayüzü ile test etme
ADK, aracınızı yerel olarak test etmek ve hata ayıklamak için kullanışlı bir web kullanıcı arayüzü içerir. App.java dosyanızı yerel olarak çalıştırdığınızda (ör. yapılandırılmışsa mvn exec:java -Dexec.mainClass="agents.App" veya yalnızca ana yöntemi çalıştırın) ADK genellikle yerel bir web sunucusu başlatır.
ADK Web kullanıcı arayüzüyle şunları yapabilirsiniz:
- Temsilcinize mesaj gönderebilirsiniz.
- Etkinlikleri (kullanıcı mesajı, araç çağrısı, araç yanıtı, LLM yanıtı) görün.
- Oturum durumunu inceleyin.
- Günlükleri ve izleri görüntüleyin.
Bu, temsilcinizin istekleri nasıl işlediğini ve araçlarını nasıl kullandığını anlamak için geliştirme sırasında çok değerlidir. Bu durumda, pom.xml dosyanızdaki mainClass değerinin com.google.adk.web.AdkWebServer olarak ayarlandığı ve aracınızın bu değere kayıtlı olduğu veya bunu gösteren yerel bir test çalıştırıcı çalıştırdığınız varsayılır.
App.java dosyanızı, konsol girişi için InMemoryRunner ve Scanner ile çalıştırdığınızda temel aracı mantığını test edersiniz. Web kullanıcı arayüzü, daha görsel bir hata ayıklama deneyimi için ayrı bir bileşendir ve genellikle ADK, aracınızı HTTP üzerinden sunarken kullanılır.
SpringBoot yerel sunucusunu başlatmak için kök dizininizden aşağıdaki Maven komutunu kullanabilirsiniz:
mvn compile exec:java -Dexec.args="--adk.agents.source-dir=src/main/java/ --logging.level.com.google.adk.dev=TRACE --logging.level.com.google.adk.demo.agents=TRACE"
Arayüze genellikle yukarıdaki komutun çıktısını verdiği URL'den erişilebilir. Cloud Run'a dağıtılmışsa Cloud Run'a dağıtılmış bağlantısından erişebilirsiniz.
Sonucu etkileşimli bir arayüzde görebilirsiniz.
Görevlendirilmiş patent temsilcimiz hakkında bilgi edinmek için aşağıdaki videoya göz atın:
12. Temizleme
Bu yayında kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:
- Google Cloud Console'da https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog adresine gidin.
- https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog sayfasına gidin.
- Proje listesinde, silmek istediğiniz projeyi seçin ve ardından Sil'i tıklayın.
- İletişim kutusuna proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.
13. Tebrikler
Tebrikler! ADK, https://cloud.google.com/alloydb/docs?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog, Vertex AI ve Vektör Arama'nın özelliklerini birleştirerek Patent Analizi Temsilcinizi Java'da başarıyla oluşturdunuz. Ayrıca, bağlamsal benzerlik aramalarını dönüştürücü, verimli ve gerçekten anlam odaklı hale getirme konusunda dev bir adım attık.
Hemen Başlayın!
ADK Dokümanları: [Link to Official ADK Java Docs]
Patent Analizi Aracısı Kaynak Kodu: [Link to your (now public) GitHub Repo]
Java Örnek Aracılar: [adk-samples deposunun bağlantısı]
ADK Topluluğuna katılın: https://www.reddit.com/r/agentdevelopmentkit/
İyi bir temsilci oluşturma dileğiyle.