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

  • Projeto do Google Cloud: crie um projeto dedicado Google Cloud com links de faturamento ativos. Para provisionamento de projetos ou consultas de lista de permissões, coordene com sua equipe de contas designada. Google Cloud

  • Licenças do Gemini Enterprise: compre licenças do Gemini Enterprise com seu Google Cloud representante de vendas 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 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 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 do ambiente único, 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 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 a 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 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 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

Como 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 ID do projeto: Google Cloud

    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 no 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}"

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

Ativar a API Discovery Engine

O administrador da nuvem precisa ativar a API discoveryengine.googleapis.com para poder fazer interface com os endpoints da API AlphaEvolve on Cloud. O administrador da nuvem pode fazer isso no Google Cloud console ou usando o SDK Google Cloud no host do Linux: gcloud services enable discoveryengine.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 acompanhar 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 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 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 ID do projeto: Google Cloud

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