با ADK، AlloyDB و ADK، اپلیکیشن‌های قدرتمند، Stateful، E2E AI Agent را در جاوا بسازید. جوزا!!

با ADK، AlloyDB و Gemini، اپلیکیشن‌های قدرتمند، دولتی، E2E AI Agent را در جاوا بسازید!!

درباره این codelab

آخرین به‌روزرسانی: مه ۲۸, ۲۰۲۵

نویسنده: Author: Abirami Sukumaran

1. نمای کلی

در صنایع مختلف، جستجوی متنی یک عملکرد حیاتی است که قلب و مرکز برنامه های آنها را تشکیل می دهد. Retrieval Augmented Generation مدتی است که با مکانیزم‌های بازیابی مبتنی بر هوش مصنوعی تولیدی خود، محرک اصلی این تکامل فناوری حیاتی بوده است. مدل‌های تولیدی، با پنجره‌های زمینه بزرگ و کیفیت خروجی چشمگیر، هوش مصنوعی را متحول می‌کنند. RAG یک روش سیستماتیک برای تزریق زمینه به برنامه‌ها و عوامل هوش مصنوعی، پایه‌گذاری آنها در پایگاه‌های داده ساختاریافته یا اطلاعات رسانه‌های مختلف ارائه می‌کند. این داده های متنی برای وضوح حقیقت و دقت خروجی بسیار مهم است، اما این نتایج چقدر دقیق هستند؟ آیا کسب و کار شما تا حد زیادی به دقت این مطابقت های متنی و ارتباط بستگی دارد؟ سپس این پروژه قرار است شما را قلقلک دهد!

حال تصور کنید که آیا می‌توانیم قدرت مدل‌های مولد را در اختیار بگیریم و عامل‌های تعاملی بسازیم که قادر به تصمیم‌گیری مستقل با پشتوانه چنین اطلاعات زمینه‌ای حیاتی و مبتنی بر حقیقت باشند. این چیزی است که ما امروز می خواهیم بسازیم. ما قصد داریم با استفاده از کیت توسعه عامل که توسط RAG پیشرفته در AlloyDB برای یک برنامه تجزیه و تحلیل پتنت طراحی شده است، یک اپلیکیشن عامل هوش مصنوعی نهایی بسازیم.

نماینده تجزیه و تحلیل پتنت به کاربر کمک می کند تا پتنت های مرتبط با متن جستجوی خود را بیابد و در صورت درخواست، توضیح واضح و مختصر و جزئیات اضافی را در صورت نیاز برای یک پتنت انتخابی ارائه می دهد. آماده‌اید ببینید چگونه انجام می‌شود؟ بیایید شیرجه بزنیم!

هدف

هدف ساده است. به کاربر اجازه دهید تا پتنت ها را بر اساس توضیحات متنی جستجو کند و سپس توضیح مفصلی درباره یک پتنت خاص از نتایج جستجو دریافت کند و همه اینها را با استفاده از یک عامل هوش مصنوعی ساخته شده با جاوا ADK، AlloyDB، جستجوی برداری (با نمایه های پیشرفته)، Gemini و کل برنامه بدون سرور در Cloud Run به دست آورد.

چیزی که خواهی ساخت

به عنوان بخشی از این آزمایشگاه، شما:

1. یک نمونه AlloyDB ایجاد کنید و داده های مجموعه داده عمومی Patents را بارگیری کنید
2. جستجوی وکتور پیشرفته را در AlloyDB با استفاده از ویژگی‌های ScaNN & Recall eval پیاده‌سازی کنید
3. با استفاده از Java ADK یک عامل ایجاد کنید
4. منطق سمت سرور پایگاه داده را در توابع ابری بدون سرور جاوا پیاده کنید
5. عامل را در Cloud Run مستقر و آزمایش کنید

نمودار زیر جریان داده ها و مراحل مربوط به پیاده سازی را نشان می دهد.

High level diagram representing the flow of the Patent Search Agent with AlloyDB & ADK

الزامات

• مرورگری مانند کروم یا فایرفاکس
• یک پروژه Google Cloud با فعال کردن صورت‌حساب.

2. قبل از شروع

یک پروژه ایجاد کنید

1. در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
2. مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.
3. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می شود، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:

gcloud auth list

5. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

7. API های مورد نیاز را فعال کنید. می توانید از دستور gcloud در ترمینال Cloud Shell استفاده کنید:

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 از طریق کنسول با جستجوی هر محصول یا استفاده از این پیوند است.

برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.

3. راه اندازی پایگاه داده

