Referencia de la API de AlphaEvolve

Este documento sirve como referencia de la API y especificación del sistema de nivel de producción para la API de AlphaEvolve Cloud en las capas conversacionales de Google CloudDiscovery Engine. Define las jerarquías de recursos anidados precisas, los extremos de REST y gRPC, las restricciones a nivel del campo, las máquinas de estado del ciclo de vida, las matrices de diagnóstico de errores, las reglas de zona de pruebas de seguridad y los flujos de trabajo de integración necesarios para diseñar un controlador y un bucle de evaluación completamente automatizados del cliente.

Máquinas de estados de ciclo de vida unificadas

El agente AlphaEvolve coordina dos máquinas de estados independientes para supervisar el progreso de las campañas experimentales y administrar la publicación y ejecución de mutaciones individuales del programa.

Estados del ciclo de vida del experimento

Un experimento representa la campaña de optimización general. Se procesa como un recurso persistente del servidor y pasa por los siguientes estados:

  • CREATED: Es el estado de inicialización. El recurso se declaró y configuró, pero aún no se completaron las generaciones iniciales ni se enviaron llamadas a la API.

  • RUNNING: Es el estado de evaluación activo. El motor muestrea de forma simultánea los candidatos principales, genera mutaciones de código a través de la combinación de LLM y transmite tareas a los evaluadores.

  • PAUSED: Es un estado de retención temporal que se activa de forma manual o a través de un idle_timeout protector automatizado. Se detiene la generación de código y los trabajadores existentes pausan la entrega de métricas.

  • COMPLETED: Es un estado terminal que indica que la búsqueda cumplió correctamente su asignación objetivo de max_programs o alcanzó su límite de generación estructural.

  • FAILED: Es un estado de error terminal que indica que los problemas sistémicos del entorno (como excepciones no detectadas de credenciales de API, corrupción del almacén de datos o pánicos consecutivos del ejecutor) detuvieron la ejecución del procesamiento.

Estados del programa

La secuencia de validación del tiempo de ejecución se aplica a las variantes candidatas individuales.

Cada mutación de código generada se comporta como una entidad de programa aislada que realiza una transición a través de una secuencia de estados operativos detallados dentro de la base de datos de la población.

  1. INITIALIZED: La entrada del programa se crea en la base de datos, y se hace un seguimiento de su linaje ancestral y de las vinculaciones con el programa principal.

  2. GENERATING: Una tarea se envía de forma activa al backend de combinación de modelos de lenguaje para redactar o mutar los bloques de código funcionales específicos.

  3. EVALUATING: El proceso de un trabajador de evaluación bloquea la carga útil de código y la ejecuta dentro de un entorno aislado de plataforma de pruebas.

  4. COMPLETED: Las puntuaciones de ejecución y las estadísticas estructurales descriptivas se confirman de forma segura en la base de datos evolutiva, y el programa se agrega al grupo de selección.

Mecánica de simultaneidad y bloqueo

Los programas se adquieren mediante bucles de trabajadores con un mecanismo de token de bloqueo atómico para evitar condiciones de carrera o una sobrecarga de puntuación duplicada en topologías distribuidas. El evaluador debe enviar el esquema de puntuación finalizado junto con el token de bloqueo de coincidencia exacta para confirmar correctamente los resultados en la base de datos.

Esquemas de configuración y parámetros

Descripción general de los parámetros, los valores predeterminados y las configuraciones del esquema principal que utiliza el entorno de ejecución del motor de AlphaEvolve.

AlphaEvolveExperimentConfig

Define los parámetros estructurales principales y las restricciones programáticas de la ejecución del experimento evolutivo.

Nombre del campo Tipo Predeterminado Restricciones y límites de valores Descripción técnica
title cadena Obligatorio Máx. 256 caracteres Es el nombre visible único del experimento.
problemDescription cadena Obligatorio Máximo de 5,000 caracteres Es la especificación formal del problema. Se inserta directamente en los contextos de las instrucciones para establecer reglas.
programLanguage cadena Obligatorio Valor de formato libre Es el lenguaje de destino de la base de código evolucionada (por ejemplo, "python", "cpp", "verilog", "cuda", "julia" o "java").
runSettings objeto Obligatorio Se asigna al esquema de RunSettings Son los parámetros de ritmo y tiempo de espera.
generationSettings objeto Optional Se asigna al esquema de GenerationSettings Parámetros de selección de modelos y contexto.
evolutionSettings objeto Optional Se asigna al esquema de EvolutionSettings Son los parámetros de selección de la población parental y de diversidad.

