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

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

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

  2. הגדרת AlphaEvolve

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

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

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

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

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

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

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

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

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

פרופיל תיאור תפקידים והרשאות נדרשים
Cloud Administrator מנהל הגדרה חד-פעמית של הסביבה, הקצאת הרשאות IAM והפעלה של Discovery Engine API ו-Gemini API ב-Vertex AI.
  • roles/resourcemanager.projectCreator (ברמת הארגון / התיקייה)
  • ‫roles/billing.user (רמת החשבון לחיוב)
  • roles/serviceusage.admin
  • הרשאות אדמין ב-Workspace או ב-Cloud Identity
משתמש במערכת
(חוקר / מדען)		 מגדיר ומבצע ניסויי אופטימיזציה. אינטראקציה עם ה-API אך ורק באמצעות התחזות לחשבון שירות.
  • roles/iam.serviceAccountTokenCreator שניתנה במשאב של חשבון השירות.
  • אופציונלי: roles/iam.serviceAccountUser אם מצרפים את חשבון השירות למשאבי מחשוב (לדוגמה, Vertex AI Workbench).
חשבון שירות זהות אוטומטית שמקיימת אינטראקציה ישירה עם שירות AlphaEvolve ב-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}"

  5. מקצים לחשבון השירות את התפקיד 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}": מזהה את משאב חשבון השירות של היעד שמקושר למדיניות הנכנסת.

הפעלת ממשקי ה-API הנדרשים

האדמין בענן צריך להפעיל שני ממשקי API בפרויקט:

  • ‫Discovery Engine API‏ (discoveryengine.googleapis.com), שמשמש את נקודות הקצה של AlphaEvolve on Cloud API.

  • ‫Vertex AI API‏ (aiplatform.googleapis.com), שמשמש את Gemini API ב-Vertex AI. ‫AlphaEvolve יוצרת כל תוכנית מועמדת באמצעות קבוצה של מודלים של Gemini, ולכן משתמש במערכת לא יכול להריץ ניסוי עד שה-API הזה מופעל.

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

הפעלת ממשקי ה-API

לחלופין, אפשר להפעיל את שני ממשקי ה-API באמצעות Google Cloud SDK במארח Linux:

gcloud services enable discoveryengine.googleapis.com \
  aiplatform.googleapis.com --project="${PROJECT_ID}"

מוודאים ששני ממשקי ה-API מופעלים:

gcloud services list --enabled --project="${PROJECT_ID}" \
  --filter="config.name:(discoveryengine.googleapis.com OR aiplatform.googleapis.com)"

יצירה של משאבים וסשנים במנוע 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. יוצרים את מנוע החיפוש:

    הפקודה הזו רושמת מנוע חדש ב 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

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

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

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

  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.