در این آزمایشگاه از AlloyDB به عنوان پایگاه داده برای داده های پتنت استفاده می کنیم. از خوشه‌ها برای نگهداری همه منابع مانند پایگاه‌های داده و گزارش‌ها استفاده می‌کند. هر خوشه دارای یک نمونه اولیه است که یک نقطه دسترسی به داده ها را فراهم می کند. جداول داده های واقعی را نگه می دارند.

بیایید یک خوشه، نمونه و جدول AlloyDB ایجاد کنیم که مجموعه داده ثبت اختراع در آن بارگذاری شود.

یک خوشه و نمونه ایجاد کنید

1. صفحه AlloyDB را در Cloud Console پیمایش کنید. یک راه آسان برای یافتن بیشتر صفحات در Cloud Console این است که آنها را با استفاده از نوار جستجوی کنسول جستجو کنید.
2. CREATE CLUSTER را از آن صفحه انتخاب کنید:

3. صفحه ای مانند تصویر زیر خواهید دید. یک خوشه و نمونه با مقادیر زیر ایجاد کنید (مطمئن شوید که مقادیر مطابقت دارند در صورتی که کد برنامه را از مخزن شبیه سازی می کنید):

• cluster id : " vector-cluster "
• رمز عبور : " alloydb "
• PostgreSQL 15 / آخرین توصیه شده است
• منطقه : " us-central1 "
• شبکه سازی : " default "

4. وقتی شبکه پیش‌فرض را انتخاب می‌کنید، صفحه‌ای مانند تصویر زیر خواهید دید.

SET UP CONECTION را انتخاب کنید.

5. از آنجا، « استفاده از محدوده IP خودکار اختصاص داده شده » را انتخاب کنید و ادامه دهید. پس از بررسی اطلاعات، CREATE CONNECTION را انتخاب کنید.
6. هنگامی که شبکه شما راه اندازی شد، می توانید به ایجاد خوشه خود ادامه دهید. روی CREATE CLUSTER کلیک کنید تا راه اندازی خوشه مطابق شکل زیر کامل شود:

مطمئن شوید که شناسه نمونه (که می توانید در زمان پیکربندی خوشه / نمونه پیدا کنید) را به تغییر دهید

vector-instance اگر نمی توانید آن را تغییر دهید، به یاد داشته باشید که از شناسه نمونه خود در همه مراجع بعدی استفاده کنید .

توجه داشته باشید که ایجاد Cluster حدود 10 دقیقه طول خواهد کشید. پس از موفقیت آمیز بودن، باید صفحه ای را ببینید که نمای کلی خوشه شما را که به تازگی ایجاد کرده اید نشان می دهد.

4. بلع داده ها

اکنون زمان اضافه کردن یک جدول با داده های مربوط به فروشگاه است. به AlloyDB بروید، خوشه اصلی و سپس AlloyDB Studio را انتخاب کنید:

ممکن است لازم باشد منتظر بمانید تا ایجاد نمونه شما به پایان برسد. پس از آن، با استفاده از اعتبارنامه هایی که هنگام ایجاد کلاستر ایجاد کردید، وارد AlloyDB شوید. از داده های زیر برای احراز هویت در PostgreSQL استفاده کنید:

• نام کاربری: " postgres "
• پایگاه داده: " postgres "
• رمز عبور: " alloydb "

هنگامی که با موفقیت در AlloyDB Studio احراز هویت شدید، دستورات SQL در ویرایشگر وارد می شوند. می‌توانید چندین پنجره ویرایشگر را با استفاده از علامت مثبت در سمت راست آخرین پنجره اضافه کنید.

در صورت لزوم با استفاده از گزینه‌های Run، Format و Clear، دستورات AlloyDB را در پنجره‌های ویرایشگر وارد می‌کنید.

برنامه های افزودنی را فعال کنید

برای ساخت این برنامه از پسوندهای pgvector و google_ml_integration استفاده خواهیم کرد. پسوند pgvector به شما امکان می دهد جاسازی های برداری را ذخیره و جستجو کنید. پسوند google_ml_integration توابعی را ارائه می دهد که شما برای دسترسی به نقاط پایانی پیش بینی هوش مصنوعی Vertex برای دریافت پیش بینی در SQL استفاده می کنید. با اجرای DDL های زیر این افزونه ها را فعال کنید :

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

اگر می خواهید افزونه هایی را که در پایگاه داده شما فعال شده اند بررسی کنید، این دستور SQL را اجرا کنید:

select extname, extversion from pg_extension;

یک جدول ایجاد کنید

می توانید با استفاده از دستور DDL زیر در استودیو AlloyDB یک جدول ایجاد کنید:

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 اجازه ذخیره سازی مقادیر برداری متن را می دهد.

اعطای مجوز

دستور زیر را اجرا کنید تا در تابع "embedding" اجرا شود:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

