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 qualité production pour l'API AlphaEvolve Cloud sous les couches conversationnelles du moteur de découverte Google Cloud. 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 à états du cycle de vie, les matrices de diagnostic des erreurs, les règles de bac à sable de sécurité et les workflows d'intégration nécessaires pour concevoir un contrôleur et une boucle d'évaluation entièrement automatisés côté client.

Machines à états du cycle de vie unifiées

L'agent AlphaEvolve coordonne deux machines à états indépendantes pour surveiller la progression des campagnes de test et gérer la diffusion et l'exécution des mutations de programme individuelles.

États du cycle de vie des tests

Un test représente la campagne d'optimisation globale. Il est traité 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 généré de générations initiales ni distribué d'appels d'API.

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

  • PAUSED : état de suspension temporaire déclenché manuellement ou par une idle_timeout de protection automatisée. La génération de code s'arrête et les nœuds de calcul existants mettent en pause 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 systémiques liés à l'environnement (tels que des exceptions non détectées liées aux identifiants API, une corruption du data store ou des paniques consécutives du runner) ont interrompu l'exécution du traitement.

États du programme

La séquence de validation de l'exécution est appliquée à chaque variante candidate.

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 la population.

  1. INITIALIZED : l'entrée du programme est créée dans la base de données, ce qui permet de suivre son pedigree ancestral 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 worker d'évaluation et exécutée dans un environnement de harnais de test isolé.

  4. COMPLETED : les scores d'exécution et les informations structurelles descriptives 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 concurrence et de verrouillage

Les boucles de nœuds de calcul acquièrent des programmes à l'aide d'un mécanisme de jeton de verrouillage atomique pour éviter les conditions de concurrence ou les surcoûts d'attribution de scores en double dans les topologies distribuées. L'évaluateur doit envoyer le schéma de notation finalisé avec le jeton de verrouillage correspondant exactement pour pouvoir renvoyer les résultats à 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 le moteur d'exécution AlphaEvolve.

AlphaEvolveExperimentConfig

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

