מאמרי עזרה על AlphaEvolve API

המסמך הזה הוא מאמר העזרה הרשמי של ה-API ומפרט המערכת של AlphaEvolve Cloud API, במסגרת שכבות השיחה של Google CloudDiscovery Engine. הוא מגדיר את ההיררכיות המדויקות של המשאבים בתצוגת עץ, נקודות הקצה של REST ו-gRPC, האילוצים ברמת השדה, מכונות המצבים של מחזור החיים, מטריצות האבחון של השגיאות, כללי ארגז החול לאבטחה ותהליכי העבודה של השילוב שנדרשים כדי לתכנן בקר בצד הלקוח ולולאת הערכה אוטומטיים לחלוטין.

מכונות מצב מאוחדות של מחזור החיים

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

מצבים במחזור החיים של הניסוי

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

  • ‫CREATED: מצב ההפעלה. המשאב מוצהר ומוגדר, אבל עדיין לא אוכלסו בו דורות ראשוניים ולא נשלחו קריאות ל-API.

  • ‫RUNNING: מצב ההערכה הפעיל. המנוע דוגם בו-זמנית מועמדים להורה, יוצר מוטציות קוד באמצעות תערובת ה-LLM ומעביר משימות למעריכים.

  • ‫PAUSED: מצב השהיה זמני שמופעל באופן ידני או באמצעות idle_timeout הגנה אוטומטי. יצירת הקוד נפסקת, וה-workers הקיימים משהים את שליחת המדדים.

  • ‫COMPLETED: מצב סופי שמציין שהחיפוש השיג את הקצאת היעד של max_programs או הגיע למגבלת היצירה המבנית.

  • ‫FAILED: מצב שגיאה סופית שמציין שבעיות סביבתיות מערכתיות – כמו חריגות לא מטופלות בפרטי הכניסה ל-API, פגיעה במאגר הנתונים או קריסות רצופות של ה-runner – עצרו את העיבוד.

מצבי התוכנית

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

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

  1. ‫INITIALIZED: הרשומה של התוכנית נוצרת במסד הנתונים, והמערכת עוקבת אחרי השושלת שלה והקישורים לתוכנית ההורה.

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

  3. ‫EVALUATING: המטען הייעודי (payload) של הקוד ננעל על ידי תהליך של עובד הערכה, ומופעל בתוך סביבה מבודדת של מסגרת בדיקה.

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

מנגנוני בו-זמניות ונעילה

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

סכימות של הגדרות אישיות והגדרות כלליות

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

AlphaEvolveExperimentConfig

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

שם השדה סוג ברירת מחדל אילוצים או גבולות ערכים תיאור טכני
title מחרוזת חובה עד 256 תווים השם הייחודי של הניסוי שמוצג.
problemDescription מחרוזת חובה עד 5,000 תווים המפרט הרשמי של הבעיה. הוא מוזרק ישירות להקשרים של ההנחיות כדי לקבוע כללים.
programLanguage מחרוזת חובה ערך בפורמט חופשי שפת היעד של בסיס הקוד המשופר (לדוגמה, "python", ‏ "cpp", ‏ "verilog",‏ "cuda", ‏ "julia", ‏ "java").
runSettings אובייקט חובה מיפוי לסכימה RunSettings פרמטרים של קצב וזמן קצוב לתפוגה.
generationSettings אובייקט אופציונלי מיפוי לסכימה GenerationSettings בחירת מודל ופרמטרים של הקשר.
evolutionSettings אובייקט אופציונלי מיפוי לסכימה EvolutionSettings פרמטרים של בחירת הורה וגיוון.

RunSettings

הוא קובע את קצב התפוקה, את מגבלות ההקבלה ואת הזמן הקצוב לתפוגה של המערכת האוטומטית.

