איך בודקים עובדות בעזרת סוכן AI של ADK ומודל Gemini

רמת הקידוד: מתקדמת
משך הזמן: 30 דקות
סוג הפרויקט: פונקציה בהתאמה אישית

סקירה כללית

פונקציה מותאמת אישית לבדיקת עובדות ב-Google Sheets, לשימוש כפרויקט Apps Script שמשולב עם סוכן Vertex AI ומודל Gemini.

בדוגמה הזו אפשר לראות איך משתמשים בשני סוגים של משאבי AI ישירות בגליונות אלקטרוניים ב-Google Sheets:

1. סוכני AI ליכולות מתוחכמות של הסקת מסקנות מרובת-שלבים באמצעות כמה כלים, באמצעות סוכני ADK שנפרסו ב-Vertex AI Agent Engine.
2. מודלים של AI להבנה מתקדמת, ליצירה ולסיכום באמצעות מודלים של Gemini מ-Vertex AI.

מטרות

• להבין מה הפתרון עושה.
• להבין איך הפתרון מיושם.
• פורסים את סוכן 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 (Python sample).
• עיצוב הפלט: מודל Gemini.

הפתרון הזה שולח בקשות ל-Vertex AI REST APIs באמצעות UrlFetchApp.

ארכיטקטורה

בתרשים הבא מוצגת הארכיטקטורה של משאבי Google Workspace ו-Google Cloud שבהם נעשה שימוש בפונקציה המותאמת אישית.

דרישות מוקדמות

כדי להשתמש בדוגמה הזו, אתם צריכים לעמוד בדרישות המוקדמות הבאות:

• חשבון Google (יכול להיות שחשבונות Google Workspace ידרשו אישור אדמין).

• דפדפן אינטרנט עם גישה לאינטרנט.

• דרישות מוקדמות לסוכן LLM Auditor ADK

  • ‫Python 3.11 ומעלה: כדי להתקין, פועלים לפי ההוראות באתר הרשמי של Python.
  • ‫Python Poetry: כדי להתקין את הכלי, פועלים לפי ההוראות באתר הרשמי של Poetry.
  • ‫Google Cloud CLI: כדי להתקין את הכלי, פועלים לפי ההוראות באתר הרשמי של Google Cloud.

הכנת הסביבה

בקטע הזה מוסבר איך ליצור ולהגדיר פרויקט ב-Google Cloud.

יצירת פרויקט של Google Cloud

מסוף Google Cloud

1. במסוף Google Cloud, עוברים אל תפריט > IAM & Admin > Create a Project (יצירת פרויקט).

   כניסה לדף Create a Project

2. בשדה Project Name (שם הפרויקט), מזינים שם תיאורי לפרויקט.

   אופציונלי: כדי לערוך את מזהה הפרויקט, לוחצים על עריכה. אי אפשר לשנות את מזהה הפרויקט אחרי שהוא נוצר, לכן חשוב לבחור מזהה שיענה על הצרכים שלכם למשך חיי הפרויקט.

3. בשדה Location, לוחצים על Browse כדי להציג מיקומים אפשריים לפרויקט. אחר כך לוחצים על בחירה.
   שימו לב: לא מוצאים את הארגון שלכם ב-Google Workspace?
   המשמעות היא שלא נכנסתם לחשבון Google Workspace. חלק מהתכונות שמתוארות במסמכי התיעוד למפתחים של Google Workspace זמינות רק לפרויקטים שמשויכים לארגון.
4. לוחצים על יצירה. מערכת Google Cloud מעבירה אתכם לדף Dashboard והפרויקט נוצר תוך כמה דקות.

CLI של gcloud

באחת מסביבות הפיתוח הבאות, ניגשים אל Google Cloud CLI‏ (gcloud):

• ‫Cloud Shell: כדי להשתמש בטרמינל אונליין שבו כבר מוגדר ה-CLI של gcloud, צריך להפעיל את Cloud Shell.
  הפעלת Cloud Shell
• מעטפת מקומית: כדי להשתמש בסביבת פיתוח מקומית, צריך להתקין ולהפעיל את ה-CLI של gcloud.
  כדי ליצור פרויקט ב-Cloud, משתמשים בפקודה gcloud projects create:
  ‫

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID במזהה של הפרויקט שרוצים ליצור.

הפעלת החיוב בפרויקט ב-Cloud

אם אין לכם אפשרות לקשר חשבון לחיוב, המשמעות היא שאין לכם את ההרשאות שנדרשות לביצוע השינוי. מידע נוסף זמין במאמר בנושא ההרשאות שנדרשות להפעלת החיוב.

מסוף Google Cloud

1. במסוף Google Cloud, עוברים אל Billing. לוחצים על תפריט > חיוב > הפרויקטים שלי.

   כניסה לדף Billing for My Projects