Nom du champ Type Par défaut Contraintes / Limites de valeurs Description technique
title string Obligatoire 256 caractères max. Nom à afficher unique du test.
problemDescription string Obligatoire 5 000 caractères au maximum Spécification formelle du problème. Il est injecté directement dans les contextes d'invite pour établir des règles.
programLanguage string Obligatoire Valeur de forme libre Langue cible du codebase évolué (par exemple, "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings objet Obligatoire Correspond au schéma RunSettings Paramètres de rythme et de délai avant expiration.
generationSettings objet Optional Correspond au schéma GenerationSettings Paramètres de sélection et de contexte du modèle.
evolutionSettings objet Optional Correspond 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 valeurs 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 heures (86 400 secondes) Chaîne ISO 8601 dayTimeDuration
Min : >0, Max : 7 jours		 Temps total écoulé autorisé avant l'arrêt de l'expérience.
idleTimeout string 5 h (États-Unis/Europe)
2 h (monde entier)		 Chaîne ISO 8601 dayTimeDuration
Min : >0
Max : valeur par défaut du lieu		 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 zones régionales (us, eu). La durée est limitée par la valeur par défaut de la zone. Par conséquent, si vous spécifiez une valeur supérieure à la valeur par défaut de la zone (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éen) : false par défaut.

    • true : le prompt de mutation inclut le EVOLVE-BLOCK mutable et le boilerplate immuable environnant (fortement recommandé pour le raisonnement structurel complexe).

    • false : seul le bloc modifiable est visible, ce qui permet d'enregistrer 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 des appels de génération de ce modèle par rapport aux autres entrées. Si vous omettez models, AlphaEvolve choisit la valeur par défaut lorsqu'il crée le test : le modèle Gemini que Google recommande pour la génération de code avec AlphaEvolve. Cette recommandation change à mesure que de nouveaux modèles sont publiés. À partir du 29 septembre 2026, la valeur par défaut sera gemini-3.8-flash. Pour utiliser un autre modèle, spécifiez celui de votre choix dans models. Pour épingler le même modèle à chaque exécution, définissez models vous-même.

    Étant donné qu'AlphaEvolve résout la valeur par défaut lorsqu'il crée le test, les tests créés avant la modification du modèle par défaut conservent le modèle enregistré dans leur configuration. Pour migrer un test existant vers Gemini 3.8 Flash, spécifiez-le dans models ou créez-en un.

    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. Elles ne doivent donc pas nécessairement être égales à 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 desservies
gemini-3.8-flash (par défaut) 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.

Paramètres d'évolution

Le schéma EvolutionSettings contrôle le réamorçage du modèle insulaire et les probabilités d'échantillonnage parent :

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float) : probabilité (de 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 le fitness. 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 composant la codebase candidate. 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 (string) : résumé généré automatiquement décrivant les modifications programmatiques suggérées par le modèle de génération (1 000 caractères maximum).

AlphaEvolveSourceFile

Représente un fichier de code source individuel dans le codebase.

  • path (string) : 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 brut comprenant les blocs d'implémentation fonctionnelle. Google recommande de maintenir la taille cumulée de la codebase dans tous les fichiers en dessous de 4 000 à 5 000 lignes de code (LOC). Cela permet d'optimiser l'attention du modèle et les performances de génération de mutations.

  • programLanguage (chaîne) : tag de mappage du parseur de langue. 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 envoyée par les instances de l'exécuteur client à la base de données évolutionnaire après l'exécution du runtime.

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

  • insights (tableau de AlphaEvolveEvaluationInsight) : libellés sémantiques de diagnostic et traces d'exécution en langage naturel renvoyés pour aider le LLM lors de ses tentatives de génération de mutations ultérieures (10 éléments maximum recommandés).

Formulation du score et formats d'ingestion

Règle de maximisation

AlphaEvolve fonctionne fondamentalement comme un algorithme d'escalade monotone et maximise strictement toutes les métriques numériques. Si votre pipeline d'évaluation suit une cible de minimisation (par exemple, la minimisation de la latence d'application en millisecondes ou la réduction de l'utilisation de la mémoire), vous devez nier 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 très discrètes ne fournissent pas un signal de gradient suffisant pour une exploration efficace de l'escalade de colline.

Schéma d'ingestion à objectif unique

Utilisez le JSON suivant lorsque votre plate-forme d'évaluation optimise une fonction objectif scalaire unique.

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

Schéma d'ingestion multi-objectifs

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 les données du programme

Le système AlphaEvolve enregistre la télémétrie, les métriques d'exécution et le code source complet de chaque mutation générée, ce qui permet aux développeurs d'interroger ce data store 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érer des 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 des métriques optimisées :

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

Récupérer des programmes à l'aide de la CLI

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

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

Exemples complets d'utilisation de la CLI

L'interface de ligne de commande AlphaEvolve permet aux développeurs de contrôler et de surveiller rapidement les campagnes directement depuis le shell :

  • Lister tous les tests d'une session conversationnelle :

    ae experiment list

  • Lister tous les programmes candidats muté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 expérience.

  • 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 expérience.

  • Pour réactiver une campagne mise en veille :

    ae experiment resume EXPERIMENT_NICKNAME

    Remplacez EXPERIMENT_NICKNAME par le nom de votre expérience.

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

Tous les points de terminaison sont versionnés sous v1alpha de l' Google Cloud API Discovery Engine.

Format du chemin d'accès à la ressource parente

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

  • AlphaEvolve est disponible dans les langues global, us et eu. La création de tests dans d'autres emplacements renvoie FAILED_PRECONDITION.
  • Les projets Assured Workloads ne sont pas acceptés.
  • 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 de l'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'obsolescence : Le champ de corps initialProgram est obsolète et ignoré.

  • Réponse : GoogleLongrunningOperation (LRO).

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

Exemples de charges utiles de l'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 facultatif de programmes mutés à récupérer (par défaut, la valeur est 1 si elle n'est pas définie).

  • États des réponses :

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

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

Exemples de charges utiles de l'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)

État HTTP 204 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 les lockToken correspondants, le chemin d'accès qualifié à la ressource du programme et la charge utile d'évaluation (scores et insights). L'API accepte exactement une soumission d'évaluation par appel. Le regroupement 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, déverrouille la serrure active et enregistre les insights)

Exemples de charges utiles de l'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 de l'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 une métrique, par exemple accuracy desc.

  • Réponse : ListAlphaEvolveProgramsResponse.

  • État HTTP : 200 OK

Exemples de charges utiles de l'API

  1. Exemple d'URL de requête

    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"
}

Code de diagnostic et informations de 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 mal formés (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]).
  • Envoyer plusieurs évaluations dans un seul appel submitProgramsEvaluations.
  • Le projet est un projet Assured Workloads.
 Assurez-vous que les marqueurs sont seuls sur leur ligne et qu'ils englobent au moins une ligne de code non commentée. Définissez maxPrograms sur 2 ou plus. 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 à la fois.