שם השדה סוג ברירת מחדל אילוצים או גבולות ערכים תיאור טכני
maxPrograms int32 100 מינימום: 2, מקסימום: 100,000 תקציב ההפעלה הכולל (תוכניות ליצירה ולהערכה). הערך חייב להיות גדול מ-1.
concurrency int32 1 מינימום: 1, מקסימום: 30 מספר המוטציות של התוכנית המקבילה שפעילות בתור. אי אפשר להזין ערכים גדולים מ-30.
maxDuration מחרוזת ‫24 שעות (86,400 שניות) מחרוזת dayTimeDuration לפי תקן ISO 8601
מינימום: >0, מקסימום: 7 ימים		 משך הזמן הכולל שמותר לניסוי לפעול לפני שהוא נעצר.
idleTimeout מחרוזת ‫5 שעות (ארה"ב/אירופה)
שעתיים (שאר העולם)		 מחרוזת dayTimeDuration לפי תקן ISO 8601
מינימום: >0
מקסימום: ברירת המחדל של המיקום		 משך הזמן של חוסר פעילות לפני מעבר אוטומטי אל PAUSED. ברירת המחדל היא שעתיים ב-global ו-5 שעות במיקומים אזוריים (us,‏ eu). משך הזמן מוגבל על ידי ברירת המחדל של המיקום, כך שאם מציינים ערך שגבוה מברירת המחדל של המיקום (לדוגמה, 12 שעות ב-global), המערכת מתעלמת ממנו והערך הוא שעתיים (בלי שגיאה).

הגדרות ליצירת סרטונים

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

  • ‫context (מחרוזת): אופציונלי. מאמרי עזרה, ממשקי API נוספים או כללים שהמשתמש סיפק. מומלץ מאוד לא לחרוג מ-200,000 טוקנים. הקשרים בגודל של יותר מ-200,000 אסימונים מדללים את תשומת הלב של המודל ופוגעים באיכות המוטציה.

  • ‫includeFullProgramInPrompt (בוליאני): ברירת המחדל היא false.

    • ‫true: ההנחיה למוטציה כוללת את EVOLVE-BLOCK שניתן לשינוי ואת התבנית שמסביב שלא ניתנת לשינוי (מומלץ מאוד להסקת מסקנות מבניות מורכבות).

    • ‫false: רק הבלוק שניתן לשינוי גלוי, וכך נשמר ההקשר של האסימון.

  • ‫models (מערך של אובייקטים): אופציונלי. כל רשומה מציינת שם של מודל ונותנת לו weight אופציונלי, שהוא החלק של המודל הזה בקריאות ליצירה ביחס לרשומות האחרות. אם לא מציינים את models, ‏AlphaEvolve מגדיר אותו למודל ברירת המחדל כשהוא יוצר את הניסוי. ברירת המחדל משתנה כשיוצאים מודלים חדשים של Gemini. ברשימה Default model מפורט איזה מודל חל בכל תאריך. כדי לבחור את המודל בעצמכם, או כדי להשתמש באותו מודל בכל הרצה, מגדירים את models.

    בדוגמה הבאה, המערכת שולחת כ-9 מתוך 10 קריאות ליצירת תוכן למודל הראשון, ואת השאר למודל השני. המשקלים הם יחסים, ולכן הסכום שלהם לא חייב להיות 1.

    "models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]

מודלים נתמכים

מגדירים את models[].name לאחד מהערכים הבאים. אפשר לשלב עד שני מודלים בניסוי אחד.

שם הדגם אזורי שירות
gemini-4-argon global, us, eu
gemini-3.8-flash global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

‫AlphaEvolve מאמת את models כשהוא יוצר את הניסוי ומחזיר את הערך INVALID_ARGUMENT אם שם המודל לא מופיע בטבלה הזו או לא זמין באזור שביקשתם.

מודל ברירת המחדל

בטבלה הבאה מפורטים המודלים שבהם AlphaEvolve משתמש כשמשמיטים את models, לפי תאריך יצירת הניסוי.

הניסוי נוצר מודל ברירת המחדל
בתאריך 24 באוקטובר 2026 או אחריו gemini-4-argon
‫29 בספטמבר 2026 עד 23 באוקטובר 2026 gemini-3.8-flash
‫30 ביוני 2026 עד 28 בספטמבר 2026 gemini-3.5-flash
לפני 30 ביוני 2026 gemini-2.5-flash

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

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

הגדרות האבולוציה

הסכימה EvolutionSettings שולטת בהסתברויות של זריעה מחדש של מודל אי ודגימת הורה:

  • parentSamplingConfig ← paretoSamplingConfig ← paretoSamplingProbability (מספר ממשי): ההסתברות (0.0 עד 1.0) לדגימת תוכניות הורה ישירות מחזית פארטו הפעילה, במקום להשתמש בבחירה רגילה שמבוססת על התאמה. אם המדדים שעברו אופטימיזציה מחזירים רק מדד סקלרי אחד, צריך להגדיר את הפרמטר הזה לערך 0.0 (מושבת).

מודלים של נתונים בתוכנית המועמדים

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

AlphaEvolveProgramContent

מגדיר את הקבצים ואת המבנה של התוכנית המועמדת.

  • ‫files (מערך של AlphaEvolveSourceFile): רשימה של כל הקבצים שמרכיבים את בסיס הקוד המועמד. המטען הייעודי (payload) חייב להכיל לפחות קובץ מקור אחד. ‫Google ממליצה להגביל את מספר הקבצים הכולל ל-50 קבצים לכל תוכנית מועמדת. כך המודל יכול להתמקד בצורה אופטימלית וחלון ההקשר פועל ביעילות.

  • ‫description (מחרוזת): סיכום שנוצר באופן אוטומטי ומתאר את השינויים הפרוגרמטיים שהמודל הציע (עד 1,000 תווים).

AlphaEvolveSourceFile

מייצג קובץ קוד מקור ספציפי בבסיס הקוד.

  • ‫path (מחרוזת): היעד של הנתיב היחסי לסביבת העבודה (חובה, עד 256 תווים). כל רשומה של קובץ מקור צריכה לציין נתיב לא ריק. אם מגדירים סביבת עבודה של Python, נקודת הכניסה הראשית של הקובץ להפעלה חייבת להיות בשם "initial_program.py".

  • ‫content (מחרוזת): מחרוזת קוד המקור הגולמי שמכילה את הבלוקים של ההטמעה הפונקציונלית. ‫Google ממליצה לשמור על גודל מצטבר של בסיס הקוד בכל הקבצים מתחת ל-4,000 עד 5,000 שורות קוד (LOC). זהו הגודל האופטימלי לביצועים של המודל וליצירת מוטציות.

  • ‫programLanguage (מחרוזת): תג המיפוי של מנתח השפה. המחרוזת הזו חייבת להתאים בדיוק לשפה שצוינה בהגדרות של הניסוי הראשי.

  • description (מחרוזת): תקציר אופציונלי שמתאר את הארכיטקטורה או המטרה של הקובץ, שחשוף ל-LLM במהלך שלבי המוטציה (עד 500 תווים).

AlphaEvolveProgramEvaluation

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

  • ‫scores (AlphaEvolveScores): ערכים מספריים אובייקטיביים וסטנדרטיים של מדדים. לפי השיטות המומלצות, כדאי להגביל את זה ל-3 עד 5 מדדי float נפרדים. מספר מוגזם של מאפייני יעד פוגע בביצועים של משווה Pareto עם כמה יעדים.

  • ‫insights (מערך של AlphaEvolveEvaluationInsight): תוויות סמנטיות לאבחון ועקבות ביצוע בשפה טבעית שמועברים בחזרה כדי לעזור ל-LLM בניסיונות הבאים ליצור מוטציות (מומלץ עד 10 פריטים).

ניסוח הניקוד ופורמטים של הטמעה

כלל המקסום

‫AlphaEvolve פועל בעיקרון כאלגוריתם מונוטוני לטיפוס על גבעות, וממקסם באופן קפדני את כל המדדים המספריים. אם צינור עיבוד הנתונים להערכה עוקב אחרי יעד מזעור (כמו מזעור זמן האחזור של האפליקציה באלפיות השנייה או הפחתת השימוש בזיכרון), צריך לשלול את הערך לפני ששולחים אותו בחזרה למסד הנתונים: submitted_score = -latency_ms.

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

סכימת הטמעה עם מטרה אחת

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

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "validation",
        "text": "Passed syntax and basic compilation."
      }
    ]
  }
}