RunSettings

Rige la capacidad de procesamiento, los límites de paralelización y los tiempos de espera automáticos del sistema.

Nombre del campo Tipo Predeterminado Restricciones y límites de valores Descripción técnica
maxPrograms int32 100 Mín.: 2, máx.: 100,000 Presupuesto total de ejecución (programas para generar y evaluar). Debe ser superior a 1.
concurrency int32 1 Mín.: 1, máx.: 30 Es la cantidad de mutaciones de programas paralelas activas en la cola. No se permiten valores superiores a 30.
maxDuration cadena 24 h (86,400 s) Cadena dayTimeDuration según ISO 8601
Mín.: >0, Máx.: 7 días		 Es el tiempo total transcurrido permitido antes de que se detenga el experimento.
idleTimeout cadena 5 h (EE.UU./UE)
2 h (global)		 Cadena dayTimeDuration según ISO 8601
Mín.: >0
Máx.: El valor predeterminado de la ubicación		 Duración de inactividad antes de la transición automática a PAUSED. El valor predeterminado es de 2 horas en global y de 5 horas en ubicaciones regionales (us, eu). La duración está limitada por el valor predeterminado de la ubicación, por lo que se ignora la especificación de un valor superior al valor predeterminado de la ubicación (por ejemplo, 12 h en global) y el valor es de 2 horas (sin errores).

Configuración de generación

El esquema GenerationSettings controla el ensamblado de instrucciones, las ventanas de contexto y la configuración del modelo para las mutaciones:

  • context (cadena): Documentación de referencia, APIs complementarias o reglas opcionales proporcionadas por el usuario. Se recomienda estrictamente que no superes los 200,000 tokens. Los tamaños de contexto que superan los 200,000 tokens diluyen la atención del modelo y degradan la calidad de la mutación.

  • includeFullProgramInPrompt (bool): Valor predeterminado false.

    • true: La instrucción de mutación incluye el EVOLVE-BLOCK mutable y la plantilla inmutable circundante (se recomienda para el razonamiento estructural complejo).

    • false: Solo se ve el bloque mutable, lo que guarda el contexto del token.

  • models (array de objetos): Opcional. Cada entrada nombra un modelo y le asigna un weight opcional, que es la proporción de llamadas de generación de ese modelo en relación con las otras entradas. Si omites models, AlphaEvolve elige el valor predeterminado cuando crea el experimento: el modelo de Gemini que Google recomienda para la generación de código con AlphaEvolve. Esa recomendación cambia a medida que se lanzan modelos más nuevos. A partir del 29 de septiembre de 2026, el valor predeterminado será gemini-3.8-flash. Para usar un modelo diferente, especifica el que quieras en models. Para fijar el mismo modelo en cada ejecución, establece models por tu cuenta.

    Dado que AlphaEvolve resuelve el valor predeterminado cuando crea el experimento, los experimentos creados antes de que cambiara el modelo predeterminado conservan el modelo registrado en su configuración. Para trasladar un experimento existente a Gemini 3.8 Flash, especifícalo en models o crea un experimento nuevo.

    En el siguiente ejemplo, se envían aproximadamente nueve de cada diez llamadas de generación al primer modelo y el resto al segundo. Los pesos son proporciones, por lo que no tienen que sumar 1.

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

Modelos compatibles

Establece models[].name en uno de los siguientes valores. Puedes combinar un máximo de dos modelos en un solo experimento.

Nombre del modelo Regiones de servicio
gemini-3.8-flash (predeterminado) global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

AlphaEvolve valida models cuando crea el experimento y devuelve INVALID_ARGUMENT para un nombre de modelo que no está en esta tabla o que no está disponible en la región que solicitaste.

Configuración de evolución