ROLE کاربر Vertex AI را به حساب سرویس AlloyDB اعطا کنید

از کنسول Google Cloud IAM ، به حساب سرویس AlloyDB (که به نظر می رسد: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) به نقش "کاربر Vertex AI" اجازه دسترسی دهید. PROJECT_NUMBER شماره پروژه شما را خواهد داشت.

یا می توانید دستور زیر را از ترمینال Cloud Shell اجرا کنید:

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"

بارگذاری اطلاعات ثبت اختراع در پایگاه داده

مجموعه داده های عمومی پتنت های Google در BigQuery به عنوان مجموعه داده ما استفاده خواهد شد. ما از AlloyDB Studio برای اجرای پرس و جوهای خود استفاده خواهیم کرد. منبع داده ها در این فایل insert_scripts.sql است و ما این را برای بارگیری داده های حق اختراع اجرا می کنیم.

1. در کنسول Google Cloud، صفحه AlloyDB را باز کنید.
2. خوشه تازه ایجاد شده خود را انتخاب کنید و روی نمونه کلیک کنید.
3. در منوی مسیریابی AlloyDB، روی AlloyDB Studio کلیک کنید. با اعتبار خود وارد شوید.
4. با کلیک بر روی نماد برگه جدید در سمت راست، یک برگه جدید باز کنید.
5. عبارت insert query را از اسکریپت insert_scripts.sql که در بالا ذکر شد در ویرایشگر کپی کنید. شما می توانید 10-50 عبارت insert را برای نمایش سریع این مورد استفاده کپی کنید.
6. روی Run کلیک کنید. نتایج جستجوی شما در جدول نتایج ظاهر می شود.

5. ایجاد جاسازی برای داده های ثبت اختراع

ابتدا اجازه دهید تابع embedding را با اجرای پرس و جوی نمونه زیر آزمایش کنیم:

SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');

این باید بردار embeddings را که شبیه آرایه ای از شناورها است، برای متن نمونه در پرس و جو برگرداند. به نظر می رسد این است:

فیلد abstract_embeddings Vector را به روز کنید

DML زیر را اجرا کنید تا چکیده های ثبت اختراع در جدول را با جاسازی های مربوطه به روز کنید:

UPDATE patents_data set abstract_embeddings = embedding( 'text-embedding-005', abstract);

6. جستجوی برداری را انجام دهید

اکنون که جدول، داده‌ها، جاسازی‌ها آماده هستند، بیایید جستجوی برداری واقعی را برای متن جستجوی کاربر انجام دهیم. شما می توانید این را با اجرای پرس و جو زیر تست کنید:

SELECT id || ' - ' || title as title FROM patents_data ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

در این پرس و جو،

1. متن جستجو شده توسط کاربر این است: "تحلیل احساسات".
2. ما آن را با استفاده از مدل text-embedding-005 به embeddings در متد embedding() تبدیل می کنیم.
3. "<=>" نشان دهنده استفاده از روش فاصله COSINE SIMILARITY است.
4. ما در حال تبدیل نتیجه روش embedding به نوع برداری هستیم تا آن را با بردارهای ذخیره شده در پایگاه داده سازگار کنیم.
5. LIMIT 10 نشان دهنده این است که ما در حال انتخاب 10 نزدیکترین مطابقت متن جستجو هستیم.

AlloyDB Vector Search RAG را به سطح بعدی می برد:

تعداد خوبی از چیزها معرفی شده است. دو مورد از برنامه‌نویسان متمرکز عبارتند از:

1. فیلتر درون خطی
2. فراخوان ارزیاب

فیلتر درون خطی

قبلاً به‌عنوان یک توسعه‌دهنده، باید کوئری جستجوی برداری را انجام می‌دادید و باید با فیلتر کردن و فراخوانی آن مقابله کنید. AlloyDB Query Optimizer نحوه اجرای پرس و جو با فیلترها را انتخاب می کند. فیلتر درون خطی، یک تکنیک جدید بهینه‌سازی پرس و جو است که به بهینه‌ساز پرس و جو AlloyDB اجازه می‌دهد تا شرایط فیلتر ابرداده و جستجوی برداری را در کنار آن ارزیابی کند و از شاخص‌های برداری و شاخص‌های روی ستون‌های ابرداده استفاده کند. این باعث افزایش عملکرد یادآوری شده است و به توسعه دهندگان این امکان را می دهد تا از آنچه که AlloyDB ارائه می دهد استفاده کنند.