סכמת הטמעה עם כמה יעדים

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

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      },
      {
        "metric": "latency",
        "score": -42.5
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "verification",
        "text": "Passed 5 out of 5 unit tests."
      },
      {
        "label": "latency_warning",
        "text": "Latency regression of 3% observed on large dataset."
      }
    ]
  }
}

אחזור נתוני התוכנית ושליחת שאילתות לגביהם

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

אחזור תוכנית באמצעות API בארכיטקטורת REST

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

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

    GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED

  • מיון לפי מדדים: שליפת מועמדים ממוינים על סמך מדדים שעברו אופטימיזציה:

    GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5

אחזור תוכניות באמצעות CLI

כדי לשלוף את ההצעות המובילות להשלמה ישירות מהטרמינל, מריצים את הפקודה הבאה:

ae results best <experiment-nickname> --top 5

דוגמאות מלאות לשימוש ב-CLI

‫AlphaEvolve CLI מספק למפתחים שליטה אדמיניסטרטיבית מהירה ומעקב אחרי קמפיינים ישירות מהמעטפת:

  • הצגת כל הניסויים בסשן שיחה:

    ae experiment list

  • רשימה של כל התוכניות המועמדות שעברו מוטציה בניסוי ספציפי:

    ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"

    מחליפים את EXPERIMENT_NICKNAME בשם הניסוי.

  • אחזור של הצעות הקוד שהניבו את הביצועים הטובים ביותר:

    ae results best EXPERIMENT_NICKNAME --top 5

    מחליפים את EXPERIMENT_NICKNAME בשם הניסוי.

  • כדי להמשיך קמפיין מושהה:

    ae experiment resume EXPERIMENT_NICKNAME

    מחליפים את EXPERIMENT_NICKNAME בשם הניסוי.

