הגדרת גישה ל-API ולסביבה

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

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

  2. הגדרת AlphaEvolve

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

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

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

  • פרויקט בענן ב-Google Cloud: יוצרים פרויקט ייעודי Google Cloud עם קישורים פעילים לחיוב. לשאלות לגבי הקצאת פרויקטים או הוספה לרשימת ההיתרים, צריך לתאם עם צוות ניהול החשבון 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).
חשבון שירות זהות אוטומטית שמקיימת אינטראקציה ישירה עם שירות AlphaEvolve on Cloud API.
  • 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 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 on Cloud API. אדמין בענן יכול לעשות זאת דרך מסוף או באמצעות Google Cloud SDK במארח Linux: gcloud services enable discoveryengine.googleapis.com Google Cloud

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

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

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

ההיררכיה של משאבי Discovery Engine מתחילה בGoogle Cloud פרויקט, והמשאבים שלו מתארחים במיקום ספציפי (אזור). בתוך המבנה הבסיסי הזה, אוסף משמש כמאגר ארגוני ברמה העליונה למשאבים קשורים. ה-engine מוקצה בתוך אוסף כדי לארח את אפליקציית ה-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. יוצרים את מנוע החיפוש:

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

    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

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

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

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

  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.