Documentation de référence de l'API AlphaEvolve

Ce document sert de documentation de référence de l'API et de spécification système de niveau production pour l'API Cloud AlphaEvolve sous les couches conversationnelles de Google CloudDiscovery Engine. Il définit les hiérarchies de ressources imbriquées précises, les points de terminaison REST et gRPC, les contraintes au niveau des champs, les machines d'état du cycle de vie, les matrices de diagnostic d'erreur, les règles de bac à sable de sécurité et les workflows d'intégration nécessaires pour concevoir un contrôleur côté client et une boucle d'évaluation entièrement automatisés.

Machines d'état du cycle de vie unifiées

L'agent AlphaEvolve coordonne deux machines d'état indépendantes pour surveiller la progression de la campagne de test, et gérer la diffusion et l'exécution des mutations de programmes individuels.

États du cycle de vie des tests

Un test représente la campagne d'optimisation globale. Elle est traitée comme une ressource persistante côté serveur et passe par les états suivants :

  • CREATED : état d'initialisation. La ressource est déclarée et configurée, mais n'a pas encore renseigné les générations initiales ni distribué les appels d'API.

  • RUNNING : état d'évaluation actif. Le moteur échantillonne simultanément les candidats parents, génère des mutations de code via le mélange de LLM et diffuse des tâches aux évaluateurs.

  • PAUSED : état de préservation temporaire déclenché manuellement ou via une idle_timeout de protection automatisée. La génération de code s'arrête et les nœuds de calcul existants interrompent l'envoi des métriques.

  • COMPLETED : état final indiquant que la recherche a atteint son allocation cible max_programs ou sa limite de génération structurelle.

  • FAILED : état d'erreur terminal indiquant que des problèmes d'environnement systémique (par exemple, des exceptions d'identifiants d'API non interceptées, une corruption du data store ou des paniques consécutives de l'exécuteur) ont interrompu l'exécution du traitement.

États du programme

La séquence de validation de l'exécution est appliquée aux variantes candidates individuelles.

Chaque mutation de code générée se comporte comme une entité de programme isolée qui passe par une séquence d'états opérationnels précis dans la base de données de population.

  1. INITIALIZED : l'entrée du programme est créée dans la base de données, ce qui permet de suivre son ascendance et ses liens avec le programme parent.

  2. GENERATING : une tâche est activement envoyée au backend du mélange de modèles de langage pour rédiger ou modifier les blocs de code fonctionnels spécifiques.

  3. EVALUATING : la charge utile du code est verrouillée par un processus de calcul d'évaluation et exécutée dans un environnement de test isolé.

  4. COMPLETED : les scores d'exécution et les insights structurels descriptifs sont enregistrés de manière sécurisée dans la base de données évolutive, et le programme est ajouté au pool de sélection.

Mécanismes de simultanéité et de verrouillage

Les programmes sont acquis par des boucles de nœuds de calcul à l'aide d'un mécanisme de jeton de verrouillage atomique afin d'éviter les conditions de concurrence ou les frais généraux de notation en double dans les topologies distribuées. L'évaluateur doit envoyer le schéma de notation finalisé ainsi que le jeton de verrouillage correspondant pour enregistrer les résultats dans la base de données.

Schémas de configuration et de paramètres

Présentation des configurations, des paramètres et des valeurs par défaut du schéma de base utilisés par l'environnement d'exécution du moteur AlphaEvolve.

AlphaEvolveExperimentConfig

Définit les principaux paramètres structurels et les contraintes programmatiques de l'exécution du test évolutif.

Nom du champ Type Par défaut Contraintes / Limites de valeur Description technique
title string Obligatoire 256 caractères maximum Nom à afficher unique du test.
problemDescription string Obligatoire 5 000 caractères maximum Spécification formelle du problème. Il est injecté directement dans les contextes de requête pour établir des règles.
programLanguage string Obligatoire Valeur libre Langage cible du codebase évolué (par exemple, "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings objet Obligatoire Mappage au schéma RunSettings Paramètres de rythme et de délai avant expiration.
generationSettings objet Optional Mappage au schéma GenerationSettings Paramètres de sélection et de contexte du modèle.
evolutionSettings objet Optional Mappage au schéma EvolutionSettings Paramètres de sélection des parents et de diversité.

RunSettings

Régit le rythme du débit, les limites de parallélisation et les délais d'expiration automatiques du système.

Nom du champ Type Par défaut Contraintes / Limites de valeur Description technique
maxPrograms int32 100 Min : 2, Max : 100 000 Budget d'exécution total (programmes à générer et à évaluer). La valeur doit être supérieure à 1.
concurrency int32 1 Min : 1, Max : 30 Nombre de mutations de programme parallèles actives dans la file d'attente. Les valeurs supérieures à 30 ne sont pas autorisées.
maxDuration string 24 h (86 400 s) Chaîne dayTimeDuration ISO 8601
Min : >0, Max : 7 jours		 Temps total autorisé avant l'arrêt du test.
idleTimeout string 5 h (États-Unis/Europe)
2 h (monde)		 Chaîne dayTimeDuration ISO 8601
Min : >0
Max : valeur par défaut de l'emplacement		 Durée d'inactivité avant la transition automatique vers PAUSED. La valeur par défaut est de deux heures dans global et de cinq heures dans les emplacements régionaux (us, eu). La durée est limitée par la valeur par défaut de l'emplacement. Par conséquent, si vous spécifiez une valeur supérieure à la valeur par défaut de l'emplacement (par exemple, 12 heures dans global), elle est ignorée et la valeur est de deux heures (sans erreur).

Paramètres de génération

Le schéma GenerationSettings contrôle l'assemblage des requêtes, les fenêtres de contexte et les configurations de modèle pour les mutations :

  • context (chaîne) : documentation de référence, API supplémentaires ou règles facultatives fournies par l'utilisateur. Il est vivement recommandé de ne pas dépasser 200 000 jetons. Les tailles de contexte dépassant 200 000 jetons diluent l'attention du modèle et dégradent la qualité de la mutation.

  • includeFullProgramInPrompt (bool) : valeur par défaut false.

    • true : la requête de mutation inclut la variable EVOLVE-BLOCK et le code récurrent immuable environnant (fortement recommandé pour un raisonnement structurel complexe).

    • false : seul le bloc modifiable est visible, ce qui permet d'économiser le contexte du jeton.

  • models (tableau d'objets) : facultatif. Chaque entrée nomme un modèle et lui attribue un weight facultatif, qui correspond à la part d'appels de génération de ce modèle par rapport aux autres entrées. Si vous omettez models, AlphaEvolve le définit sur le modèle par défaut lorsqu'il crée le test. La valeur par défaut change à mesure que de nouveaux modèles Gemini sont publiés. Modèle par défaut indique quel modèle s'applique à quelle date. Pour choisir vous-même le modèle ou pour conserver le même modèle à chaque exécution, définissez models.

    L'exemple suivant envoie environ neuf appels de génération sur dix au premier modèle et le reste au second. Les pondérations sont des ratios. Leur somme n'a donc pas besoin d'être égale à 1.

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

Modèles compatibles

Définissez models[].name sur l'une des valeurs suivantes. Vous pouvez combiner au maximum deux modèles dans un même test.

Nom du modèle Régions de diffusion
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 valide models lorsqu'il crée le test et renvoie INVALID_ARGUMENT pour un nom de modèle qui ne figure pas dans ce tableau ou qui n'est pas disponible dans la région que vous avez demandée.

Modèle par défaut

Le tableau suivant liste le modèle utilisé par AlphaEvolve lorsque vous omettez models, par date de création du test.

Test créé Modèle par défaut
À partir du 24 octobre 2026 gemini-4-argon
Du 29 septembre 2026 au 23 octobre 2026 gemini-3.8-flash
Du 30 juin 2026 au 28 septembre 2026 gemini-3.5-flash
Avant le 30 juin 2026 gemini-2.5-flash

Pour identifier le modèle attribué à un test, vérifiez generationSettings.models dans la configuration du test ou dans la réponse de création. Étant donné que les modifications prennent effet tout au long de la journée de transition, les tests créés à ces dates peuvent recevoir l'ancien ou le nouveau modèle par défaut. Les tests créés sans models avant le 30 juin 2026 ne contiennent pas de valeur pour ce champ.

Étant donné que le modèle est stocké dans chaque test, une modification de la valeur par défaut n'affecte pas les tests existants. Pour utiliser un modèle par défaut plus récent, créez un test.

Paramètres d'évolution

Le schéma EvolutionSettings contrôle le réensemencement du modèle d'îles et les probabilités d'échantillonnage parent :

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float) : probabilité (0,0 à 1,0) d'échantillonner les programmes parents directement à partir de la frontière de Pareto active plutôt que d'utiliser la sélection standard basée sur l'aptitude. Ce paramètre doit être défini sur 0.0 (désactivé) si les métriques optimisées ne renvoient qu'une seule métrique scalaire.

Modèles de données des programmes candidats

Cette section décrit les schémas et les représentations de données utilisés pour définir et organiser les structures de code candidates dans la base de données de population.

AlphaEvolveProgramContent

Définit les fichiers et la structure du programme candidat.

  • files (tableau de AlphaEvolveSourceFile) : liste de tous les fichiers constituant le codebase candidat. La charge utile doit contenir au moins un fichier source. Google recommande de limiter le nombre total de fichiers à 50 par programme candidat. Cela permet d'optimiser l'attention du modèle et l'efficacité de la fenêtre de contexte.

  • description (chaîne) : résumé généré automatiquement décrivant les modifications programmatiques suggérées par le modèle génératif (1 000 caractères maximum).

AlphaEvolveSourceFile

Représente un fichier de code source individuel dans la base de code.

  • path (chaîne) : destination du chemin d'accès relatif à l'espace de travail (obligatoire, 256 caractères maximum). Chaque entrée de fichier source doit spécifier un chemin d'accès non vide. Si vous configurez un espace de travail Python, le point d'entrée du fichier exécutable principal doit être nommé exactement "initial_program.py".

  • content (chaîne) : chaîne de code source brute comprenant les blocs d'implémentation fonctionnelle. Google recommande de limiter la taille cumulée de la codebase de tous les fichiers à 4 000 à 5 000 lignes de code. C'est la taille optimale pour les performances d'attention et de génération de mutations du modèle.

  • programLanguage (chaîne) : tag de mappage de l'analyseur de langage. Cette chaîne doit correspondre explicitement à la langue désignée dans la configuration du test parent.

  • description (chaîne) : résumé facultatif décrivant l'architecture ou l'objectif du fichier, qui est exposé au LLM lors des passes de mutation (500 caractères maximum).

AlphaEvolveProgramEvaluation

Charge utile structurée renvoyée par les instances d'exécuteur client à la base de données évolutive après l'exécution.

  • scores (AlphaEvolveScores) : valeurs de métriques numériques standardisées et objectives. Les bonnes pratiques recommandent de limiter ce nombre à trois à cinq métriques flottantes distinctes. Un nombre excessif de dimensions cibles dégrade les performances du comparateur Pareto multi-objectifs.

  • insights (tableau de AlphaEvolveEvaluationInsight) : étiquettes sémantiques de diagnostic et traces d'exécution en langage naturel renvoyées pour faciliter les tentatives ultérieures de génération de mutations du LLM (maximum recommandé de 10 éléments).

Formulation du score et formats d'ingestion

La règle de maximisation

AlphaEvolve fonctionne fondamentalement comme un algorithme d'ascension monotone et maximise strictement toutes les métriques numériques. Si votre pipeline d'évaluation suit une cible de minimisation (par exemple, minimiser la latence de l'application en millisecondes ou réduire l'utilisation de la mémoire), vous devez inverser la valeur avant de la renvoyer à la base de données : submitted_score = -latency_ms.

Idéalement, les scores doivent être continus. Les métriques booléennes ou hautement discrètes ne fournissent pas un signal de gradient suffisant pour une exploration efficace de l'algorithme de montée de gradient.

Schéma d'ingestion à objectif unique

Utilisez le code JSON suivant lorsque votre outil d'évaluation optimise une seule fonction d'objectif scalaire.

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

Schéma d'ingestion multi-objectif

Utilisez le code JSON suivant lorsque vous transmettez des paramètres de suivi multi-objectifs indépendants pour activer les routines d'optimisation de la frontière de Pareto côté serveur.

{
  "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."
      }
    ]
  }
}