El esquema EvolutionSettings controla las probabilidades de reinicio del modelo de isla y de muestreo de elementos superiores:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (número de punto flotante): Es la probabilidad (de 0.0 a 1.0) de muestrear programas principales directamente desde la frontera de Pareto activa en lugar de usar la selección estándar basada en la adecuación. Este parámetro debe establecerse en 0.0 (inhabilitado) si las métricas optimizadas solo devuelven una sola métrica escalar.

Modelos de datos de programas candidatos

En esta sección, se describen los esquemas y las representaciones de datos que se usan para definir y organizar las estructuras de código candidatas dentro de la base de datos de la población.

AlphaEvolveProgramContent

Define los archivos y la estructura del programa candidato.

  • files (array de AlphaEvolveSourceFile): Es una lista de todos los archivos que componen la base de código candidata. La carga útil debe contener al menos un archivo fuente. Google recomienda mantener el recuento total de archivos en 50 por programa candidato, lo que proporciona una atención óptima del modelo y eficiencia de la ventana de contexto.

  • description (cadena): Es un resumen generado automáticamente que describe los cambios programáticos sugeridos por el modelo de generación (máximo de 1,000 caracteres).

AlphaEvolveSourceFile

Representa un archivo de código fuente individual en la base de código.

  • path (cadena): Es la ruta de destino relativa al espacio de trabajo (obligatorio, máximo de 256 caracteres). Cada entrada de archivo fuente debe especificar una ruta de acceso no vacía. Si configuras un espacio de trabajo de Python, el punto de entrada del archivo ejecutable principal debe llamarse exactamente "initial_program.py".

  • content (cadena): Cadena de código fuente sin procesar que comprende los bloques de implementación funcionales. Google recomienda mantener el tamaño acumulativo de la base de código en todos los archivos entre 4,000 y 5,000 líneas de código (LOC), ya que esto es óptimo para la atención del modelo y el rendimiento de la generación de mutaciones.

  • programLanguage (cadena): Es la etiqueta de asignación del analizador de idioma. Esta cadena debe coincidir de forma explícita con el idioma designado en la configuración del experimento principal.

  • description (cadena): Es un resumen opcional que describe la arquitectura o el propósito individual del archivo, que se expone al LLM durante los pases de mutación (máx. 500 caracteres).

AlphaEvolveProgramEvaluation

Es la carga útil estructurada que envían las instancias del ejecutor del cliente a la base de datos evolutiva después de la ejecución del tiempo de ejecución.

  • scores (AlphaEvolveScores): Son valores de métricas numéricas objetivos y estandarizados. Las prácticas recomendadas indican que se debe restringir esta cantidad a entre 3 y 5 métricas de flotación distintas, ya que una cantidad excesiva de dimensiones objetivo degrada el rendimiento del comparador de Pareto para múltiples objetivos.

  • insights (array de AlphaEvolveEvaluationInsight): Etiquetas semánticas de diagnóstico y registros de ejecución en lenguaje natural que se devuelven para ayudar a los intentos posteriores de generación de mutaciones del LLM (se recomienda un máximo de 10 elementos).

Formatos de transferencia y formulación de la puntuación

La regla de maximización

AlphaEvolve funciona fundamentalmente como un algoritmo de ascenso de colinas monótono y maximiza estrictamente todas las métricas numéricas. Si tu canalización de evaluación hace un seguimiento de un objetivo de minimización (como minimizar la latencia de la aplicación en milisegundos o reducir el uso de memoria), debes negar el valor antes de volver a enviarlo a la base de datos: submitted_score = -latency_ms.

Lo ideal es que las puntuaciones sean continuas. Las métricas booleanas o altamente discretas no proporcionan un indicador de gradiente suficiente para una exploración eficaz de la búsqueda de la mejor solución.

Esquema de transferencia de un solo objetivo

Usa el siguiente JSON cuando tu arnés de evaluación se optimice en función de una sola función objetivo escalar.

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

Esquema de transferencia con varios objetivos

Usa el siguiente JSON cuando pases parámetros de seguimiento independientes de varios objetivos para activar las rutinas de optimización de la frontera de Pareto del servidor.

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

Cómo recuperar y consultar datos del programa

