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

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

نمای کلی

یک تابع سفارشی راستی‌آزمایی برای Google Sheets که به‌عنوان یک پروژه Apps Script محدود شده با یک عامل Vertex AI و مدل Gemini استفاده می‌شود.

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

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

نمونه استفاده از عملکرد سفارشی Google Sheets بررسی واقعیت

اهداف

  • درک کنید که راه حل چه کاری انجام می دهد.
  • درک چگونگی پیاده سازی راه حل.
  • عامل Vertex AI را مستقر کنید.
  • اسکریپت را تنظیم کنید
  • اسکریپت را اجرا کنید.

در مورد این راه حل

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

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

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

معماری

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

نمودار معماری عملکرد سفارشی Google Sheets را بررسی کنید

پیش نیازها

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

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

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

یک پروژه Google Cloud ایجاد کنید

کنسول Google Cloud

  1. در کنسول Google Cloud، به منو > IAM & Admin > ایجاد پروژه بروید.

    به Create a Project بروید

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

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

  3. در قسمت Location ، روی Browse کلیک کنید تا مکان های احتمالی پروژه شما نمایش داده شود. سپس، روی انتخاب کلیک کنید.
  4. روی ایجاد کلیک کنید. کنسول Google Cloud به صفحه داشبورد می رود و پروژه شما در عرض چند دقیقه ایجاد می شود.

gcloud CLI

در یکی از محیط‌های توسعه زیر، به Google Cloud CLI ( gcloud ) دسترسی پیدا کنید:

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

صورتحساب پروژه Cloud را فعال کنید

کنسول Google Cloud

  1. در کنسول Google Cloud، به Billing بروید. > صورت‌حساب > پروژه‌های من کلیک کنید.

    به Billing for My Projects بروید

  2. در انتخاب سازمان ، سازمان مرتبط با پروژه Google Cloud خود را انتخاب کنید.
  3. در ردیف پروژه، منوی Actions ( ) را باز کنید، روی Change billing کلیک کنید و حساب Cloud Billing را انتخاب کنید.
  4. روی تنظیم حساب کلیک کنید.

gcloud CLI

  1. برای فهرست کردن حساب‌های صورت‌حساب موجود، اجرا کنید: 
    gcloud billing accounts list
  2. پیوند یک حساب صورت‌حساب با پروژه Google Cloud:
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

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

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

Vertex AI API را فعال کنید

کنسول Google Cloud

  1. در کنسول Google Cloud، Vertex AI API را فعال کنید.

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

  2. تأیید کنید که Vertex AI API را در پروژه Cloud صحیح فعال می‌کنید، سپس روی Next کلیک کنید.

  3. تأیید کنید که API صحیح را فعال کرده اید، سپس روی فعال کردن کلیک کنید.

gcloud CLI

  1. در صورت لزوم، پروژه فعلی Cloud را روی پروژه ای که با دستور gcloud config set project ایجاد کرده اید، تنظیم کنید:

    gcloud config set project PROJECT_ID

    PROJECT_ID با Project ID پروژه Cloud که ایجاد کردید جایگزین کنید.

  2. Vertex AI API را با دستور gcloud services enable فعال کنید:

    gcloud services enable aiplatform.googleapis.com

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

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

کنسول Google Cloud

  1. در کنسول Google Cloud، به منو > IAM & Admin > حساب‌های سرویس بروید.

    به حساب های خدماتی بروید

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

gcloud CLI

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

حساب سرویس در صفحه حساب سرویس ظاهر می شود. بعد، یک کلید خصوصی برای حساب سرویس ایجاد کنید.

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

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

  1. در کنسول Google Cloud، به منو > IAM & Admin > حساب‌های سرویس بروید.

    به حساب های خدماتی بروید

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

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

  5. روی Close کلیک کنید.

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

عامل LLM Auditor ADK AI را مستقر کنید

  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

    شناسه پروژه Cloud را که ایجاد کردید جایگزین PROJECT_ID کنید.

  2. این مخزن GitHub را دانلود کنید

    دانلود کنید

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

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

  4. یک سطل Cloud Storage جدید اختصاص داده شده به عامل ADK ایجاد کنید.

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

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

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

  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 با شناسه پروژه Cloud که ایجاد کردید.
    3. PROJECT_LOCATION با مکان پروژه Cloud که ایجاد کردید.

  6. عامل ADK را از محیط مجازی نصب و اجرا کنید. 

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

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

    python3 deployment/deploy.py --list

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

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

در GitHub مشاهده کنید

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

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

    صفحه‌نگار Google Sheets را کپی کنید

  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. در کنسول Google Cloud، به صفحه مدیریت منابع بروید. > IAM & Admin > Manage Resources کلیک کنید.

    به Resource Manager بروید

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

مراحل بعدی