ساختن برنامه Google Chat با عامل هوش مصنوعی ADK

این صفحه توضیح می‌دهد چگونه برنامه Google Chat بسازید که با عامل هوش مصنوعی Agent Development Kit (ADK) میزبانی‌شده در Vertex AI Agent Engine میانای کاربری داشته باشد.

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

نمونه چندعاملی LLM Auditor به‌عنوان برنامه Chat.

نمودار زیر معماری و الگوی پیام‌رسانی را نشان می‌دهد:

معماری برنامه گپ پیاده‌سازی‌شده با عامل هوش مصنوعی ADK.

در نمودار قبلی، کاربری که با برنامه Chat پیاده‌سازی‌شده با عامل هوش مصنوعی ADK تعامل دارد، جریان اطلاعات زیر را دارد:

  1. کاربری پیامی را به برنامه Chat ارسال می‌کند، چه در پیام مستقیم و چه در فضای Chat.
  2. منطق برنامه Chat که در Apps Script یا به‌عنوان سرور وب با نقاط پایانی HTTP پیاده‌سازی شده است، پیام را دریافت و پردازش می‌کند.
  3. عامل هوشواره‌ای که با ADK پیاده‌سازی شده است و با Vertex AI Agent Engine میزبانی می‌شود تعامل را دریافت و پردازش می‌کند.
  4. به‌صورت اختیاری، برنامه Chat یا عامل هوش مصنوعی می‌تواند با سرویس‌های Google Workspace، مثل «تقویم» یا «کاربرگ‌نگار»، یا سرویس‌های دیگر Google، مثل Google Maps یا YouTube، ادغام شود.
  5. برنامه Chat بااستفاده از Google Chat API به‌صورت ناهم‌زمان پاسخ‌ها را ارسال می‌کند تا پیشرفت عامل هوش مصنوعی را اطلاع دهد.
  6. پاسخ‌ها به کاربر ارائه می‌شود.

اهداف

  • محیط خود را راه‌اندازی کنید.
  • عامل هوش مصنوعی ADK را مستقر کنید.
  • برنامه Chat را مستقر کنید.
  • برنامه Chat را پیکربندی کنید.
  • برنامه Chat را آزمایش کنید.

پیش‌نیازها

راه‌اندازی محیط

فعال کردن Google Cloud APIs

قبل‌از استفاده از «میاناهای برنامه‌سازی کاربردی Google»، باید آن‌ها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

پیکربندی صفحه کسب رضایت OAuth

همه برنامه‌هایی که از OAuth 2.0 استفاده می‌کنند به پیکربندی صفحه کسب رضایت نیاز دارند. پیکربندی صفحه موافقت OAuth برنامه‌تان مشخص می‌کند چه چیزی به کاربران و بازبینان برنامه نمایش داده شود و برنامه‌تان را ثبت می‌کند تا بتوانید آن را بعداً منتشر کنید.

  1. در «کنسول Google API»، به «منو» > پلاتفرم «احراز هویت Google» > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم «احراز هویت Google» را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه موافقت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم «احراز هویت Google» هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:
    1. در بخش اطلاعات برنامه، در نام برنامه، نامی برای برنامه وارد کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل پشتیبانی را انتخاب کنید که کاربران بتوانند درصورت داشتن سؤال درباره رضایتشان با شما تماس بگیرند.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی وارد کنید که ازطریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش تکمیل، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و درصورت موافقت، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
  3. درحال‌حاضر می‌توانید از افزودن محدوده‌ها رد شوید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خودتان ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید. سپس محدوده‌های مجوز موردنیاز برنامه‌تان را اضافه کنید. برای کسب اطلاعات بیشتر، راهنمای کامل پیکربندی موافقت OAuth را ببینید.

ایجاد حساب خدمات در کنسول Google Cloud

با دنبال کردن این مراحل، حساب سرویس جدیدی با نقش Vertex AI User ایجاد کنید:

Google Cloud Console

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی ایجاد حساب سرویس کلیک کنید.
  4. نام حساب سرویسی را که می‌خواهید در Google Cloud Console نمایش داده شود وارد کنید.
  5. اگر نمی‌خواهید اکنون کنترل‌های دسترسی را تنظیم کنید، برای تکمیل ایجاد حساب سرویس روی تمام کلیک کنید. برای تنظیم کنترل‌های دسترسی در این لحظه، روی ایجاد و ادامه کلیک کنید و به مرحله بعد بروید.
  6. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.
  7. روی ادامه کلیک کنید.
  8. اختیاری: کاربرها یا گروه‌هایی را که می‌توانند این حساب سرویس را مدیریت کنند و با آن کنش انجام دهند وارد کنید. برای جزئیات بیشتر، به جعل هویت حساب سرویس مراجعه کنید.
  9. برای تکمیل ایجاد حساب خدمات، روی تمام کلیک کنید.

    نشانی ایمیل حساب سرویس را یادداشت کنید.

gcloud CLI

  1. حساب سرویس را ایجاد کنید: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.

حساب سرویس در صفحه حساب سرویس نشان داده می‌شود.

ایجاد کلید خصوصی

برای ایجاد و بارگیری کلید خصوصی برای حساب سرویس، این مراحل را دنبال کنید:

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی نشانی ایمیل حساب سرویسی که می‌خواهید کلید برای آن ایجاد کنید کلیک کنید.
  4. روی برگه کلیدها کلیک کنید.
  5. روی منوِ کرکره‌ای افزودن کلید کلیک کنید، سپس ایجاد کلید جدید را انتخاب کنید.
  6. JSON را به‌عنوان نوع کلید انتخاب کنید و روی ایجاد کلیک کنید.

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

برای کسب اطلاعات بیشتر درباره حساب‌های خدمات، به حساب‌های خدمات در اسناد Google Cloud IAM مراجعه کنید.

عامل هوش مصنوعی ADK را مستقر کنید

  1. نمونه LLM Auditor را در «باغچه عامل Vertex AI» باز کنید:

    باز کردن نمونه

  2. روی استقرار کلیک کنید.

  3. درصورت درخواست، پروژه Google Cloud خود را انتخاب کنید.

  4. روی استقرار در Cloud Shell کلیک کنید.

  5. درصورت درخواست، روی مجاز کردن کلیک کنید و جریان OAuth را برای Cloud Shell طی کنید.

  6. وقتی Cloud Shell کاملاً بار شد، برای اجرای خط فرمان پیش‌بارشده و شروع استقرار، کلید Enter را فشار دهید.

  7. اگر از شما خواسته شد منطقه را وارد کنید، برای استفاده از منطقه پیش‌فرض، کلید Enter را فشار دهید.

  8. پس‌از تکمیل، به Vertex AI Agent Engine بروید:

    باز کردن Vertex AI Agent Engine

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

ایجاد و پیکربندی پروژه برنامه Chat

  1. برای باز کردن پروژه شروع سریع «عامل هوش مصنوعی ADK» Apps Script، روی دکمه زیر کلیک کنید.

    باز کردن پروژه

  2. روی نمای کلی > نماد تهیه کپی تهیه رونوشت کلیک کنید.

  3. در پروژه Apps Script خود، روی نماد تنظیمات پروژه تنظیمات پروژه > ویرایش دارایی‌های نوشتار > افزودن دارایی نوشتار کلیک کنید تا دارایی‌های نوشتار زیر را اضافه کنید:

    1. REASONING_ENGINE_RESOURCE_NAME با نام منبع عامل Vertex AI کپی‌شده در مراحل قبلی.
    2. ‫SERVICE_ACCOUNT_KEY با کلید JSON از حساب سرویس بارگیری‌شده در مراحل قبلی مثل { ... }.

  4. روی ذخیره کردن دارایی‌های نوشتار کلیک کنید

  5. در «کنسول Google API»، به «منو» > IAM و سرپرست > تنظیمات بروید.

    به «تنظیمات IAM و سرپرست» بروید

  6. در فیلد شماره پروژه، مقدار را کپی کنید.

  7. در پروژه Apps Script خود، روی نماد تنظیمات پروژه تنظیمات پروژه کلیک کنید.

  8. در بخش پروژه Google Cloud Platform (GCP)، روی تغییر پروژه کلیک کنید.

  9. در شماره پروژه GCP، شماره پروژه Google Cloud را که در مراحل قبلی کپی کرده‌اید جای‌گذاری کنید.

  10. روی تنظیم پروژه کلیک کنید. پروژه Cloud و پروژه Apps Script اکنون متصل هستند.

