Esta página foi traduzida pela API Cloud Translation.

Implemente uma aplicação de IA com agentes no GKE com o Agent Development Kit (ADK) e um LLM autoalojado

Este tutorial demonstra como implementar e gerir aplicações de IA/ML baseadas em agentes em contentores usando o Google Kubernetes Engine (GKE). Ao combinar o Agent Development Kit (ADK) da Google com um modelo de linguagem (conteúdo extenso) (MDL/CE) autoalojado, como o Llama 3.1, publicado pelo vLLM, pode operacionalizar agentes de IA de forma eficiente e em grande escala, mantendo o controlo total sobre a pilha de modelos. Este tutorial explica o processo completo de implementação de um agente baseado em Python, desde o desenvolvimento à implementação em produção num cluster do GKE Autopilot com aceleração de GPU.

Este tutorial destina-se a engenheiros de aprendizagem automática, programadores e arquitetos da nuvem interessados em usar as 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 as tarefas de exemplo a que fazemos referência no Google Cloud conteúdo, consulte o artigo Funções e tarefas de utilizador comuns do GKE Enterprise.

Antes de começar, certifique-se de que conhece o seguinte:

Contexto

Esta secção descreve as principais tecnologias usadas neste tutorial.

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 não requer que use um modelo ou uma implementação específicos e foi criado para ser compatível com outras frameworks. O ADK foi concebido para que o desenvolvimento de agentes se assemelhe mais ao desenvolvimento de software, de modo a facilitar a criação, a implementação e a orquestração de arquiteturas de agentes que vão desde tarefas básicas a fluxos de trabalho complexos.

Para mais informações, consulte a documentação do ADK.

Serviço Kubernetes gerido do GKE

Google Cloud oferece uma variedade de serviços, incluindo o GKE, que é adequado para implementar e gerir cargas de trabalho de IA/AA. O GKE é um serviço Kubernetes gerido que simplifica a implementação, o dimensionamento e a gestão de 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.

vLLM

O vLLM é uma framework de publicação de LLMs de código aberto altamente otimizada que pode aumentar a taxa de transferência de publicação em GPUs, com funcionalidades como as seguintes:

Implementação do transformador otimizada com PagedAttention.
Processamento em lote contínuo para melhorar o débito geral da publicação.
Paralelismo de tensores e serviço distribuído em várias GPUs.

Para mais informações, consulte a documentação do vLLM.

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 o Google Cloud CLI.

Para configurar o seu ambiente com o Cloud Shell, siga estes passos:

Na Google Cloud consola, inicie uma sessão do Cloud Shell e clique em Ativar Cloud Shell. Esta ação inicia uma sessão num painel da consola Google Cloud .
Defina as variáveis de ambiente predefinidas:
```
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
Substitua os seguintes valores:
- PROJECT_ID: o seu Google Cloud ID do projeto.
- REGION: a Google Cloud região (por exemplo, us-east4) para aprovisionar o seu cluster do GKE, o Artifact Registry e outros recursos regionais. Certifique-se de que especifica uma região que suporte instâncias de tipo de máquina G2 e GPUs L4. Para verificar a disponibilidade nas regiões, consulte o artigo Regiões e zonas de GPU na documentação do Compute Engine.

Clone o projeto de exemplo

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-vllm

Crie e configure Google Cloud recursos

Para implementar o seu agente, primeiro tem de aprovisionar os recursos Google Cloud necessários. Pode criar o cluster do GKE e o repositório do Artifact Registry através da CLI gcloud ou do Terraform.

gcloud

Esta secção fornece comandos da CLI gcloud para configurar o cluster do GKE e o Artifact Registry.

Crie um cluster do GKE: pode implementar a sua aplicação com agente contentorizada 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 Acerca dos modos de funcionamento do GKE.
Piloto automático
No Cloud Shell, execute o seguinte comando:
```
gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION
```
Substitua CLUSTER_NAME pelo nome do seu cluster do GKE.

Com o Autopilot, o GKE aprovisiona automaticamente nós com base nas solicitações de recursos da sua carga de trabalho. A GPU necessária para o MDG é pedida no deploy-llm.yamlmanifesto através de um nodeSelector.

Para adicionar um pedido nodeSelector para a GPU nvidia-l4, siga estes passos:
1. Abra kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml num editor.
2. Adicione o seguinte nodeSelector em spec.template.spec:
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Standard
1. No Cloud Shell, crie um cluster padrão executando o seguinte comando:
  gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
  Substitua CLUSTER_NAME pelo nome do cluster do GKE.
2. Crie um node pool com GPU para o seu cluster executando o seguinte comando:
  gcloud container node-pools create gpu-node-pool \ --cluster=CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION \ --machine-type=g2-standard-8 \ --accelerator=type=nvidia-l4,count=1 \ --enable-gvnic
  O ficheiro deploy-llm.yaml especifica uma GPU nvidia-l4, que está disponível na série de máquinas G2. Para mais informações sobre este tipo de máquina, consulte o artigo Tipos de máquinas com GPU na documentação do Compute Engine.
Crie um repositório do Artifact Registry: crie um repositório do Artifact Registry para armazenar e gerir em segurança a imagem de contentor Docker do seu agente.
```
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION
```
Substitua REPO_NAME pelo nome do repositório do Artifact Registry que quer usar (por exemplo, adk-repo).
Obtenha o URL do repositório: para validar o caminho completo para o seu repositório, execute este comando. Vai usar este formato para etiquetar a sua imagem do Docker quando criar a imagem do agente.
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

Esta secção descreve como usar a configuração do Terraform incluída no repositório de exemplo para aprovisionar automaticamente os seus recursos Google Cloud .

Navegue para o diretório do Terraform: o diretório \terraform contém todos os ficheiros de configuração necessários para criar o cluster do GKE e outros recursos necessários.
```
cd terraform
```
Crie um ficheiro de variáveis do Terraform: copie o ficheiro de variáveis de exemplo fornecido (example_vars.tfvars) para criar o seu próprio ficheiro vars.tfvars.
```
cp example_vars.tfvars vars.tfvars
```
Abra o ficheiro vars.tfvars num editor e substitua os valores dos marcadores de posição pela sua configuração específica. No mínimo, tem de substituir PROJECT_ID pelo Google Cloud ID do projetoCLUSTER_NAME e pelo nome do cluster do GKE.
Inicialize o Terraform: para transferir os plug-ins do fornecedor necessários para o Google Cloud, execute este comando.
```
terraform init
```
Reveja o plano de execução: este comando mostra as alterações à infraestrutura que o Terraform vai fazer.
```
terraform plan -var-file=vars.tfvars
```
Aplique a configuração: para criar os recursos no seu projeto do Google Cloud , execute o plano do Terraform. Confirme com yes quando lhe for pedido.
```
terraform apply -var-file=vars.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.

Para saber mais sobre a utilização do Terraform, consulte o artigo Aprovisione recursos do GKE com o Terraform.

Configure o `kubectl` para comunicar com o seu cluster

Para configurar o kubectl para comunicar com o seu cluster, execute o seguinte comando:

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_REGION}

Substitua CLUSTER_NAME pelo nome do seu cluster do GKE.

Crie a imagem do agente

Depois de criar a infraestrutura com a CLI gcloud ou o Terraform, siga estes passos para criar a aplicação do agente.

Conceda a função do IAM necessária para o Cloud Build: o serviço Cloud Build requer autorizações para enviar a imagem do contentor do agente para o Artifact Registry. Conceda a função roles/artifactregistry.writer à conta de serviço predefinida do Compute Engine, que é usada pelo Cloud Build.
1. Construa o email para a conta de serviço predefinida do Compute Engine:
```
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
```
2. Conceda a função roles/artifactregistry.writer à conta de serviço:
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
Crie e envie a imagem do contentor do agente: no diretório raiz do projeto (adk/llama/vllm), crie a imagem do Docker e envie-a para o Artifact Registry executando estes comandos.
```
export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL
```
Verifique se a imagem foi enviada: após a conclusão bem-sucedida do processo de compilação, verifique se a imagem do contentor do agente foi enviada para o Artifact Registry listando as imagens no seu repositório.
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
Deverá ver um resultado que apresenta a imagem que acabou de enviar por push e etiquetada como latest.

Implemente o modelo

Depois de configurar o cluster do GKE e criar a imagem do agente, o passo seguinte é implementar o modelo Llama 3.1 alojado por si no cluster. Para o fazer, implemente um servidor de inferência vLLM pré-configurado que extrai o modelo do Hugging Face e o publica internamente no cluster.

Crie um segredo do Kubernetes para as credenciais do Hugging Face: para permitir que o cluster do GKE transfira o modelo Llama 3.1 restrito, tem de fornecer o seu token do Hugging Face como um segredo do Kubernetes. O manifesto do deploy-llm.yaml está configurado para usar este segredo para autenticação.
```
kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
```
Substitua HUGGING_FACE_TOKEN pelo seu token.
Ver o manifesto: no diretório raiz do projeto (adk/llama/vllm), navegue para o diretório /deploy-llm que contém o manifesto de implementação do modelo.
```
cd deploy-llm
```
Aplique o manifesto: execute o seguinte comando para aplicar o deploy-llm.yaml manifesto ao seu cluster.
```
kubectl apply -f deploy-llm.yaml
```
O comando cria três recursos do Kubernetes:
- Uma implementação que executa o servidor vLLM, configurado para usar o modelo meta-llama/Llama-3.1-8B-Instruct.
- Um serviço denominado vllm-llama3-service que expõe o servidor vLLM num endereço IP do cluster interno, o que permite que o agente do ADK comunique com ele.
- Um ConfigMap que contém um modelo de chat Jinja exigido pelo modelo Llama 3.1.
Valide a implementação do modelo: o servidor vLLM extrai os ficheiros do modelo do Hugging Face. Este processo pode demorar vários minutos. Pode monitorizar o estado do Pod para garantir que está pronto.
1. Aguarde até que a implementação fique disponível.
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. Veja os registos do pod em execução para confirmar que o servidor foi iniciado com êxito.
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  A implementação está pronta quando vir um resultado do registo semelhante ao seguinte, o que indica que o servidor do MDG foi iniciado e que as rotas da API estão disponíveis:
```
INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```
3. Envie um pedido diretamente para o servidor do modelo para confirmar que o MDL está pronto. Para tal, abra um novo terminal do Cloud Shell e execute o seguinte comando para encaminhar a porta vllm-llama3-service para a sua máquina local:
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. Noutro terminal, envie um pedido de exemplo para o ponto final da API do modelo usando curl. Por exemplo:
```
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'
```
  Se o comando devolver uma resposta JSON bem-sucedida, o seu MDG está pronto. Já pode terminar o processo de encaminhamento de portas regressando à respetiva janela do terminal e premindo Ctrl+C. Em seguida, avance para a implementação do agente.

Implemente a aplicação do agente

O passo seguinte é implementar a aplicação do agente baseada no ADK.

Navegue para o diretório /deploy-agent: no diretório raiz do projeto (adk/llama/vllm), navegue para o diretório /deploy-agent que contém o código-fonte e o manifesto de implementação do agente.
```
cd ../deploy-agent
```
Atualize o manifesto de implementação do agente:
1. O ficheiro de manifesto de exemplo deploy-agent.yaml contém um marcador de posição para o ID do projeto no URL da imagem do contentor. Tem de substituir o marcador de posição pelo seu Google Cloud ID do projeto.
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  Para realizar esta substituição no local, pode executar o seguinte comando:
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. Certifique-se de que o caminho readinessProbe está definido como / em vez de /dev-ui. Para realizar esta substituição no local, pode executar o seguinte comando:
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
Aplique o manifesto: execute o seguinte comando para aplicar o deploy-agent.yaml manifesto ao seu cluster.
```
kubectl apply -f deploy-agent.yaml
```
Este comando cria dois recursos do Kubernetes:
- Uma implementação denominada adk-agent que executa a imagem do contentor do agente criado por si.
- Um serviço denominado adk-agent do tipo NodePort que expõe a aplicação do agente para que possa ser acedida para testes.
Valide a implementação do agente: verifique o estado do pod para garantir que está a ser executado corretamente.
1. Aguarde até que a implementação fique disponível:
```
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
```
2. Veja os registos do pod do agente em execução:
```
export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD
```

A implementação é bem-sucedida quando vê um resultado do registo semelhante ao seguinte, indicando que o servidor Uvicorn está em execução e pronto para aceitar pedidos:

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Teste o agente implementado

Depois de implementar com êxito o servidor vLLM e a aplicação do agente, pode testar a funcionalidade integral interagindo com a IU Web do agente.

Encaminhe o serviço do agente para a sua máquina local: o serviço é do tipo NodePort, mas a forma mais direta de aceder ao mesmo a partir do seu ambiente do Cloud Shell é usar o comando kubectl port-forward.adk-agent Execute este comando para criar um túnel seguro para o pod do agente.
```
kubectl port-forward $AGENT_POD 8001:8001
```
Aceda à IU Web do agente: no Cloud Shell, clique no botão Pré-visualização Web e selecione Pré-visualizar na porta 8001. É aberto um novo separador do navegador que apresenta a interface de chat do agente.
Interagir com o agente: faça uma pergunta ao agente que invoque a respetiva ferramenta get_weather. Por exemplo:
```
What's the weather like in Tokyo?
```
Primeiro, o agente chama o MDG para compreender a intenção e identificar a necessidade de usar a ferramenta get_weather. Em seguida, executa a ferramenta com "Tóquio" como parâmetro. Por último, usa o resultado da ferramenta para gerar uma resposta. Deve ver uma resposta semelhante à seguinte:
```
  The weather in Tokyo is 25°C and sunny.
```
(Opcional) Valide a chamada de ferramenta nos registos: pode observar a interação do agente com o MDG e a execução da ferramenta através da visualização dos registos dos respetivos pods.
1. Registos do Agent Pod: num novo terminal, veja os registos do pod adk-agent. Vê a chamada de ferramenta e o respetivo resultado.
```
kubectl logs -f $AGENT_POD
```
  O resultado mostra a ferramenta que está a ser chamada e o resultado que está a ser processado.
2. Registos do LLM Pod: veja os registos do vllm-llama3-deployment Pod para ver o pedido recebido do agente.
```
kubectl logs -f $LLM_POD
```
  Os registos mostram o comando completo enviado pelo agente ao MDG, incluindo a mensagem do sistema, a sua consulta e a definição da ferramenta get_weather.

Depois de terminar os testes, pode terminar o processo port-forward regressando à respetiva janela do terminal e premindo Ctrl+C.