ספריית נקודות הקצה העיקריות של ה-API בארכיטקטורת REST

כל נקודות הקצה מוגדרות בגרסה v1alpha של Google Cloud Discovery Engine API.

תבנית הנתיב של משאב ההורה

ה-URI של משאב ההורה האמיתי המקונן בנוי כך: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • ‫AlphaEvolve זמין בglobal, בus ובeu. יצירת ניסויים במיקומים אחרים מחזירה את השגיאה FAILED_PRECONDITION.
  • אין תמיכה בפרויקטים של Assured Workloads.
  • בכל פרויקט אפשר להפעיל בו-זמנית עד 30 ניסויים של AlphaEvolve (במצב STARTED או RUNNING) בכל מיקום. אם תנסו להפעיל או להמשיך ניסוי שיחרוג מהמגבלה הזו, תוחזר השגיאה RESOURCE_EXHAUSTED.

יצירת ניסוי (POST)

  • נתיב:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/alphaEvolveExperiments

  • גוף הבקשה: AlphaEvolveExperimentConfig (ראו סעיף 2.1)

  • תגובה: משאב AlphaEvolveExperiment שמכיל את הקמפיין שעבר אתחול.

  • סטטוס HTTP‏: 200 OK

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לגוף הבקשה (POST /alphaEvolveExperiments)

    {
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

  2. דוגמה לגוף התגובה (200 OK)

    {
  "name": "projects/.../sort-opt-01",
  "state": "CREATED",
  "createTime": "2026-06-23T13:30:00Z",
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

התחלת הניסוי (POST)

  • נתיב:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:start

  • גוף הבקשה: StartExperimentRequest

  • אזהרה לגבי הוצאה משימוש: השדה initialProgram בגוף הבקשה הוצא משימוש והמערכת מתעלמת ממנו.

  • תשובה: GoogleLongrunningOperation (LRO).

  • סטטוס HTTP‏: 200 OK (הסטטוס משתנה מ-CREATED ל-RUNNING)

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לגוף הבקשה

    {
  "desiredProgramsCount": 1
}

  2. דוגמה לגוף התגובה (‎200 OK – פעולה ממושכת)

    {
  "name": "projects/.../operations/start-op-7788",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata",
    "createTime": "2026-06-23T13:31:00Z"
  },
  "done": false
}

רכישת תוכניות (POST)

  • נתיב:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:acquirePrograms

  • גוף הבקשה: AcquireProgramsRequest

    • ‫desiredProgramsCount (int32): מספר אופציונלי של תוכניות שעברו מוטציה לאחזור (ברירת המחדל היא 1 אם לא הוגדר).

  • סטטוסים של תשובות:

    • ‫200 OK: מחזירה תשובה שמכילה משאבי AlphaEvolveProgram נעולים.

    • 204 No Content: התור ריק או שהקמפיין מושהה. ה-runners צריכים להמתין (למשל, 15 שניות) ולנסות שוב.

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לגוף הבקשה

    {
  "desiredProgramsCount": 1
}

  2. דוגמה לגוף התגובה (200 OK)

    {
  "programs": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "lockToken": "token_uuid_8877_x99",
      "state": "EVALUATING",
      "createTime": "2026-06-23T13:32:00Z",
      "content": {
        "description": "Mutated candidate program.",
        "files": [
          {
            "path": "initial_program.py",
            "programLanguage": "python",
            "description": "Primary sorting executable.",
            "content": "def custom_heuristic(arr, _):\n    ..."
          }
        ]
      }
    }
  ]
}

  3. דוגמה לגוף התגובה (‎204 No Content)

סטטוס HTTP ‏204 הוחזר עם הקשר מטען ייעודי (payload) ריק.

