این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ساخت دستیار هوش مصنوعی Sports Shop Agent با ADK، MCP Toolbox و AlloyDB

۱. مقدمه

آنچه خواهید ساخت

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه یک دستیار هوش مصنوعی برای عامل فروشگاه ورزشی بسازید. این برنامه هوش مصنوعی عامل نسل بعدی، که توسط ADK ، MCP Toolbox و AlloyDB پشتیبانی می‌شود، به کاربران در انجام وظایف مختلف، از جمله موارد زیر، کمک خواهد کرد:

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

آنچه یاد خواهید گرفت

تهیه و پر کردن یک AlloyDB برای پایگاه داده PostgreSQL.
راه‌اندازی جعبه ابزار MCP برای پایگاه‌های داده با AlloyDB خود برای نمونه PostgreSQL.
طراحی و توسعه یک عامل هوش مصنوعی با استفاده از کیت توسعه عامل (ADK) برای کمک به سوالات فروشگاه‌های ورزشی.
آزمایش عامل و جعبه ابزار MCP برای پایگاه‌های داده در یک محیط ابری.
بهره‌گیری از قابلیت‌های پیشرفته‌ی کوئری AlloyDB برای پاسخ‌های هوشمند عامل.

آنچه نیاز دارید

برای تکمیل این آزمایشگاه کد، به موارد زیر نیاز دارید:

یک مرورگر وب کروم.
یک حساب جیمیل.
یک پروژه ابری گوگل با قابلیت پرداخت صورتحساب.

این codelab برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، طراحی شده است.

۲. قبل از شروع

این بخش شما را در تنظیمات اولیه مورد نیاز در پروژه گوگل کلود خود، قبل از شروع ساخت دستیار هوش مصنوعی Sports Shop Agent، راهنمایی می‌کند.

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

در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
با کلیک روی این لینک، Cloud Shell را فعال کنید. می‌توانید با کلیک روی دکمه مربوطه از Cloud Shell، بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه‌ها) جابجا شوید.

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

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

۳. نمونه AlloyDB را ایجاد کنید

در این بخش، خوشه و نمونه پایگاه داده AlloyDB خود را راه‌اندازی کرده و شبکه و مجوزهای لازم را برای عامل هوش مصنوعی خود پیکربندی خواهید کرد.

ابتدا، دستور زیر را در ترمینال Cloud Shell خود اجرا کنید تا کلاستر AlloyDB ایجاد شود:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB برای دسترسی ایمن و با کارایی بالا به اتصال IP خصوصی متکی است. شما باید یک محدوده IP خصوصی را در VPC خود اختصاص دهید تا گوگل از آن برای اتصال همتاسازی سرویس به زیرساخت شبکه سرویس مدیریت‌شده توسط گوگل استفاده کند. دستور زیر را اجرا کنید:

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) شما اجازه می‌دهد تا به صورت ایمن و خصوصی با سرویس‌های مدیریت‌شده گوگل، از جمله 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 را فعال کنید

برای اینکه به نمونه AlloyDB خود اجازه دهید پرس‌وجوهای جستجوی برداری (که برای قابلیت‌های هوش مصنوعی مانند جستجوی معنایی ضروری هستند) را انجام دهد و مدل‌های مستقر در Vertex AI را فراخوانی کند، باید مجوزهای Vertex AI را به عامل سرویس AlloyDB اعطا کنید.

ابتدا، شماره پروژه گوگل کلود خود را بازیابی کنید، زیرا برای اتصال IAM لازم است.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

سپس به نماینده سرویس AlloyDB، مجوز Vertex AI را اعطا کنید:

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 بروید و دستور " ifconfig | grep -A 1 eth0 " را وارد کنید. از نتیجه، دو رقم آخر را با 0.0 با اندازه ماسک '/16' جایگزین کنید. برای مثال، به شکل "XX.XX.0.0/16" خواهد بود که در آن XX عدد است.

