התקנה והגדרה של AlphaEvolve

בדף הזה מוסבר איך לאתחל את הסביבה, להקצות את ה-API ולהגדיר את הגדרות המשתמש כדי להתחיל לעבוד עם AlphaEvolve.

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

  2. הגדרת AlphaEvolve

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

לפני שמגדירים את הסביבה, צריך לוודא שהארגון שלכם השלים את השלבים הבסיסיים של רכש ותשתית. Google Cloud

Google Cloud פרויקט ורישוי

  • פרויקט ב-Google Cloud: יוצרים פרויקט ייעודי ב- Google Cloud (GCP) עם קישורי חיוב פעילים. לשאלות לגבי הקצאת פרויקטים או הוספה לרשימת ההיתרים, צריך לתאם עם צוות ניהול החשבון Google Cloud שמשויך לחשבון שלכם.

  • רישיונות ל-Gemini Enterprise: אפשר לרכוש רישיונות ל-Gemini Enterprise דרך נציג המכירות או דרך Google Cloud Marketplace. Google Cloud אתם יכולים להוסיף רישיונות ל-Google Workspace או להקצות אותם כהצעות נפרדות. כל רמה של Gemini Enterprise, כולל רישיון ניסיון, מעניקה גישה ל-AlphaEvolve.

  • הערה לגבי הקצאת רישיונות: המערכת דורשת רישיון אחד ל-Gemini Enterprise לכל משתמש במערכת שמקיים אינטראקציה עם ה-API באמצעות התחזות לחשבון שירות. Google Cloud חשבונות שירות לא צורכים רישיונות ל-Workspace או ל-Cloud Identity.

פרופילי משתמשים ודרישות IAM

מחזור החיים של AlphaEvolve מתבסס על שלושת הזהויות השונות.

חשוב לוודא שהפרויקט תואם לתפקידים הבאים של בקרת גישה חובה:

פרופיל תיאור תפקידים והרשאות נדרשים
Cloud Administrator ניהול של הגדרת סביבה ראשונית חד-פעמית, הפעלת API והקצאת IAM.
  • roles/resourcemanager.projectCreator (ברמת הארגון / התיקייה)
  • ‫roles/billing.user (רמת החשבון לחיוב)
  • roles/serviceusage.admin
  • הרשאות אדמין ב-Workspace או ב-Cloud Identity
משתמש במערכת
(חוקר / מדען)		 מגדיר ומבצע ניסויי אופטימיזציה. אינטראקציה עם ה-API אך ורק באמצעות התחזות לחשבון שירות.
  • roles/iam.serviceAccountTokenCreator שניתנה במשאב של חשבון השירות.
  • אופציונלי: roles/iam.serviceAccountUser אם מחברים את חשבון השירות למשאבי מחשוב (לדוגמה, Vertex AI Workbench).
חשבון שירות זהות אוטומטית שמתקשרת ישירות עם שירות ה-API של AlphaEvolve בגרסת Cloud Private Preview.
  • roles/discoveryengine.admin (בהיקף הפרויקט)

סביבת מארח אדמיניסטרטיבית

מארח Linux אדמיניסטרטיבי (למשל, Google Cloud Shell או מארח bastion מאובטח) מריץ את סקריפטים ההגדרה ואת מטען המבחן. מוודאים שהמארח מכיל את כלי השירות הבסיסיים הבאים:

  • Google Cloud SDK: נדרש להפעלת פקודות לניהול פרויקטים. אם gcloud CLI לא מותקן במארח, צריך להתקין אותו.

  • ‫curl: מאמת את הגישה לתעבורת HTTP לנקודת הקצה של ה-API בעורף השרת. במערכות הפעלה מסוג Debian או Ubuntu, מתקינים את כלי השירות דרך מנהל החבילות:

    sudo apt update && sudo apt install -y curl

הגדרת AlphaEvolve

כדי להגדיר את AlphaEvolve, צריך לתאם בין האדמין בענן לבין משתמש המערכת. צריך להשלים את משימות ההתקנה הבאות:

יצירה של חשבון שירות

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

  1. מגדירים את מזהה הפרויקט: Google Cloud

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

    PROJECT_ID="my-gcp-project-id"

    לחלופין, אפשר לאחזר באופן דינמי את מזהה הפרויקט הפעיל ב-CLI:

    PROJECT_ID=$(gcloud config get project)

  2. בוחרים שם לחשבון השירות:

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

    SA_NAME="alpha-evolve-client"

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

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

    gcloud iam service-accounts create "${SA_NAME}" \
  --description="Service Account to call AlphaEvolve on Cloud Private \
Preview API service" \
  --display-name="AlphaEvolve Client SA" \
  --project=$PROJECT_ID

  4. מחפשים את המחרוזת של כתובת האימייל של חשבון השירות:

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

    SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list \
  --filter="displayName:AlphaEvolve Client SA" \
  --format='value(email)' \
  --project=$PROJECT_ID)

echo "Newly created Service Account Email: ${SERVICE_ACCOUNT_EMAIL}"

  1. מקצים לחשבון השירות את התפקיד Discovery Engine:

    מריצים את הפקודה gcloud הבאה כדי להעניק לחשבון השירות את התפקיד roles/discoveryengine.admin ברמת הפרויקט:

    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/discoveryengine.admin" \
  --project="${PROJECT_ID}"

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

    • ‫--member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}": מציין את חשבון המשתמש שמקבל את היכולות של תפקיד האדמין.

    • ‫--role="roles/discoveryengine.admin": מעניקה את ההרשאות הנדרשות ליצירת מופעים בסיסיים של Discovery Engine, סשנים של שיחות ומשאבי צאצא של AlphaEvolveExperiments.

    • ‫${SERVICE_ACCOUNT_EMAIL}: מזהה את המשאב (חשבון השירות החדש) שחשבון המשתמש יכול להתחזות אליו.

התחזות לחשבון השירות

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

  1. מגדירים את הגורם המבצע את ההתחזות: מצהירים על משתנה מחרוזת היעד. מחליפים את SYSTEM_USER_EMAIL בזהות הארגונית או בכתובת האימייל של החוקר שמבצע את הרצות האופטימיזציה.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

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

    gcloud iam service-accounts add-iam-policy-binding \
  "${SERVICE_ACCOUNT_EMAIL}" \
  --member="${SYSTEM_USER}" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project="${PROJECT_ID}"

    קישור ההרשאה הזה מבטיח:

    • ‫--member="${SYSTEM_USER}": מציין את המשתמש האנושי שמקבל את ההרשאה ליצירת אישורים.

    • ‫--role="roles/iam.serviceAccountTokenCreator": מעניקה הרשאה ליצור אסימוני גישה לטווח קצר מסוג OAuth 2.0, שמאפשרים התחזות בטוחה לחשבון שירות.

    • "${SERVICE_ACCOUNT_EMAIL}": מזהה את משאב חשבון השירות של היעד שמקושר למדיניות הנכנסת.

הפעלת Discovery Engine API

אדמין בענן צריך להפעיל את discoveryengine.googleapis.com API כדי שיוכל ליצור אינטראקציה עם נקודות הקצה של AlphaEvolve בגרסת טרום-השקה פרטית בענן. אדמין בענן יכול לעשות את זה דרך Google Cloud המסוף או באמצעות Google Cloud SDK במארח Linux: gcloud services enable discoveryengine.googleapis.com

יצירה של משאבים וסשנים במנוע Discovery

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

היררכיית המשאבים של Discovery Engine

ההיררכיה של משאבי Discovery Engine מתחילה בGoogle Cloud פרויקט, והמשאבים שלו מתארחים במיקום ספציפי (אזור). בתוך המבנה הבסיסי הזה, אוסף משמש כמאגר ארגוני ברמה העליונה למשאבים קשורים. המנוע מוקצה בתוך אוסף כדי לארח את אפליקציית ה-AI המרכזית, וגם כדי להגדיר משאב של עוזר וירטואלי לניהול המאפיינים והכלים של ה-AI הגנרטיבי באפליקציה. המנוע מנהל אינטראקציות של משתמשים בודדים שנרשמות כאובייקטים של סשן.

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

היררכיה ב-Discovery Engine

הקצאת המשאבים

  1. מגדירים את מזהה הפרויקט: Google Cloud

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

    PROJECT_ID="my-gcp-project-id"

    או

    PROJECT_ID=$(gcloud config get project)

  2. מגדירים את מזהה המנוע:

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

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. יוצרים את מנוע החיפוש:

    הפקודה הזו רושמת מנוע חדש בפרויקט Google Cloud , ומגדירה את השם הייחודי שלו, השם המוצג ו-SolutionType (SOLUTION_TYPE_GENERATIVE_CHAT)

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}?engineId=${ENGINE_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ENGINE_ID}"'",
    "data_store_ids": [],
    "solution_type": "SOLUTION_TYPE_GENERATIVE_CHAT"
  }'

  4. מגדירים את מזהה העוזר הדיגיטלי:

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

    ASSISTANT_ID="default_assistant"

  5. יוצרים את העוזר האישי:

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

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}/${ENGINE_ID}/assistants?assistantId=${ASSISTANT_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ASSISTANT_ID}"'",
    "description": null,
    "generation_config": null,
    "web_grounding_type": "WEB_GROUNDING_TYPE_UNSPECIFIED",
    "enabled_actions": null,
    "customer_policy": null
  }'

בדיקת הגישה ל-API

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

יצירת אסימון גישה באמצעות התחזות

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

  gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}"

שימוש בטוקן הגישה

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

  TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}")
  curl -X GET \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}"

הצגה ומחיקה של מנועי חיפוש

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

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines"
  curl -X GET "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines/${ENGINE_ID}"
  curl -X DELETE "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

סיימתם את שלבי ההגדרה. עכשיו אפשר להריץ את AlphaEvolve V1 API.