שליחת הערכות של תוכניות (POST)

  • נתיב:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations

  • גוף הבקשה: SubmitProgramsEvaluationsRequest

    • ‫evaluationSubmissions (מערך): מכיל את lockToken התואם, את נתיב המשאב של התוכנית שעומדת בדרישות ואת המטען הייעודי (payload) של ההערכה (ציונים ותובנות). ה-API מקבל בדיוק בקשה אחת להערכה בכל קריאה. אם תשלחו כמה הערכות בבקשה אחת, תקבלו את השגיאה INVALID_ARGUMENT. אם אתם בודקים כמה מועמדים, שלחו כל תוכנית בנפרד.

  • תשובה: SubmitProgramsEvaluationsResponse (ריקה).

  • סטטוס HTTP: ‏200 OK (שומר את הציונים, משחרר את הנעילה הפעילה ורושם תובנות)

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לגוף הבקשה

    {
  "evaluationSubmissions": [
    {
      "lockToken": "token_uuid_8877_x99",
      "program": "projects/.../alphaEvolvePrograms/prog-102",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": evaluation_payload["score"]
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ]
}

  2. דוגמה לגוף התגובה (200 OK)

    {}

המשך הניסוי (POST)

  • נתיב:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume

  • גוף הבקשה: ResumeExperimentRequest

  • תשובה: GoogleLongrunningOperation (LRO).

  • סטטוס HTTP‏: 200 OK (הסטטוס משתנה מ-PAUSED בחזרה ל-RUNNING)

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לגוף הבקשה

    {}

  2. דוגמה לגוף התגובה (‎200 OK – פעולה ממושכת)

    {
  "name": "projects/.../operations/resume-op-9900",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
    "createTime": "2026-06-23T13:45:00Z"
  },
  "done": false
}

הצגת רשימת תוכניות (GET)

  • נתיב:

    GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms

  • פרמטרים של שאילתה:

    • ‫stateFilter (מחרוזת): אופציונלי. מסנן רשימה רגיל, לדוגמה, stateFilter = 'COMPLETED'.

    • ‫orderBy (מחרוזת): אופציונלי. מיון לפי מדדים, לדוגמה, accuracy desc.

  • תשובה: ListAlphaEvolveProgramsResponse.

  • סטטוס HTTP‏: 200 OK

דוגמאות למטען ייעודי (payload) של API

  1. דוגמה לכתובת URL של שאילתת בקשה

    GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/
  alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc
  &pageSize=1

  2. דוגמה לגוף התגובה (200 OK)

    {
  "alphaEvolvePrograms": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "state": "COMPLETED",
      "createTime": "2026-06-23T13:32:00Z",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": -12.45
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "token_page_1_next"
}

קוד אבחון והפניה לפתרון בעיות

מטריצת קודי האבחון של ה-API

סטטוס HTTP סוג השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
400 INVALID_ARGUMENT
  • סמני EVOLVE-BLOCK-START / EVOLVE-BLOCK-END לא תקינים (לדוגמה, תוכן שמשתף את השורה של הסמן, בלוקים בתצוגת עץ או סמן סיום חסר).
  • בלוק פיתוח ריק שמכיל רק הערות או רווחים לבנים בלי קוד שניתן לערוך.
  • הערך maxPrograms הוגדר לפחות מ-2.
  • שדות תצורה לא מזוהים.
  • הגדרת מודל לא תקינה (יותר משני מודלים, רשומות כפולות, משקלים לא חיוביים או טמפרטורה מחוץ לטווח [0.0, 2.0]).
  • שליחת כמה הערכות בקריאה אחת ל-submitProgramsEvaluations.
  • הפרויקט הוא פרויקט Assured Workloads.
 חשוב לוודא שהסמנים נמצאים לבד בשורה שלהם, ושהם כוללים לפחות שורת קוד אחת שהיא לא הערה. מגדירים את maxPrograms לערך 2 או יותר. מסירים שדות שלא נכללים ב-API, כמו notes שהיה קיים בגרסת טרום-ההשקה (Preview) של ה-API. צריך לשלוח את ההערכות בנפרד, אחת בכל פעם.
403 PERMISSION_DENIED
  • לגורם המבקש אין את התפקיד "עריכה ב-Discovery Engine" (roles/discoveryengine.editor) או "אדמין" (roles/discoveryengine.admin). הערה: התפקיד roles/discoveryengine.user לא מעניק הרשאות ל-AlphaEvolve, והתפקיד roles/discoveryengine.viewer לא יכול לקבל ניסויים.
  • למבצע הקריאה החוזרת אין הרשאה במשאב הסשן הראשי.
  • אין רישיון פעיל של Gemini Enterprise.
 נותנים את התפקיד roles/discoveryengine.editor או roles/discoveryengine.admin ברמת הפרויקט, ומוודאים שיש גישה לסשן ההורה. מוודאים שיש רישיונות פעילים ל-Gemini Enterprise. מגדירים את Application Default Credentials:

gcloud auth application-default login --project=PROJECT_ID

הערה: אין תמיכה ב-Model Armor בהגדרות של AlphaEvolve.
400 FAILED_PRECONDITION
  • טוקן הנעילה לא עדכני או שפג תוקפו, או שיש חוסר התאמה במצב התוכנית (לדוגמה, המועמד נרכש מחדש או שהרכישה הושלמה אחרי שתוקף ההשכרה פג).
  • הניסוי נוצר במיקום שלא נתמך (מחוץ ל-global, ל-us או ל-eu).
  • ‫Vertex AI API‏ (aiplatform.googleapis.com) לא מופעל בפרויקט.
 צריך להחזיר את הערך המדויק של lockToken שהוחזר על ידי :acquirePrograms. לאכוף זמנים קצובים לתפוגה בצד הלקוח (מומלץ 30 דקות) ולשלוח ציוני עונש על כישלון כשהזמן הקצוב לתפוגה נגמר. ליצור מחדש את הניסוי במיקום נתמך. מפעילים את Vertex AI API: ‏gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • הפרויקט הגיע למגבלה של 30 ניסויים פעילים בו-זמנית (STARTED מתוך RUNNING) לכל מיקום.
  • מכסת הטוקנים ליצירת מודלים בקצה העורפי מוצתה.
 למגבלת הניסויים הפעילים: צריך להשלים או להפסיק את הניסויים הפעילים לפני שמתחילים ניסוי חדש (הפחתת concurrency ב-runSettings לא משפיעה על המגבלה הזו). למכסת טוקנים של מודל: צריך להקטין את concurrency ב-runSettings ולהטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
503 SERVICE_UNAVAILABLE מסווג הבטיחות של הקלט לא זמין או שהשירות לקצה העורפי עמוס באופן זמני. מטמיעים לולאת ניסיון חוזר עם השהיה מעריכית אקראית לפני ניסיון חוזר (exponential backoff) בצד הלקוח.

הודעות שגיאה נפוצות ופתרונות

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

שגיאות ניתוח ראשוניות של התוכנית ושל EVOLVE-BLOCK

הודעת השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. שני הסמנים EVOLVE-BLOCK-START ו-EVOLVE-BLOCK-END מופיעים באותה שורה. צריך להציב את סמני ההתחלה והסיום בשורות נפרדות.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. קוד, טקסט או תווים ריקים בסוף מופיעים באותה שורה עם הסמן EVOLVE-BLOCK-START או EVOLVE-BLOCK-END. מוודאים שהסמן נמצא לבד בשורה (לפניו מופיעה רק תחילית של הערה, כמו # EVOLVE-BLOCK-START).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. סמן EVOLVE-BLOCK-START מופיע בתוך בלוק פיתוח שכבר נפתח. צריך להסיר סמני התחלה מקוננים. אין תמיכה בבלוקים מקוננים של evolve.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. מופיע סמן EVOLVE-BLOCK-END בלי EVOLVE-BLOCK-START לפניו. מוודאים שלפני כל סמן סיום מופיע סמן התחלה תואם.
Parsing error: Evolve block started but not ended. נמצא סמן EVOLVE-BLOCK-START בלי סמן סגירה תואם EVOLVE-BLOCK-END. מוסיפים סמן סגירה EVOLVE-BLOCK-END.

שגיאות בתוכן ובמבנה של התוכנית

הודעת השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
Program content must contain at least one source file. השדה program_content.source_files ריק. צריך לספק לפחות קובץ מקור אחד.
source_files entries must have a non-empty path. רשומה בקובץ המקור מכילה מחרוזת path ריקה. צריך לציין נתיב יחסי תקין לכל קובץ מקור.
source_files entry has empty content; path: <path> רשומה בקובץ המקור מכילה תוכן של מחרוזת ריקה. ממלאים את תוכן הקובץ.
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). בלוקים של Evolve מכילים רק הערות, מחרוזות תיעוד או רווחים לבנים, בלי קוד שניתן לערוך. הוסיפו לפחות שורת קוד אחת שניתן לערוך (כמו הגדרות של פונקציות או לוגיקה של אלגוריתם) בתוך הבלוק.

