Configuração do ambiente e do acesso à API

Nesta página, mostramos as etapas necessárias para inicializar o ambiente, provisionar a API e definir as configurações do usuário para começar a trabalhar com o AlphaEvolve.

  1. Pré-requisitos

  2. Como configurar o AlphaEvolve

Pré-requisitos

Antes de configurar o ambiente, verifique se a organização do Google Cloud conclui as etapas básicas de aquisição e infraestrutura.

Google Cloud projeto e licenciamento

  • Projeto doGoogle Cloud : crie um projeto dedicado do Google Cloud . Para o provisionamento de projetos, entre em contato com a equipe de conta do Google Cloud atribuída.

  • Licenças do Gemini Enterprise: compre licenças do Gemini Enterprise com seu representante de vendas do Google Cloud . 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 meio da identidade temporária de conta de serviço. As contas de serviço do Google Cloud 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 utiliza as três identidades distintas.

Verifique se o projeto obedece aos seguintes papéis obrigatórios de controle de acesso:

Perfil Descrição Papéis e permissões necessárias
Administrador de nuvem Gerencia a configuração inicial única do ambiente, a atribuição do IAM e a ativação da API Discovery Engine e da API Gemini na Vertex AI.
  • roles/resourcemanager.projectCreator (nível de 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 meio da identidade temporária de conta de serviço.
  • roles/iam.serviceAccountTokenCreator concedido no recurso da conta de serviço.
  • Opcional: roles/iam.serviceAccountUser se você estiver anexando a conta de serviço a recursos de computação (por exemplo, Vertex AI Workbench).
Conta de serviço Identidade automatizada que interage diretamente com o serviço das APIs do Cloud AlphaEvolve.
  • roles/discoveryengine.editor ou roles/discoveryengine.admin (com escopo de projeto)

Ambiente de host administrativo

Um host administrativo do Linux (como o shell do Google Cloud 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

Configurar o AlphaEvolve

A configuração do AlphaEvolve exige coordenação 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 as etapas abaixo para provisionar uma conta de serviço para seus experimentos de otimização. O administrador da nuvem precisa executar os seguintes comandos em um host administrativo:

  1. Defina o ID do projeto do Google Cloud :

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

    PROJECT_ID="my-gcp-project-id"

    Como alternativa, é possível recuperar dinamicamente o ID do projeto ativo da CLI:

    PROJECT_ID=$(gcloud config get project)

  2. Escolha um nome de 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á usado 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 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}"

  5. 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 os recursos do papel administrativo.

    • --role="roles/discoveryengine.admin": concede as permissões necessárias para criar instâncias subjacentes do Discovery Engine, sessões de conversação e recursos filhos do 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 personificar 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 realiza 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 criação de tokens de credencial de curta duração para o usuário do sistema especificado:

    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 do OAuth 2.0 de curta duração, o que impulsiona a identidade temporária segura da conta de serviço.

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

Ative as APIs necessárias

O administrador de nuvem precisa ativar duas APIs no projeto:

  • A API Discovery Engine (discoveryengine.googleapis.com), que disponibiliza os endpoints da API AlphaEvolve on Cloud.

  • A API Vertex AI (aiplatform.googleapis.com), que disponibiliza a API Gemini na Vertex AI. O AlphaEvolve gera cada programa candidato com um conjunto de modelos do Gemini. Portanto, um usuário do sistema não pode executar um experimento até que essa API seja ativada.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Como alternativa, ative as duas APIs com o SDK Google Cloud no host do Linux:

gcloud services enable discoveryengine.googleapis.com \
  aiplatform.googleapis.com --project="${PROJECT_ID}"

Confirme se as duas APIs estão ativadas:

gcloud services list --enabled --project="${PROJECT_ID}" \
  --filter="config.name:(discoveryengine.googleapis.com OR aiplatform.googleapis.com)"

Criar recursos e sessões do Discovery Engine

O processo de configuração passa das configurações de identidade administrativa para o provisionamento da camada de dados do aplicativo principal. Nesta etapa, você cria os componentes lógicos aninhados exigidos pela API para gerenciar, rotear 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 projeto doGoogle Cloud , e os recursos dele são hospedados em um local específico (os locais compatíveis com o AlphaEvolve são global, us e eu). Nessa estrutura básica, uma coleção atua como um contêiner organizacional de nível superior para recursos relacionados. O mecanismo é provisionado em uma coleção para hospedar o aplicativo de IA principal, que também é onde um recurso de assistente é configurado para gerenciar as propriedades e ferramentas de IA generativa do aplicativo. O mecanismo gerencia as interações individuais do usuário capturadas como objetos de sessão.

O AlphaEvolveExperiment é 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 do Google Cloud :

    Esta etapa declara uma variável de ambiente para o projeto de destino do Google Cloud, 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 do ID do assistente, que é compatível com URLs.

    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 dele.

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

Como testar o acesso à API

Depois que o administrador da nuvem terminar de provisionar identidades, configurar a identidade temporária de conta de serviço e verificar o layout do mecanismo, execute estas verificações finais. Esse teste de fumaça rápido verifica sua autorização e conexão de ponta a ponta antes de executar cargas de trabalho de otimização ativa.

Ver e excluir mecanismos

Use o token de acesso atual ou a conta de serviço personificada 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.