این IP را در کادر متنی «شبکه‌های خارجی مجاز» در صفحه ویرایش نمونه قرار دهید.

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

۴. بارگذاری پایگاه داده

ایجاد پایگاه داده فروشگاه

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

برای فعال کردن psql برای اتصال به نمونه‌ی خصوصی AlloyDB شما از طریق Cloud Shell، از AlloyDB Auth Proxy استفاده خواهید کرد. این ابزار به طور ایمن اتصال شما را به پایگاه داده تونل می‌کند. (به AlloyDB Auth Proxy مراجعه کنید)

با استفاده از دستور زیر، AlloyDB Auth Proxy را دانلود کنید:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.6/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

آن را قابل اجرا کنید:

chmod +x alloydb-auth-proxy

این دستور را در اولین پنجره ترمینال Cloud Shell خود اجرا کنید. پروکسی در پس‌زمینه اجرا می‌شود و اتصالات را هدایت می‌کند.

nohup ./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip &

با استفاده از psql به نمونه AlloyDB متصل شوید:

psql -h 127.0.0.1 -U postgres

توجه: در صورت درخواست، رمز عبوری را که برای کاربر postgres در هنگام ایجاد خوشه تنظیم کرده‌اید، وارد کنید (اگر مستقیماً از مستندات پیروی می‌کنید، رمز عبور alloydb است).

و پایگاه داده فروشگاه را برای برنامه خود ایجاد کنید (دستورات را یکی یکی اجرا کنید):

CREATE DATABASE store;
\c store
exit

کد منبع S

حالا، مخزن کد منبع codelab را کپی کنید. قبل از کپی کردن، مطمئن شوید که در دایرکتوری خانگی خود یا مکان مناسبی هستید و دستور زیر را اجرا کنید:

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 هستند. برخی هشدارها و خطاها را خواهید دید که می‌توان آنها را نادیده گرفت.

۵. راه‌اندازی سرویس احراز هویت

در این بخش، سرویس احراز هویت را برای برنامه خود تنظیم خواهید کرد. این سرویس برای ایمن‌سازی دسترسی و محافظت در برابر آسیب‌پذیری‌های تزریق سریع در عامل هوش مصنوعی شما بسیار مهم است.

ابتدا، یک کاربر نمونه به جدول users در پایگاه داده store خود اضافه خواهید کرد. این کاربر برای احراز هویت در برنامه شما استفاده خواهد شد.

به کنسول بروید و به AlloyDB بروید، نمونه اصلی و سپس AlloyDB Studio را انتخاب کنید:

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

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

در ویرایشگر SQL، دستور INSERT را اجرا کنید تا کاربر خود را به پایگاه داده اضافه کنید. نام، نام خانوادگی و آدرس ایمیل را تغییر دهید.

مهم:

مکان را همانطور که در مثال است نگه دارید
از همان آدرس ایمیلی که برای ثبت نام در کنسول ابری گوگل استفاده می‌کنید، استفاده کنید.

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 را برای پروژه خود پیکربندی کنید. این صفحه زمانی که برنامه شما درخواست دسترسی به حساب گوگل کاربران را می‌دهد، به آنها نمایش داده می‌شود و نام تجاری برنامه شما را تعریف می‌کند.

در کنسول، به «APIs and Services» و سپس «Google OAuth Consent» بروید:

برای ایجاد برند برنامه خود، اطلاعات زیر را ارائه دهید:

نام برنامه: "هوش مصنوعی عامل خرید ورزشی"
ایمیل پشتیبانی کاربر: "YOUR_EMAIL"
مخاطب: «خارجی»
اطلاعات تماس: "ایمیل شما"

اکنون، شما شناسه کلاینت OAuth را ایجاد خواهید کرد که برنامه frontend شما برای اعتبارسنجی هویت کاربر با Google از آن استفاده خواهد کرد.

ابتدا، مطمئن شوید که شماره پروژه گوگل کلود خود را دارید. این شماره برای پیکربندی صحیح URL های ریدایرکت لازم است. دستور زیر را در ترمینال کلود شل اجرا کنید:

در صورتی که متغیر PROJECT_ID شما در این پنجره Cloud Shell Terminal تنظیم نشده باشد، دستور زیر را اجرا کنید:

export PROJECT_ID=[YOUR_PROJECT_ID]

سپس، با استفاده از دستور زیر، PROJECT_NUMBER را دریافت کنید:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

سپس، به «APIها و خدمات» -> «اعتبارنامه‌ها» -> «ایجاد اعتبارنامه‌ها» -> «شناسه کلاینت OAuth» بروید.

۴۵۶۲۳e۹۶d۴۱۷۱۹۲d.png

برای ایجاد اعتبارنامه از اطلاعات زیر استفاده کنید:

نوع برنامه: "برنامه وب"
نام: "اپلیکیشن هوش مصنوعی نماینده خرید ورزشی"

ریشه‌های مجاز جاوا اسکریپت:

آدرس اینترنتی ۱: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

آدرس‌های اینترنتی تغییر مسیر مجاز:

آدرس اینترنتی ۱: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

نکته: آدرس اینترنتی https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app آدرس اینترنتی مورد انتظار برای استقرار برنامه frontend شماست که بعداً در این آزمایشگاه کد تنظیم خواهد شد. مطمئن شوید که [YOUR_PROJECT_NUMBER] را با شماره واقعی که کپی کرده‌اید جایگزین می‌کنید.

۱۸۷۳d292fd27f07c.png

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

6. جعبه ابزار MCP برای راه‌اندازی پایگاه‌های داده

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

از آنجایی که یکی از پایگاه‌های داده‌ای که توسط MCP Toolbox for Databases پشتیبانی می‌شود، AlloyDB است و ما قبلاً آن را در بخش قبلی فراهم کرده‌ایم، بیایید Toolbox را راه‌اندازی کنیم.

۲۶۵۹۶۱۳۸ffc۳۲d۹۸.png

ابتدا، سرور MCP Toolbox را به صورت محلی در محیط Cloud Shell خود راه‌اندازی خواهید کرد تا عملکرد آن را تأیید کنید.

در ترمینال Cloud Shell خود، به پوشه toolbox واقع در مخزن پروژه کلون شده خود بروید:

cd sports-agent-adk-mcp-alloydb/src/toolbox

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

# see releases page for other versions
export VERSION=0.16.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

توجه: نسخه 0.16.0 در اینجا مشخص شده است. برای محیط‌های عملیاتی، همیشه آخرین نسخه پایدار را از صفحه انتشارهای جعبه ابزار تأیید و استفاده کنید.

به ویرایشگر Cloud Shell بروید (می‌توانید با کلیک روی نماد ویرایشگر از ترمینال، آن را تغییر دهید).

در همان دایرکتوری sports-agent-adk-mcp-alloydb/src/toolbox ، فایلی با نام tools.yaml پیدا خواهید کرد. این فایل را باز کنید و متغیرهای (placeholders) را با شناسه OAuth Client و شناسه Google Cloud Project خود از مراحل قبلی به‌روزرسانی کنید.

بیایید tools.yaml را درک کنیم

منابع (Sources) منابع داده مختلفی را نشان می‌دهند که یک ابزار می‌تواند با آنها تعامل داشته باشد. یک منبع (Sources) نشان دهنده یک منبع داده است که یک ابزار می‌تواند با آن تعامل داشته باشد. می‌توانید منابع (Sources) را به عنوان یک نقشه (map) در بخش منابع (sources) فایل tools.yaml خود تعریف کنید. به طور معمول، پیکربندی منبع (source configuration) شامل هرگونه اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده خواهد بود.