403 PERMISSION_DENIED
  • L'appelant ne dispose pas du rôle Éditeur Discovery Engine (roles/discoveryengine.editor) ni du rôle Administrateur (roles/discoveryengine.admin). Remarque : roles/discoveryengine.user n'accorde pas d'autorisations AlphaEvolve, et roles/discoveryengine.viewer ne peut pas obtenir d'expériences.
  • L'appelant ne dispose pas de l'autorisation requise 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, puis 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 état du programme non concordant (par exemple, le candidat a été réacquis ou finalisé après l'expiration du bail).
  • Test créé dans une zone géographique non acceptée (en dehors de global, us ou eu).
  • L'API Vertex AI (aiplatform.googleapis.com) n'est pas activée dans le projet.
 Répétez exactement le lockToken renvoyé par :acquirePrograms. Appliquez des délais avant expiration côté client (30 minutes recommandées) et envoyez les scores de pénalité en cas d'échec. 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 de modèle backend est épuisé.
 Pour la limite de tests actifs : terminez ou arrêtez les tests en cours avant d'en lancer un autre (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 est indisponible 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 courants et solutions

La liste 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 apparaissent 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 "Évoluer" déjà ouvert. Supprimez les repères de début imbriqués, car les blocs d'évolution 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 s'affiche 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 d'accès relatif valide pour chaque fichier source.
source_files entry has empty content; path: <path> Une entrée de fichier source contient un contenu de 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 (telle que 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 Paramètres de génération.
model '<model_name>' is not served from domain shard '<location>'. Le modèle n'est pas disponible dans la région spécifiée. Pour connaître les modèles et les zones géographiques 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 de l'échantillonnage du modèle est négative, nulle ou non finie. Définissez un poids positif 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]. Réglez 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 0 ou une valeur inférieure. Définissez concurrency sur un entier positif (généralement 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.

Erreurs liées aux prérequis du projet et au cycle de vie de l'expérience

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 dans 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 expériences actives simultanément (STARTED ou RUNNING) dans cet emplacement. Arrêtez ou terminez les tests existants avant d'en démarrer ou de reprendre un nouveau.
Cannot <action> experiment from state <current_state> Vous avez tenté une transition d'état non valide (par exemple, en démarrant un test déjà en cours d'exécution ou en reprenant un test récemment créé). Assurez-vous que les expériences 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 livraison 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 des programmes

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 la demande d'é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 la requête ne correspond pas au bail de serveur actif (par exemple, le bail a expiré et un autre employé l'a acquis, ou un jeton incorrect a été fourni). Répétez exactement lockToken à partir de acquirePrograms et envoyez les résultats avant les délais d'expiration 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 transféré hors de EVALUATION_IN_PROGRESS. Supprimez l'évaluation obsolète ou récupérez le candidat s'il est disponible.
The request was rejected by a safety policy. La description du problème, le code initial ou les métriques d'évaluation ont déclenché des règles de classification de sécurité. Nettoyez le texte de la requête 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é (fermeture en cas d'échec). Implémentez une logique de nouvelle tentative avec intervalle exponentiel entre les tentatives.

Remédier aux "abandons silencieux"

Une interception par un filtre de sécurité (suppression silencieuse) se produit lorsque des modèles de langage côté serveur signalent et suppriment des requêtes candidates mutées 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écutants du client peuvent attendre indéfiniment.

Solution de contournement :

  • Nettoyer le contexte : supprimez les expressions émotionnellement chargées ou sensibles en termes de sécurité du problemDescription.

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

  • Localisez 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 lors de l'exécution de la boucle d'évaluation.

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

Le goulot d'étranglement du "code spaghetti"

Une mise en forme de la source non optimale 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 afin que les variables et les signatures de fonction soient clairement nommées.

  • Ajoutez des docstrings descriptives et concises expliquant ce que font chaque fonction ou variable et pourquoi. Assurez-vous que les docstrings se trouvent à côté du code fonctionnel proprement dit. Le fait de placer uniquement une docstring ou des commentaires dans un EVOLVE-BLOCK est refusé, car il s'agit d'un bloc vide.

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

  • Assurez-vous que toutes les dépendances externes et 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 du 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.

Amorcez 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 :

  • Préparer le seed : corrigez les bugs de syntaxe évidents, les problèmes de compilation et les cas extrêmes.

  • Vérifiez le score de départ : assurez-vous 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).

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

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

Ne transmettez pas un programme de base déjà fortement optimisé en tant que seed. Si votre programme initial est déjà presque optimal, AlphaEvolve aura du mal à effectuer l'escalade, car il y a très peu de marge d'amélioration. Commencez par une base raisonnable, mais pas encore optimisée au maximum. Cela donne à AlphaEvolve l'espace nécessaire pour explorer et effectuer une recherche par escalade.

Mesures de protection pour 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 ne répondant pas de bloquer les workers parallèles :

  • Délai d'attente strict : 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 d'attente : si une variante du programme candidat dépasse la limite de délai d'attente, mettez fin 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é pour é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 : exécutez toujours une vérification d'inspection de l'arbre syntaxique abstrait (AST) sur la charge utile du code source entrant avant la compilation. Interrompre immédiatement l'exécution et appliquer une pénalité en cas d'échec grave 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 :