ایجاد استقرار آزمایشی

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

برای دریافت شناسه استقرار سر، کارهای زیر را انجام دهید:

  1. در پروژه برنامه Chat در Apps Script، روی پیاده‌سازی > آزمایش پیاده‌سازی‌ها کلیک کنید.
  2. در بخش شناسه استقرار سر، روی نماد تهیه کپی کپی کردن کلیک کنید.
  3. روی تمام کلیک کنید.

پیکربندی برنامه Chat

بااستفاده از پیاده‌سازی Apps Script، این مراحل را برای پیاده‌سازی برنامه Google Chat برای آزمایش دنبال کنید:

  1. در API Console، Google Chat API را جستجو کنید، و روی Google Chat API کلیک کنید.
  2. روی مدیریت کلیک کنید.

  3. روی پیکربندی کلیک کنید و برنامه Chat را راه‌اندازی کنید:

    1. در فیلد نام برنامه، ADK Quickstart را وارد کنید.
    2. در فیلد نشانی وب چهرک، https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png را وارد کنید.
    3. در فیلد شرح، ADK Quickstart را وارد کنید.
    4. در بخش عملکرد، گزینه پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید.
    5. در بخش «تنظیمات اتصال»، پروژه Apps Script را انتخاب کنید.
    6. در فیلد شناسه استقرار، شناسه استقرار «سر» را که قبلاً کپی کرده‌اید جای‌گذاری کنید.
    7. در بخش «رؤیت‌پذیری»، افراد و گروه‌های خاص در دامنه‌تان را انتخاب کنید و ایمیلتان را وارد کنید.

  4. روی ذخیره کلیک کنید.

برنامه Chat آماده پاسخ دادن به پیام‌ها است.

آزمایش کردن برنامه Chat

برای آزمایش برنامه Chat، فضای پیام مستقیمی را با برنامه Chat باز کنید و پیامی ارسال کنید:

  1. بااستفاده از حساب Google Workspace که هنگام اضافه کردن خودتان به‌عنوان آزمایش‌کننده معتمد ارائه کردید، Google Chat را باز کنید.

    رفتن به Google Chat

  2. روی گپ جدید کلیک کنید.
  3. در فیلد افزودن ۱ یا چند نفر، نام برنامه Chat خود را تایپ کنید.

  4. برنامه Chat را از نتایج انتخاب کنید. پیام مستقیمی باز می‌شود.

  5. در پیام مستقیم جدید با برنامه، The Eiffel Tower was completed in 1900 را تایپ کنید و enter را فشار دهید.

    برنامه Chat با پاسخ‌های منتقد و بازبین پاسخ می‌دهد.

برای افزودن آزمایش‌گران مطمئن و کسب اطلاعات بیشتر درباره آزمایش ویژگی‌های تعاملی، به آزمایش ویژگی‌های تعاملی برای برنامه‌های Google Chat مراجعه کنید.

عیب‌یابی

وقتی برنامه یا کارت Google Chat خطایی برمی‌گرداند، میانای Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمد». یا «نمی‌توانیم درخواستتان را پردازش کنیم.» گاهی‌اوقات «میانای کاربری Chat» هیچ پیام خطایی نمایش نمی‌دهد، اما برنامه Chat یا کارت نتیجه غیرمنتظره‌ای تولید می‌کند؛ برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در واسط کاربر Chat نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش برای کمک به شما در رفع خطاها وقتی گزارش خطا برای برنامه‌های Chat روشن باشد دردسترس است. برای دریافت راهنمایی درباره مشاهده، اشکال‌زدایی، و رفع خطاها، عیب‌یابی و رفع خطاهای Google Chat را ببینید.

مرتب‌سازی

برای اینکه هزینه منابع استفاده‌شده در این آموزش به حساب Google Cloud شما اضافه نشود، توصیه می‌کنیم پروژه Cloud را حذف کنید.

  1. در «کنسول Google API»، به صفحه مدیریت منابع بروید. روی منو > IAM و سرپرست > مدیریت منابع کلیک کنید.

    به «مدیر منابع» بروید

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