ساخت یک برنامه گوگل چت با عامل هوش مصنوعی ADK

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

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

نمونه چند عامله حسابرس LLM به عنوان برنامه چت.

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

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

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

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

اهداف

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

پیش‌نیازها

محیط خود را تنظیم کنید

فعال کردن APIهای گوگل کلود

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.

  • در کنسول گوگل کلود، APIهای گوگل چت، ورتکس آی‌آی و کلود ریسورس منیجر را فعال کنید.

    فعال کردن APIها

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

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

  1. در کنسول گوگل کلود، به Menu > برویدGoogle Auth platform > برندسازی .

    به بخش برندسازی بروید

  2. اگر قبلاً تنظیمات را انجام داده‌اید Google Auth platformمی‌توانید تنظیمات صفحه رضایت OAuth زیر را در Branding ، Audience و Data Access پیکربندی کنید. اگر پیامی با این مضمون مشاهده کردید Google Auth platform هنوز پیکربندی نشده است ، روی شروع کار کلیک کنید:
    1. در قسمت اطلاعات برنامه ، در قسمت نام برنامه ، نامی برای برنامه وارد کنید.
    2. در ایمیل پشتیبانی کاربر ، یک آدرس ایمیل پشتیبانی انتخاب کنید که کاربران در صورت داشتن هرگونه سوال در مورد رضایت خود بتوانند با شما تماس بگیرند.
    3. روی بعدی کلیک کنید.
    4. در قسمت مخاطبان ، داخلی (Internal) را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در قسمت اطلاعات تماس ، یک آدرس ایمیل وارد کنید که از طریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در قسمت Finish ، سیاست داده‌های کاربر سرویس‌های API گوگل را مرور کنید و در صورت موافقت، گزینه «من با سیاست‌های داده‌های کاربر سرویس‌های API گوگل موافقم» را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کلیک کنید.
  3. فعلاً می‌توانید از اضافه کردن محدوده‌ها صرف نظر کنید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر (User type) را به خارجی (External) تغییر دهید. سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید. برای کسب اطلاعات بیشتر، به راهنمای کامل پیکربندی رضایت OAuth مراجعه کنید.

یک حساب کاربری سرویس در کنسول گوگل کلود ایجاد کنید

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

کنسول گوگل کلود

  1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

    به حساب‌های سرویس بروید

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

رابط خط فرمان جی‌کلاود

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

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

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

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

  1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

    به حساب‌های سرویس بروید

  2. حساب کاربری سرویس خود را انتخاب کنید.
  3. روی کلیدها > افزودن کلید > ایجاد کلید جدید کلیک کنید.
  4. JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.

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

  5. روی بستن کلیک کنید.

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

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

  1. نمونه LLM Auditor را در Vertex AI Agent Garden باز کنید:

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

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

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

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

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

  6. وقتی Cloud Shell کاملاً بارگذاری شد، Enter را فشار دهید تا خط فرمان از پیش بارگذاری شده اجرا شود و استقرار آغاز گردد.

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

  8. پس از اتمام، به موتور عامل هوش مصنوعی ورتکس بروید:

    موتور عامل هوش مصنوعی ورتکس را باز کنید

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

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

  1. برای باز کردن پروژه ADK AI Agent Quickstart Apps Script روی دکمه زیر کلیک کنید.

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

  2. روی نمای کلی کلیک کنید > آیکون مربوط به کپی کردن یک کپی تهیه کنید .

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

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

  4. روی ذخیره ویژگی‌های اسکریپت کلیک کنید

  5. در کنسول گوگل کلود، به Menu > IAM & Admin > Settings بروید.

    به تنظیمات IAM و مدیریت بروید

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

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

  8. در زیر پروژه پلتفرم ابری گوگل (GCP) ، روی تغییر پروژه کلیک کنید.

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

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

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

شما برای این پروژه Apps Script به یک شناسه استقرار نیاز دارید تا بتوانید در مرحله بعدی از آن استفاده کنید.

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

  1. در پروژه‌ی اسکریپت برنامه‌های چت، روی Deploy > Test deployments کلیک کنید.
  2. در زیر شناسه استقرار Head ، کلیک کنید آیکون مربوط به کپی کردن کپی کنید .
  3. روی انجام شد کلیک کنید.

پیکربندی برنامه چت

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

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

  3. روی پیکربندی کلیک کنید و برنامه چت را تنظیم کنید:

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

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

برنامه چت آماده پاسخگویی به پیام‌ها است.

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

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

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

    به گوگل چت بروید

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

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

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

    برنامه چت با پاسخ‌های زیر-عامل منتقد و بازبینی‌کننده پاسخ می‌دهد.

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

عیب‌یابی

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

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

تمیز کردن

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

  1. در کنسول گوگل کلود، به صفحه مدیریت منابع بروید. منو > مدیریت و دسترسی به منابع (IAM & Admin) > مدیریت منابع (Manage Resources) کلیک کنید.

    به مدیریت منابع بروید

  2. در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف کلیک کنید.
  3. در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن (Shut down) کلیک کنید.