Récupérer et interroger des données de programme

Le système AlphaEvolve consigne la télémétrie, les métriques d'exécution et le code source complet de chaque mutation générée. Les développeurs peuvent ainsi interroger ce datastore historique à l'aide de l'API ou de la CLI pour suivre la progression de l'optimisation et extraire les candidats de code les plus performants.

Récupération de programmes à l'aide de l'API REST

Les ressources de programme évaluées peuvent être interrogées à partir de la base de données à l'aide du point de terminaison ListAlphaEvolvePrograms standard avec des paramètres de requête de filtrage et de tri :

  • Filtrage par état : interrogez les programmes correspondant à un état de cycle de vie spécifique :

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

  • Tri basé sur les métriques : récupérez les candidats triés en fonction de métriques optimisées :

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

Récupération de programme à l'aide de la CLI

Pour extraire les meilleurs candidats directement depuis votre terminal, exécutez la commande suivante :

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

Exemples complets d'utilisation de la CLI

La CLI AlphaEvolve permet aux développeurs de contrôler et de surveiller rapidement les campagnes directement depuis le shell :

  • Répertoriez tous les tests d'une session conversationnelle :

    ae experiment list

  • Répertoriez tous les programmes candidats modifiés pour un test spécifique :

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

    Remplacez EXPERIMENT_NICKNAME par le nom de votre test.

  • Récupérez les candidats de code complété les plus performants :

    ae results best EXPERIMENT_NICKNAME --top 5

    Remplacez EXPERIMENT_NICKNAME par le nom de votre test.

  • Réactiver une campagne mise en veille :

    ae experiment resume EXPERIMENT_NICKNAME

    Remplacez EXPERIMENT_NICKNAME par le nom de votre test.

