Referência da API AlphaEvolve

Este documento serve como Referência da API e especificação de sistema autoritativa e de nível de produção para a API AlphaEvolve Cloud nos níveis de conversa do Discovery Engine Google Cloud. Ele define as hierarquias de recursos aninhados precisas, os endpoints REST e gRPC, as restrições no nível do campo, as máquinas de estado do ciclo de vida, as matrizes de diagnóstico de erros, as regras de sandbox de segurança e os fluxos de trabalho de integração necessários para projetar um controlador e um loop de avaliação totalmente automatizados do lado do cliente.

Máquinas de estado unificadas do ciclo de vida

O agente AlphaEvolve coordena duas máquinas de estado independentes para monitorar a progressão da campanha experimental e gerenciar a entrega e a execução de mutações individuais do programa.

Estados do ciclo de vida do experimento

Um experimento representa a campanha de otimização geral. Ele é processado como um recurso permanente do lado do servidor e passa pelos seguintes estados:

  • CREATED:o estado de inicialização. O recurso foi declarado e configurado, mas ainda não preencheu as gerações iniciais nem enviou chamadas de API.

  • RUNNING:o estado ativo da avaliação. O mecanismo está simultaneamente amostrando candidatos principais, gerando mutações de código pela combinação de LLMs e transmitindo tarefas para avaliadores.

  • PAUSED:um estado de espera temporário acionado manualmente ou por um idle_timeout de proteção automatizado. A geração de código é interrompida, e os workers atuais pausam a entrega de métricas.

  • COMPLETED:um estado terminal que indica que a pesquisa atingiu com sucesso a alocação de meta max_programs ou o limite de geração estrutural.

  • FAILED:um estado de erro terminal que indica que problemas sistêmicos no ambiente, como exceções de credenciais de API não capturadas, corrupção do repositório de dados ou falhas consecutivas do executor, interromperam a execução do processamento.

Estados do programa

A sequência de validação de tempo de execução é aplicada a variantes candidatas individuais.

Cada mutação de código gerada se comporta como uma entidade de programa isolada que passa por uma sequência de estados operacionais granulares no banco de dados de população.

  1. INITIALIZED:a entrada do programa é criada no banco de dados, rastreando o pedigree ancestral e as vinculações do programa principal.

  2. GENERATING:uma tarefa é enviada ativamente para o back-end de combinação de modelos de linguagem para criar ou mudar os blocos de código funcionais específicos.

  3. EVALUATING:o payload de código é bloqueado por um processo de worker de avaliação e executado em um ambiente de teste isolado.

  4. COMPLETED:as pontuações de execução e os insights estruturais descritivos são enviados com segurança ao banco de dados evolutivo, e o programa é adicionado ao pool de seleção.

Simultaneidade e mecanismos de bloqueio

Os programas são adquiridos por loops de worker usando um mecanismo de token de bloqueio atômico para evitar condições de corrida ou sobrecarga de pontuação duplicada em topologias distribuídas. O avaliador precisa enviar o esquema de pontuação finalizado junto com o token de bloqueio de correspondência exata para confirmar os resultados no banco de dados.

Esquemas de configuração e configurações

Visão geral das principais configurações, parâmetros e padrões de esquema usados pelo ambiente de execução do mecanismo AlphaEvolve.

AlphaEvolveExperimentConfig

Define os parâmetros estruturais principais e as restrições programáticas da execução do experimento evolutivo.

