Instalar e configurar o AlphaEvolve

Esta página aborda as etapas necessárias para inicializar seu ambiente, provisionar a API e configurar as definições do usuário para começar a trabalhar com AlphaEvolve.

  1. Pré-requisitos

  2. Como configurar o AlphaEvolve

Pré-requisitos

Antes de configurar seu ambiente, verifique se a organização Google Cloudconcluiu as etapas básicas de infraestrutura e compras.

Google Cloud projeto e licenciamento

  • Projeto do Google Cloud:crie um projeto Google Cloud (GCP) dedicado com links de faturamento ativos. Para consultas sobre provisionamento de projetos ou inclusão na lista de permissões, coordene com a Google Cloud equipe de contas atribuída.

  • Licenças do Gemini Enterprise:compre licenças do Gemini Enterprise com seu representante de vendas Google Cloud ou no Google Cloud Marketplace. É possível adicionar licenças ao Google Workspace ou provisioná-las como ofertas independentes. Qualquer nível do Gemini Enterprise, incluindo uma licença de teste, concede acesso ao AlphaEvolve.

  • Observação sobre a alocação de licenças:o sistema exige uma licença do Gemini Enterprise por usuário do sistema que interage com a API por representação de conta de serviço. Google Cloud As contas de serviço não consomem licenças do Workspace ou do Cloud Identity.

Perfis de usuário e requisitos do IAM

O ciclo de vida do AlphaEvolve usa as três identidades distintas.

Verifique se o projeto está em conformidade com os seguintes papéis obrigatórios de controle de acesso:

Perfil Descrição Papéis e permissões necessárias
Administrador da nuvem Gerencia a configuração inicial única do ambiente, a ativação da API e a atribuição do IAM.
  • roles/resourcemanager.projectCreator (nível da organização / pasta)
  • roles/billing.user (nível da conta de faturamento)
  • roles/serviceusage.admin
  • Privilégios de administrador do Workspace ou do Cloud Identity
Usuário do sistema
(pesquisador / cientista)		 Configura e executa experimentos de otimização. Interage com a API estritamente por representação de conta de serviço.
  • roles/iam.serviceAccountTokenCreator concedidas no recurso "Conta de serviço".
  • Opcional:roles/iam.serviceAccountUser se você estiver anexando a conta de serviço a recursos de computação (por exemplo, o Vertex AI Workbench).
Conta de serviço Identidade automatizada que interage diretamente com o serviço de API AlphaEvolve no Cloud Private Preview.
  • roles/discoveryengine.admin (com escopo de projeto)

Ambiente do organizador administrativo

Um host administrativo do Linux (como o Google Cloud Shell ou um host bastion seguro) executa os scripts de configuração e os payloads de teste. Verifique se o host contém os seguintes utilitários básicos:

  • SDK Google Cloud: necessário para executar comandos de gerenciamento de projetos. Instale a CLI gcloud se ela não estiver presente no host.

  • curl: valida o acesso de transporte HTTP ao endpoint de API de back-end. Para distribuições Debian ou Ubuntu, instale o utilitário pelo gerenciador de pacotes:

    sudo apt update && sudo apt install -y curl

Como configurar o AlphaEvolve

Para configurar o AlphaEvolve, é necessário coordenar o processo entre o administrador da nuvem e o usuário do sistema. Você precisa concluir as seguintes tarefas de instalação:

Criar uma conta de serviço

Siga estas etapas para provisionar uma conta de serviço para seus experimentos de otimização. O administrador da nuvem precisa executar os comandos a seguir em um host administrativo:

  1. Defina o ID do projeto Google Cloud :

    Esta etapa declara uma variável de ambiente para seu projeto de destino Google Cloud, garantindo que os comandos subsequentes operem no contexto correto.

    PROJECT_ID="my-gcp-project-id"

    Como alternativa, você pode recuperar dinamicamente o ID do projeto ativo da CLI:

    PROJECT_ID=$(gcloud config get project)

  2. Escolha um nome para a conta de serviço:

    Esta etapa declara uma variável de ambiente para o identificador legível por humanos da conta de serviço, que será usada no comando de criação.

    SA_NAME="alpha-evolve-client"

  3. Crie a conta de serviço:

    Esse comando registra uma nova conta de serviço no projeto Google Cloud , definindo o nome exclusivo, o nome de exibição e uma breve descrição da finalidade pretendida.

    gcloud iam service-accounts create "${SA_NAME}" \
  --description="Service Account to call AlphaEvolve on Cloud Private \
Preview API service" \
  --display-name="AlphaEvolve Client SA" \
  --project=$PROJECT_ID

  4. Extraia a string de e-mail da conta de serviço:

    Esse comando consulta a lista de contas de serviço com base no nome de exibição e extrai o endereço de e-mail oficial como uma variável de ambiente (SERVICE_ACCOUNT_EMAIL) para identificar o recurso de maneira exclusiva.

    SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list \
  --filter="displayName:AlphaEvolve Client SA" \
  --format='value(email)' \
  --project=$PROJECT_ID)

echo "Newly created Service Account Email: ${SERVICE_ACCOUNT_EMAIL}"

  1. Conceda o papel do Discovery Engine à conta de serviço:

    Execute o seguinte comando gcloud para conceder o papel roles/discoveryengine.admin à conta de serviço no nível do projeto:

    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/discoveryengine.admin" \
  --project="${PROJECT_ID}"

    Essa configuração aplica os seguintes parâmetros de lógica técnica:

    • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}": especifica o principal que recebe as funcionalidades da função administrativa.

    • --role="roles/discoveryengine.admin": concede as permissões necessárias para criar instâncias do Discovery Engine, sessões de conversa e recursos filhos AlphaEvolveExperiments.

    • ${SERVICE_ACCOUNT_EMAIL}: identifica o recurso (a nova conta de serviço) que o principal tem permissão para personificar.

Representar a conta de serviço

Depois de concluir as etapas de criação, use a ferramenta de linha de comando gcloud para conceder a um pesquisador (SYSTEM_USER) a capacidade explícita de representar a conta de serviço recém-criada.

  1. Defina o principal de representação: declare a string de destino da variável. Substitua SYSTEM_USER_EMAIL pela identidade corporativa ou pelo endereço de e-mail do pesquisador que está realizando as execuções de otimização.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

  2. Conceda o papel de criação de token ao principal: execute o comando a seguir para mapear a capacidade de geração de token de credencial de curta duração ao usuário especificado do sistema:

    gcloud iam service-accounts add-iam-policy-binding \
  "${SERVICE_ACCOUNT_EMAIL}" \
  --member="${SYSTEM_USER}" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project="${PROJECT_ID}"

    Essa vinculação de autorização garante que:

    • --member="${SYSTEM_USER}": especifica o usuário humano que recebe a autorização de geração de credenciais.

    • --role="roles/iam.serviceAccountTokenCreator": concede permissão para gerar tokens de acesso OAuth 2.0 de curta duração, o que impulsiona a representação segura de contas de serviço.

    • "${SERVICE_ACCOUNT_EMAIL}": identifica o recurso da conta de serviço de destino que está sendo vinculado à política recebida.

Ativar a API Discovery Engine

O administrador da nuvem precisa ativar a API discoveryengine.googleapis.com para interagir com os endpoints da API AlphaEvolve na prévia privada da nuvem. O administrador da nuvem pode fazer isso no console Google Cloud ou usando o SDK Google Cloud no host Linux: gcloud services enable discoveryengine.googleapis.com

Criar recursos e sessões do Discovery Engine

O processo de configuração passa de configurações de identidade administrativa para provisionamento da camada de dados principal do aplicativo. Nesta etapa, você vai criar os componentes lógicos aninhados necessários pela API subjacente para gerenciar, direcionar e rastrear seus experimentos de mutação de código.

Hierarquia de recursos do Discovery Engine

A hierarquia de recursos do Discovery Engine começa com um projetoGoogle Cloud , e os recursos dele são hospedados em um local específico (região). Nessa estrutura fundamental, uma coleção funciona como um contêiner organizacional de nível superior para recursos relacionados. O mecanismo é provisionado em uma coleção para hospedar o aplicativo principal de IA, que também é onde um recurso de assistente é configurado para gerenciar as propriedades e ferramentas de IA generativa do aplicativo. O mecanismo gerencia interações individuais do usuário capturadas como objetos de sessão.

O AlphaEvolveExperiment fica aninhado em uma sessão, representando uma única execução do agente de programação evolutiva usado para descoberta e otimização de algoritmos no contexto dessa interação específica do usuário.

Hierarquia do Discovery Engine

Provisionar os recursos

  1. Defina o ID do projeto Google Cloud :

    Esta etapa declara uma variável de ambiente para seu projeto Google Cloudde destino, garantindo que os comandos subsequentes operem no contexto correto:

    PROJECT_ID="my-gcp-project-id"

    ou

    PROJECT_ID=$(gcloud config get project)

  2. Defina o ID do mecanismo:

    Esta etapa declara uma variável de ambiente para o identificador exclusivo compatível com URL do ID do mecanismo.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crie o mecanismo:

    Esse comando registra um novo mecanismo no projeto Google Cloud , definindo o nome exclusivo, o nome de exibição e o SolutionType (SOLUTION_TYPE_GENERATIVE_CHAT).

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}?engineId=${ENGINE_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ENGINE_ID}"'",
    "data_store_ids": [],
    "solution_type": "SOLUTION_TYPE_GENERATIVE_CHAT"
  }'

  4. Defina o ID do assistente:

    Esta etapa declara uma variável de ambiente para o identificador exclusivo compatível com URL do ID do assistente.

    ASSISTANT_ID="default_assistant"

  5. Crie o assistente:

    Esse comando registra um novo assistente no projeto Google Cloud , definindo o nome exclusivo, o nome de exibição e uma breve descrição da finalidade pretendida.

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}/${ENGINE_ID}/assistants?assistantId=${ASSISTANT_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ASSISTANT_ID}"'",
    "description": null,
    "generation_config": null,
    "web_grounding_type": "WEB_GROUNDING_TYPE_UNSPECIFIED",
    "enabled_actions": null,
    "customer_policy": null
  }'

Testar o acesso à API

Depois que o administrador da nuvem provisionar as identidades necessárias, configurar a representação da conta de serviço e verificar o layout do mecanismo, o usuário do sistema de pesquisa precisará executar as seguintes etapas de validação. Essa sequência serve como um teste rápido pré-voo para confirmar o transporte e a autorização de ponta a ponta antes de iniciar cargas de trabalho de otimização ativas.

Gerar um token de acesso usando a representação

Execute o comando a seguir para validar se a política vincula a representação da conta de serviço corretamente. Essa verificação garante que sua identidade de pesquisador local assuma com segurança a identidade de execução automatizada.

  gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}"

Usar o token de acesso

O comando gera uma string de credencial bruta e temporária do OAuth 2.0. Para fluxos de trabalho de verificação em várias etapas, armazene em cache esse token em uma variável de shell de curta duração ou incorpore-o diretamente nas chamadas de transporte para consultar os metadados do projeto fundamental:

  TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}")
  curl -X GET \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}"

Ver e excluir mecanismos

Use seu token de acesso atual ou a conta de serviço representada para verificar, listar ou excluir seus mecanismos:

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines"
  curl -X GET "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines/${ENGINE_ID}"
  curl -X DELETE "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Parabéns! Você concluiu as etapas de configuração. Agora você pode executar a API AlphaEvolve V1.