2. בקטע Select an organization (בחירת ארגון), בוחרים את הארגון שמשויך לפרויקט שלכם ב-Google Cloud.
3. בשורת הפרויקט, פותחים את התפריט Actions (), לוחצים על Change billing ובוחרים את החשבון לחיוב ב-Cloud.
4. לוחצים על Set account.

CLI של gcloud

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, ואז לוחצים על הבא.

3. מוודאים שמפעילים את ה-API הנכון ולוחצים על הפעלה.

CLI של gcloud

1. אם צריך, מגדירים את פרויקט Cloud הנוכחי לפרויקט שיצרתם באמצעות הפקודה gcloud config set project:

   gcloud config set project 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 > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. לוחצים על יצירת חשבון שירות.
3. ממלאים את פרטי חשבון השירות ולוחצים על יצירה והמשך.
   הערה: כברירת מחדל, Google יוצרת מזהה ייחודי לחשבון שירות. אם רוצים לשנות את המזהה, משנים אותו בשדה של מזהה חשבון השירות.
4. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
5. לוחצים על המשך.
6. אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל את חשבון השירות הזה ולבצע בו פעולות. פרטים נוספים זמינים במאמר ניהול התחזות לחשבון שירות.
7. לוחצים על סיום. רושמים את כתובת האימייל של חשבון השירות.

CLI של gcloud

1. יוצרים את חשבון השירות:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.

חשבון השירות מופיע בדף של חשבון השירות. בשלב הבא, יוצרים מפתח פרטי לחשבון השירות.

יצירת מפתח פרטי

אזהרה: בדוגמה הזו נעשה שימוש במפתח של חשבון שירות שיוצא, כדי לפשט את התהליך. לא מומלץ לייצא מפתח פרטי בסביבת ייצור, כי אסור לאחסן אותו במיקום לא מאובטח, כמו בקרת מקור.

מידע נוסף על יישומים מאובטחים של חשבונות שירות ושיטות מומלצות זמין במאמר מתי כדאי להשתמש בחשבונות שירות.

כדי ליצור ולהוריד מפתח פרטי לחשבון השירות, פועלים לפי השלבים הבאים:

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
4. בוחרים באפשרות JSON ולוחצים על Create.

   זוג המפתחות הציבורי/הפרטי החדש נוצר ומורד למחשב שלכם כקובץ חדש. שומרים את קובץ ה-JSON שהורדתם בשם credentials.json בספריית העבודה. הקובץ הזה הוא העותק היחיד של המפתח. מידע על אחסון מאובטח של המפתח זמין במאמר ניהול מפתחות לחשבונות שירות.

5. לוחצים על סגירה.

מידע נוסף על חשבונות שירות זמין במאמר חשבונות שירות במרכז העזרה של IAM ב-Google Cloud.

פריסת סוכן ה-AI של 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 במזהה של פרויקט Cloud שיצרתם.

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, כולל פרויקט Apps Script שקשור למאגר התגים.

   העתקת גיליון אלקטרוני ב-Google Sheets

2. בגיליון האלקטרוני החדש שנוצר, עוברים אל תוספים > Apps Script.

3. בפרויקט Apps Script, עוברים אל Project Settings (הגדרות הפרויקט), לוחצים על Edit script properties (עריכת מאפייני הסקריפט), ואז על Add script property (הוספת מאפיין סקריפט) כדי להוסיף את מאפייני הסקריפט הבאים:

   1. LOCATION במיקום של הפרויקט ב-Google Cloud שנוצר בשלבים הקודמים, למשל us-central1.
   2. ‫GEMINI_MODEL_ID עם המודל של Gemini שרוצים להשתמש בו, כמו gemini-2.5-flash-lite.
   3. ‫REASONING_ENGINE_ID עם המזהה של סוכן LLM Auditor ADK שנפרס בשלבים הקודמים, כמו 1234567890.
   4. ‫SERVICE_ACCOUNT_KEY עם מפתח ה-JSON מחשבון השירות שהורדתם בשלבים הקודמים, כמו { ... }.

4. לוחצים על שמירת מאפייני סקריפט.

בדיקת הפונקציה המותאמת אישית

1. עוברים לגיליון האלקטרוני החדש שנוצר.
2. משנים את ההצהרות בעמודה A.
3. הנוסחאות בעמודה B מופעלות ואז מוצגות תוצאות בדיקת העובדות.

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, מומלץ למחוק את פרויקט Cloud.

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו כתובת URL ב-appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

אם אתם מתכננים להיעזר במספר מדריכי לימוד או מדריכים למתחילים, מומלץ להשתמש שוב באותו פרויקט כדי לא לחרוג ממכסות הפרויקטים.

1. במסוף Google Cloud, עוברים לדף Manage resources. לוחצים על תפריט > IAM & Admin > Manage Resources.

   כניסה ל-Resource Manager

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete .
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

השלבים הבאים

• פונקציות מותאמות אישית ב-Google Sheets
• הרחבת Google Sheets