El sistema AlphaEvolve registra la telemetría, las métricas de ejecución y el código fuente completo de cada mutación generada, lo que permite a los desarrolladores consultar este almacén de datos históricos con la API o la CLI para hacer un seguimiento del progreso de la optimización y extraer los candidatos de código con el mejor rendimiento.

Recuperación de programas con la API de REST

Los recursos del programa evaluados se pueden consultar en la base de datos con el extremo ListAlphaEvolvePrograms estándar y los parámetros de consulta de filtrado y ordenamiento:

  • Filtrado por estado: Consulta los programas que coinciden con un estado del ciclo de vida específico:

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

  • Ordenamiento basado en métricas: Recupera candidatos ordenados según métricas optimizadas:

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

Recuperación de programas con la CLI

Para extraer los candidatos completados principales directamente desde tu terminal, ejecuta el siguiente comando:

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

Ejemplos completos de uso de la CLI

La CLI de AlphaEvolve proporciona a los desarrolladores un control administrativo y una supervisión rápidos de las campañas directamente desde el shell:

  • Enumera todos los experimentos en una sesión de conversación:

    ae experiment list

  • Enumera todos los programas candidatos mutados para un experimento específico:

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

    Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.

  • Recupera los candidatos de código completado con mejor rendimiento:

    ae results best EXPERIMENT_NICKNAME --top 5

    Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.

  • Sigue estos pasos para reanudar una campaña detenida:

    ae experiment resume EXPERIMENT_NICKNAME

    Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.

Directorio de extremos principales de la API de REST

Todos los extremos tienen versiones en v1alpha de la API de Google Cloud Discovery Engine.

Patrón de ruta de acceso del recurso principal

El URI del recurso principal anidado verdadero se estructura de la siguiente manera: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve está disponible en global, us y eu. La creación de experimentos en otras ubicaciones devuelve FAILED_PRECONDITION.
  • No se admiten proyectos de Assured Workloads.
  • Un proyecto está limitado a 30 experimentos de AlphaEvolve activos de forma simultánea (STARTED o RUNNING) por ubicación. Si inicias o reanudas un experimento que supera este límite, se devuelve RESOURCE_EXHAUSTED.

Crea un experimento (POST)

  • Path:

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

  • Cuerpo de la solicitud: AlphaEvolveExperimentConfig (consulta la sección 2.1)

  • Respuesta: Recurso AlphaEvolveExperiment que contiene la campaña inicializada.

  • Estado HTTP: 200 OK

Ejemplos de cargas útiles de la API

  1. Ejemplo de cuerpo de la solicitud (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. Ejemplo del cuerpo de la respuesta (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
        }
      }
    }
  }
}

Iniciar experimento (POST)

  • Path:

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

  • Cuerpo de la solicitud: StartExperimentRequest

  • Advertencia de baja: El campo del cuerpo initialProgram dejó de estar disponible y se ignora.

  • Respuesta: GoogleLongrunningOperation (LRO).

  • Estado HTTP: 200 OK (el estado pasa de CREATED a RUNNING)

Ejemplos de cargas útiles de la API

  1. Ejemplo de cuerpo de la solicitud

    {
  "desiredProgramsCount": 1
}

  2. Ejemplo del cuerpo de la respuesta (200 OK - operación de larga duración)

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

Adquiere programas (POST)

  • Path:

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

  • Cuerpo de la solicitud: AcquireProgramsRequest

    • desiredProgramsCount (int32): Es el recuento opcional por lotes de los programas modificados que se recuperarán (el valor predeterminado es 1 cuando no se establece).

  • Estados de respuesta:

    • 200 OK: Devuelve una respuesta que contiene recursos AlphaEvolveProgram bloqueados.

    • 204 No Content: La cola está vacía o la campaña está detenida. Los subprocesos deben suspenderse (por ejemplo, durante 15 segundos) y volver a intentarlo.

Ejemplos de cargas útiles de la API

  1. Ejemplo de cuerpo de la solicitud

    {
  "desiredProgramsCount": 1
}

  2. Ejemplo del cuerpo de la respuesta (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. Ejemplo del cuerpo de la respuesta (204 No Content)

Se devolvió el estado HTTP 204 con un contexto de carga útil vacío.

Enviar evaluaciones de programas (POST)

  • Path:

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

  • Cuerpo de la solicitud: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (array): Contiene el lockToken coincidente, la ruta de acceso calificada al recurso del programa y la carga útil de evaluación (puntuaciones y estadísticas). La API acepta exactamente un envío de evaluación por llamada. El procesamiento por lotes de varias evaluaciones en una sola solicitud se rechaza con INVALID_ARGUMENT. Cuando evalúes a varios candidatos, envía cada programa por separado.

  • Respuesta: SubmitProgramsEvaluationsResponse (vacía).

  • Estado HTTP: 200 OK (guarda las puntuaciones, libera el bloqueo activo y registra las estadísticas)

Ejemplos de cargas útiles de la API

  1. Ejemplo de cuerpo de la solicitud

    {
  "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. Ejemplo del cuerpo de la respuesta (200 OK)

    {}

Reanudar el experimento (POST)

  • Path:

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

  • Cuerpo de la solicitud: ResumeExperimentRequest

  • Respuesta: GoogleLongrunningOperation (LRO).

  • Estado HTTP: 200 OK (el estado pasa de PAUSED a RUNNING)

Ejemplos de cargas útiles de la API

  1. Ejemplo de cuerpo de la solicitud

    {}

  2. Ejemplo del cuerpo de la respuesta (200 OK - operación de larga duración)

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

Enumera programas (GET)

  • Path:

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

  • Parámetros de consulta:

    • stateFilter (cadena): Opcional. Es un filtro de lista estándar, por ejemplo, stateFilter = 'COMPLETED'.

    • orderBy (cadena): Opcional. Ordenamiento basado en métricas, por ejemplo, accuracy desc.

  • Respuesta: ListAlphaEvolveProgramsResponse.

  • Estado HTTP: 200 OK

Ejemplos de cargas útiles de la API

  1. Ejemplo de URL de consulta de solicitud

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

  2. Ejemplo del cuerpo de la respuesta (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"
}

Referencia de códigos de diagnóstico y solución de problemas

Matriz de códigos de diagnóstico de la API

Estado de HTTP Tipo de error Causa del sistema Solución o acción de mitigación
400 INVALID_ARGUMENT
  • Marcadores EVOLVE-BLOCK-START o EVOLVE-BLOCK-END con formato incorrecto (por ejemplo, contenido que comparte la línea del marcador, bloques anidados o falta el marcador de cierre).
  • Bloque de evolución vacío que solo contiene comentarios o espacios en blanco sin código editable.
  • maxPrograms se estableció en menos de 2.
  • No se reconocieron los campos de configuración.
  • Configuración del modelo no válida (más de dos modelos, entradas duplicadas, pesos no positivos o temperatura fuera de [0.0, 2.0]).
  • Envía varias evaluaciones en una sola llamada a submitProgramsEvaluations.
  • El proyecto es un proyecto de Assured Workloads.
 Asegúrate de que los marcadores estén solos en su línea y encierren al menos una línea de código que no sea un comentario. Establece maxPrograms en 2 o más. Quita los campos que no forman parte de la API, como notes, que estaba presente en la versión preliminar de la API. Envía las evaluaciones de forma individual, una a la vez.
403 PERMISSION_DENIED
  • La persona que llama no tiene el rol de Editor de Discovery Engine (roles/discoveryengine.editor) ni de administrador (roles/discoveryengine.admin). Nota: roles/discoveryengine.user no otorga permisos de AlphaEvolve, y roles/discoveryengine.viewer no puede obtener experimentos.
  • El emisor no tiene permiso para acceder al recurso de sesión principal.
  • No se asignó ninguna licencia activa de Gemini Enterprise.
 Otorga roles/discoveryengine.editor o roles/discoveryengine.admin a nivel del proyecto y verifica el acceso a la sesión principal. Verifica las licencias activas de Gemini Enterprise. Configura las credenciales predeterminadas de la aplicación:

gcloud auth application-default login --project=PROJECT_ID

Nota: Model Armor no es compatible con las configuraciones de AlphaEvolve.
400 FAILED_PRECONDITION
  • El token de bloqueo está vencido o no es válido, o bien no coincide el estado del programa (por ejemplo, se volvió a adquirir o se finalizó el candidato después de que venció el alquiler).
  • Se creó un experimento en una ubicación no admitida (fuera de global, us o eu).
  • La API de Vertex AI (aiplatform.googleapis.com) no está habilitada en el proyecto.
 Repite el lockToken exacto que devuelve :acquirePrograms. Aplica tiempos de espera del cliente (se recomiendan 30 minutos) y envía puntuaciones de penalización por fallas cuando se agote el tiempo de espera. Vuelve a crear el experimento en una ubicación compatible. Habilita la API de Vertex AI: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • El proyecto alcanzó el límite de 30 experimentos activos simultáneamente (STARTED / RUNNING) por ubicación.
  • Se agotó la cuota de tokens de generación del modelo de backend.
 En el caso del límite de experimentos activos, completa o detén los experimentos en ejecución antes de comenzar uno nuevo (reducir concurrency en runSettings no afecta este límite). Para la cuota de tokens del modelo: Reduce concurrency en runSettings y aplica la retirada exponencial.
503 SERVICE_UNAVAILABLE El clasificador de seguridad de entradas no está disponible o el servicio de backend está sobrecargado temporalmente. Implementa un bucle de reintento con retirada exponencial aleatorizada en el cliente.

Mensajes de error y soluciones comunes

En la siguiente referencia, se enumeran los mensajes de error comunes que devuelve la API, sus causas subyacentes y los pasos para resolverlos.

Errores iniciales de análisis del programa y de EVOLVE-BLOCK

Mensaje de error Causa del sistema Solución o acción de mitigación
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Los marcadores EVOLVE-BLOCK-START y EVOLVE-BLOCK-END aparecen en la misma línea. Coloca los marcadores de inicio y finalización en líneas separadas.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. El código, el texto o los caracteres finales comparten la línea con un marcador EVOLVE-BLOCK-START o EVOLVE-BLOCK-END. Asegúrate de que el marcador esté solo en su línea (precedido solo por el prefijo de comentario, como # EVOLVE-BLOCK-START).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Aparece un marcador EVOLVE-BLOCK-START dentro de un bloque evolve ya abierto. Quita los marcadores de inicio anidados, ya que no se admiten los bloques de evolución anidados.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Aparece un marcador EVOLVE-BLOCK-END sin un EVOLVE-BLOCK-START anterior. Asegúrate de que cada marcador de finalización esté precedido por un marcador de inicio coincidente.
Parsing error: Evolve block started but not ended. Se encontró un marcador EVOLVE-BLOCK-START sin un marcador de cierre EVOLVE-BLOCK-END coincidente. Agrega un marcador de cierre EVOLVE-BLOCK-END.

Errores de estructura y contenido del programa

Mensaje de error Causa del sistema Solución o acción de mitigación
Program content must contain at least one source file. program_content.source_files está vacío. Proporciona al menos un archivo fuente.
source_files entries must have a non-empty path. Una entrada de archivo fuente tiene una cadena path vacía. Especifica una ruta de acceso relativa válida para cada archivo fuente.
source_files entry has empty content; path: <path> Una entrada de archivo fuente contiene contenido de cadena vacío. Completa el contenido del archivo.
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). Los bloques de evolución solo contienen comentarios, cadenas de documentación o espacios en blanco, sin código editable. Incluye al menos una línea de código editable (como definiciones de funciones o lógica de algoritmos) dentro del bloque.

Errores de validación del modelo y la configuración

Mensaje de error Causa del sistema Solución o acción de mitigación
unsupported model: <model_name> El modelo solicitado no es compatible o no está habilitado para tu proyecto. Usa modelos compatibles. Consulta Configuración de generación.
model '<model_name>' is not served from domain shard '<location>'. El modelo no está disponible en la ubicación regional especificada. Consulta Configuración de generación para conocer los modelos y las ubicaciones compatibles.
generation_settings.models must contain at most 2 distinct models; got <count>. Se especificaron más de dos configuraciones del modelo en generation_settings.models. Especifica un máximo de dos modelos en la mezcla.
generation_settings.models contains duplicate entry: <model_name> El mismo nombre del modelo aparece más de una vez en generation_settings.models. Quita las entradas de modelos duplicadas.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. El peso de muestreo del modelo es negativo, cero o no finito. Establece un peso positivo o quita la entrada.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. La temperatura del modelo está fuera del rango válido [0.0, 2.0]. Ajusta la temperatura a un valor entre 0.0 y 2.0.
RunSettings.max_programs is required and must be greater than 1. Se omitió max_programs o se estableció en 1 o menos. Establece max_programs en 2 o más (se requiere un mínimo de 2 para admitir candidatos evolucionados).
RunSettings.concurrency is required and must be positive. Se omitió concurrency o se estableció en 0 o menos. Establece concurrency en un número entero positivo (por lo general, de 1 a 30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability está fuera de [0.0, 1.0]. Establece una probabilidad entre 0.0 y 1.0.

Requisitos previos del proyecto y errores del ciclo de vida del experimento

Mensaje de error Causa del sistema Solución o acción de mitigación
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> La API de Vertex AI (aiplatform.googleapis.com) no está habilitada en el proyecto Google Cloud . Ejecuta 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. El proyecto alcanzó la cuota de 30 experimentos activos simultáneamente (STARTED o RUNNING) en esa ubicación. Detén o completa los experimentos existentes antes de comenzar o reanudar uno nuevo.
Cannot <action> experiment from state <current_state> Se intentó una transición de estado no válida (por ejemplo, iniciar un experimento que ya se estaba ejecutando o reanudar un experimento recién creado). Asegúrate de que los experimentos sigan las transiciones estándar del ciclo de vida: 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. Una operación anterior de inicio o reanudación aún está en curso. Espera a que se complete la entrega pendiente o llama a STOP para descartar los mensajes pendientes.
AlphaEvolve is not available for this project. El proyecto está bloqueado o tiene un perfil de cumplimiento no compatible. Consulta Perfil de cumplimiento y seguridad.

Errores de adquisición y evaluación de programas

Mensaje de error Causa del sistema Solución o acción de mitigación
Exactly one evaluation submission is required. Se agruparon varios envíos de evaluación en una sola solicitud de submitProgramsEvaluations. Envía evaluaciones de forma individual, una por llamada a la API.
Program is required for each evaluation submission./submission.program is required. No se proporcionó la ruta de acceso al recurso program en el envío de la evaluación. Pasa la ruta de acceso completa del recurso del programa.
Lock token is required for each evaluation submission./submission.lock_token is required. Se omitió el lock_token que se devolvió durante acquirePrograms. Pasa la cadena lock_token exacta que se devolvió cuando se adquirió el programa.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' El token de bloqueo enviado en el envío no coincide con el arrendamiento activo del servidor (por ejemplo, el arrendamiento venció y otro trabajador lo adquirió, o se proporcionó un token incorrecto). Devuelve el mismo lockToken de acquirePrograms y envía los resultados antes de que se agote el tiempo de espera del cliente.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> El programa ya se evaluó, canceló o dejó de formar parte de EVALUATION_IN_PROGRESS. Descarta la evaluación obsoleta o vuelve a adquirir el candidato si está disponible.
The request was rejected by a safety policy. La descripción del problema de entrada, el código inicial o las métricas de evaluación activaron las políticas de clasificación de seguridad. Se anonimizan el texto de las instrucciones y las descripciones de los problemas para quitar palabras clave o rastros sensibles.
The input safety classifier is currently unavailable. El servicio de clasificación de seguridad no está disponible temporalmente o está sobrecargado (falla cerrada). Implementa la lógica de reintento de retirada exponencial.

Cómo corregir los "silent drops"

Una intercepción del filtro de seguridad (descarte silencioso) ocurre cuando los modelos de lenguaje del servidor marcan y descartan mensajes candidatos mutados debido a un lenguaje sensible o a activadores de reglas de seguridad. El servidor silencia la salida, lo que hace que la fila devuelva respuestas vacías y que los ejecutores del cliente esperen de forma indefinida.

Solución alternativa:

  • Limpiar el contexto: Quita las frases cargadas de emociones o sensibles a la seguridad del problemDescription.

  • Estadísticas de filtrado: Analiza y trunca los registros de errores sin procesar o los registros de stderr de la terminal en la carga útil de insights para evitar que se repita contenido del sistema no seguro que active filtros posteriores.

  • Localiza los conjuntos de datos: No coloques registros de entrenamiento ni grandes corpus de texto dentro de las instrucciones; cárgalos de forma local en el entorno del cliente durante la ejecución del bucle de evaluación.

Prácticas recomendadas para la evaluación del cliente

El cuello de botella del "código espagueti"

El formato de código no óptimo degrada la calidad de la optimización: "Código espagueti == Espacio de búsqueda ruidoso". Antes de colocar marcadores de EVOLVE-BLOCK, haz lo siguiente:

  • Refactoriza los bloques de código para que las variables y las firmas de funciones tengan nombres claros.

  • Agrega cadenas de documentación descriptivas y concisas que expliquen qué hace cada función o variable y por qué. Asegúrate de que las cadenas de documentación residan junto al código funcional real. Colocar solo una cadena de documentación o comentarios dentro de un EVOLVE-BLOCK se rechaza como un bloque vacío.

  • Asegúrate de que los marcadores de comentarios EVOLVE-BLOCK-START y EVOLVE-BLOCK-END se coloquen solos en sus respectivas líneas, excepto los espacios en blanco iniciales y los prefijos de comentarios (como # o //).

  • Asegúrate de que las dependencias externas inmutables (como la importación de módulos de ayuda o la carga de datos estáticos) se encuentren fuera de EVOLVE-BLOCK.

Asignación de ventana de contexto

Para maximizar la creatividad de las mutaciones, limita la carga útil de código que se envía a la API. El contexto total del programa debe mantenerse entre 150,000 y 200,000 tokens. Los grandes bloques de código estándar estático e inmutable consumen la atención del modelo y degradan el rendimiento. Mueve por completo los secuencias de comandos de utilidad, las canalizaciones de transferencia de datos y las bibliotecas de validación pesadas al evaluador del cliente.

Primero, prepara el programa inicial.

Antes de ejecutar AlphaEvolve, usa un agente de programación estándar para depurar tanto tu base de código inicial como tu evaluador:

  • Prepara la semilla: Corrige errores de sintaxis evidentes, problemas de compilación y casos extremos.

  • Verifica la puntuación inicial: Verifica que la puntuación de referencia sea razonable y que el evaluador sea completamente determinístico (el mismo código y la misma entrada generan la misma puntuación).

  • Prueba con entradas no válidas: Ejecuta el evaluador con funciones dañadas intencionalmente para confirmar que detecta problemas del compilador, controla los bucles infinitos de forma correcta y devuelve puntuaciones de penalización negativas altas.

Evita los modelos de referencia demasiado optimizados

No pases como inicial un programa de referencia que ya esté muy optimizado. Si tu programa inicial ya es casi óptimo, AlphaEvolve tendrá dificultades para realizar el ascenso de colina porque hay muy poco espacio para mejorar. Comienza con un modelo de referencia razonable, pero no optimizado al máximo. Esto le da espacio a AlphaEvolve para explorar y mejorar.

Protecciones del ejecutor del cliente

Los evaluadores del cliente deben aplicar medidas de protección estrictas para evitar que los candidatos maliciosos, que consumen muchos recursos o que no responden detengan a los trabajadores paralelos:

  • Tiempos de espera estrictos: Se aplica un límite estricto de ejecución de 30 minutos (o menos, según la estructura del espacio de búsqueda).

  • Envío de penalización por tiempo de espera: Si una variante del programa candidato supera el límite de tiempo de espera, finaliza su subproceso de ejecución de inmediato. No permitas que falle el proceso candidato. En su lugar, compila y envía al instante una puntuación de penalización por falla grave (por ejemplo, -100000.0) junto con una estadística de depuración descriptiva al servidor para liberar el bloqueo de la cola del programa.

  • Filtros de seguridad del AST: Siempre ejecuta una verificación de inspección del árbol de sintaxis abstracta (AST) en la carga útil del código fuente entrante antes de la compilación. Se debe anular la ejecución de inmediato y aplicar una penalización por falla grave si se detectan primitivas de reflexión o ejecución restringidas (como eval, exec, getattr o setattr).

Recursos adicionales

Para obtener más información, consulta los siguientes recursos: