Configuração do ambiente e do acesso à API

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 o AlphaEvolve.

  1. Pré-requisitos

  2. Como configurar o AlphaEvolve

Pré-requisitos

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

Google Cloud projeto e licenciamento

  • Google Cloud projeto: crie um Google Cloud projeto dedicado. Para o provisionamento de projetos, coordene com sua equipe de conta Google Cloud atribuída.

  • Licenças do Gemini Enterprise: compre licenças do Gemini Enterprise com seu Google Cloud representante de vendas. 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. 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 utiliza as três identidades distintas.

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

Perfil Descrição Papéis e permissões necessárias
Administrador da nuvem Gerencia a configuração inicial do ambiente único, atribuição do IAM e a ativação da Discovery Engine API e da API Gemini na Vertex AI.
  • 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 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ê anexar a conta de serviço aos recursos de computação (por exemplo, o Vertex AI Workbench).
Conta de serviço Identidade automatizada que faz interface diretamente com o serviço da API AlphaEvolve on Cloud.
  • roles/discoveryengine.admin (com escopo de projeto)

Ambiente de host administrativo

Um host Linux administrativo (como 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 gcloud CLI 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 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 Google Cloud ID do projeto:

    Esta etapa declara uma variável de ambiente para o 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 da CLI ativa:

    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 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 dentro do Google Cloud projeto, 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 comando gcloud a seguir 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 de papel administrativo.

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

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

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 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 geração de token 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, que impulsionam a representação 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 recebida.

Ative as APIs necessárias

O administrador da nuvem precisa ativar duas APIs no projeto:

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

  • A API Vertex AI (aiplatform.googleapis.com), que veicula 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 as 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, você pode receber essa permissão pelo papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Como alternativa, ative as duas APIs com o SDK Google Cloud no host 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 faz a transição das configurações de identidade administrativa para o provisionamento da camada de dados do aplicativo principal. Nessa fase, você cria os componentes lógicos aninhados exigidos pela API subjacente 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 Google Cloud projeto, e os recursos são hospedados em um local específico (região). Nessa estrutura básica, uma coleção atua como um contêiner organizacional de nível superior para recursos relacionados. O mecanismo é provisionado dentro de 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 está aninhado em uma sessão, representando uma única execução do agente de codificaçã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 Google Cloud ID do projeto:

    Esta etapa declara uma variável de ambiente para o projeto de destino 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 do ID do mecanismo compatível com URL.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crie o mecanismo:

    Esse comando registra um novo mecanismo dentro do Google Cloud projeto, 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 compatível com URL.

    ASSISTANT_ID="default_assistant"

  5. Crie o assistente:

    Esse comando registra um novo assistente dentro do Google Cloud projeto, 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 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 rápido verifica sua autorização e conexão de ponta a ponta antes de executar cargas de trabalho de otimização ativas.

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.