فیلتر درون خطی برای موارد با گزینش پذیری متوسط ​​بهترین است. همانطور که AlloyDB در میان شاخص برداری جستجو می کند، فقط فاصله ها را برای بردارهایی محاسبه می کند که با شرایط فیلتر ابرداده مطابقت دارند (فیلترهای عملکردی شما در یک پرس و جو معمولاً در عبارت WHERE استفاده می شوند). این به طور گسترده ای عملکرد این پرسش ها را بهبود می بخشد و مزایای پس فیلتر یا پیش فیلتر را تکمیل می کند.

1. پسوند pgvector را نصب یا به روز کنید

CREATE EXTENSION IF NOT EXISTS vector WITH VERSION '0.8.0.google-3';

اگر پسوند pgvector قبلاً نصب شده است، پسوند برداری را به نسخه 0.8.0.google-3 یا جدیدتر ارتقا دهید تا قابلیت‌های ارزیابی فراخوان را دریافت کنید.

ALTER EXTENSION vector UPDATE TO '0.8.0.google-3';

این مرحله فقط در صورتی باید اجرا شود که پسوند برداری شما <0.8.0.google-3 باشد.

نکته مهم: اگر تعداد ردیف شما کمتر از 100 باشد، در وهله اول نیازی به ایجاد نمایه ScaNN نخواهید داشت زیرا برای ردیف های کمتر اعمال نمی شود. لطفا در این صورت مراحل زیر را نادیده بگیرید.

2. برای ایجاد نمایه های ScaNN، پسوند alloydb_scann را نصب کنید.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

3. ابتدا درخواست جستجوی برداری را بدون ایندکس و بدون فعال بودن فیلتر درون خطی اجرا کنید:

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;

نتیجه باید شبیه به:

4. Explain Analyze را روی آن اجرا کنید: (بدون ایندکس و فیلتر درون خطی)

زمان اجرا 2.4 میلی ثانیه است

5. بیایید یک نمایه معمولی در فیلد num_claims ایجاد کنیم تا بتوانیم بر اساس آن فیلتر کنیم:

CREATE INDEX idx_patents_data_num_claims ON patents_data (num_claims);

6. بیایید فهرست ScaNN را برای برنامه جستجوی پتنت خود ایجاد کنیم. موارد زیر را از AlloyDB Studio خود اجرا کنید:

CREATE INDEX patent_index ON patents_data 
USING scann (abstract_embeddings cosine)
WITH (num_leaves=32);

نکته مهم: (num_leaves=32) برای کل مجموعه داده ما با بیش از 1000 ردیف اعمال می شود. اگر تعداد ردیف شما کمتر از 100 باشد، در وهله اول نیازی به ایجاد نمایه نخواهید داشت زیرا برای ردیف های کمتر اعمال نمی شود.

7. فیلتر درون خطی را در فهرست ScaNN فعال کنید:

SET scann.enable_inline_filtering = on

8. اکنون، بیایید همان کوئری را با فیلتر و جستجوی برداری در آن اجرا کنیم:

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;

همانطور که می بینید زمان اجرا برای همان Vector Search به میزان قابل توجهی کاهش می یابد. Inline Filtering ایندکس ScaNN را در جستجوی برداری ایجاد کرده است که این امکان را فراهم کرده است!!!

در مرحله بعد، بیایید فراخوانی را برای این جستجوی برداری فعال ScaNN ارزیابی کنیم.

فراخوان ارزیاب

یادآوری در جستجوی شباهت درصد موارد مرتبطی است که از یک جستجو بازیابی شده‌اند، یعنی تعداد موارد مثبت واقعی. این رایج ترین معیاری است که برای اندازه گیری کیفیت جستجو استفاده می شود. یکی از منابع از دست دادن یادآوری از تفاوت بین جستجوی تقریبی نزدیکترین همسایه یا aNN و k (دقیق) جستجوی نزدیکترین همسایه یا kNN ناشی می شود. شاخص‌های برداری مانند ScaNN AlloyDB الگوریتم‌های aNN را پیاده‌سازی می‌کنند و به شما این امکان را می‌دهند که جستجوی برداری را در مجموعه داده‌های بزرگ در ازای یک معاوضه کوچک در یادآوری سرعت بخشید. اکنون، AlloyDB این امکان را برای شما فراهم می کند که این مبادله را مستقیماً در پایگاه داده برای پرس و جوهای فردی اندازه گیری کنید و از پایداری آن در طول زمان اطمینان حاصل کنید. برای دستیابی به نتایج و عملکرد بهتر، می توانید پارامترهای پرس و جو و فهرست را در پاسخ به این اطلاعات به روز کنید.