Répertoire des points de terminaison de l'API REST Core

Tous les points de terminaison sont gérés par version sous v1alpha de l'API Google Cloud Discovery Engine.

Modèle de chemin d'accès de la ressource parente

L'URI de la véritable ressource parente imbriquée est structuré comme suit : projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve est disponible en global, us et eu. La création de tests dans d'autres emplacements renvoie FAILED_PRECONDITION.
  • Les projets Assured Workloads ne sont pas compatibles.
  • Un projet est limité à 30 tests AlphaEvolve actifs simultanément (STARTED ou RUNNING) par emplacement. Si vous démarrez ou reprenez un test qui dépasse cette limite, l'erreur RESOURCE_EXHAUSTED s'affiche.

Créer un test (POST)

  • Path (Chemin)

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

  • Corps de la requête : AlphaEvolveExperimentConfig (voir la section 2.1)

  • Réponse : ressource AlphaEvolveExperiment contenant la campagne initialisée.

  • État HTTP : 200 OK

Exemples de charges utiles d'API

  1. Exemple de corps de requête (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. Exemple de corps de réponse (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
        }
      }
    }
  }
}

Démarrer le test (POST)

  • Path (Chemin)

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

  • Corps de la requête : StartExperimentRequest

  • Avertissement d'abandon : Le champ de corps initialProgram est obsolète et ignoré.

  • Réponse : GoogleLongrunningOperation (LRO).

  • État HTTP : 200 OK (transition de l'état CREATED à RUNNING)

Exemples de charges utiles d'API

  1. Exemple de corps de la requête

    {
  "desiredProgramsCount": 1
}

  2. Exemple de corps de réponse (200 OK - opération de longue durée)

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

Acquérir des programmes (POST)

  • Path (Chemin)

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

  • Corps de la requête : AcquireProgramsRequest

    • desiredProgramsCount (int32) : nombre de lots facultatif de programmes mutés à récupérer (par défaut, 1 s'il n'est pas défini).

  • États de réponse :

    • 200 OK : renvoie une réponse contenant les ressources AlphaEvolveProgram verrouillées.

    • 204 No Content : la file d'attente est vide ou la campagne est mise en veille. Les exécuteurs doivent se mettre en veille (par exemple, pendant 15 secondes) et réessayer.

Exemples de charges utiles d'API

  1. Exemple de corps de la requête

    {
  "desiredProgramsCount": 1
}

  2. Exemple de corps de réponse (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. Exemple de corps de réponse (204 No Content)

L'état HTTP 204 est renvoyé avec un contexte de charge utile vide.

Envoyer des évaluations de programmes (POST)

  • Path (Chemin)

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

  • Corps de la requête : SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (tableau) : contient l'élément lockToken correspondant, le chemin d'accès qualifié de la ressource du programme et la charge utile d'évaluation (scores et insights). L'API n'accepte qu'une seule demande d'évaluation par appel. Le traitement par lot de plusieurs évaluations dans une seule requête est refusé avec INVALID_ARGUMENT. Lorsque vous évaluez plusieurs candidats, envoyez chaque programme individuellement.

  • Réponse : SubmitProgramsEvaluationsResponse (vide).

  • État HTTP : 200 OK (enregistre les scores, libère le verrou actif et enregistre les insights)

Exemples de charges utiles d'API

  1. Exemple de corps de la requête

    {
  "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. Exemple de corps de réponse (200 OK)

    {}

Reprendre le test (POST)

  • Path (Chemin)

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

  • Corps de la requête : ResumeExperimentRequest

  • Réponse : GoogleLongrunningOperation (LRO).

  • État HTTP : 200 OK (l'état passe de PAUSED à RUNNING)

Exemples de charges utiles d'API

  1. Exemple de corps de la requête

    {}

  2. Exemple de corps de réponse (200 OK - opération de longue durée)

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

Lister les programmes (GET)

  • Path (Chemin)

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

  • Paramètres de requête :

    • stateFilter (chaîne) : facultatif. Filtre de liste standard, par exemple stateFilter = 'COMPLETED'.

    • orderBy (chaîne) : facultatif. Tri basé sur les métriques, par exemple accuracy desc.

  • Réponse : ListAlphaEvolveProgramsResponse.

  • État HTTP : 200 OK

Exemples de charges utiles d'API

  1. Exemple d'URL de requête de demande

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

  2. Exemple de corps de réponse (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"
}

Informations de référence sur les codes de diagnostic et le dépannage

Matrice des codes de diagnostic de l'API

État HTTP Type d'erreur Cause système Solution ou mesure corrective
400 INVALID_ARGUMENT
  • Marqueurs EVOLVE-BLOCK-START / EVOLVE-BLOCK-END incorrects (par exemple, contenu partageant la ligne du marqueur, blocs imbriqués ou marqueur de fin manquant).
  • Bloc evolve vide ne contenant que des commentaires ou des espaces blancs sans code modifiable.
  • maxPrograms défini sur moins de 2.
  • Champs de configuration non reconnus.
  • Configuration de modèle non valide (plus de deux modèles, entrées en double, pondérations non positives ou température en dehors de [0.0, 2.0]).
  • Envoi de plusieurs évaluations dans un seul appel submitProgramsEvaluations.
  • Le projet est un projet Assured Workloads.
 Assurez-vous que les repères sont seuls sur leur ligne et qu'ils encadrent au moins une ligne de code qui n'est pas un commentaire. Définissez maxPrograms sur une valeur supérieure ou égale à 2. Supprimez les champs qui ne font pas partie de l'API, tels que notes, qui était présent dans la version preview de l'API. Envoyez les évaluations individuellement, une par une.
403 PERMISSION_DENIED
  • L'appelant ne dispose pas du rôle d'éditeur Discovery Engine (roles/discoveryengine.editor) ni du rôle d'administrateur (roles/discoveryengine.admin). Remarque : roles/discoveryengine.user n'accorde pas d'autorisations AlphaEvolve et roles/discoveryengine.viewer ne peut pas obtenir de tests.
  • L'appelant ne dispose pas des autorisations nécessaires sur la ressource de session parente.
  • Aucune licence Gemini Enterprise active n'est attribuée.
 Accordez roles/discoveryengine.editor ou roles/discoveryengine.admin au niveau du projet et vérifiez l'accès à la session parente. Vérifiez les licences Gemini Enterprise actives. Configurez les identifiants par défaut de l'application :

gcloud auth application-default login --project=PROJECT_ID

Remarque : Model Armor n'est pas compatible avec les configurations AlphaEvolve.
400 FAILED_PRECONDITION
  • Jeton de verrouillage obsolète ou expiré, ou incompatibilité de l'état du programme (par exemple, le candidat a été réacquis ou finalisé après l'expiration du bail).
  • Le test a été créé dans un emplacement non compatible (en dehors de global, us ou eu).
  • L'API Vertex AI (aiplatform.googleapis.com) n'est pas activée sur le projet.
 Renvoyez le lockToken exact renvoyé par :acquirePrograms. Appliquez des délais avant expiration côté client (30 minutes recommandées) et envoyez des scores de pénalité d'échec en cas de délai avant expiration. Recréez le test dans un emplacement compatible. Activez l'API Vertex AI : gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • Le projet a atteint la limite de 30 tests actifs simultanément (STARTED / RUNNING) par emplacement.
  • Le quota de jetons de génération du modèle de backend est épuisé.
 Pour la limite de tests actifs : terminez ou arrêtez les tests en cours avant d'en lancer un nouveau (diminuer concurrency dans runSettings n'a aucune incidence sur cette limite). Pour le quota de jetons de modèle : réduisez concurrency dans runSettings et implémentez un intervalle exponentiel entre les tentatives.
503 SERVICE_UNAVAILABLE Le classificateur de sécurité des entrées n'est pas disponible ou le service de backend est temporairement surchargé. Implémentez une boucle de nouvelle tentative avec un intervalle exponentiel aléatoire entre les tentatives côté client.

Messages d'erreur et solutions courants

La documentation de référence suivante répertorie les messages d'erreur courants renvoyés par l'API, leurs causes sous-jacentes et les étapes de résolution.

Erreurs d'analyse du programme initial et d'EVOLVE-BLOCK

Message d'erreur Cause système Solution ou mesure corrective
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Les repères EVOLVE-BLOCK-START et EVOLVE-BLOCK-END s'affichent sur la même ligne. Placez les repères de début et de fin sur des lignes distinctes.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. Le code, le texte ou les caractères de fin partagent la ligne avec un repère EVOLVE-BLOCK-START ou EVOLVE-BLOCK-END. Assurez-vous que le repère est seul sur sa ligne (précédé uniquement du préfixe de commentaire, tel que # EVOLVE-BLOCK-START).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Un repère EVOLVE-BLOCK-START apparaît dans un bloc d'évolution déjà ouvert. Supprimez les repères de début imbriqués. Les blocs evolve imbriqués ne sont pas acceptés.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Un repère EVOLVE-BLOCK-END apparaît sans EVOLVE-BLOCK-START précédent. Assurez-vous que chaque marqueur de fin est précédé d'un marqueur de début correspondant.
Parsing error: Evolve block started but not ended. Un repère EVOLVE-BLOCK-START a été trouvé sans repère de fermeture EVOLVE-BLOCK-END correspondant. Ajoutez un repère de fermeture EVOLVE-BLOCK-END.

Erreurs de contenu et de structure du programme

Message d'erreur Cause système Solution ou mesure corrective
Program content must contain at least one source file. program_content.source_files est vide. Fournissez au moins un fichier source.
source_files entries must have a non-empty path. Une entrée de fichier source comporte une chaîne path vide. Spécifiez un chemin relatif valide pour chaque fichier source.
source_files entry has empty content; path: <path> Une entrée de fichier source contient une chaîne vide. Remplissez le contenu du fichier.
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). Les blocs Evolve ne contiennent que des commentaires, des docstrings ou des espaces blancs, sans code modifiable. Incluez au moins une ligne de code modifiable (comme des définitions de fonction ou une logique d'algorithme) dans le bloc.

Erreurs de validation de la configuration et du modèle

Message d'erreur Cause système Solution ou mesure corrective
unsupported model: <model_name> Le modèle demandé n'est pas compatible ou n'est pas activé pour votre projet. Utilisez des modèles compatibles. Consultez la section Paramètres de génération.
model '<model_name>' is not served from domain shard '<location>'. Le modèle n'est pas disponible dans l'emplacement régional spécifié. Pour connaître les modèles et les emplacements compatibles, consultez Paramètres de génération.
generation_settings.models must contain at most 2 distinct models; got <count>. Plus de deux configurations de modèle ont été spécifiées dans generation_settings.models. Spécifiez au maximum deux modèles dans le mélange.
generation_settings.models contains duplicate entry: <model_name> Le même nom de modèle apparaît plusieurs fois dans generation_settings.models. Supprimez les entrées de modèle en double.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. La pondération d'échantillonnage du modèle est négative, nulle ou non finie. Définissez une pondération positive ou supprimez l'entrée.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. La température du modèle est en dehors de la plage valide [0.0, 2.0]. Ajustez la température sur une valeur comprise entre 0.0 et 2.0.
RunSettings.max_programs is required and must be greater than 1. max_programs a été omis ou défini sur 1 ou moins. Définissez max_programs sur 2 ou plus (un minimum de 2 est requis pour accepter les candidats évolués).
RunSettings.concurrency is required and must be positive. concurrency a été omis ou défini sur une valeur inférieure ou égale à 0. Définissez concurrency sur un entier positif (généralement compris entre 1 et 30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability est en dehors de [0.0, 1.0]. Définissez une probabilité comprise entre 0.0 et 1.0.

Prérequis du projet et erreurs liées au cycle de vie du test

Message d'erreur Cause système Solution ou mesure corrective
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> L'API Vertex AI (aiplatform.googleapis.com) n'est pas activée sur le projet Google Cloud . Exécutez 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. Le projet a atteint le quota de 30 tests actifs simultanément (STARTED ou RUNNING) dans cet emplacement. Arrêtez ou terminez les tests existants avant d'en démarrer ou d'en reprendre un autre.
Cannot <action> experiment from state <current_state> Tentative de transition d'état non valide (par exemple, démarrage d'un test déjà en cours d'exécution ou reprise d'un test nouvellement créé). Assurez-vous que les tests suivent les transitions de cycle de vie standards : 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. Une opération de démarrage ou de reprise précédente est toujours en cours. Attendez que la distribution en attente soit terminée ou appelez STOP pour vider les messages en attente.
AlphaEvolve is not available for this project. Le projet est bloqué ou correspond à un profil de conformité non compatible. Consultez Profil de conformité et de sécurité.

Erreurs d'acquisition et d'évaluation du programme

Message d'erreur Cause système Solution ou mesure corrective
Exactly one evaluation submission is required. Plusieurs envois d'évaluation ont été regroupés dans une seule requête submitProgramsEvaluations. Envoyez les évaluations individuellement, une par appel d'API.
Program is required for each evaluation submission./submission.program is required. Le chemin d'accès à la ressource program n'a pas été fourni dans l'envoi de l'évaluation. Transmettez le chemin d'accès complet à la ressource du programme.
Lock token is required for each evaluation submission./submission.lock_token is required. Le lock_token renvoyé lors de acquirePrograms a été omis. Transmettez la chaîne lock_token exacte renvoyée lors de l'acquisition du programme.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' Le jeton de verrouillage envoyé dans l'envoi ne correspond pas au bail du serveur actif (par exemple, le bail a expiré et un autre nœud de calcul l'a acquis, ou un jeton incorrect a été fourni). Renvoyez exactement le même lockToken que celui de acquirePrograms et envoyez les résultats avant l'expiration du délai d'attente du client.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> Le programme a déjà été évalué, annulé ou retiré de EVALUATION_IN_PROGRESS. Supprimez l'évaluation obsolète ou réacquérez le candidat s'il est disponible.
The request was rejected by a safety policy. La description du problème d'entrée, le code initial ou les métriques d'évaluation ont déclenché des règles de classification de sécurité. Nettoyez le texte des requêtes et les descriptions des problèmes pour supprimer les mots clés ou les traces sensibles.
The input safety classifier is currently unavailable. Le service de classification de la sécurité est temporairement inaccessible ou surchargé (échec de la fermeture). Implémentez une logique de nouvelle tentative avec intervalle exponentiel entre les tentatives.

Résoudre les "abandons silencieux"

Une interception de filtre de sécurité (suppression silencieuse) se produit lorsque les modèles de langage côté serveur signalent et suppriment les prompts candidats modifiés en raison d'une formulation sensible ou de déclencheurs de règles de sécurité. Le serveur désactive la sortie, ce qui entraîne le renvoi de réponses vides par la file d'attente, et les exécuteurs clients peuvent attendre indéfiniment.

Solution de contournement :

  • Nettoyer le contexte : supprimez les expressions chargées d'émotion ou sensibles à la sécurité de problemDescription.

  • Filtrer les insights : analysez et tronquez les traces d'exceptions brutes ou les journaux stderr du terminal dans la charge utile insights pour éviter de renvoyer du contenu système non sécurisé qui déclenche des filtres en aval.

  • Localiser les ensembles de données : ne placez pas d'enregistrements d'entraînement ni de grands corpus de texte dans les requêtes. Chargez-les localement dans l'environnement client pendant l'exécution de la boucle d'évaluation.

Bonnes pratiques pour l'évaluation côté client

Le goulot d'étranglement du "code spaghetti"

Un formatage source non optimal dégrade la qualité de l'optimisation : "Code spaghetti == espace de recherche bruyant". Avant de placer des repères EVOLVE-BLOCK :

  • Refactorisez les blocs de code de sorte que les variables et les signatures de fonction soient clairement nommées.

  • Ajoutez des docstrings descriptives et concises expliquant ce que fait chaque fonction ou variable, et pourquoi. Assurez-vous que les docstrings se trouvent à côté du code fonctionnel réel. Placer uniquement une docstring ou des commentaires dans un EVOLVE-BLOCK est rejeté comme un bloc vide.

  • Assurez-vous que les repères de commentaire EVOLVE-BLOCK-START et EVOLVE-BLOCK-END sont placés seuls sur leurs lignes respectives, à l'exception des espaces blancs de début et des préfixes de commentaire (tels que # ou //).

  • Assurez-vous que toutes les dépendances externes immuables (comme l'importation de modules d'assistance ou le chargement de données statiques) se trouvent en dehors de EVOLVE-BLOCK.

Allocation de la fenêtre de contexte

Pour maximiser la créativité des mutations, limitez la charge utile de code envoyée à l'API. Le contexte total du programme doit rester inférieur à 150 000 à 200 000 jetons. Les grands blocs de code récurrent statique et immuable consomment l'attention du modèle et dégradent les performances. Déplacez entièrement les scripts utilitaires, les pipelines d'ingestion de données et les bibliothèques de validation lourdes vers l'évaluateur côté client.

Amorcer d'abord le programme initial

Avant d'exécuter AlphaEvolve, utilisez un agent de codage standard pour déboguer votre codebase de départ et votre évaluateur :

  • Amorcer la graine : corrigez les bugs de syntaxe évidents, les problèmes de compilation et les cas particuliers.

  • Vérifier le score de départ : vérifiez que le score de référence est raisonnable et que l'évaluateur est entièrement déterministe (même code + même entrée = même score).

  • Tester avec des entrées non valides : exécutez l'évaluateur avec des fonctions intentionnellement défectueuses pour vérifier qu'il détecte les problèmes de compilateur, gère correctement les boucles infinies et renvoie des scores de pénalité négatifs élevés.

Éviter les références trop optimisées

Ne transmettez pas un programme de référence déjà hautement optimisé en tant que seed. Si votre programme initial est déjà presque optimal, AlphaEvolve aura du mal à l'améliorer, car la marge de progression est très faible. Commencez par une référence raisonnable, mais pas optimisée au maximum. Cela donne à AlphaEvolve l'espace nécessaire pour explorer et optimiser.

Mesures de protection de l'exécuteur côté client

Les évaluateurs côté client doivent appliquer des mesures de protection strictes pour empêcher les candidats malveillants, gourmands en ressources ou qui ne répondent pas de bloquer les nœuds de calcul parallèles :

  • Délais avant expiration stricts : appliquez un délai d'exécution strict de 30 minutes (ou moins, selon la structure de l'espace de recherche).

  • Envoi d'une pénalité de délai avant expiration : si une variante de programme candidate dépasse la limite de délai avant expiration, arrêtez immédiatement son thread d'exécution. Ne laissez pas le processus candidat échouer. Au lieu de cela, compilez et envoyez instantanément un score de pénalité d'échec grave (par exemple, -100000.0) ainsi qu'un insight de débogage descriptif au serveur pour libérer le verrou de file d'attente du programme.

  • Filtres de sécurité AST : effectuez toujours une vérification d'inspection de l'arbre syntaxique abstrait (AST) sur la charge utile du code source entrant avant la compilation. Interrompez immédiatement l'exécution et appliquez une pénalité d'échec sévère si des primitives de réflexion ou d'exécution restreintes (telles que eval, exec, getattr ou setattr) sont détectées.

Autres ressources

Pour en savoir plus, consultez les ressources suivantes :