Este guia demonstra como implementar e gerir aplicações de IA/ML baseadas em agentes em contentores usando o Google Kubernetes Engine (GKE). Ao combinar o Google Agent Development Kit (ADK) com o Vertex AI como fornecedor de modelos de linguagem (conteúdo extenso) (MDIs/CEs), pode operacionalizar agentes de IA de forma eficiente e em grande escala. Este guia explica o processo completo de implementação de um agente baseado no FastAPI com tecnologia do Gemini 2.0 Flash, desde o desenvolvimento à implementação em produção no GKE.
Este guia destina-se a engenheiros de aprendizagem automática (AA), programadores e arquitetos da nuvem interessados em usar capacidades de orquestração de contentores do Kubernetes para publicar aplicações de IA/AA baseadas em agentes. Para saber mais sobre as funções comuns e exemplos de tarefas no conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE Enterprise. Google Cloud
Antes de começar, certifique-se de que conhece o seguinte:
Contexto
Este guia combina várias tecnologias Google para criar uma plataforma escalável para IA autónoma. O GKE fornece a orquestração de contentores para o agente, que é criado através do ADK. Ao usar a API Vertex AI para inferência de MDIs, o cluster do GKE não requer hardware de GPU especializado, porque a inferência é processada pela infraestrutura gerida da Google.
Google Agent Development Kit (ADK)
O Agent Development Kit (ADK) é uma estrutura flexível e modular para desenvolver e implementar agentes de IA. Embora esteja otimizado para o Gemini e o ecossistema Google, o ADK é independente do modelo, da implementação e foi criado para compatibilidade com outros frameworks.
Para mais informações, consulte a documentação do ADK.
Serviço Kubernetes gerido do GKE
O GKE é um serviço Kubernetes gerido para implementar, dimensionar e gerir aplicações contentorizadas. O GKE fornece a infraestrutura necessária, incluindo recursos escaláveis, computação distribuída e redes eficientes, para processar as exigências computacionais dos MDIs.
Para mais informações sobre os principais conceitos do Kubernetes, consulte o artigo Comece a saber mais sobre o Kubernetes. Para mais informações sobre o GKE e como este ajuda a dimensionar, automatizar e gerir o Kubernetes, consulte a vista geral do GKE.
Vertex AI
O Vertex AI é a plataforma de ML unificada da Google Cloud, que permite aos programadores criar, implementar e dimensionar modelos de IA/ML. Google CloudPara aplicações de IA autónomas no GKE, a Vertex AI oferece ferramentas e serviços essenciais, incluindo acesso a MDIs como o Gemini 2.0 Flash, infraestrutura gerida para preparação e inferência, e capacidades de MLOps para uma gestão eficiente do ciclo de vida.
Quando consome MDIs através da API Vertex AI, a inferência de modelos ocorre na infraestrutura gerida pela Google, o que reduz a necessidade de quotas específicas de GPU ou TPU no seu cluster do GKE.
Para mais informações sobre a Vertex AI para aplicações de IA autónomas, consulte a documentação da Vertex AI.
Gemini 2.0 Flash
O Gemini 2.0 Flash oferece funcionalidades de próxima geração e capacidades melhoradas concebidas para cargas de trabalho de agentes, incluindo maior velocidade, utilização de ferramentas incorporadas, geração multimodal e uma capacidade de resposta de 1 milhão de tokens. O Gemini 2.0 Flash melhora o modelo Flash anterior e oferece uma qualidade melhorada a velocidades semelhantes.
Para informações técnicas sobre o Gemini 2.0 Flash (como referências de desempenho, informações sobre os nossos conjuntos de dados de preparação, esforços em termos de sustentabilidade, utilização pretendida e limitações, e a nossa abordagem à ética e segurança), consulte o cartão do modelo do Gemini 2.0 Flash.
Objetivos
Este guia mostra-lhe como fazer o seguinte:
- Configure o seu Google Cloud ambiente.
- Crie uma imagem de contentor para o seu agente.
- Implemente o agente num cluster do GKE.
- Teste o agente implementado.
Custos
Este guia usa os seguintes componentes faturáveis do Google Cloud:
Reveja os preços de cada serviço para compreender os potenciais custos.
Antes de começar
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
Aceder ao IAM - Selecione o projeto.
- Clique em Conceder acesso.
-
No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.
- Na lista Selecionar uma função, selecione uma função.
- Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
- Clique em Guardar.
- Na Google Cloud consola, inicie uma sessão do Cloud Shell e clique em
Ativar Cloud Shell. Esta ação inicia uma sessão no painel inferior da consola do Google Cloud .
Defina as variáveis de ambiente predefinidas:
gcloud config set project PROJECT_ID export GOOGLE_CLOUD_LOCATION=REGION export PROJECT_ID=PROJECT_ID export GOOGLE_CLOUD_PROJECT=$PROJECT_ID export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")
Substitua os seguintes valores:
- PROJECT_ID: o seu Google Cloud ID do projeto.
- REGION: a Google Cloud região (por exemplo,
us-central1
) para aprovisionar o cluster do GKE, o Artifact Registry e outros recursos regionais.
No terminal do Cloud Shell, clone o repositório de código de exemplo do tutorial:
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
Navegue para o diretório de tutoriais:
cd kubernetes-engine-samples/ai-ml/adk-vertex
Crie um cluster do GKE: pode implementar a sua aplicação baseada em agente em contentores num cluster do GKE Autopilot ou Standard. Use um cluster do Autopilot para uma experiência do Kubernetes totalmente gerida. Para escolher o modo de funcionamento do GKE mais adequado às suas cargas de trabalho, consulte o artigo Escolha um modo de funcionamento do GKE.
Piloto automático
No Cloud Shell, execute o seguinte comando:
gcloud container clusters create-auto CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Substitua CLUSTER_NAME pelo nome do cluster do GKE Autopilot.
Standard
No Cloud Shell, execute o seguinte comando:
gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID \ --release-channel=stable \ --num-nodes=1 \ --machine-type=e2-medium \ --workload-pool=$PROJECT_ID.svc.id.goog
Substitua CLUSTER_NAME pelo nome do seu cluster padrão.
Crie um repositório do Artifact Registry para o seu contentor Docker: crie um repositório do Artifact Registry para armazenar e gerir em segurança a imagem do contentor Docker do seu agente. Este registo privado ajuda a garantir que a sua aplicação está prontamente disponível para implementação no GKE e integra-se com o Cloud Build.
gcloud artifacts repositories create adk-repo \ --repository-format=docker \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Obtenha o URL do repositório: execute este comando para validar o caminho completo para o seu repositório. Vai usar este formato de caminho para etiquetar a sua imagem do Docker no passo seguinte.
gcloud artifacts repositories describe adk-repo \ --location $GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Conceda à conta de serviço predefinida do Compute Engine as funções IAM necessárias: Por predefinição, a conta de serviço predefinida do Compute Engine não tem autorizações para enviar imagens para o Artifact Registry nem para ver objetos no Cloud Storage ou registos. Conceda as funções necessárias para estas operações.
ROLES_TO_ASSIGN=( "roles/artifactregistry.writer" "roles/storage.objectViewer" "roles/logging.viewer" ) for ROLE in "${ROLES_TO_ASSIGN[@]}"; do gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ --role="${ROLE}" done
Crie e envie a imagem do contentor do agente: execute este comando para criar a imagem do Docker e enviá-la para o Artifact Registry. Certifique-se de que o Dockerfile e o código da aplicação estão no diretório
/app
.export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest" gcloud builds submit \ --tag "$IMAGE_URL" \ --project="$PROJECT_ID" \ app
Verifique se a imagem foi enviada:
gcloud artifacts docker images list \ $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \ --project=$PROJECT_ID
Inicialize o Terraform: navegue para o diretório
terraform
e inicialize o Terraform.terraform init
Reveja o plano de execução: este comando mostra as alterações à infraestrutura que o Terraform vai fazer.
terraform plan -var-file=default_env.tfvars
Aplique a configuração: execute o plano do Terraform para criar os recursos no seu projeto do Google Cloud. Google Cloud Confirme com
yes
quando lhe for pedido.terraform apply -var-file=default_env.tfvars
Depois de executar estes comandos, o Terraform aprovisiona o cluster do GKE e o repositório do Artifact Registry, e configura as funções do IAM e as contas de serviço necessárias, incluindo a Workload Identity Federation para o GKE.
Crie uma conta de serviço para acesso à Vertex AI:
gcloud iam service-accounts create vertex-sa \ --project=$PROJECT_ID
Conceda à conta de serviço a função
aiplatform.user
. Isto permite que a conta de serviço interaja com o Vertex AI.gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user"
Crie um KSA no seu cluster. Certifique-se de que segue as instruções em Configurar
kubectl
para comunicar com o cluster antes de executar este comando.kubectl create serviceaccount vertex-sa
Anote o KSA para o associar à sua conta de serviço:
kubectl annotate serviceaccount vertex-sa \ iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
Conceda autorizações à sua conta de serviço para atuar como uma federação de identidades da carga de trabalho para o utilizador do GKE para o KSA:
gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"
- Compreenda a estrutura da aplicação do agente: o diretório
/app
contém os ficheiros principais da sua aplicação do agente:main.py
: o ponto de entrada da aplicação FastAPI, responsável por expor a API do agente.agent.py
: contém a lógica do agente ADK, definindo como usa o Vertex AI e processa os pedidos.__init__.py
: inicializa o pacote Python.requirements.txt
: lista todas as dependências do Python para o seu agente.Dockerfile
: define como a sua aplicação é incluída num pacote numa imagem do Docker.
Crie o manifesto de implementação do agente: no diretório
tutorials-and-examples/adk/vertex
, crie o seguinte manifesto como um ficheiro denominadoagent-deployment.yaml
:apiVersion: apps/v1 kind: Deployment metadata: name: adk-agent-deployment labels: app: adk-agent spec: replicas: 1 selector: matchLabels: app: adk-agent template: metadata: labels: app: adk-agent spec: serviceAccountName: vertex-sa containers: - name: adk-agent image: IMAGE_URL ports: - containerPort: 8000 env: - name: GOOGLE_CLOUD_PROJECT_ID value: PROJECT_ID - name: GOOGLE_CLOUD_LOCATION value: REGION - name: GOOGLE_GENAI_USE_VERTEXAI value: "1" - name: PORT value: "8000" resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "1Gi" cpu: "1"
Substitua os seguintes valores:
- IMAGE_URL: o URL completo da imagem Docker que enviou para o
Artifact Registry (por exemplo,
us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest
). Pode obter este valor a partir do resultado do comandogcloud artifacts docker images list
na secção anterior. Em alternativa, execute um comando como o seguinte:sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml
. - PROJECT_ID: o ID do seu Google Cloud projeto.
- REGION: a Google Cloud região onde o cluster do GKE é aprovisionado.
- IMAGE_URL: o URL completo da imagem Docker que enviou para o
Artifact Registry (por exemplo,
Aplique o manifesto de implementação:
kubectl apply -f agent-deployment.yaml
Este comando cria a implementação e os pods associados para a sua aplicação de agente no cluster do GKE.
Exponha o agente: pode usar estes métodos para expor o seu agente para acesso.
- Para aceder ao seu agente a partir do exterior do cluster, crie um serviço Kubernetes.
Para uma API Web, um serviço do tipo
LoadBalancer
é comum. Para o desenvolvimento e os testes locais, use o comando
kubectl port-forward
para aceder diretamente ao seu agente.
LoadBalancer
Crie o seguinte manifesto como um ficheiro denominado
agent-service.yaml
:apiVersion: v1 kind: Service metadata: name: adk-agent-service spec: selector: app: adk-agent type: LoadBalancer # Creates an external IP address for access ports: - protocol: TCP port: 80 targetPort: 8000 # Matches the containerPort exposed in the Deployment
Aplique o manifesto:
kubectl apply -f agent-service.yaml
O aprovisionamento do endereço IP externo pode demorar alguns minutos.
Verifique se o endereço IP está aprovisionado:
kubectl get service adk-agent-service
Procure o valor
EXTERNAL-IP
no resultado. Depois de o valor estar disponível, use este endereço IP para interagir com o agente implementado.
port-forward
Se usar principalmente
port-forward
, considere usar umClusterIP
tipo de serviço em vez deLoadBalancer
, uma vez que oClusterIP
serviço é interno e consome menos recursos.POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}') kubectl port-forward $POD_NAME 8000:8000
Este comando bloqueia o seu terminal, mas encaminha o tráfego de
localhost:8000
na sua máquina para o agente em execução no cluster do GKE.- Para aceder ao seu agente a partir do exterior do cluster, crie um serviço Kubernetes.
Para uma API Web, um serviço do tipo
Identifique o ponto final do agente: consoante a forma como optou por expor o seu agente na secção anterior, identifique o respetivo ponto final acessível:
LoadBalancer
Recupere o endereço IP externo:
kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
Armazene o endereço IP externo numa variável de ambiente para facilitar a utilização:
export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
O URL base do seu agente é
http://${AGENT_IP}
.
port-forward
Certifique-se de que o comando
kubectl port-forward
é executado num terminal separado. O URL base do seu agente éhttp://localhost:8000
.Teste a API do agente: teste a API do agente fazendo um pedido curl ao respetivo ponto final
/run
. O agente espera um payload JSON com um campo de mensagem. Substitua AGENT_BASE_URL porhttp://${AGENT_IP}
(para LoadBalancer) ouhttp://localhost:8000
(para encaminhamento de portas).Crie uma nova sessão. Esta ação prepara o agente para uma nova conversa.
# The user ID and session ID are arbitrary. # The appName must match the agent's Python package directory name (in this case, "capital-agent"). curl -X POST AGENT_BASE_URL/apps/capital-agent/users/user-123/sessions/session-123
Pode apresentar uma lista das apps disponíveis com o seguinte comando:
curl -X GET AGENT_BASE_URL/list-apps
Envie uma consulta ao agente através dos detalhes da sessão do passo anterior.
curl -X POST AGENT_BASE_URL/run \ -H "Content-Type: application/json" \ -d '{ "appName": "capital-agent", "userId": "user-123", "sessionId": "session-123", "newMessage": { "role": "user", "parts": [{ "text": "Hello, agent! What can you do for me?" }] } }'
Deve receber uma resposta JSON do seu agente, a indicar que processa pedidos com êxito e interage com o modelo Gemini através do Vertex AI. A resposta contém a resposta gerada do agente com base na sua mensagem.
Aceda à IU Web do agente (se aplicável): se o seu agente incluir uma interface do utilizador baseada na Web, aceda à mesma navegando para o seu AGENT_BASE_URL num navegador de Internet. Normalmente, o ADK inclui uma IU Web básica para interação e depuração. Por exemplo, se expôs o seu agente através de um LoadBalancer e o respetivo
EXTERNAL-IP
for34.123.45.67
, navegue parahttp://34.123.45.67
no seu navegador.No terminal do Cloud Shell, navegue para o diretório
tutorials-and-examples/adk/vertex/
:cd tutorials-and-examples/adk/vertex/
Execute este comando para remover todos os recursos definidos nos seus ficheiros de configuração do Terraform.
cd terraform terraform destroy
- Saiba como configurar o Horizontal Pod Autoscaler (HPA) para ajustar automaticamente os recursos do seu agente a pedido.
- Saiba como configurar o Identity-Aware Proxy (IAP) para as suas aplicações Web em execução noGoogle Cloud, fornecendo autorização centralizada para o acesso à IU do seu agente.
- Saiba como usar o Cloud Logging e o Cloud Monitoring para obter estatísticas sobre o desempenho e o estado do seu agente no cluster do GKE.
- Explore exemplos experimentais no GKE AI Labs que podem ajudar a usar o GKE para acelerar as suas iniciativas de IA baseadas em agentes.
Prepare o ambiente
Este tutorial usa a Cloud Shell para gerir recursos alojados no Google Cloud. O Cloud Shell vem pré-instalado com o software de que precisa para este tutorial, incluindo
kubectl
,terraform
e oGoogle Cloud CLI
.Para configurar o seu ambiente com o Cloud Shell, siga estes passos:
Clone o projeto de exemplo
Crie e configure Google Cloud recursos
Para implementar o seu agente no GKE, aprovisione osGoogle Cloud recursos necessários. Pode implementar o agente através da CLI gcloud para execução direta na linha de comandos ou do Terraform para infraestrutura como código.
gcloud
Esta secção fornece comandos da CLI gcloud para configurar o cluster do GKE, o Artifact Registry e a Workload Identity Federation para o GKE para uma integração perfeita com o Vertex AI. Certifique-se de que definiu as variáveis de ambiente conforme descrito em Prepare o ambiente.
Terraform
Esta secção descreve como usar o Terraform para aprovisionar os seus Google Cloud recursos. O repositório de exemplo que clonou inclui os ficheiros de configuração do Terraform necessários.
Para saber mais sobre a utilização do Terraform, consulte o apoio técnico do Terraform para o GKE.
Configure o
kubectl
para comunicar com o seu clusterSe não configurou o
kubectl
para comunicar com o cluster, execute o seguinte comando:gcloud container clusters get-credentials CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION}
Substitua CLUSTER_NAME pelo nome do seu cluster do GKE.
Configure a Workload Identity Federation para acesso ao GKE
Pode ignorar este passo se estiver a usar o Terraform. Este processo associa uma conta de serviço do Kubernetes (KSA) a uma conta de serviço do IAM para conceder ao seu agente acesso seguro aos serviços Google Cloud .
Implemente e configure a aplicação do agente
Depois de configurar os Google Cloud recursos, prepare a aplicação do agente para a implementação e configure o respetivo tempo de execução no GKE. Isto envolve definir o código do seu agente, criar um Dockerfile para o colocar num contentor e escrever um manifesto do Kubernetes para o implementar no seu cluster.
Teste o agente implementado
Agora que a sua aplicação de agente está implementada e exposta, teste a respetiva funcionalidade.
Esta secção descreve como identificar o ponto final do seu agente e testar a API do agente.
Limpar
Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.
Elimine os recursos implementados
Para evitar incorrer em custos na sua Google Cloud conta pelos recursos que criou neste guia, execute os seguintes comandos:
gcloud
gcloud container clusters delete CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION} \ --project=$PROJECT_ID gcloud projects remove-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user" gcloud iam service-accounts delete vertex-sa@$PROJECT_ID.iam.gserviceaccount.com gcloud artifacts repositories delete adk-repo \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Substitua CLUSTER_NAME pelo nome do seu cluster do GKE.
Terraform
O que se segue?
-