Nome do campo Tipo Padrão Restrições / limites de valor Descrição técnica
title string Obrigatório Máximo de 256 caracteres Nome de exibição exclusivo do experimento.
problemDescription string Obrigatório Máximo de 5.000 caracteres A especificação formal do problema. Ele é injetado diretamente nos contextos de comandos para estabelecer regras.
programLanguage string Obrigatório Valor de formato livre Linguagem de destino da base de código evoluída (por exemplo, "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings objeto Obrigatório Mapeia para o esquema RunSettings Parâmetros de ritmo e tempo limite.
generationSettings objeto Opcional Mapeia para o esquema GenerationSettings Seleção de modelo e parâmetros de contexto.
evolutionSettings objeto Opcional Mapeia para o esquema EvolutionSettings Parâmetros de seleção de família e diversidade.

RunSettings

Governa a limitação de taxa de transferência, os limites de paralelização e os tempos limite automáticos do sistema.

Nome do campo Tipo Padrão Restrições / limites de valor Descrição técnica
maxPrograms int32 100 Mín.: 2, Máx.: 100.000 Orçamento total de execução (programas para gerar e avaliar). Precisa ser maior que 1.
concurrency int32 1 Mín.: 1, Máx.: 30 Número de mutações de programa paralelas ativas na fila. Valores maiores que 30 não são permitidos.
maxDuration string 24h (86400s) String ISO 8601 dayTimeDuration
Mínimo: >0, Máximo: 7 dias		 Tempo total permitido antes da interrupção do experimento.
idleTimeout string 5h (EUA/UE)
2h (global)		 String ISO 8601 dayTimeDuration
Mínimo: >0
Máximo: o padrão do local		 Duração da inatividade antes da transição automática para PAUSED. O padrão é de 2 horas em global e 5 horas em locais regionais (us, eu). A duração é limitada pelo padrão do local. Portanto, especificar um valor acima do padrão do local (por exemplo, 12 horas em global) é ignorado, e o valor é de 2 horas (sem erro).

Configurações de geração

O esquema GenerationSettings controla a montagem de comandos, as janelas de contexto e as configurações de modelo para mutações:

  • context (string): documentação de referência, APIs complementares ou regras opcionais fornecidas pelo usuário. Recomendamos usar menos de 200.000 tokens. Tamanhos de contexto que excedem 200.000 tokens diluem a atenção do modelo e degradam a qualidade da mutação.

  • includeFullProgramInPrompt (bool): false padrão.

    • true: o comando de mutação inclui o EVOLVE-BLOCK mutável e o boilerplate imutável ao redor (altamente recomendado para raciocínio estrutural complexo).

    • false: apenas o bloco mutável fica visível, salvando o contexto do token.

  • models (matriz de objetos): opcional. Cada entrada nomeia um modelo e atribui a ele um weight opcional, que é a parte das chamadas de geração desse modelo em relação às outras entradas. Se você omitir models, o AlphaEvolve vai escolher o padrão ao criar o experimento: o modelo do Gemini recomendado pelo Google para geração de código com o AlphaEvolve. Essa recomendação muda conforme modelos mais recentes são lançados. A partir de 29 de setembro de 2026, o padrão será gemini-3.8-flash. Para usar um modelo diferente, especifique o que você quer em models. Para fixar o mesmo modelo em todas as execuções, defina models.

    Como o AlphaEvolve resolve o padrão ao criar o experimento, os experimentos criados antes da mudança do modelo padrão mantêm o modelo registrado na configuração. Para mover um experimento para o Gemini 3.8 Flash, especifique-o em models ou crie um novo experimento.

    O exemplo a seguir envia cerca de nove em dez chamadas de geração para o primeiro modelo e o restante para o segundo. Os pesos são proporções, então não precisam somar 1.

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

Modelos compatíveis

Defina models[].name como um dos seguintes valores: É possível combinar no máximo dois modelos em um único experimento.

Nome do modelo Regiões de veiculação
gemini-3.8-flash (padrão) global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

O AlphaEvolve valida models ao criar o experimento e retorna INVALID_ARGUMENT para um nome de modelo que não está nesta tabela ou que não está disponível na região solicitada.

Configurações de evolução

O esquema EvolutionSettings controla a nova geração de modelos de ilha e as probabilidades de amostragem de elementos principais:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (ponto flutuante): a probabilidade (0,0 a 1,0) de amostrar programas principais diretamente da fronteira de Pareto ativa em vez de usar a seleção padrão com base na adequação. Esse parâmetro precisa ser definido como 0.0 (desativado) se as métricas otimizadas retornarem apenas uma métrica escalar única.

Modelos de dados de programas candidatos

Esta seção descreve os esquemas e as representações de dados usados para definir e organizar estruturas de código candidatas no banco de dados da população.

AlphaEvolveProgramContent

Define os arquivos e a estrutura do programa candidato.

  • files (matriz de AlphaEvolveSourceFile): uma lista de todos os arquivos que compõem a base de código candidata. O payload precisa conter pelo menos um arquivo de origem. O Google recomenda manter o número total de arquivos em 50 por programa candidato. Isso oferece atenção ideal do modelo e eficiência da janela de contexto.

  • description (string): um resumo gerado automaticamente que descreve as mudanças programáticas sugeridas pelo modelo de geração (máximo de 1.000 caracteres).

AlphaEvolveSourceFile

Representa um arquivo de código-fonte individual na base de código.

  • path (string): o destino do caminho relativo ao espaço de trabalho (obrigatório, máximo de 256 caracteres). Cada entrada de arquivo de origem precisa especificar um caminho preenchido. Se você estiver configurando um espaço de trabalho do Python, o ponto de entrada do arquivo executável principal precisará ser chamado exatamente "initial_program.py".

  • content (string): a string de código-fonte bruto que compreende os blocos de implementação funcional. O Google recomenda manter o tamanho cumulativo da base de código em todos os arquivos abaixo de 4.000 a 5.000 linhas de código (LOC, na sigla em inglês). Isso é ideal para a atenção do modelo e o desempenho da geração de mutações.

  • programLanguage (string): a tag de mapeamento do analisador de linguagem. Essa string precisa corresponder explicitamente ao idioma designado na configuração do experimento principal.

  • description (string): um resumo opcional que descreve a arquitetura ou a finalidade individual do arquivo, que é exposta ao LLM durante as transmissões de mutação (máximo de 500 caracteres).

AlphaEvolveProgramEvaluation

O payload estruturado enviado pelas instâncias do executor do cliente de volta ao banco de dados evolutivo após a execução do tempo de execução.

  • scores (AlphaEvolveScores): valores de métricas numéricas objetivas e padronizadas. As práticas recomendadas restringem isso a 3 a 5 métricas de ponto flutuante distintas. O excesso de dimensões de destino prejudica a performance do comparador de Pareto multi-objetivo.

  • insights (matriz de AlphaEvolveEvaluationInsight): rótulos semânticos de diagnóstico e traces de execução em linguagem natural transmitidos para ajudar nas tentativas subsequentes de geração de mutações do LLM (máximo recomendado de 10 itens).

Formulação de pontuação e formatos de ingestão

A regra de maximização

O AlphaEvolve funciona fundamentalmente como um algoritmo de escalada de colina monotônica e maximiza estritamente todas as métricas numéricas. Se o pipeline de avaliação rastrear uma meta de minimização (como minimizar a latência do aplicativo em milissegundos ou reduzir o uso da memória), negue o valor antes de enviá-lo de volta ao banco de dados: submitted_score = -latency_ms.

O ideal é que as pontuações sejam contínuas. Métricas booleanas ou altamente discretas não fornecem um indicador de gradiente suficiente para uma exploração eficaz de hill climbing.

Esquema de ingestão de objetivo único

Use o JSON a seguir quando o simulador de avaliação otimizar uma única função objetiva escalar.

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

Esquema de ingestão com vários objetivos

Use o JSON a seguir ao transmitir parâmetros independentes de rastreamento multi-objetivo para ativar rotinas de otimização da fronteira de Pareto do lado do 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."
      }
    ]
  }
}

