بیانیه های بررسی واقعیت با عامل ADK AI و مدل Gemini

سطح کدنویسی : پیشرفته
مدت زمان : ۳۰ دقیقه
نوع پروژه : تابع سفارشی

نمای کلی

یک تابع سفارشی بررسی صحت اطلاعات برای Google Sheets که به عنوان یک پروژه اسکریپت برنامه‌های مقید (bound Apps Script) با پشتیبانی یک عامل هوش مصنوعی Vertex و مدل Gemini مورد استفاده قرار می‌گیرد.

این نمونه نشان می‌دهد که چگونه می‌توانید از دو نوع منبع قدرتمند هوش مصنوعی مستقیماً در صفحات گسترده Google Sheets خود استفاده کنید:

1. عامل‌های هوش مصنوعی برای قابلیت‌های استدلال پیچیده، چند ابزاری و چند مرحله‌ای با استفاده از عامل‌های ADK مستقر در موتور عامل هوش مصنوعی Vertex.
2. مدل‌های هوش مصنوعی برای درک پیشرفته، قابلیت‌های تولید و خلاصه‌سازی با استفاده از مدل‌های Gemini از Vertex AI.

اهداف

• بفهمید که راه حل چه کاری انجام می‌دهد.
• نحوه اجرای راه حل را درک کنید.
• عامل هوش مصنوعی Vertex را مستقر کنید.
• اسکریپت را تنظیم کنید.
• اسکریپت را اجرا کنید.

درباره این راهکار

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

• طریقه استفاده:
  • برای خروجی مختصر و مفید =FACT_CHECK("Your statement here") .
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") برای یک قالب خروجی خاص.
• استدلال: LLM Auditor ADK AI Agent (نمونه پایتون) .
• قالب‌بندی خروجی: مدل جمینی .

این راهکار با استفاده از UrlFetchApp، APIهای Vertex AI REST را درخواست می‌کند.

معماری

نمودار زیر معماری منابع Google Workspace و Google Cloud مورد استفاده توسط تابع سفارشی را نشان می‌دهد.

پیش‌نیازها

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

• یک حساب گوگل (حساب‌های کاربری گوگل ورک‌اسپیس ممکن است نیاز به تأیید مدیر داشته باشند).

• یک مرورگر وب با دسترسی به اینترنت.

• پیش نیازهای نماینده LLM Auditor ADK

  • پایتون ۳.۱۱+: برای نصب، دستورالعمل‌های موجود در وب‌سایت رسمی پایتون را دنبال کنید.
  • شعر پایتون: برای نصب، دستورالعمل‌های موجود در وب‌سایت رسمی شعر را دنبال کنید.
  • رابط خط فرمان گوگل کلود: برای نصب، دستورالعمل‌های موجود در وب‌سایت رسمی گوگل کلود را دنبال کنید.

محیط را آماده کنید

این بخش نحوه ایجاد و پیکربندی یک پروژه Google Cloud را نشان می‌دهد.

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

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

1. در کنسول گوگل کلود، به menu Menu > IAM & Admin > Create a Project بروید.

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

2. در قسمت نام پروژه ، یک نام توصیفی برای پروژه خود وارد کنید.

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

3. در فیلد «مکان» ، روی «مرور» کلیک کنید تا مکان‌های بالقوه برای پروژه شما نمایش داده شود. سپس، روی «انتخاب» کلیک کنید.
4. روی ایجاد کلیک کنید. کنسول Google Cloud به صفحه داشبورد هدایت می‌شود و پروژه شما ظرف چند دقیقه ایجاد می‌شود.

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

در یکی از محیط‌های توسعه زیر، به رابط خط فرمان گوگل کلود ( gcloud ) دسترسی پیدا کنید:

• Cloud Shell : برای استفاده از یک ترمینال آنلاین با رابط خط فرمان gcloud که از قبل تنظیم شده است، Cloud Shell را فعال کنید.
  فعال کردن پوسته ابری
• پوسته محلی : برای استفاده از یک محیط توسعه محلی، رابط خط فرمان gcloud را نصب و راه‌اندازی کنید .
  برای ایجاد یک پروژه ابری، از دستور gcloud projects create استفاده کنید:

  gcloud projects create PROJECT_ID

  به جای PROJECT_ID ، شناسه پروژه‌ای که می‌خواهید ایجاد کنید را وارد کنید.

فعال کردن پرداخت برای پروژه ابری

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

1. در کنسول گوگل کلود، به بخش صورتحساب (Billing) بروید. menu ) > صورتحساب (Billing) > پروژه‌های من (My Projects) کلیک کنید.

   به بخش پرداخت هزینه‌های پروژه‌های من بروید

2. در بخش «انتخاب سازمان» ، سازمانی را که با پروژه Google Cloud شما مرتبط است، انتخاب کنید.
3. در ردیف پروژه، منوی اقدامات ( more_vert ) را باز کنید، روی تغییر صورتحساب کلیک کنید و حساب صورتحساب ابری را انتخاب کنید.
4. روی تنظیم حساب کلیک کنید.

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

1. برای فهرست کردن حساب‌های صورتحساب موجود، دستور زیر را اجرا کنید:

   gcloud billing accounts list

2. یک حساب صورتحساب را با یک پروژه Google Cloud مرتبط کنید:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   موارد زیر را جایگزین کنید:

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

فعال کردن API هوش مصنوعی ورتکس

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

با دنبال کردن مراحل زیر، یک حساب کاربری سرویس جدید با نقش 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 مراجعه کنید.

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

1. اگر قبلاً این کار را نکرده‌اید، با حساب Google Cloud خود احراز هویت کنید و Google Cloud CLI را برای استفاده از پروژه Google Cloud خود پیکربندی کنید.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   به جای PROJECT_ID شناسه پروژه ابری که ایجاد کرده‌اید را قرار دهید.

2. این مخزن گیت‌هاب را دانلود کنید

   دانلود

3. در محیط توسعه محلی مورد نظر خود، فایل بایگانی دانلود شده را استخراج کرده و دایرکتوری adk-samples/python/agents/llm-auditor را باز کنید.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. یک سطل ذخیره‌سازی ابری جدید مختص عامل ADK ایجاد کنید.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   موارد زیر را جایگزین کنید:

   1. CLOUD_STORAGE_BUCKET_NAME با یک نام سطل منحصر به فرد که می‌خواهید استفاده کنید، پر کنید.
   2. PROJECT_ID با شناسه پروژه ابری که ایجاد کرده‌اید.
   3. PROJECT_LOCATION با محل پروژه ابری که ایجاد کرده‌اید.

5. متغیرهای محیطی زیر را تنظیم کنید:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   موارد زیر را جایگزین کنید:

   1. CLOUD_STORAGE_BUCKET_NAME با نام باکتی که ایجاد کرده‌اید.
   2. PROJECT_ID با شناسه پروژه ابری که ایجاد کرده‌اید.
   3. PROJECT_LOCATION با محل پروژه ابری که ایجاد کرده‌اید.

6. نصب و استقرار ADK agent از محیط مجازی.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. شناسه عامل را بازیابی کنید، بعداً برای پیکربندی تابع سفارشی به آن نیاز خواهید داشت.

   python3 deployment/deploy.py --list

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

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

مشاهده در گیت‌هاب

ایجاد و پیکربندی در یک صفحه گسترده جدید

1. روی دکمه‌ی زیر کلیک کنید و یک کپی کامل از نمونه‌ی صفحه‌گسترده‌ی گوگل شیت، شامل پروژه‌ی اسکریپت برنامه‌های متصل به کانتینر آن، تهیه کنید.

   کپی کردن صفحات گوگل اسپیدشیت

2. در صفحه‌گسترده‌ی تازه ایجاد شده، به Extensions > Apps Script بروید.

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

   1. LOCATION با مکان پروژه Google Cloud که در مراحل قبلی مانند us-central1 ایجاد شده است.
   2. GEMINI_MODEL_ID با مدل Gemini که می‌خواهید استفاده کنید مانند gemini-2.5-flash-lite .
   3. REASONING_ENGINE_ID با شناسه‌ی LLM Auditor ADK Agent که در مراحل قبلی پیاده‌سازی شده است، مانند 1234567890 .
   4. SERVICE_ACCOUNT_KEY با کلید JSON از حساب سرویس دانلود شده در مراحل قبلی مانند { ... } .

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

تابع سفارشی را آزمایش کنید

1. به صفحه گسترده تازه ایجاد شده بروید.
2. عبارات ستون A را تغییر دهید.
3. فرمول‌های ستون B اجرا می‌شوند و سپس نتایج بررسی صحت اطلاعات را نمایش می‌دهند.

تمیز کردن

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

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

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

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

مراحل بعدی

• توابع سفارشی در گوگل شیت
• گسترش صفحات گوگل