می توانید فراخوانی برای یک پرس و جو برداری را در یک شاخص برداری برای یک پیکربندی معین با استفاده از تابع ارزیابی_query_recall پیدا کنید. این تابع به شما امکان می دهد پارامترهای خود را تنظیم کنید تا به نتایج فراخوانی پرس و جو برداری که می خواهید برسید. یادآوری معیاری است که برای کیفیت جستجو استفاده می شود و به عنوان درصدی از نتایج بازگشتی که به طور عینی نزدیک به بردارهای پرس و جو هستند تعریف می شود. تابع value_query_recal به طور پیش فرض روشن است.

نکته مهم:

اگر در مراحل زیر با خطای رد مجوز در نمایه HNSW مواجه هستید، فعلاً از این بخش ارزیابی فراخوان کامل صرفنظر کنید. ممکن است در این مرحله با محدودیت‌های دسترسی مرتبط باشد زیرا در زمان مستندسازی این کد لبه منتشر شده است.

1. پرچم Enable Index Scan را روی فهرست ScaNN Index & HNSW تنظیم کنید:

SET scann.enable_indexscan = on
SET hnsw.enable_index_scan = on

2. کوئری زیر را در AlloyDB Studio اجرا کنید:

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']);

تابع value_query_recall پرس و جو را به عنوان پارامتر می گیرد و فراخوانی آن را برمی گرداند. من از همان پرس و جوی استفاده می کنم که برای بررسی عملکرد به عنوان پرس و جو ورودی تابع استفاده کردم. من SCaNN را به عنوان روش شاخص اضافه کرده ام. برای گزینه های پارامتر بیشتر به مستندات مراجعه کنید.

فراخوانی برای این عبارت جستجوی برداری که از آن استفاده کرده ایم:

من می بینم که RECALL 70٪ است. اکنون می توانم از این اطلاعات برای تغییر پارامترهای شاخص، روش ها و پارامترهای پرس و جو و بهبود فراخوانی خود برای این جستجوی برداری استفاده کنم!

من تعداد سطرها را در مجموعه نتیجه به 7 تغییر دادم (از 10 مورد قبلی) و یک ReCALL کمی بهبود یافته، یعنی 86%.

این بدان معناست که در زمان واقعی می‌توانم تعداد منطبق‌هایی را که کاربرانم می‌بینند تغییر دهم تا ارتباط منطبق‌ها را مطابق با زمینه جستجوی کاربران بهبود بخشم.

خوب حالا! زمان استقرار منطق پایگاه داده و حرکت به سمت عامل است!!!

7. منطق پایگاه داده را بدون سرور به وب سرور ببرید

برای بردن این برنامه به وب آماده هستید؟ مراحل زیر را دنبال کنید:

1. برای ایجاد یک عملکرد Cloud Run جدید، به Cloud Run Functions در Google Cloud Console بروید یا از پیوند استفاده کنید: https://console.cloud.google.com/functions/add .
2. Environment را به عنوان " عملکرد Cloud Run " انتخاب کنید. نام تابع " patent-search " را وارد کنید و منطقه را به عنوان " us-central1 " انتخاب کنید. Authentication را روی " Allow unauthenticated invocations " تنظیم کنید و روی NEXT کلیک کنید. جاوا 17 را به عنوان زمان اجرا و ویرایشگر داخلی را برای کد منبع انتخاب کنید.
3. به طور پیش فرض نقطه ورودی را روی " gcfv2.HelloHttpFunction " تنظیم می کند. کد مکان نگهدار در HelloHttpFunction.java و pom.xml تابع Cloud Run خود را به ترتیب با کدهای « PatentSearch.java » و « pom.xml » جایگزین کنید. نام فایل کلاس را به PatentSearch.java تغییر دهید.
4. به یاد داشته باشید که مکان نگهدار ************* و اعتبار اتصال AlloyDB را با مقادیر خود در فایل جاوا تغییر دهید. اعتبارنامه های AlloyDB آنهایی هستند که در ابتدای این کد لبه استفاده کرده بودیم. اگر از مقادیر متفاوتی استفاده کرده اید، لطفاً همان را در فایل جاوا تغییر دهید.
5. روی Deploy کلیک کنید.

گام مهم:

پس از استقرار، برای اینکه به تابع Cloud اجازه دهیم به نمونه پایگاه داده AlloyDB ما دسترسی پیدا کند، ما کانکتور VPC را ایجاد می کنیم.

هنگامی که برای استقرار راه افتادید، باید بتوانید عملکردها را در کنسول Google Cloud Run Functions مشاهده کنید. تابع تازه ایجاد شده (پتنت-جستجو) را جستجو کنید، روی آن کلیک کنید، سپس روی EDIT AND DEPLOY NEW REVISIONS (که با نماد EDIT (قلم) در بالای کنسول Cloud Run Functions مشخص می شود) کلیک کنید و موارد زیر را تغییر دهید:

1. به تب Networking بروید:

2. " Connect to a VPC for Outbound Traffic " را انتخاب کنید و سپس " Use Serverless VPC Access Connectors " را انتخاب کنید.
3. در قسمت کشویی Network، تنظیمات، روی منوی کشویی Network کلیک کنید و گزینه " Add New VPC Connector " را انتخاب کنید (اگر قبلاً اتصال پیش فرض را پیکربندی نکرده اید) و دستورالعمل هایی را که در کادر محاوره ای ظاهر می شود دنبال کنید:

4. نامی برای اتصال VPC ارائه دهید و مطمئن شوید که منطقه با نمونه شما یکسان است. مقدار Network را به عنوان پیش فرض بگذارید و Subnet را به عنوان محدوده IP سفارشی با محدوده IP 10.8.0.0 یا چیزی مشابه که در دسترس است تنظیم کنید.
5. SHOW SCALING SETTINGS را باز کنید و مطمئن شوید که پیکربندی دقیقاً روی موارد زیر تنظیم شده است:

6. روی CREATE کلیک کنید و این رابط باید اکنون در تنظیمات خروج لیست شود.
7. کانکتور تازه ایجاد شده را انتخاب کنید.
8. انتخاب کنید که تمام ترافیک از طریق این رابط VPC هدایت شود.
9. روی NEXT و سپس DEPLOY کلیک کنید.
10. پس از به روز رسانی Cloud Function، باید نقطه پایانی تولید شده را ببینید. آن را کپی کرده و در دستور زیر جایگزین کنید:

PROJECT_ID=$(gcloud config get-value project)

curl -X POST <<YOUR_ENDPOINT>> \
  -H 'Content-Type: application/json' \
  -d '{"search":"Sentiment Analysis"}'

همین! انجام یک جستجوی بردار تشابه متنی پیشرفته با استفاده از مدل Embeddings در داده های AlloyDB بسیار ساده است.

8. بیایید عامل را با جاوا ADK بسازیم

ابتدا اجازه دهید با پروژه جاوا در ویرایشگر شروع کنیم.

1. به ترمینال Cloud Shell بروید

https://shell.cloud.google.com/?fromcloudshell=true&show=ide%2Cterminal

2. وقتی از شما خواسته شد مجوز بدهید
3. با کلیک بر روی نماد ویرایشگر از بالای کنسول Cloud Shell به ویرایشگر Cloud Shell بروید.

4. در کنسول Cloud Shell Editor، یک پوشه جدید ایجاد کنید و نام آن را "adk-agents" بگذارید.

مطابق شکل زیر روی ایجاد پوشه جدید در پوشه ریشه پوسته ابری خود کلیک کنید:

نام آن را adk-agents بگذارید:

5. ساختار پوشه زیر و فایل های خالی را با نام فایل های مربوطه در ساختار زیر ایجاد کنید:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java

6. مخزن github را در یک تب جداگانه باز کنید و کد منبع فایل های App.java و pom.xml را کپی کنید.
7. اگر ویرایشگر را در یک برگه جدید با استفاده از نماد "Open in new tab" در گوشه سمت راست بالا باز کرده اید، می توانید ترمینال را در پایین صفحه باز کنید. می توانید هم ویرایشگر و هم ترمینال را به صورت موازی باز کنید و به شما امکان می دهد آزادانه کار کنید.
8. پس از شبیه سازی، به کنسول Cloud Shell Editor برگردید
9. از آنجایی که ما قبلاً عملکرد Cloud Run را ایجاد کرده ایم، نیازی به کپی کردن فایل های تابع Cloud Run از پوشه repo ندارید.

شروع به کار با ADK Java SDK

نسبتاً سرراست است. شما در درجه اول باید اطمینان حاصل کنید که موارد زیر در مرحله کلون شما پوشش داده شده است:

1. افزودن وابستگی ها:

مصنوعات google-adk و google-adk-dev (برای رابط کاربری وب) را در pom.xml خود قرار دهید.

<!-- 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>

مطمئن شوید که به pom.xml از مخزن منبع ارجاع می دهید زیرا وابستگی ها و پیکربندی های دیگری وجود دارد که برای اجرای برنامه مورد نیاز است.

2. پروژه خود را پیکربندی کنید:

مطمئن شوید که نسخه جاوا (17+ توصیه می شود) و تنظیمات کامپایلر Maven شما به درستی در pom.xml پیکربندی شده اند. شما می توانید پروژه خود را به گونه ای پیکربندی کنید که ساختار زیر را دنبال کند:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java

3. تعریف عامل و ابزارهای آن (App.java):

اینجاست که جادوی ADK Java SDK می درخشد. ما عامل خود، قابلیت های آن (دستورالعمل ها) و ابزارهایی را که می تواند استفاده کند تعریف می کنیم.