Como buscar e consultar dados do programa

O sistema AlphaEvolve registra a telemetria, as métricas de execução e o código-fonte completo de cada mutação gerada. Assim, os desenvolvedores podem consultar esse repositório de dados históricos usando a API ou a CLI para acompanhar o progresso da otimização e extrair os candidatos de código com melhor desempenho.

Recuperação de programas usando a API REST

É possível consultar os recursos do programa avaliados no banco de dados usando o endpoint ListAlphaEvolvePrograms padrão com parâmetros de consulta de filtragem e classificação:

  • Filtragem por estado: consulte programas que correspondem a um estado específico do ciclo de vida:

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

  • Classificação com base em métricas: recupere candidatos classificados com base em métricas otimizadas:

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

Recuperação de programas usando a CLI

Para extrair os principais candidatos concluídos diretamente do seu terminal, execute o seguinte comando:

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

Exemplos completos de uso da CLI

A CLI AlphaEvolve oferece aos desenvolvedores controle administrativo rápido e monitoramento de campanhas diretamente do shell:

  • Listar todos os experimentos em uma sessão de conversa:

    ae experiment list

  • Listar todos os programas candidatos mutantes de um experimento específico:

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

    Substitua EXPERIMENT_NICKNAME pelo nome do experimento.

  • Recupere os principais candidatos a código concluído:

    ae results best EXPERIMENT_NICKNAME --top 5

    Substitua EXPERIMENT_NICKNAME pelo nome do experimento.

  • Retomar uma campanha pausada:

    ae experiment resume EXPERIMENT_NICKNAME

    Substitua EXPERIMENT_NICKNAME pelo nome do experimento.

Diretório de endpoint de API REST principal

Todos os endpoints são versionados em v1alpha da API Google Cloud Discovery Engine.

Padrão de caminho do recurso pai

O URI do recurso pai aninhado verdadeiro é estruturado da seguinte forma: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • O AlphaEvolve está disponível em global, us e eu. A criação de experimentos em outros locais retorna FAILED_PRECONDITION.
  • Projetos do Assured Workloads não são compatíveis.
  • Um projeto é limitado a 30 experimentos AlphaEvolve ativos simultaneamente (STARTED ou RUNNING) por local. Iniciar ou retomar um experimento que excede esse limite retorna RESOURCE_EXHAUSTED.

Criar experimento (POST)

  • Caminho:

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

  • Corpo da solicitação:AlphaEvolveExperimentConfig (consulte a seção 2.1)

  • Resposta:recurso AlphaEvolveExperiment que contém a campanha inicializada.

  • Status HTTP:200 OK

Exemplos de payload da API

  1. Exemplo de corpo da solicitação (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. Exemplo de corpo da resposta (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)

  • Caminho:

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

  • Corpo da solicitação:StartExperimentRequest

  • Aviso de descontinuação:o campo de corpo initialProgram foi descontinuado e é ignorado.

  • Resposta:GoogleLongrunningOperation (LRO).

  • Status HTTP:200 OK (transiciona o estado de CREATED para RUNNING)

Exemplos de payload da API

  1. Exemplo de corpo da solicitação

    {
  "desiredProgramsCount": 1
}

  2. Exemplo de corpo da resposta (200 OK - operação de longa duração)

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

Adquirir programas (POST)

  • Caminho:

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

  • Corpo da solicitação:AcquireProgramsRequest

    • desiredProgramsCount (int32): contagem opcional de lote de programas mutados a serem recuperados (o padrão é 1 quando não definido).

  • Status das respostas:

    • 200 OK: retorna uma resposta que contém recursos AlphaEvolveProgram bloqueados.

    • 204 No Content: a fila está vazia ou a campanha está pausada. Os executores precisam dormir (por exemplo, 15 segundos) e tentar de novo.

Exemplos de payload da API

  1. Exemplo de corpo da solicitação

    {
  "desiredProgramsCount": 1
}

  2. Exemplo de corpo da resposta (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. Exemplo de corpo de resposta (204 No Content)

Status HTTP 204 retornado com um contexto de payload vazio.

Enviar avaliações de programas (POST)

  • Caminho:

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

  • Corpo da solicitação:SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (matriz): contém o lockToken correspondente, o caminho qualificado do recurso do programa e o payload da avaliação (pontuações e insights). A API aceita exatamente um envio de avaliação por chamada. Agrupar várias avaliações em uma única solicitação é rejeitado com INVALID_ARGUMENT. Ao avaliar vários candidatos, envie cada programa individualmente.

  • Resposta:SubmitProgramsEvaluationsResponse (vazia).

  • Status HTTP:200 OK (salva pontuações, libera o bloqueio ativo e registra insights)

Exemplos de payload da API

  1. Exemplo de corpo da solicitação

    {
  "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. Exemplo de corpo da resposta (200 OK)

    {}

Retomar experimento (POST)

  • Caminho:

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

  • Corpo da solicitação:ResumeExperimentRequest

  • Resposta:GoogleLongrunningOperation (LRO).

  • Status HTTP:200 OK (transiciona o estado de PAUSED de volta para RUNNING)

Exemplos de payload da API

  1. Exemplo de corpo da solicitação

    {}

  2. Exemplo de corpo da resposta (200 OK - operação de longa duração)

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

Listar programas (GET)

  • Caminho:

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

  • Parâmetros de consulta:

    • stateFilter (string): opcional. Filtro de lista padrão, por exemplo, stateFilter = 'COMPLETED'.

    • orderBy (string): opcional. Classificação com base em métricas, por exemplo, accuracy desc.

  • Resposta:ListAlphaEvolveProgramsResponse.

  • Status HTTP:200 OK

Exemplos de payload da API

  1. Exemplo de URL de consulta de solicitação

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

  2. Exemplo de corpo da resposta (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"
}

Código de diagnóstico e referência para solução de problemas

Matriz de código de diagnóstico da API

Status HTTP Tipo de erro Causa do sistema Solução alternativa ou ação de mitigação
400 INVALID_ARGUMENT
  • Marcadores EVOLVE-BLOCK-START / EVOLVE-BLOCK-END malformados (por exemplo, conteúdo compartilhando a linha do marcador, blocos aninhados ou marcador final ausente).
  • Bloco de evolução vazio que contém apenas comentários ou espaços em branco sem código editável.
  • maxPrograms definido como menos de 2.
  • Campos de configuração não reconhecidos.
  • Configuração de modelo inválida (mais de dois modelos, entradas duplicadas, pesos não positivos ou temperatura fora de [0.0, 2.0]).
  • Enviar várias avaliações em uma única chamada submitProgramsEvaluations.
  • O projeto é do Assured Workloads.
 Verifique se os marcadores estão sozinhos na linha e incluem pelo menos uma linha de código que não seja um comentário. Defina maxPrograms como 2 ou mais. Remova campos que não fazem parte da API, como notes, que estava presente na versão de prévia da API. Envie as avaliações individualmente, uma por vez.
403 PERMISSION_DENIED
  • O usuário não tem o papel de editor do Discovery Engine (roles/discoveryengine.editor) ou de administrador (roles/discoveryengine.admin). Observação: roles/discoveryengine.user não concede permissões do AlphaEvolve, e roles/discoveryengine.viewer não pode receber experimentos.
  • O autor da chamada não tem permissão no recurso de sessão principal.
  • Nenhuma licença ativa do Gemini Enterprise foi atribuída.
 Conceda roles/discoveryengine.editor ou roles/discoveryengine.admin no nível do projeto e verifique o acesso à sessão principal. Verifique as licenças ativas do Gemini Enterprise. Configure as credenciais padrão do aplicativo:

gcloud auth application-default login --project=PROJECT_ID

Observação:o Model Armor não é compatível com as configurações do AlphaEvolve.
400 FAILED_PRECONDITION
  • Token de bloqueio desatualizado ou expirado ou incompatibilidade de estado do programa (por exemplo, o candidato foi readquirido ou finalizado após o término da locação).
  • O experimento foi criado em um local não compatível (fora de global, us ou eu).
  • A API Vertex AI (aiplatform.googleapis.com) não está ativada no projeto.
 Reflete o lockToken exato retornado por :acquirePrograms. Aplique tempos limite do lado do cliente (recomendado 30 minutos) e envie pontuações de penalidade de falha após o tempo limite. Recrie o experimento em um local aceito. Ative a API Vertex AI: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • O projeto atingiu o limite de 30 experimentos ativos simultaneamente (STARTED / RUNNING) por local.
  • A cota de tokens de geração de modelos de back-end foi esgotada.
 Para o limite de experimentos ativos: conclua ou pare os experimentos em execução antes de iniciar um novo. Diminuir concurrency em runSettings não afeta esse limite. Para cota de tokens do modelo: diminua concurrency em runSettings e implemente a espera exponencial.
503 SERVICE_UNAVAILABLE O classificador de segurança da entrada está indisponível ou o serviço de back-end está temporariamente sobrecarregado. Implemente um loop de repetição com espera exponencial aleatória do lado do cliente.

Mensagens de erro e soluções comuns

A referência a seguir lista mensagens de erro comuns retornadas pela API, as causas e as etapas de resolução.

Erros de análise do programa inicial e do EVOLVE-BLOCK

Mensagem de erro Causa do sistema Solução alternativa ou ação de mitigação
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Os marcadores EVOLVE-BLOCK-START e EVOLVE-BLOCK-END aparecem na mesma linha. Coloque os marcadores de início e fim em linhas separadas.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. O código, o texto ou os caracteres finais compartilham a linha com um marcador EVOLVE-BLOCK-START ou EVOLVE-BLOCK-END. Verifique se o marcador está sozinho na linha, precedido apenas pelo prefixo de comentário, como # EVOLVE-BLOCK-START.
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Um marcador EVOLVE-BLOCK-START aparece dentro de um bloco de evolução já aberto. Remova marcadores de início aninhados. Blocos de evolução aninhados não são indisponíveis.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Um marcador EVOLVE-BLOCK-END aparece sem um EVOLVE-BLOCK-START anterior. Verifique se todos os marcadores de fim são precedidos por um marcador de início correspondente.
Parsing error: Evolve block started but not ended. Um marcador EVOLVE-BLOCK-START foi encontrado sem um marcador de fechamento EVOLVE-BLOCK-END correspondente. Adicione um marcador de fechamento EVOLVE-BLOCK-END.

Erros de conteúdo e estrutura do programa

Mensagem de erro Causa do sistema Solução alternativa ou ação de mitigação
Program content must contain at least one source file. program_content.source_files está vazio. Forneça pelo menos um arquivo de origem.
source_files entries must have a non-empty path. Uma entrada de arquivo de origem tem uma string path vazia. Especifique um caminho relativo válido para cada arquivo de origem.
source_files entry has empty content; path: <path> Uma entrada de arquivo de origem contém conteúdo de string vazia. Preencha o conteúdo do arquivo.
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). Os blocos de evolução contêm apenas comentários, docstrings ou espaços em branco, sem código editável. Inclua pelo menos uma linha de código editável (como definições de função ou lógica de algoritmo) dentro do bloco.

Erros de validação de configuração e modelo

Mensagem de erro Causa do sistema Solução alternativa ou ação de mitigação
unsupported model: <model_name> O modelo solicitado não é compatível ou não está ativado para seu projeto. Use modelos compatíveis. Consulte Configurações de geração.
model '<model_name>' is not served from domain shard '<location>'. O modelo não está disponível no local regional especificado. Consulte Configurações de geração para saber quais modelos e locais são compatíveis.
generation_settings.models must contain at most 2 distinct models; got <count>. Mais de duas configurações de modelo foram especificadas em generation_settings.models. Especifique no máximo dois modelos na mistura.
generation_settings.models contains duplicate entry: <model_name> O mesmo nome de modelo aparece mais de uma vez em generation_settings.models. Remova as entradas de modelo 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. O peso da amostragem do modelo é negativo, zero ou não finito. Defina um peso positivo ou remova a entrada.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. A temperatura do modelo está fora do intervalo válido [0.0, 2.0]. Ajuste a temperatura para um valor entre 0.0 e 2.0.
RunSettings.max_programs is required and must be greater than 1. max_programs foi omitido ou definido como 1 ou menos. Defina max_programs como 2 ou mais (é necessário um mínimo de 2 para permitir candidatos evoluídos).
RunSettings.concurrency is required and must be positive. concurrency foi omitido ou definido como 0 ou menos. Defina concurrency como um número inteiro positivo (normalmente de 1 a 30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability está fora de [0.0, 1.0]. Defina uma probabilidade entre 0.0 e 1.0.

Pré-requisitos do projeto e erros no ciclo de vida do experimento

Mensagem de erro Causa do sistema Solução alternativa ou ação de mitigação
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> A API Vertex AI (aiplatform.googleapis.com) não está ativada no projeto Google Cloud . Execute 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. O projeto atingiu a cota de 30 experimentos ativos simultaneamente (STARTED ou RUNNING) nesse local. Interrompa ou conclua os experimentos atuais antes de iniciar ou retomar um novo.
Cannot <action> experiment from state <current_state> Tentativa de uma transição de estado inválida (por exemplo, iniciar um experimento já em execução ou retomar um experimento recém-criado). Verifique se os experimentos seguem as transições padrão do 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. Uma operação de início ou retomada anterior ainda está em andamento. Aguarde a conclusão da entrega pendente ou chame STOP para esvaziar as mensagens pendentes.
AlphaEvolve is not available for this project. O projeto está bloqueado ou é um perfil de compliance sem suporte. Consulte Perfil de compliance e segurança.

Erros de aquisição e avaliação de programas

Mensagem de erro Causa do sistema Solução alternativa ou ação de mitigação
Exactly one evaluation submission is required. Vários envios de avaliação foram agrupados em uma única solicitação submitProgramsEvaluations. Envie as avaliações individualmente, uma por chamada de API.
Program is required for each evaluation submission. / submission.program is required. O caminho do recurso program não foi informado no envio da avaliação. Transmita o caminho completo do recurso do programa.
Lock token is required for each evaluation submission. / submission.lock_token is required. O lock_token retornado durante acquirePrograms foi omitido. Transmita a string lock_token exata retornada quando o programa foi adquirido.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' O token de bloqueio enviado no envio não corresponde à concessão ativa do servidor. Por exemplo, a concessão expirou e outro worker a adquiriu, ou um token incorreto foi fornecido. Repita o lockToken exato de acquirePrograms e envie os resultados antes que o cliente atinja o tempo limite.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> O programa já foi avaliado, cancelado ou desativado do EVALUATION_IN_PROGRESS. Descarte a avaliação desatualizada ou adquira novamente o candidato, se disponível.
The request was rejected by a safety policy. A descrição do problema de entrada, o código inicial ou as métricas de avaliação acionaram políticas de classificação de segurança. Higienize o texto do comando e as descrições do problema para remover palavras-chave ou rastros sensíveis.
The input safety classifier is currently unavailable. O serviço de classificação de segurança está temporariamente inacessível ou sobrecarregado (falha fechada). Implemente a lógica de espera exponencial para novas tentativas.

Como corrigir "quedas silenciosas"

Uma interceptação de filtro de segurança (descarte silencioso) ocorre quando os modelos de linguagem do lado do servidor sinalizam e descartam comandos candidatos mutantes devido a frases sensíveis ou acionadores de regras de segurança. O servidor silencia a saída, fazendo com que a fila retorne respostas vazias, e os executores de clientes podem esperar indefinidamente.

Remediação alternativa:

  • Limpar contexto:remova frases emocionalmente carregadas ou sensíveis à segurança do problemDescription.

  • Filtrar insights:analise e trunque rastreamentos de exceção brutos ou registros stderr do terminal no payload insights para evitar a repetição de conteúdo do sistema não seguro que aciona filtros downstream.

  • Localizar conjuntos de dados:não coloque registros de treinamento ou grandes corpora de texto em comandos. Carregue-os localmente no ambiente do cliente durante a execução do loop de avaliação.

Práticas recomendadas de avaliação do lado do cliente

O gargalo do "código espaguete"

A formatação de origem abaixo do ideal prejudica a qualidade da otimização: "Código espaguete == Espaço de pesquisa ruidoso". Antes de colocar marcadores EVOLVE-BLOCK:

  • Refatore os blocos de código para que as variáveis e assinaturas de função sejam nomeadas claramente.

  • Adicione docstrings descritivas e concisas explicando o que cada função ou variável faz e por quê. Verifique se as docstrings estão ao lado do código funcional real. Colocar apenas uma docstring ou comentários dentro de um EVOLVE-BLOCK é rejeitado como um bloco vazio.

  • Verifique se os marcadores de comentário EVOLVE-BLOCK-START e EVOLVE-BLOCK-END estão sozinhos nas respectivas linhas, exceto por espaços em branco à esquerda e prefixos de comentário (como # ou //).

  • Verifique se todas as dependências externas e imutáveis (como importação de módulos auxiliares ou carregamento de dados estáticos) estão fora do EVOLVE-BLOCK.

Alocação da janela de contexto

Para maximizar a criatividade da mutação, limite o payload de código enviado à API. O contexto total do programa precisa ficar entre 150.000 e 200.000 tokens. Grandes blocos de boilerplate estático e imutável consomem a atenção do modelo e prejudicam o desempenho. Mova scripts de utilidade, pipelines de ingestão de dados e bibliotecas de validação pesadas totalmente para o avaliador do lado do cliente.

Primeiro, prepare o programa inicial

Antes de executar o AlphaEvolve, use um agente de programação padrão para depurar a base de código inicial e o avaliador:

  • Inicialize a seed:corrija bugs óbvios de sintaxe, problemas de compilação e casos extremos.

  • Verifique a pontuação inicial:confira se a pontuação de base é razoável e se o avaliador é totalmente determinista (mesmo código + mesma entrada = mesma pontuação).

  • Teste com entradas inválidas:execute o avaliador com funções intencionalmente corrompidas para confirmar se ele detecta problemas do compilador, lida com loops infinitos de maneira adequada e retorna pontuações de penalidade negativas altas.

Evitar valores de referência otimizados demais

Não transmita um programa de base já altamente otimizado como uma seed. Se o programa inicial já estiver quase ideal, o AlphaEvolve terá dificuldade em fazer a otimização por escalada de encosta porque há muito pouco espaço para melhorias. Comece com um valor de referência razoável, mas não totalmente otimizado. Isso dá espaço para o AlphaEvolve explorar e fazer hill-climbing.

Proteções do executor do lado do cliente

Os avaliadores do lado do cliente precisam aplicar salvaguardas rigorosas para evitar que candidatos maliciosos, que consomem muitos recursos ou que não respondem impeçam o trabalho paralelo:

  • Tempos limite rígidos:aplique um corte de execução rígido de 30 minutos (ou menos, dependendo da estrutura do espaço de pesquisa).

  • Envio de penalidade de tempo limite:se uma variante de programa candidata exceder o limite de tempo limite, encerre a linha de execução imediatamente. Não permita que o processo de candidato falhe. Em vez disso, compile e envie instantaneamente uma pontuação de penalidade de falha grave (por exemplo, -100000.0) junto com um insight de depuração descritivo de volta ao servidor para liberar o bloqueio da fila do programa.

  • Filtros de segurança da AST:sempre execute uma verificação de inspeção da árvore de sintaxe abstrata (AST, na sigla em inglês) na carga útil do código-fonte recebido antes da compilação. Aborte imediatamente a execução e aplique uma penalidade grave de falha se forem detectadas primitivas de reflexão ou execução restritas (como eval, exec, getattr ou setattr).

Outros recursos

Para saber mais, acesse os recursos a seguir: