1. مقدمه
چیزی که خواهی ساخت
در این کد لبه، یاد خواهید گرفت که چگونه یک دستیار هوش مصنوعی Sports Shop Agent بسازید. این نسل بعدی برنامه کاربردی Agent AI که توسط ADK ، MCP Toolbox و AlloyDB پشتیبانی می‌شود، به کاربران در انجام وظایف مختلف، از جمله:
- جستجوی محصولات با استفاده از زبان طبیعی
- یافتن فروشگاه های نزدیک برای خرید محصولات توصیه شده.
- ثبت سفارشات جدید.
- بررسی وضعیت سفارشات موجود
- به روز رسانی سفارش ها با روش های تحویل ترجیحی.
چیزی که یاد خواهید گرفت
- تهیه و پر کردن یک AlloyDB برای پایگاه داده PostgreSQL.
- راه اندازی جعبه ابزار MCP برای پایگاه های داده با AlloyDB خود برای نمونه PostgreSQL.
- طراحی و توسعه یک عامل هوش مصنوعی با استفاده از کیت توسعه عامل (ADK) برای کمک به سوالات فروشگاه های ورزشی.
- آزمایش Agent و جعبه ابزار MCP خود برای پایگاه داده در یک محیط ابری.
- استفاده از قابلیت‌های جستجوی پیشرفته AlloyDB برای پاسخ‌های عامل هوشمند.
آنچه شما نیاز دارید
برای تکمیل این کد لبه، شما نیاز دارید:
- یک مرورگر وب کروم.
- یک اکانت جیمیل
- یک پروژه Google Cloud با فعال کردن صورتحساب.
این کد لبه برای توسعه دهندگان در تمام سطوح از جمله مبتدیان طراحی شده است.
2. قبل از شروع
قبل از اینکه بتوانید ساخت دستیار هوش مصنوعی Sports Shop Agent را شروع کنید، این بخش شما را از طریق تنظیمات اولیه مورد نیاز در پروژه Google Cloud خود راهنمایی می کند.
یک پروژه ایجاد کنید
- در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورتحساب در پروژه آشنا شوید.
- Cloud Shell را با کلیک بر روی این پیوند فعال کنید. می توانید با کلیک بر روی دکمه مربوطه از Cloud Shell بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه ها) جابه جا شوید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- متغیر PROJECT_ID را تنظیم کنید، از دستور زیر برای تنظیم آن استفاده کنید:
export PROJECT_ID=[YOUR_PROJECT_ID]
gcloud config set project $PROJECT_ID
- API های زیر را با اجرای دستورات زیر فعال کنید:
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
vpcaccess.googleapis.com \
aiplatform.googleapis.com
3. نمونه AlloyDB را ایجاد کنید
در این بخش، کلاستر و نمونه پایگاه داده AlloyDB خود را راه اندازی می کنید و شبکه و مجوزهای لازم را برای عامل هوش مصنوعی خود پیکربندی می کنید.
ابتدا دستور زیر را در ترمینال Cloud Shell خود اجرا کنید تا AlloyDB Cluster ایجاد شود:
gcloud alloydb clusters create alloydb-cluster \
--password=alloydb\
--network=default \
--region=us-central1 \
--database-version=POSTGRES_16
AlloyDB برای دسترسی ایمن و با کارایی بالا به اتصال IP خصوصی متکی است. شما باید یک محدوده IP خصوصی را در VPC خود اختصاص دهید تا Google از آن برای اتصال همتا سرویس به زیرساخت شبکه خدماتی تحت مدیریت Google استفاده کند. دستور زیر را اجرا کنید:
gcloud compute addresses create peering-range-for-alloydb \
--global \
--purpose=VPC_PEERING \
--prefix-length=16 \
--description="Automatically allocated IP range for service networking" \
--network=default
بعد، اتصال VPC Service Peering را ایجاد کنید. این به شبکه Google Cloud Virtual Private Cloud (VPC) شما اجازه می دهد تا به صورت ایمن و خصوصی با سرویس های مدیریت شده Google از جمله AlloyDB ارتباط برقرار کند. دستور زیر را اجرا کنید:
gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default
اکنون، نمونه اولیه را در خوشه AlloyDB خود ایجاد کنید. این نقطه پایانی پایگاه داده واقعی است که برنامه های کاربردی شما به آن متصل می شوند. دستور زیر را برای ایجاد یک نمونه AlloyDB اجرا کنید:
gcloud alloydb instances create alloydb-inst \
--instance-type=PRIMARY \
--cpu-count=2 \
--region=us-central1 \
--cluster=alloydb-cluster \
--availability-type=ZONAL \
--ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED
توجه: ایجاد نمونه تقریباً 10 دقیقه طول می کشد. لطفاً قبل از ادامه، منتظر بمانید تا این عملیات به پایان برسد.
Vertex AI Integration را فعال کنید
برای اجازه دادن به نمونه AlloyDB شما برای انجام پرس و جوهای جستجوی برداری (که برای عملکردهای هوش مصنوعی مانند جستجوی معنایی ضروری هستند) و مدل های فراخوانی مستقر در Vertex AI، باید مجوزهای Vertex AI را به AlloyDB Service Agent بدهید.
ابتدا، شماره پروژه Google Cloud خود را بازیابی کنید، زیرا برای اتصال IAM لازم است.
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"
سپس مجوز Vertex AI را به AlloyDB Service Agent بدهید:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
IP عمومی را فعال کنید
در آماده سازی برای مراحل زیر، اتصال IP عمومی را در نمونه AlloyDB خود فعال می کنیم.
در کنسول، به قسمت جستجو در وسط بالای صفحه بروید و "alloydb" را معرفی کنید، سپس ویرایش کنید و به بخش اتصال IP عمومی بروید. چک باکس «فعال کردن IP عمومی» را علامت بزنید و آدرس IP دستگاه Cloud Shell خود را وارد کنید.
برای دریافت IP دستگاه Cloud Shell خود، به Cloud Shell Terminal بروید و دستور "ifconfig | grep -A 1 eth0" را وارد کنید. از نتیجه، 2 رقم آخر را با 0.0 با اندازه ماسک '/16' جایگزین کنید. به عنوان مثال به نظر می رسد "XX.XX.0.0/16" که در آن XX اعداد هستند.
این IP را در کادر متنی «شبکه‌ها» شبکه‌های خارجی مجاز صفحه ویرایش نمونه قرار دهید.
توجه: عملیات به روز رسانی می تواند تا 3 دقیقه طول بکشد
4. پایگاه داده را بارگذاری کنید
پایگاه داده فروشگاه را ایجاد کنید
اکنون زمان آن است که پایگاه داده خود را ایجاد کنید و داده های اولیه را برای فروشگاه ورزشی خود بارگیری کنید.
برای فعال کردن psql برای اتصال به نمونه AlloyDB خصوصی شما از Cloud Shell، از AlloyDB Auth Proxy استفاده خواهید کرد. این ابزار به طور ایمن اتصال شما به پایگاه داده را تونل می کند. (به AlloyDB Auth Proxy مراجعه کنید)
پروکسی AlloyDB Auth را با استفاده از دستور زیر دانلود کنید:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
آن را اجرایی کنید:
chmod +x alloydb-auth-proxy
این دستور را در اولین پنجره ترمینال Cloud Shell خود اجرا کنید. پروکسی در پس‌زمینه و اتصالات رو به جلو اجرا می‌شود.
./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip
مهم: این پنجره ترمینال را باز بگذارید و پروکسی را اجرا کنید. آن را نبندید.
یک پنجره ترمینال جدید در Cloud Shell باز کنید (روی نماد + در کنار تب "Cloud Shell Terminal" در بالا کلیک کنید).
با استفاده از psql به نمونه AlloyDB متصل شوید:
psql -h 127.0.0.1 -U postgres
توجه: هنگامی که از شما خواسته شد، رمز عبوری را که برای کاربر postgres در طول ایجاد خوشه تنظیم کرده‌اید، وارد کنید (اگر مستقیماً مستندات را دنبال می‌کنید، رمز عبور alloydb است).
و پایگاه داده فروشگاه را برای برنامه ما ایجاد کنید (دستورات را یکی یکی اجرا کنید):
CREATE DATABASE store;
\c store
exit
کد ما
اکنون، مخزن کد منبع کد لبه را شبیه سازی کنید. قبل از کلون کردن مطمئن شوید که در فهرست اصلی خود یا مکان مناسبی هستید و دستور زیر را اجرا کنید:
git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git
پایگاه داده را پر کنید
برای دسترسی به فایل dump پایگاه داده به پوشه data پروژه کلون شده بروید.
cd sports-agent-adk-mcp-alloydb/data
سپس مجموعه داده نمونه را با استفاده از فایل store_backup.sql از مخزن وارد پایگاه داده store خود کنید.
psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql
توجه: ممکن است برخی از پیام‌های هشدار و خطا را در طول این وارد کردن مشاهده کنید، که می‌توان آنها را برای این کد کد نادیده گرفت. اینها اغلب به مجوزها یا اشیایی مربوط می‌شوند که از قبل وجود داشته‌اند، در صورتی که dump حاوی طرح کامل باشد. برخی از هشدارها و خطاها را خواهید دید که می‌توان آنها را نادیده گرفت.
5. راه اندازی سرویس مجوز
در این بخش، سرویس مجوز را برای برنامه خود راه اندازی می کنید. این سرویس برای ایمن کردن دسترسی و محافظت در برابر آسیب‌پذیری‌های تزریق سریع در عامل هوش مصنوعی شما بسیار مهم است.
ابتدا یک کاربر نمونه را به جدول users در پایگاه داده store خود اضافه می کنید. این کاربر برای احراز هویت در برنامه شما استفاده خواهد شد.
به کنسول بروید و به AlloyDB بروید، نمونه اولیه و سپس AlloyDB Studio را انتخاب کنید:
هنگامی که از شما خواسته شد، با استفاده از اعتبارنامه‌هایی که هنگام راه‌اندازی خوشه ایجاد کردید ، وارد استودیو AlloyDB شوید:
- نام کاربری: "postgres"
- پایگاه داده: "فروشگاه"
- رمز عبور: "alloydb"
در ویرایشگر SQL، یک عبارت INSERT را اجرا کنید تا کاربر خود را به پایگاه داده اضافه کنید. نام و نام خانوادگی و آدرس ایمیل را تغییر دهید.
مهم:
- LOCATION را همانطور که در مثال است نگه دارید
- از همان آدرس ایمیلی که برای ثبت نام در Google Cloud Console استفاده می کنید استفاده کنید
INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');
در مرحله بعد، باید صفحه رضایت OAuth را برای پروژه خود پیکربندی کنید. این صفحه زمانی به کاربران نمایش داده می شود که برنامه شما درخواست دسترسی به حساب Google آنها را می دهد و نام تجاری برنامه شما را مشخص می کند.
در کنسول، به «APIs and Services»، «Google OAuth Consent» بروید:
اطلاعات زیر را برای ایجاد نام تجاری برنامه خود ارائه دهید:
- نام برنامه: "Sports Shopping Agent AI"
- ایمیل پشتیبانی کاربر: "YOUR_EMAIL"
- مخاطب: "خارجی"
- اطلاعات تماس: "YOUR_EMAIL"
اکنون، شناسه مشتری OAuth را ایجاد می کنید که برنامه frontend شما از آن برای تأیید هویت کاربر با Google استفاده می کند.
ابتدا مطمئن شوید که شماره پروژه Google Cloud خود را دارید. این برای پیکربندی صحیح URIهای تغییر مسیر مورد نیاز است. دستور زیر را در ترمینال Cloud Shell اجرا کنید:
در صورتی که متغیر PROJECT_ID شما در این پنجره Cloud Shell Terminal تنظیم نشده باشد، اجرا کنید:
export PROJECT_ID=[YOUR_PROJECT_ID]
سپس با استفاده از دستور زیر PROJECT_NUMBER را دریافت کنید:
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"
سپس، به "APIs and Services" -> "Credentials" -> "Create Credentials" -> "OAuth Client ID" بروید.
برای ایجاد اعتبار از اطلاعات زیر استفاده کنید:
- نوع برنامه: "برنامه تحت وب"
- نام: "برنامه هوش مصنوعی عامل خرید ورزشی"
منابع مجاز جاوا اسکریپت:
- URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app
URIهای مجاز تغییر مسیر:
- URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app
توجه: نشانی اینترنتی https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app نشانی اینترنتی پیش‌بینی‌شده استقرار برنامه کاربردی شما است که بعداً در این لبه کد راه‌اندازی خواهد شد. مطمئن شوید [YOUR_PROJECT_NUMBER] را با شماره واقعی که کپی کرده اید جایگزین کرده اید.
مهم: پس از ایجاد، یک پنجره بازشو شناسه مشتری OAuth و گاهی اوقات یک Client Secret نمایش داده می شود. شناسه مشتری OAuth خود را در مکانی امن ذخیره کنید ، زیرا در مرحله بعد هنگام پیکربندی ظاهر خود به آن نیاز خواهید داشت.
6. جعبه ابزار MCP برای راه اندازی پایگاه داده
جعبه ابزار بین چارچوب سازماندهی برنامه شما و پایگاه داده شما قرار می گیرد و یک صفحه کنترل را ارائه می دهد که برای اصلاح، توزیع یا فراخوانی ابزارها استفاده می شود. با ارائه یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما این امکان را می‌دهد که ابزارها را بین عوامل و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود به‌روزرسانی کنید.
از آنجایی که یکی از پایگاه‌های داده پشتیبانی شده توسط MCP Toolbox برای پایگاه‌های داده، AlloyDB است، و ما قبلاً این موضوع را در بخش قبلی ارائه کرده‌ایم، بیایید پیش برویم و Toolbox را راه‌اندازی کنیم.
ابتدا، سرور MCP Toolbox را به صورت محلی در محیط Cloud Shell خود راه اندازی می کنید تا عملکرد آن را تأیید کنید.
- در ترمینال Cloud Shell خود، به پوشه جعبه
toolboxواقع در مخزن پروژه کلون شده خود بروید:
cd sports-agent-adk-mcp-alloydb/src/toolbox
- دستورات زیر را برای دانلود باینری جعبه ابزار اجرا کنید و به آن مجوزهای اجرایی بدهید:
# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
توجه: نسخه 0.7.0 در اینجا مشخص شده است. برای محیط‌های تولید، همیشه آخرین نسخه پایدار را از صفحه نسخه‌های جعبه ابزار تأیید کرده و از آن استفاده کنید.
- به ویرایشگر پوسته ابری بروید (می توانید با کلیک کردن روی نماد ویرایشگر از ترمینال جابجا شوید).
در همان فهرست راهنمای sports-agent-adk-mcp-alloydb/src/toolbox ، فایلی به نام tools.yaml پیدا خواهید کرد. این فایل را باز کنید و جای‌بان‌ها را با شناسه مشتری OAuth و شناسه پروژه Google Cloud از مراحل قبل به‌روزرسانی کنید.
بیایید tools.yaml را بفهمیم
منابع نشان دهنده منابع داده های مختلف شما هستند که یک ابزار می تواند با آنها تعامل داشته باشد. منبع یک منبع داده را نشان می دهد که یک ابزار می تواند با آن تعامل داشته باشد. می توانید Sources را به عنوان نقشه در قسمت sources فایل tools.yaml خود تعریف کنید. به طور معمول، یک پیکربندی منبع حاوی اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده است.
ابزارها اقداماتی را که یک عامل می تواند انجام دهد را تعریف می کند - مانند خواندن و نوشتن برای یک منبع. یک ابزار عملکردی را نشان می دهد که نماینده شما می تواند انجام دهد، مانند اجرای یک دستور SQL. می توانید Tools را به عنوان نقشه در قسمت tools فایل tools.yaml خود تعریف کنید. به طور معمول، یک ابزار برای عمل کردن به یک منبع نیاز دارد.
برای جزئیات بیشتر در مورد پیکربندی tools.yaml خود، به این مستندات مراجعه کنید.
بیایید جعبه ابزار MCP را برای سرور پایگاه داده اجرا کنیم
دستور زیر را (از پوشه mcp-toolbox) برای راه اندازی سرور اجرا کنید:
./toolbox --tools-file "tools.yaml"
اکنون، اگر سرور را در حالت پیش‌نمایش وب در فضای ابری باز کنید، باید بتوانید سرور جعبه ابزار را با تمام ابزارهای برنامه ما در حال اجرا و در حال اجرا مشاهده کنید.
سرور MCP Toolbox به طور پیش فرض روی پورت 5000 اجرا می شود. اجازه دهید از Cloud Shell برای آزمایش آن استفاده کنیم.
مطابق شکل زیر روی Web Preview در Cloud Shell کلیک کنید:
بر روی Change port کلیک کنید و مطابق شکل زیر پورت را روی 5000 قرار دهید و روی Change and Preview کلیک کنید.
این باید خروجی را بیاورد:
MCP Toolkit برای پایگاه‌های داده یک SDK پایتون را برای اعتبارسنجی و آزمایش ابزارها توصیف می‌کند که در اینجا مستند شده است. ما آن را نادیده می گیریم و در بخش بعدی که از این ابزارها استفاده می کند، مستقیماً به کیت توسعه عامل (ADK) می پریم.
بیایید جعبه ابزار خود را در Cloud Run مستقر کنیم
برای اینکه سرور جعبه ابزار خود را به عنوان یک نقطه پایانی عمومی که می تواند با سایر برنامه ها و عامل هوش مصنوعی خود یکپارچه شود، در دسترس قرار دهید، آن را در Cloud Run مستقر خواهید کرد. دستورالعمل های دقیق برای میزبانی جعبه ابزار در Cloud Run در اینجا آورده شده است.
به ترمینال Cloud Shell برگردید و به پوشه جعبه ابزار بروید:
cd sports-agent-adk-mcp-alloydb/src/toolbox
مطمئن شوید که متغیر محیطی PROJECT_ID شما روی شناسه پروژه Google Cloud شما تنظیم شده است.
export PROJECT_ID=$PROJECT_ID
سپس، بررسی کنید که سرویس‌های Google Cloud زیر در پروژه فعال هستند.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
بیایید یک حساب سرویس جداگانه ایجاد کنیم که به عنوان هویت سرویس Toolbox که در Google Cloud Run اجرا خواهیم کرد، عمل می کند. ما همچنین اطمینان حاصل می کنیم که این حساب سرویس دارای نقش های صحیح است، یعنی توانایی دسترسی به Secret Manager و صحبت با AlloyDB.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
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 را به صورت مخفی آپلود می‌کنید و از آنجایی که باید جعبه ابزار را در Cloud Run نصب کنیم، می‌خواهیم از آخرین تصویر Container برای جعبه ابزار استفاده کنیم و آن را در متغیر IMAGE تنظیم کنیم.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
در نهایت، سرور جعبه ابزار خود را با استفاده از دستور زیر در Cloud Run مستقر کنید. این دستور برنامه شما را محفظه بندی می کند، حساب سرویس را پیکربندی می کند، راز را تزریق می کند و آن را به صورت عمومی نشان می دهد:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
این باید فرآیند استقرار Toolbox Server را با tools.yaml پیکربندی شده در Cloud Run آغاز کند. در استقرار موفقیت آمیز، باید پیامی شبیه به زیر مشاهده کنید:
Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app
اکنون می‌توانید از URL خدمات فهرست شده در بالا در مرورگر دیدن کنید. باید پیام "Hello World" را که قبلاً دیدیم نمایش دهد. علاوه بر این، می‌توانید برای مشاهده ابزارهای موجود، به آدرس اینترنتی زیر نیز مراجعه کنید:
https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset
همچنین می توانید از طریق کنسول Google Cloud به Cloud Run مراجعه کنید و سرویس Toolbox را در لیست خدمات موجود در Cloud Run مشاهده خواهید کرد.
7. عامل ساخته شده بر روی ADK
در این بخش، عامل هوش مصنوعی خود را که با استفاده از کیت توسعه عامل (ADK) ساخته شده است، در Cloud Run مستقر خواهید کرد.
ابتدا، APIهای لازم را در پروژه خود برای ساخت و استقرار Agent خود در Cloud Run و برای تعامل با Artifact Registry و Cloud Storage فعال کنید. دستور زیر را در ترمینال Cloud Shell خود اجرا کنید:
gcloud services enable artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
storage.googleapis.com
سپس، ما مجوزهای لازم را به حساب پیش فرض خدمات محاسباتی در پروژه خود اختصاص می دهیم. ابتدا دستور زیر را در ترمینال Cloud Shell خود اجرا کنید تا PROJECT_NUMBER را دریافت کنید:
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
مجوزها را به حساب پیش‌فرض خدمات محاسباتی اختصاص دهید:
# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"
# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"
نماینده ما را به Tools متصل کنید
ما قصد داریم Agent خود را به Tools متصل کنیم. در زمینه ADK، یک ابزار قابلیت خاصی را نشان می‌دهد که به یک عامل هوش مصنوعی ارائه می‌شود و آن را قادر می‌سازد تا اقداماتی را انجام دهد و با جهان فراتر از تولید متن اصلی و توانایی‌های استدلال خود تعامل داشته باشد.
در مورد ما، اکنون می‌خواهیم نماینده خود را با ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم، مجهز کنیم.
با استفاده از Cloud Shell Editor، به sports-agent-adk-mcp-alloydb/src/backend/ بروید و فایل "finn_agent.py" را با کد زیر ویرایش کنید. توجه داشته باشید که ما از URL سرویس Cloud Run از سرور MCP ToolBox مستقر در مرحله قبل استفاده می کنیم:
Agent ما را در Cloud Run مستقر کنید
در نهایت، عامل AI پیکربندی شده خود را در Cloud Run مستقر خواهید کرد و آن را از طریق یک نقطه پایانی HTTP قابل دسترسی خواهید بود.
ابتدا یک مخزن Docker در Artifact Registry ایجاد کنید تا تصاویر کانتینر Agent خود را ذخیره کنید. دستور زیر را در Cloud Shell اجرا کنید:
gcloud artifacts repositories create finn-agent-images \
--repository-format=docker \
--location=us-central1 \
--project=$PROJECT_ID \
--description="Repository for finn-agent images"
سپس با استفاده از Cloud Build، تصویر Docker را برای Agent خود بسازید. این دستور را از دایرکتوری ریشه پروژه کلون شده خود ( sports-agent-adk-mcp-alloydb/ ) اجرا کنید:
gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent
اکنون، سرویس Agent را مستقر کنید. این دستور یک سرویس Cloud Run ایجاد می کند، تصویر را از Artifact Registry می کشد و متغیرهای محیط را پیکربندی می کند.
gcloud run deploy finn-agent \
--image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
--platform managed \
--allow-unauthenticated \
--region us-central1 \
--project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"
توجه: ما متغیرهای محیطی از جمله GOOGLE_CLOUD_PROJECT را به صورت پویا تنظیم می‌کنیم (با استفاده از متغیر پوسته $PROJECT_ID )
شما باید خروجی مشابهی دریافت کنید که نشان دهنده استقرار موفقیت آمیز Agent شما است:
Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app
در نهایت، عامل خود را با اجرای این دستور curl از ترمینال Cloud Shell خود آزمایش کنید:
curl -X POST \
-H "Content-Type: application/json" \
-d '{"message":"Hello"}' \
https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat
خروجی مشابه این دریافت خواهید کرد:
"سلام! من فین هستم، دستیار خرید AI Sports شما. می توانم به شما کمک کنم محصولات ورزشی، تجهیزات و تجهیزات را پیدا کنید. چگونه می توانم امروز به شما کمک کنم؟"
در این مرحله، استقرار AlloyDB، MCP Toolbox و عامل خود را که با استفاده از ADK ساخته شده است، با موفقیت تأیید کرده اید.
8. Frontend را مستقر کنید
در این بخش، رابط کاربری مکالمه ای را برای دستیار هوش مصنوعی خود در Cloud Run قرار می دهید. این فرانت اند با استفاده از React و JavaScript ساخته شده است.
قبل از استقرار، باید کد منبع فرانت اند را با URL های عامل مستقر شده و شناسه مشتری OAuth خود به روز کنید.
با استفاده از Cloud Shell Editor، به sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ بروید و فایل Home.jsx باز کنید. شما باید مکان نگهدار را برای نشانی وب Agent's Cloud Run Service خود به روز کنید. سپس، آن را با نشانی وب سرویس Agent's Cloud Run از مرحله قبل جایگزین کنید (به عنوان مثال، https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app ).
اکنون، Next، به sports-agent-adk-mcp-alloydb/src/frontend/src/components/ بروید و فایل GoogleSignInButton.jsx باز کنید. شما این فایل را با شناسه مشتری OAuth که در بخش "تنظیم سرویس مجوز" به دست آورده اید به روز می کنید:
فرانت اند را در Cloud Run مستقر کنید
اکنون که برنامه frontend شما پیکربندی شده است، آماده استقرار آن در Cloud Run هستید.
دستور زیر را در ترمینال Cloud Shell از دایرکتوری ریشه ( sports-agent-adk-mcp-alloydb/ ) اجرا کنید تا یک مخزن Docker در Artifact Registry برای تصاویر frontend خود ایجاد کنید.
gcloud artifacts repositories create finn-frontend-images \
--repository-format=docker \
--location=us-central1 \
--project=$PROJECT_ID \
--description="Repository for finn-frontend images"
سپس، با استفاده از Cloud Build، تصویر Docker را برای برنامه frontend خود بسازید. این دستور را از دایرکتوری ریشه پروژه خود اجرا کنید:
gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend
در نهایت، ما frontend را با استفاده از دستور زیر در Cloud Run مستقر خواهیم کرد:
gcloud run deploy finn-frontend \
--image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
--platform managed \
--allow-unauthenticated \
--region us-central1 \
--project $PROJECT_ID
شما باید خروجی مشابهی دریافت کنید که نشان دهنده استقرار موفقیت آمیز frontend شما است:
Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app
مرورگر وب خود را باز کنید و از نشانی وب سرویس مرحله قبل برای باز کردن برنامه جدید خود استفاده کنید که توسط عامل هوش مصنوعی شما پشتیبانی می شود!
9. Agent ما را اجرا کنید
دستیار هوش مصنوعی عامل فروشگاه ورزشی شما، فین، اکنون به طور کامل مستقر شده و آماده کمک به خرید است!
مرورگر وب خود را باز کنید و از مرحله قبل به URL سرویس برنامه frontend خود بروید. URL از این قالب پیروی می کند: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app
پس از بارگیری صفحه اصلی، روی دکمه سمت راست بالا (معمولاً با برچسب "ورود به سیستم" یا یک درخواست مشابه) کلیک کنید تا با استفاده از اعتبار Google خود احراز هویت شوید. این عمل از پیکربندی OAuth که قبلاً تنظیم کرده‌اید، استفاده می‌کند.
پس از احراز هویت موفق، شما آماده تعامل با فین هستید! برای شروع تجربه خرید مکالمه خود، روی دکمه "خرید اکنون" کلیک کنید.
از اسکریپت زیر برای آزمایش عملکردهای مختلف عامل هوش مصنوعی خود استفاده کنید. این دستورات را یکی یکی در رابط چت کپی و جایگذاری کنید:
- سلام فین!
- من به دنبال کفش دویدن برای یک تریل می گردم
- جزئیات بیشتری درباره Ultra Glide به من بگویید
- Ultra Glide، سایز 40، رنگ قرمز/خاکستری را به لیست خرید من اضافه کنید
- نمایش لیست خرید من
- فروشگاه های نزدیک من را پیدا کنید
- لطفا با استفاده از لیست خرید من برای فروشگاه Sports Diagonal Mar سفارش دهید
- وضعیت سفارشات من را بررسی کنید
- لطفاً روش های تحویل را برای فروشگاه Sports Diagonal Mar ذکر کنید
- روش تحویل را برای سفارش [YOUR_ORDER_NUMBER] به تحویل سریع به‌روزرسانی کنید
- وضعیت سفارشات من را بررسی کنید
- ممنون فین!
برای نمایش بصری Finn Agent مستقر شده و قابلیت های آن، ویدیوی زیر را ببینید:
نسخه ی نمایشی دستیار هوش مصنوعی Sports Agent که توسط AlloyDB طراحی شده است
10. نتایج
پس از اجرای اسکریپت قبلی، ادغام کامل عامل ADK خود، اتصال آن به AlloyDB و استفاده آن از جعبه ابزار MCP را با موفقیت تأیید کردید. این بخش قابلیت های اصلی را که شما پیاده سازی کرده اید برجسته می کند.
- خدمات مجوز
جعبه ابزار MCP برای پایگاه‌های داده این قابلیت را فراهم می‌کند که یک سرویس مجوز (به‌ویژه، Google Sign-In در این کد لبه) را برای احراز هویت کاربران در برنامه شما ایجاد کند. با جعبه ابزار MCP، شناسه مشتری OAuth شما برای تأیید هویت کاربر هنگام فراخوانی ابزار استفاده می شود.
این مکانیزم احراز هویت قوی یک راه حل عالی برای محافظت از برنامه عامل شما در برابر تزریق سریع ارائه می دهد، نوعی حمله که در آن ورودی مخرب تلاش می کند رفتار مورد نظر عامل را دور بزند یا دستکاری کند. برای جزئیات بیشتر می توانید به مقاله ویکی پدیا در مورد تزریق سریع مراجعه کنید
در این برنامه زمانی از این تکنیک استفاده می‌شود که کاربر بخواهد وضعیت سفارشات ما را بررسی کند. یا "نمایش لیست خرید من". این نماینده طوری طراحی شده است که فقط سفارشاتی را نشان دهد که متعلق به کاربر تأیید شده است و از دسترسی غیرمجاز به اطلاعات سفارش جلوگیری می کند.
- جستجوی برداری
برنامه کاربردی شما از AlloyDB برای PostgreSQL برای ارائه قابلیت های جستجوی پیشرفته، به ویژه از طریق جستجوی برداری، استفاده می کند. AlloyDB از تولید جاسازی آنلاین به طور مستقیم در داخل پایگاه داده با استفاده از توابع SQL پشتیبانی می کند.
این ویژگی قدرتمند به عامل اجازه می دهد تا ورودی زبان طبیعی کاربر را به یک نمایش تعبیه شده عددی ترجمه کند. متعاقباً، می‌تواند جستجوی مشابهی را در برابر کاتالوگ محصول شما (یا سایر داده‌های مرتبط) بر اساس این جاسازی‌ها انجام دهد و نتایج جستجوی بسیار مرتبط را فعال کند.
در برنامه خود، زمانی که از فین می‌پرسید: «من به دنبال کفش‌های مخصوص دویدن برای یک مسیر فوق‌العاده هستم»، این تکنیک را تجربه می‌کنید.
- قابلیت های جغرافیایی (PostGis)
AlloyDB برای PostgreSQL سازگاری 100٪ با ویژگی های استاندارد PostgreSQL را حفظ می کند. در این برنامه، ما از پسوند محبوب PostgreSQL PostGIS برای ارائه قابلیت های مکان جغرافیایی به عامل استفاده می کنیم.
وقتی از نماینده می‌پرسید: "فروشگاه‌های نزدیک من را بیابید"، عامل ابزاری را اجرا می‌کند که از نمایه‌های PostGIS در پایگاه داده استفاده می‌کند تا نزدیک‌ترین فروشگاه‌ها به مکان مشخص یا استنباط‌شده کاربر را به‌طور موثر مکان‌یابی کند.
11. (اختیاری) زبان طبیعی AlloyDB AI را در SQL تست کنید
این بخش یک ویژگی پیشرفته و Pre-GA از AlloyDB برای PostgreSQL: زبان طبیعی به SQL را معرفی می کند. این ویژگی به شما این امکان را می دهد که پرس و جوهای SQL را مستقیماً از اعلان های زبان طبیعی ایجاد کنید و از قدرت هوش مصنوعی در پایگاه داده خود استفاده کنید.
مهم: از آنجایی که این یک ویژگی Pre-GA است، باید ثبت نام کنید و دسترسی به پروژه Google Cloud، خوشه AlloyDB و پایگاه داده خود را فعال کنید.
- ثبت نام برای دسترسی: لطفاً برای درخواست دسترسی برای پروژه خود، این فرم را دنبال کنید
- مستندات: می‌توانید در اسناد رسمی درباره استفاده از AlloyDB AI Natural Language در SQL اطلاعات بیشتری کسب کنید.
پس از ثبت نام و تایید دسترسی برای پروژه خود، مراحل زیر را در AlloyDB Studio انجام دهید.
با استفاده از اعتبارنامه هایی که هنگام ایجاد خوشه ایجاد کردیم، وارد AlloyDB شوید:
- نام کاربری: "postgres"
- پایگاه داده: "فروشگاه"
- رمز عبور: "alloydb"
1- پسوند alloydb_ai_nl را ایجاد کنید. این برنامه افزودنی توابع لازم برای قابلیت‌های زبان طبیعی AlloyDB AI را فراهم می‌کند.
CREATE EXTENSION alloydb_ai_nl cascade;
2- یک پیکربندی برای برنامه خود ایجاد کنید. یک پیکربندی، زمینه طرحواره ای را تعریف می کند که مدل هوش مصنوعی برای درک پایگاه داده شما از آن استفاده می کند.
SELECT
alloydb_ai_nl.g_create_configuration(
'finn_app_config' -- configuration_id
);
3- طرح و جداول را با پیکربندی ثبت کنید. جداول و طرحواره های خاصی را که عامل برنامه شما با آنها تعامل خواهد داشت به پیکربندی اضافه کنید.
SELECT alloydb_ai_nl.g_manage_configuration(
operation => 'register_table_view',
configuration_id_in => 'finn_app_config',
table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);
4- زمینه طرح و جداول را ایجاد کنید. این مرحله جداول ثبت شده را پردازش می کند تا زمینه لازم برای مدل هوش مصنوعی را ایجاد کند. این فرآیند می تواند تقریباً 2-3 دقیقه طول بکشد.
SELECT alloydb_ai_nl.generate_schema_context(
'finn_app_config',
TRUE
);
5- زمینه تولید خودکار را برای جداول و ستون های خاص بررسی کنید (اختیاری). شما می توانید زمینه ایجاد شده را بررسی کنید تا متوجه شوید که چگونه مدل هوش مصنوعی طرحواره شما را تفسیر می کند.
SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';
SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';
SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';
در "tools.yaml" نماینده ما ابزاری به نام "چک موجودی-بر-استگاه-برند-رده" پیدا خواهید کرد. این ابزار از زبان طبیعی AlloyDB برای SQL استفاده می کند:
یک مرورگر وب را باز کنید و از URL سرویس برای باز کردن برنامه استفاده کنید: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"
سپس، از اسکریپت زیر در رابط چت برای آزمایش این قابلیت جدید استفاده کنید:
- سلام فین!
- تعداد کل محصولات دسته بندی رانینگ سالومون موجود در فروشگاه "Sports Diagonal Mar" چقدر است؟
برای مشاهده پرس و جو واقعی SQL که AlloyDB AI از ورودی زبان طبیعی شما ایجاد کرده است، به استودیو AlloyDB برگردید و پرس و جو زیر را اجرا کنید:
SELECT
alloydb_ai_nl.get_sql(
'finn_app_config',
'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
) ->> 'sql';
این دستور SQL را نشان می دهد که توسط AlloyDB AI تولید شده است.
12. پاکسازی کنید
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این آزمایشگاه، این مراحل را دنبال کنید:
- در کنسول Google Cloud، به صفحه مدیریت منابع بروید.
- در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
- در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.
13. تبریک می گویم
تبریک می گویم! شما با استفاده از ADK، جعبه ابزار MCP برای پایگاه‌های داده و AlloyDB برای PostgreSQL با موفقیت یک برنامه هوش مصنوعی مبتنی بر داده ایجاد کردید.
برای اطلاعات بیشتر، به اسناد محصول مراجعه کنید: کیت توسعه عامل ، جعبه ابزار MCP برای پایگاه‌های داده و AlloyDB برای PostgreSQL