הגדרת גישה ל-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 משתמש בשלוש הזהויות הנפרדות.

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

פרופיל תיאור תפקידים והרשאות נדרשים
אדמין בענן מנהל את הגדרת הסביבה הראשונית החד-פעמית, את הקצאת ה-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 on Cloud API.
  • ‫roles/discoveryengine.editor או roles/discoveryengine.admin (ברמת הפרויקט)

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

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

  • ‫Google Cloud SDK: נדרש כדי להריץ פקודות לניהול פרויקטים. אם ה-CLI של gcloud לא מותקן במארח, מתקינים אותו.

  • ‫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). אחרת, אתם יכולים לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (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 Engine

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

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

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

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

    ASSISTANT_ID="default_assistant"

  5. יוצרים את ה-Assistant:

    הפקודה הזו רושמת Assistant חדש בפרויקט 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.