یک نسخه ساده شده از چند قطعه کد کلاس عامل اصلی را در اینجا پیدا کنید. برای پروژه کامل به مخزن پروژه اینجا مراجعه کنید.

// 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)
    }
}

اجزای کلیدی کد جاوا ADK برجسته شده:

1. LlmAgent.builder(): API روان برای پیکربندی عامل شما.
2. .instruction(...): دستورات و دستورالعمل های اصلی را برای LLM ارائه می دهد، از جمله زمان استفاده از کدام ابزار.
3. FunctionTool.create (App.class، "methodName"): به راحتی متدهای جاوا شما را به عنوان ابزارهایی که عامل می تواند فراخوانی کند، ثبت می کند. رشته نام متد باید با یک روش استاتیک عمومی واقعی مطابقت داشته باشد.
4. @Schema(description = ...): پارامترهای ابزار را حاشیه نویسی می کند و به LLM کمک می کند تا بفهمد هر ابزار چه ورودی هایی را انتظار دارد. این توضیحات برای انتخاب دقیق ابزار و پر کردن پارامتر بسیار مهم است.
5. InvocationContext ctx: به طور خودکار به روش‌های ابزار منتقل می‌شود و به وضعیت جلسه (ctx.session().state())، اطلاعات کاربر و موارد دیگر دسترسی می‌دهد.
6. .outputKey ("اختراعات"): هنگامی که ابزاری داده ها را برمی گرداند، ADK می تواند به طور خودکار آنها را در حالت جلسه تحت این کلید ذخیره کند. به این ترتیب توضیحPatent می تواند به نتایج getPatents دسترسی پیدا کند.
7. VECTOR_SEARCH_ENDPOINT: این متغیری است که منطق عملکردی اصلی را برای پرسش و پاسخ متنی برای کاربر در مورد استفاده جستجوی اختراع نگه می‌دارد.
8. مورد اقدام در اینجا: شما باید یک مقدار نقطه پایانی مستقر به روز شده را تنظیم کنید، پس از اجرای مرحله Java Cloud Run Function از بخش قبل.
9. searchTool : با کاربر درگیر می شود تا مطابق با زمینه مربوط به پتنت را از پایگاه داده پتنت برای متن جستجوی کاربر بیابد.
10. توضیح ابزار : این از کاربر یک پتنت خاص برای غواصی در عمق می خواهد. سپس چکیده اختراع را خلاصه می کند و برای پاسخ به سوالات بیشتر کاربر بر اساس جزئیات ثبت اختراع که دارد قوزک پا است.

نکته مهم: مطمئن شوید که متغیر VECTOR_SEARCH_ENDPOINT را با نقطه پایانی CRF مستقر شده خود جایگزین کنید.

استفاده از InvocationContext برای تعاملات حالت دار

یکی از ویژگی های حیاتی برای ساخت عوامل مفید، مدیریت حالت در چندین نوبت یک مکالمه است. InvocationContext ADK این را ساده می کند.

در App.java ما:

1. هنگامی که initAgent() تعریف می شود، از .outputKey ("اختراعات") استفاده می کنیم. این به ADK می‌گوید که وقتی ابزاری (مانند getPatents) داده‌ها را در قسمت گزارش خود برمی‌گرداند، آن داده‌ها باید در حالت جلسه تحت کلید "اختراعات" ذخیره شوند.
2. در روش ابزار توضیح پتنت، InvocationContext ctx را تزریق می کنیم:

public static Map<String, String> explainPatent(
    @Schema(description = "...") String patentId, InvocationContext ctx) {
    String previousResults = (String) ctx.session().state().get("patents");
    // ... use previousResults ...
}

این به ابزار توضیح پتنت اجازه می دهد تا به لیست ثبت اختراع دریافت شده توسط ابزار getPatents در نوبت قبلی دسترسی پیدا کند و مکالمه را حالتی و منسجم کند.

9. تست CLI محلی

تعریف متغیرهای محیطی

شما باید دو متغیر محیطی را صادر کنید:

1. یک کلید Gemini که می توانید از AI Studio دریافت کنید:

برای انجام این کار، به https://aistudio.google.com/apikey بروید و کلید API را برای پروژه Google Cloud فعال خود که در حال پیاده سازی این برنامه در آن هستید دریافت کنید و کلید را در جایی ذخیره کنید:

1. هنگامی که کلید را به دست آوردید، Cloud Shell Terminal را باز کنید و با اجرای دستور زیر به دایرکتوری جدیدی بروید که adk-agents را ایجاد کردیم:

cd adk-agents

2. متغیری که مشخص می کند این بار از Vertex AI استفاده نمی کنیم.

export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=AIzaSyDF...

3. اولین عامل خود را روی CLI اجرا کنید

برای راه اندازی اولین عامل، از دستور Maven زیر در ترمینال خود استفاده کنید:

mvn compile exec:java -DmainClass="agents.App"

پاسخ تعاملی نماینده را در ترمینال خود خواهید دید.

10. استقرار در Cloud Run

استقرار عامل جاوا ADK خود در Cloud Run مشابه استقرار هر برنامه جاوا دیگری است:

1. Dockerfile: یک Dockerfile برای بسته بندی برنامه جاوا خود ایجاد کنید.
2. Build & Push Docker Image: از Google Cloud Build and Artifact Registry استفاده کنید.
3. شما می توانید مرحله فوق را انجام داده و در Cloud Run تنها با یک دستور مستقر کنید:

gcloud run deploy --source . --set-env-vars GOOGLE_API_KEY=<<Your_Gemini_Key>>

به طور مشابه، شما می‌توانید عملکرد Java Cloud Run (gcfv2.PatentSearch) خود را مستقر کنید. از طرف دیگر، می توانید تابع Java Cloud Run را برای منطق پایگاه داده مستقیماً از کنسول Cloud Run Function ایجاد و استقرار دهید.

11. تست با رابط کاربری وب

ADK با یک رابط کاربری وب مفید برای آزمایش محلی و اشکال زدایی عامل شما ارائه می شود. هنگامی که App.java خود را به صورت محلی اجرا می کنید (مثلاً mvn exec:java -Dexec.mainClass="agents.App" در صورت پیکربندی، یا فقط روش اصلی را اجرا می کنید)، ADK معمولاً یک وب سرور محلی راه اندازی می کند.

رابط کاربری وب ADK به شما اجازه می دهد:

1. برای نماینده خود پیام ارسال کنید.
2. رویدادها (پیام کاربر، تماس ابزار، پاسخ ابزار، پاسخ LLM) را ببینید.
3. وضعیت جلسه را بررسی کنید
4. مشاهده سیاهههای مربوط و آثار.

این در طول توسعه برای درک اینکه چگونه نماینده شما درخواست ها را پردازش می کند و از ابزارهای آن استفاده می کند بسیار ارزشمند است. این فرض را بر این می‌گذارد که کلاس اصلی شما در pom.xml روی com.google.adk.web.AdkWebServer تنظیم شده است و نماینده شما در آن ثبت شده است، یا شما در حال اجرای یک تست محلی هستید که این موضوع را فاش می‌کند.

هنگامی که App.java خود را با InMemoryRunner و Scanner برای ورودی کنسول اجرا می کنید، منطق عامل اصلی را آزمایش می کنید. رابط کاربری وب یک مؤلفه جداگانه برای یک تجربه اشکال زدایی بصری است که اغلب زمانی استفاده می شود که ADK به عامل شما از طریق HTTP سرویس می دهد.

برای راه اندازی سرور محلی SpringBoot می توانید از دستور Maven زیر از دایرکتوری ریشه خود استفاده کنید:

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"

این رابط اغلب در URL که فرمان فوق با آن خروجی می‌دهد قابل دسترسی است. اگر Cloud Run Deployed است، باید بتوانید از پیوند Cloud Run Deployed به آن دسترسی داشته باشید.

شما باید بتوانید نتیجه را در یک رابط تعاملی ببینید.

ویدیوی زیر را برای نماینده ثبت اختراع مستقر ما بررسی کنید:

نسخه ی نمایشی یک نماینده ثبت اختراع کنترل شده با کیفیت با جستجوی درونی و ارزیابی فراخوان AlloyDB!

12. پاک کن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این پست، این مراحل را دنبال کنید:

1. در کنسول Google Cloud، به https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog بروید
2. https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source= صفحه وبلاگ.
3. در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
4. در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.

13. تبریک میگم

تبریک می گویم! شما با ترکیب قابلیت‌های ADK، https://cloud.google.com/alloydb/docs?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source و Verxternal&utm_source و Verx. یک جهش بزرگ به جلو در ایجاد جستجوهای مشابه متنی بسیار متحول کننده، کارآمد و واقعاً معنادار انجام داد.

همین امروز شروع کنید!

اسناد ADK: [پیوند به اسناد رسمی ADK Java]

کد منبع نماینده تجزیه و تحلیل پتنت: [پیوند به مخزن GitHub (اکنون عمومی) شما]

عوامل نمونه جاوا: [پیوند به مخزن adk-samples]

به انجمن ADK بپیوندید: https://www.reddit.com/r/agentdevelopmentkit/

ساختمان عامل مبارک!