ابزارها اقداماتی را که یک عامل می‌تواند انجام دهد تعریف می‌کنند - مانند خواندن و نوشتن در یک منبع. یک ابزار نشان دهنده عملی است که عامل شما می‌تواند انجام دهد، مانند اجرای یک دستور SQL. می‌توانید ابزارها را به عنوان یک نقشه در بخش ابزارهای فایل tools.yaml خود تعریف کنید. معمولاً، یک ابزار برای اقدام به یک منبع نیاز دارد.

برای جزئیات بیشتر در مورد پیکربندی tools.yaml خود، به این مستندات مراجعه کنید.

بیایید جعبه ابزار MCP را برای سرور پایگاه داده اجرا کنیم

برای شروع سرور، دستور زیر را (از پوشه mcp-toolbox) اجرا کنید:

./toolbox --tools-file "tools.yaml"

حال، اگر سرور را در حالت پیش‌نمایش وب روی فضای ابری باز کنید، باید بتوانید سرور Toolbox را در حال اجرا و با تمام ابزارهای برنامه ما ببینید.

سرور جعبه ابزار MCP به طور پیش‌فرض روی پورت ۵۰۰۰ اجرا می‌شود. بیایید از Cloud Shell برای آزمایش این مورد استفاده کنیم.

مطابق شکل زیر، روی پیش‌نمایش وب در Cloud Shell کلیک کنید:

روی Change port کلیک کنید و پورت را مانند تصویر زیر روی ۵۰۰۰ تنظیم کنید و روی Change and Preview کلیک کنید.

این باید خروجی را به همراه داشته باشد:

جعبه ابزار MCP برای پایگاه‌های داده، یک SDK پایتون را برای اعتبارسنجی و آزمایش ابزارها شرح می‌دهد که در اینجا مستند شده است. ما از آن صرف نظر می‌کنیم و در بخش بعدی مستقیماً به کیت توسعه عامل (ADK) می‌پردازیم که از این ابزارها استفاده خواهد کرد.

بیایید جعبه ابزار خود را در Cloud Run مستقر کنیم

برای اینکه سرور Toolbox شما به عنوان یک نقطه پایانی عمومی که بتواند با سایر برنامه‌ها و عامل هوش مصنوعی شما ادغام شود، قابل دسترسی باشد، آن را در Cloud Run مستقر خواهید کرد. دستورالعمل‌های دقیق برای میزبانی Toolbox در Cloud Run در اینجا ارائه شده است.

به ترمینال Cloud Shell برگردید و به پوشه جعبه ابزار بروید:

cd sports-agent-adk-mcp-alloydb/src/toolbox

مطمئن شوید که متغیر محیطی PROJECT_ID شما روی شناسه پروژه گوگل کلود شما تنظیم شده است.

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 را به عنوان یک فایل مخفی آپلود خواهید کرد و از آنجایی که باید Toolbox را در Cloud Run نصب کنیم، قصد داریم از جدیدترین تصویر Container برای toolbox استفاده کنیم و آن را در متغیر IMAGE تنظیم کنیم.

gcloud secrets create tools --data-file=tools.yaml

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

در نهایت، سرور Toolbox خود را با استفاده از دستور زیر روی 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

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

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

همچنین می‌توانید از کنسول Google Cloud به Cloud Run مراجعه کنید و سرویس Toolbox را در لیست سرویس‌های Cloud Run مشاهده خواهید کرد.

۷. عامل ساخته شده بر روی 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"

اتصال نماینده ما به ابزارها

ما قصد داریم عامل خود را به ابزارها متصل کنیم. در زمینه ADK، یک ابزار نشان‌دهنده یک قابلیت خاص ارائه شده به یک عامل هوش مصنوعی است که آن را قادر می‌سازد فراتر از توانایی‌های اصلی تولید متن و استدلال، اقداماتی را انجام دهد و با جهان تعامل داشته باشد.

در مورد ما، اکنون قصد داریم Agent خود را به ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم، مجهز کنیم.

با استفاده از ویرایشگر Cloud Shell، به sports-agent-adk-mcp-alloydb/src/backend/ بروید و فایل "finn_agent.py" را با کد زیر ویرایش کنید. توجه داشته باشید که ما از آدرس اینترنتی Cloud Run Service از سرور MCP ToolBox که در مرحله قبل مستقر شده است، استفاده می‌کنیم:

۱۴cdb7fdcb9f6176.png

عامل ما را در Cloud Run مستقر کنید

در نهایت، شما عامل هوش مصنوعی پیکربندی‌شده خود را در Cloud Run مستقر خواهید کرد و آن را از طریق یک نقطه پایانی HTTP در دسترس قرار خواهید داد.

ابتدا، یک مخزن داکر در رجیستری Artifact ایجاد کنید تا تصاویر کانتینر 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، ایمیج داکر را برای 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

خروجی مشابه این دریافت خواهید کرد:

«سلام! من فین هستم، دستیار خرید شما در بخش هوش مصنوعی ورزشی. می‌توانم در یافتن محصولات، تجهیزات و لوازم ورزشی به شما کمک کنم. امروز چطور می‌توانم به شما کمک کنم؟»

در این مرحله، شما با موفقیت استقرار AlloyDB، MCP Toolbox و Agent ساخته شده با استفاده از ADK را تأیید کرده‌اید.

۸. استقرار فرانت‌اند

در این بخش، رابط کاربری محاوره‌ای را برای دستیار هوش مصنوعی خود در Cloud Run مستقر خواهید کرد. این رابط کاربری با استفاده از React و JavaScript ساخته شده است.

قبل از استقرار، باید کد منبع frontend را با URL های Agent مستقر شده و شناسه OAuth Client خود به روز کنید.

با استفاده از ویرایشگر Cloud Shell، به sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ بروید و فایل Home.jsx را باز کنید. شما باید محل قرارگیری آدرس اینترنتی سرویس Cloud Run نماینده خود را به‌روزرسانی کنید. سپس، آن را با آدرس اینترنتی سرویس Cloud Run نماینده خود از مرحله قبل جایگزین کنید (مثلاً https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app ).

حالا، در مرحله بعد، به sports-agent-adk-mcp-alloydb/src/frontend/src/components/ بروید و فایل GoogleSignInButton.jsx را باز کنید. این فایل را با شناسه OAuth Client که در بخش "Authorization Service Setup" دریافت کرده‌اید، به‌روزرسانی خواهید کرد:

استقرار رابط کاربری روی 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، تصویر داکر را برای برنامه frontend خود بسازید. این دستور را از دایرکتوری ریشه پروژه خود اجرا کنید:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-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

مرورگر وب خود را باز کنید و از URL سرویس از مرحله قبل برای باز کردن برنامه تازه مستقر شده خود که توسط عامل هوش مصنوعی شما پشتیبانی می‌شود، استفاده کنید!

۹. عامل ما را اجرا کنید

دستیار هوش مصنوعی شما، فین، اکنون کاملاً مستقر شده و آماده کمک به خریدها است!

مرورگر وب خود را باز کنید و به آدرس سرویس (Service URL) برنامه frontend خود که در مرحله قبل ایجاد کرده‌اید، بروید. این آدرس اینترنتی از این فرمت پیروی می‌کند: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

پس از بارگذاری رابط کاربری، روی دکمه بالا سمت راست (که معمولاً با عنوان "ورود" یا عبارتی مشابه آن مشخص شده است) کلیک کنید تا با استفاده از اطلاعات حساب گوگل خود، احراز هویت شوید. این اقدام از پیکربندی OAuth که قبلاً تنظیم کرده‌اید، بهره می‌برد.

پس از احراز هویت موفقیت‌آمیز، شما آماده تعامل با فین هستید! برای شروع تجربه خرید محاوره‌ای خود، روی دکمه «همین حالا خرید کنید» کلیک کنید.

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

سلام فین!
من دنبال کفش دویدن برای یک مسیر فوق‌العاده هستم
جزئیات بیشتری در مورد Ultra Glide به من بگویید
کفش ورزشی Ultra Glide سایز ۴۰، رنگ قرمز/خاکستری را به لیست خرید من اضافه کنید
نمایش لیست خرید من
فروشگاه‌های نزدیک من را پیدا کنید
لطفا با استفاده از لیست خرید من برای فروشگاه Sports Diagonal Mar سفارش دهید
وضعیت سفارشات من را بررسی کنید
لطفا روش‌های تحویل فروشگاه Sports Diagonal Mar را فهرست کنید
روش تحویل را برای سفارش من [YOUR_ORDER_NUMBER] به تحویل سریع به‌روزرسانی کنید.
وضعیت سفارشات من را بررسی کنید
ممنون فین!

برای نمایش بصری Finn Agent مستقر شده و قابلیت‌های آن، ویدیوی زیر را تماشا کنید:

نسخه آزمایشی دستیار هوش مصنوعی عامل ورزشی با پشتیبانی AlloyDB

۱۰. نتایج

با اجرای اسکریپت قبلی، شما با موفقیت ادغام کامل ADK Agent خود، اتصال آن به AlloyDB و استفاده از MCP Toolbox را تأیید کرده‌اید. این بخش قابلیت‌های اصلی پیاده‌سازی شده را برجسته می‌کند.

خدمات مجوزدهی

جعبه ابزار MCP برای پایگاه‌های داده، قابلیتی را فراهم می‌کند که با استفاده از آن می‌توانید یک سرویس احراز هویت (به‌طور خاص، در این آزمایشگاه کد، Google Sign-In) را برای احراز هویت کاربران در برنامه خود یکپارچه کنید. با استفاده از جعبه ابزار MCP، شناسه کلاینت OAuth شما برای اعتبارسنجی هویت کاربر هنگام فراخوانی یک ابزار استفاده می‌شود.

این مکانیزم احراز هویت قوی، یک راه حل عالی برای محافظت از برنامه عامل شما در برابر تزریق سریع (prompt injection) ارائه می‌دهد، نوعی حمله که در آن ورودی مخرب سعی در دور زدن یا دستکاری رفتار مورد نظر عامل دارد. برای جزئیات بیشتر، می‌توانید به مقاله ویکی پدیا در مورد تزریق سریع (Prompt Injection) مراجعه کنید.

در این برنامه، این تکنیک زمانی استفاده می‌شود که کاربر درخواست «بررسی وضعیت سفارشات ما» یا «نمایش لیست خرید من» را دارد. این عامل به گونه‌ای طراحی شده است که فقط سفارشاتی را که متعلق به کاربر احراز هویت شده است نشان دهد و از دسترسی غیرمجاز به اطلاعات سفارش جلوگیری کند.

جستجوی برداری

برنامه کاربردی شما از AlloyDB برای PostgreSQL استفاده می‌کند تا قابلیت‌های پرس‌وجوی پیشرفته، به‌ویژه از طریق جستجوی برداری، را ارائه دهد. AlloyDB از تولید جاسازی آنلاین مستقیماً درون پایگاه داده با استفاده از توابع SQL پشتیبانی می‌کند.

این ویژگی قدرتمند به عامل اجازه می‌دهد تا ورودی زبان طبیعی کاربر را به یک نمایش جاسازی عددی ترجمه کند. متعاقباً، می‌تواند بر اساس این جاسازی‌ها، جستجوی مشابهی را در کاتالوگ محصولات شما (یا سایر داده‌های مرتبط) انجام دهد و نتایج جستجوی بسیار مرتبطی را ممکن سازد.

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

قابلیت‌های مکانی (PostGis)

AlloyDB برای PostgreSQL سازگاری ۱۰۰٪ با ویژگی‌های استاندارد PostgreSQL را حفظ می‌کند. در این برنامه، ما از افزونه محبوب PostgreSQL به نام PostGIS برای ارائه قابلیت‌های موقعیت مکانی به عامل استفاده می‌کنیم.

وقتی از نماینده می‌پرسید: «فروشگاه‌های نزدیک من را پیدا کن»، نماینده ابزاری را اجرا می‌کند که از شاخص‌های PostGIS در پایگاه داده برای یافتن کارآمد نزدیکترین فروشگاه‌ها به مکان مشخص شده یا استنباط شده کاربر استفاده می‌کند.

۱۱. (اختیاری) تبدیل زبان طبیعی AlloyDB AI به SQL

این بخش یک ویژگی پیشرفته Pre-GA از AlloyDB برای PostgreSQL: Natural Language to SQL را معرفی می‌کند. این ویژگی به شما امکان می‌دهد تا کوئری‌های SQL را مستقیماً از زبان طبیعی تولید کنید و از قدرت هوش مصنوعی در پایگاه داده خود بهره ببرید.

مهم: از آنجایی که این یک ویژگی Pre-GA است، لازم است که ثبت نام کنید و دسترسی به پروژه Google Cloud، کلاستر AlloyDB و پایگاه داده خود را فعال کنید.

ثبت نام برای دسترسی: لطفاً برای درخواست دسترسی به پروژه خود، این فرم را دنبال کنید
مستندات: می‌توانید در مستندات رسمی، اطلاعات بیشتری در مورد استفاده از زبان طبیعی هوش مصنوعی AlloyDB برای SQL کسب کنید.

پس از ثبت نام و تأیید دسترسی به پروژه خود، مراحل زیر را در AlloyDB Studio ادامه دهید.

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

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

۱- افزونه alloydb_ai_nl را ایجاد کنید. این افزونه توابع لازم برای قابلیت‌های زبان طبیعی AI در AlloyDB را فراهم می‌کند.

CREATE EXTENSION alloydb_ai_nl cascade;

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

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

۳- طرحواره/جداول را با پیکربندی ثبت کنید. جداول و طرحواره‌های خاصی را که عامل برنامه شما با آنها تعامل خواهد داشت، به پیکربندی اضافه کنید.

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

۴- ایجاد زمینه برای طرحواره/جداول. این مرحله جداول ثبت شده را پردازش می‌کند تا زمینه لازم برای مدل هوش مصنوعی را ایجاد کند. این فرآیند تقریباً ۲-۳ دقیقه طول می‌کشد.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

۵- زمینه تولید شده خودکار را برای جداول و ستون‌های خاص بررسی کنید (اختیاری). می‌توانید زمینه تولید شده را بررسی کنید تا بفهمید مدل هوش مصنوعی چگونه طرحواره شما را تفسیر می‌کند.

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

شما ابزاری به نام "check-inventory-by-store-brand-category" را در فایل "tools.yaml" نماینده ما پیدا خواهید کرد. این ابزار از زبان طبیعی AlloyDB برای SQL استفاده می‌کند:

یک مرورگر وب باز کنید و از آدرس اینترنتی سرویس برای باز کردن برنامه استفاده کنید: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

سپس، از اسکریپت زیر در رابط چت برای آزمایش این قابلیت جدید استفاده کنید:

سلام فین!
تعداد کل محصولات دسته دویدن سالومون موجود در فروشگاه "Sports Diagonal Mar" چقدر است؟

برای مشاهده‌ی کوئری SQL واقعی که AlloyDB AI از ورودی زبان طبیعی شما تولید کرده است، به AlloyDB Studio برگردید و کوئری زیر را اجرا کنید:

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 را نمایش می‌دهد.

۱۲. تمیز کردن

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

در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی حذف کلیک کنید.
در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.

۱۳. تبریک

تبریک! شما با موفقیت یک برنامه هوش مصنوعی عامل‌دار داده‌محور با استفاده از ADK، MCP Toolbox برای پایگاه‌های داده و AlloyDB برای PostgreSQL ایجاد کردید.

برای اطلاعات بیشتر، به مستندات محصول مراجعه کنید: کیت توسعه عامل ، جعبه ابزار MCP برای پایگاه‌های داده و AlloyDB برای PostgreSQL