שגיאות באימות ההגדרות והמודל

הודעת השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
unsupported model: <model_name> המודל שביקשתם לא נתמך או לא מופעל בפרויקט שלכם. להשתמש במודלים נתמכים. הגדרות ליצירת תוכן
model '<model_name>' is not served from domain shard '<location>'. המודל לא זמין במיקום האזורי שצוין. בקטע הגדרות ליצירת תוכן מפורטים המודלים והמיקומים הנתמכים.
generation_settings.models must contain at most 2 distinct models; got <count>. צוינו יותר משתי הגדרות של מודלים ב-generation_settings.models. צריך לציין שני מודלים לכל היותר בתערובת.
generation_settings.models contains duplicate entry: <model_name> אותו שם מודל מופיע יותר מפעם אחת ב-generation_settings.models. מסירים רשומות כפולות של מודלים.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. משקל הדגימה של המודל הוא שלילי, אפס או לא סופי. צריך להגדיר משקל חיובי או להסיר את הרשומה.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. טמפרטורת המודל חורגת מהטווח התקין [0.0, 2.0]. צריך לשנות את הטמפרטורה לערך בין 0.0 ל-2.0.
RunSettings.max_programs is required and must be greater than 1. הערך max_programs הושמט או הוגדר ל-1 או פחות. מגדירים את max_programs לערך 2 או יותר (נדרש ערך מינימלי של 2 כדי לאפשר מועמדים מפותחים).
RunSettings.concurrency is required and must be positive. השדה concurrency הושמט או שהוגדר בו ערך של 0 או פחות. מגדירים את concurrency כמספר שלם חיובי (בדרך כלל 1-30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. הכתובת pareto_sampling_probability היא לא בדומיין [0.0, 1.0]. צריך להגדיר הסתברות בין 0.0 ל-1.0.

שגיאות שקשורות לדרישות המוקדמות של הפרויקט ולמחזור החיים של הניסוי

הודעת השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> ‫Vertex AI API‏ (aiplatform.googleapis.com) לא מופעל בפרויקט Google Cloud . מריצים את gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
Project has reached the limit of 30 concurrently active AlphaEvolve experiments in location <location>. Stop or wait for a running experiment to finish before starting or resuming another. הפרויקט הגיע למכסה של 30 ניסויים פעילים בו-זמנית (STARTED או RUNNING) במיקום הזה. צריך להפסיק או להשלים את הניסויים הקיימים לפני שמתחילים או ממשיכים ניסוי חדש.
Cannot <action> experiment from state <current_state> ניסיון לבצע מעבר לא חוקי בין מצבים (לדוגמה, הפעלת ניסוי שכבר פועל או המשך של ניסוי שנוצר לאחרונה). חשוב לוודא שהניסויים עוברים את שלבי מחזור החיים הרגילים: CREATED ← START, PAUSED/COMPLETED ← RESUME, STARTED/RUNNING ← STOP.
Cannot resume experiment: a start or watchdog message is already pending. Stop the experiment first to drain it, or wait for the pending delivery to complete. פעולה קודמת של התחלה או המשך עדיין מתבצעת. צריך להמתין עד שהמסירה בהמתנה תסתיים, או להפעיל את STOP כדי לרוקן את ההודעות בהמתנה.
AlphaEvolve is not available for this project. הפרויקט חסום או שהוא פרופיל תאימות שלא נתמך. פרופיל תאימות ואבטחה

שגיאות ברכישה ובהערכה של תוכניות

הודעת השגיאה סיבה שקשורה למערכת פתרון עקיף או פעולה להפחתת הסיכון
Exactly one evaluation submission is required. כמה בקשות הערכה נשלחו בבקשת submitProgramsEvaluations אחת. צריך לשלוח כל הערכה בנפרד, אחת לכל קריאה ל-API.
Program is required for each evaluation submission. / submission.program is required. נתיב המשאב program לא צוין בבקשה לבדיקה. מעבירים את הנתיב המלא למשאב של התוכנית.
Lock token is required for each evaluation submission. / submission.lock_token is required. הערך lock_token שהוחזר במהלך acquirePrograms הושמט. צריך להעביר את המחרוזת המדויקת של lock_token שמוחזרת כשהתוכנית נרכשת.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' אסימון הנעילה שנשלח בבקשה לא תואם להשכרה הפעילה של השרת (לדוגמה, תוקף ההשכרה פג ועובד אחר רכש אותה, או שסופק אסימון שגוי). צריך להחזיר את הערך המדויק של lockToken מ-acquirePrograms ולשלוח את התוצאות לפני שנגמר הזמן הקצוב לתפוגה של הלקוח.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> התוכנית כבר נבדקה, בוטלה או הועברה מ-EVALUATION_IN_PROGRESS. צריך למחוק את ההערכה הישנה או להשיג מחדש את המועמד אם הוא זמין.
The request was rejected by a safety policy. תיאור הבעיה, הקוד הראשוני או מדדי ההערכה שהוזנו הפעילו כללי מדיניות לסיווג בטיחות. הסירו תוכן זדוני או רגיש מהטקסט של ההנחיות ומתיאורי הבעיות כדי להסיר מילות מפתח או עקבות רגישים.
The input safety classifier is currently unavailable. שירות סיווג הבטיחות לא זמין זמנית או עמוס מדי (נכשל במצב סגור). להטמיע לוגיקה של השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

תיקון "השמטות שקטות"

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

פתרון עקיף:

  • הסרת תוכן זדוני או רגיש מההקשר: מסירים מההקשר problemDescription ביטויים טעונים רגשית או רגישים מבחינה אבטחתית.

  • סינון תובנות: מנתחים ומקצרים עקבות של חריגות גולמיות או יומני stderr של מסוף ב-payload של insights כדי למנוע חזרה על תוכן מערכת לא בטוח שמפעיל מסננים בהמשך.

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

שיטות מומלצות להערכה בצד הלקוח

צוואר הבקבוק של "קוד ספגטי"

פורמט מקור לא אופטימלי פוגע באיכות האופטימיזציה: "קוד ספגטי == מרחב חיפוש רועש". לפני שמציבים סמנים של EVOLVE-BLOCK:

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

  • הוסיפו מחרוזות תיעוד (docstrings) תמציתיות שמתארות מה כל פונקציה או משתנה עושים ולמה. חשוב לוודא שמחרוזות התיעוד נמצאות לצד קוד פונקציונלי בפועל. אם תציבו רק מחרוזת תיעוד או הערות בתוך EVOLVE-BLOCK, המערכת תדחה את הקוד כבלוק ריק.

  • חשוב לוודא שסימני ההערות EVOLVE-BLOCK-START ו-EVOLVE-BLOCK-END ממוקמים לבד בשורות שלהם, חוץ מרווחים בתחילת השורה ותחיליות של הערות (כמו # או //).

  • חשוב לוודא שכל יחסי התלות החיצוניים שלא ניתנים לשינוי (כמו ייבוא של מודולים מסייעים או טעינה של נתונים סטטיים) נמצאים מחוץ ל-EVOLVE-BLOCK.

הקצאת חלון הקשר

כדי למקסם את היצירתיות של המוטציות, הגבילו את המטען הייעודי (payload) של הקוד שנשלח ל-API. ההקשר הכולל של התוכנית צריך להיות פחות מ-150,000 עד 200,000 טוקנים. בלוקים גדולים של קטעי קוד סטטיים ובלתי ניתנים לשינוי צורכים את תשומת הלב של המודל ופוגעים בביצועים. מעבירים סקריפטים של כלי שירות, פייפליינים של הטמעת נתונים וספריות אימות כבדות לחלוטין למעריך בצד הלקוח.

קודם צריך להפעיל את התוכנית הראשונית

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

  • הכנת ה-seed: מתקנים באגים ברורים בתחביר, בעיות בקומפילציה ומקרי קצה.

  • אימות הניקוד ההתחלתי: מוודאים שהניקוד הבסיסי סביר ושהמעריך הוא דטרמיניסטי לחלוטין (אותו קוד + אותו קלט = אותו ניקוד).

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

הימנעו מקווי בסיס שעברו אופטימיזציית יתר

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

אמצעי הגנה על הרצת קוד בצד הלקוח

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

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

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

  • מסנני אבטחה של AST: תמיד צריך להריץ בדיקה של Abstract Syntax Tree (AST) על המטען הייעודי (payload) של קוד המקור הנכנס לפני ההידור. אם מזוהים פרימיטיבים מוגבלים של השתקפות או ביצוע (כמו eval, ‏ exec,‏ getattr או setattr), צריך להפסיק מיד את הביצוע ולהחיל עונש חמור על הכישלון.

מקורות מידע נוספים

מידע נוסף זמין במקורות המידע הבאים: