Esta página foi traduzida pela API Cloud Translation.

Implantar um aplicativo de IA com agentes no GKE usando o Kit de Desenvolvimento de Agente (ADK) e um LLM autohospedado

Neste tutorial, mostramos como implantar e gerenciar aplicativos de IA/ML em contêineres usando o Google Kubernetes Engine (GKE). Ao combinar o Google Agent Development Kit (ADK) com um modelo de linguagem grande (LLM) auto-hospedado, como o Llama 3.1 veiculado pelo vLLM, é possível operacionalizar agentes de IA de maneira eficiente e em escala, mantendo o controle total sobre a pilha de modelos. Este tutorial mostra o processo completo de levar um agente baseado em Python do desenvolvimento para a implantação em produção em um cluster do GKE Autopilot com aceleração de GPU.

Este tutorial é destinado a engenheiros de machine learning (ML), desenvolvedores e arquitetos de nuvem interessados em usar os recursos de orquestração de contêineres do Kubernetes para veiculação de aplicativos de IA/ML com agentes. Para saber mais sobre papéis comuns e tarefas de exemplo que mencionamos no conteúdo do Google Cloud, consulte Tarefas e funções de usuário comuns do GKE Enterprise.

Antes de começar, confira se você tem familiaridade com o seguinte:

Contexto

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

Kit de Desenvolvimento de Agente (ADK)

O Agent Development Kit (ADK) é um framework flexível e modular para desenvolver e implantar agentes de IA. Embora seja otimizado para o Gemini e o ecossistema do Google, o ADK não exige que você use um modelo ou implantação específica e foi criado para ser compatível com outras estruturas. O ADK foi projetado para que o desenvolvimento de agentes pareça mais com o desenvolvimento de software, facilitando a criação, a implantação e a organização de arquiteturas de agentes que variam de tarefas básicas a fluxos de trabalho complexos.

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

Serviço gerenciado do Kubernetes do GKE

OGoogle Cloud oferece uma variedade de serviços, incluindo o GKE, que é adequado para implantação e gerenciamento de cargas de trabalho de IA/ML. O GKE é um serviço gerenciado do Kubernetes que simplifica a implantação, o escalonamento e o gerenciamento de aplicativos conteinerizados. O GKE oferece a infraestrutura necessária, incluindo recursos escalonáveis, computação distribuída e rede eficiente, para lidar com as demandas computacionais dos LLMs.

Para mais informações sobre os principais conceitos do Kubernetes, consulte Começar a aprender sobre o Kubernetes. Para mais informações sobre o GKE e como ele ajuda você a escalonar, automatizar e gerenciar o Kubernetes, consulte a visão geral do GKE.

vLLM

O vLLM é um framework de exibição de LLM de código aberto altamente otimizado que pode aumentar a capacidade de exibição em GPUs, com recursos como:

Otimização da implementação do transformador com PagedAttention.
Lotes contínuos para melhorar a capacidade geral de exibição.
Paralelismo de tensor e exibição distribuída em várias GPUs.

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

Prepare o ambiente

Neste tutorial, usamos o Cloud Shell para gerenciar recursos hospedados no Google Cloud. O Cloud Shell vem pré-instalado com o software necessário para este tutorial, incluindo kubectl, terraform e Google Cloud CLI.

Para configurar o ambiente com o Cloud Shell, siga estas etapas:

No console do Google Cloud , inicie uma sessão do Cloud Shell e clique em Ativar o Cloud Shell. Essa ação inicia uma sessão em um painel do console Google Cloud .
Defina as variáveis de ambiente padrão:
```
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
Substitua os seguintes valores:
- PROJECT_ID: o Google Cloud ID do projeto.
- REGION: a Google Cloud região (por exemplo, us-east4) para provisionar o cluster do GKE, o Artifact Registry e outros recursos regionais. Especifique uma região que seja compatível com GPUs L4 e instâncias do tipo de máquina G2. Para verificar a disponibilidade de regiões, consulte Regiões e zonas de GPU na documentação do Compute Engine.

Clonar o projeto de exemplo

No terminal do Cloud Shell, clone o repositório de exemplo de código do tutorial:
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
```

Navegue até o diretório do tutorial:

cd kubernetes-engine-samples/ai-ml/adk-vllm

Criar e configurar recursos Google Cloud

Para implantar o agente, primeiro provisione os recursos necessários do Google Cloud. É possível criar o cluster do GKE e o repositório do Artifact Registry usando a CLI gcloud ou o Terraform.

gcloud

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

Crie um cluster do GKE: é possível implantar seu aplicativo de agente em contêineres em um cluster do GKE Autopilot ou Standard. Use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Sobre os modos de operação do GKE.
Piloto automático
No Cloud Shell, execute este comando:
```
gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION
```
Substitua CLUSTER_NAME pelo nome do cluster do GKE.

Com o Autopilot, o GKE provisiona automaticamente nós com base nas solicitações de recursos da sua carga de trabalho. A GPU necessária para o LLM é solicitada no manifesto deploy-llm.yaml usando um nodeSelector.

Para adicionar uma solicitação nodeSelector à GPU nvidia-l4, siga estas etapas:
1. Abra kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml em um editor.
2. Adicione o seguinte nodeSelector em spec.template.spec:
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Padrão
1. No Cloud Shell, crie um cluster Standard 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 pool de nós compatível com GPU para 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 arquivo deploy-llm.yaml especifica uma GPU nvidia-l4, que está disponível na série de máquinas G2. Para mais informações sobre esse tipo de máquina, consulte 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 gerenciar com segurança a imagem do contêiner 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 você quer usar (por exemplo, adk-repo).
Receber o URL do repositório: para verificar o caminho completo do seu repositório, execute este comando. Você vai usar esse formato para marcar a imagem do Docker ao criar a imagem do agente.
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

Nesta seção, descrevemos como usar a configuração do Terraform incluída no repositório de exemplo para provisionar seus recursos do Google Cloud automaticamente.

Acesse o diretório do Terraform: o diretório \terraform contém todos os arquivos de configuração necessários para criar o cluster do GKE e outros recursos necessários.
```
cd terraform
```
Crie um arquivo de variáveis do Terraform: copie o exemplo de arquivo de variáveis (example_vars.tfvars) para criar seu próprio arquivo vars.tfvars.
```
cp example_vars.tfvars vars.tfvars
```
Abra o arquivo vars.tfvars em um editor e substitua os valores de marcador de posição pela sua configuração específica. No mínimo, substitua PROJECT_ID pelo ID do projeto Google Cloud e CLUSTER_NAME pelo nome do cluster do GKE.
Inicialize o Terraform: para fazer o download dos plug-ins de provedor necessários para Google Cloud, execute este comando.
```
terraform init
```
Analise o plano de execução: esse comando mostra as mudanças na infraestrutura que o Terraform vai fazer.
```
terraform plan -var-file=vars.tfvars
```
Aplique a configuração: para criar os recursos no projeto Google Cloud , execute o plano do Terraform. Confirme com yes quando solicitado.
```
terraform apply -var-file=vars.tfvars
```

Depois de executar esses comandos, o Terraform provisiona o cluster do GKE e o repositório do Artifact Registry e configura as funções e contas de serviço necessárias do IAM, incluindo a Federação de Identidade da Carga de Trabalho para GKE.

Para saber mais sobre como usar o Terraform, consulte Provisionar recursos do GKE com o Terraform.

Configure `kubectl` para se comunicar com o cluster

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

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

Substitua CLUSTER_NAME pelo nome do cluster do GKE.

Criar a imagem do agente

Depois de criar a infraestrutura usando CLI gcloud ou o Terraform, siga estas etapas para criar o aplicativo do agente.

Conceda o papel do IAM necessário para o Cloud Build: o serviço do Cloud Build requer permissões para enviar a imagem do contêiner do agente ao Artifact Registry. Conceda o papel roles/artifactregistry.writer à conta de serviço padrão do Compute Engine, que é usada pelo Cloud Build.
1. Crie o e-mail para a conta de serviço padrão 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 ela o papel roles/artifactregistry.writer:
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
Crie e envie a imagem do contêiner do agente: no diretório raiz do projeto (adk/llama/vllm), crie a imagem do Docker e envie-a ao 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: depois que o processo de build for concluído, verifique se a imagem do contêiner do seu agente foi enviada para o Artifact Registry listando as imagens no repositório.
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
Você vai ver uma saída que lista a imagem que acabou de enviar e marcou como latest.

Implantar o modelo

Depois de configurar o cluster do GKE e criar a imagem do agente, a próxima etapa é implantar o modelo Llama 3.1 autohospedado no cluster. Para fazer isso, implante um servidor de inferência vLLM pré-configurado que extrai o modelo da Hugging Face e o disponibiliza internamente no cluster.

Crie um secret do Kubernetes para as credenciais do Hugging Face: para permitir que o cluster do GKE faça o download do modelo Llama 3.1 restrito, forneça seu token do Hugging Face como um secret do Kubernetes. O manifesto deploy-llm.yaml está configurado para usar esse secret na 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 até o diretório /deploy-llm que contém o manifesto de implantação do modelo.
```
cd deploy-llm
```
Aplique o manifesto: execute o comando a seguir para aplicar o manifesto deploy-llm.yaml ao cluster.
```
kubectl apply -f deploy-llm.yaml
```
O comando cria três recursos do Kubernetes:
- Uma implantação que executa o servidor vLLM, configurado para usar o modelo meta-llama/Llama-3.1-8B-Instruct.
- Um serviço chamado vllm-llama3-service que expõe o servidor vLLM em um endereço IP interno do cluster, permitindo que o agente do ADK se comunique com ele.
- Um ConfigMap que contém um modelo de chat Jinja exigido pelo modelo Llama 3.1.
Verifique a implantação do modelo: o servidor vLLM extrai os arquivos do modelo do Hugging Face. Esse processo pode levar vários minutos. Você pode monitorar o status do pod para garantir que ele esteja pronto.
1. Aguarde até que a implantação esteja disponível.
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. Confira os registros do pod em execução para confirmar se o servidor foi iniciado com sucesso.
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  A implantação estará pronta quando você vir uma saída de registro semelhante a esta, indicando que o servidor de LLM foi iniciado e as rotas de 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 uma solicitação diretamente ao servidor do modelo para confirmar que o LLM está pronto. Para fazer isso, abra um novo terminal do Cloud Shell e execute o seguinte comando para encaminhar o vllm-llama3-service para sua máquina local:
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. Em outro terminal, envie uma solicitação de amostra ao endpoint de API do modelo usando curl. 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 retornar uma resposta JSON bem-sucedida, seu LLM estará pronto. Agora, encerre o processo de encaminhamento de porta voltando à janela do terminal e pressionando Ctrl+C. Em seguida, implante o agente.

Implantar o aplicativo do agente

A próxima etapa é implantar o aplicativo de agente baseado no ADK.

Navegue até o diretório /deploy-agent: no diretório raiz do projeto (adk/llama/vllm), navegue até o diretório /deploy-agent que contém o código-fonte do agente e o manifesto de implantação.
```
cd ../deploy-agent
```
Atualize o manifesto de implantação do agente:
1. O arquivo de manifesto deploy-agent.yaml de exemplo contém um marcador de posição para o ID do projeto no URL da imagem do contêiner. Substitua o marcador de posição pelo ID do seu projeto do Google Cloud .
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  Para fazer essa substituição no lugar, execute o seguinte comando:
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. Verifique se o caminho readinessProbe está definido como / em vez de /dev-ui. Para fazer essa substituição no lugar, execute o seguinte comando:
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
Aplique o manifesto: execute o comando a seguir para aplicar o manifesto deploy-agent.yaml ao cluster.
```
kubectl apply -f deploy-agent.yaml
```
Esse comando cria dois recursos do Kubernetes:
- Uma implantação chamada adk-agent que executa a imagem do contêiner do agente criado de forma personalizada.
- Um serviço chamado adk-agent do tipo NodePort que expõe o aplicativo do agente para que ele possa ser acessado para testes.
Verifique a implantação do agente: confira o status do pod para garantir que ele esteja sendo executado corretamente.
1. Aguarde até que a implantação esteja disponível:
```
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
```
2. Confira os registros 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 implantação será bem-sucedida quando você vir uma saída de registro semelhante a esta, indicando que o servidor Uvicorn está em execução e pronto para aceitar solicitações:

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

Testar o agente implantado

Depois de implantar o servidor vLLM e o aplicativo do agente, teste a funcionalidade de ponta a ponta interagindo com a UI da Web do agente.

Encaminhe o serviço do agente para sua máquina local: o serviço adk-agent é do tipo NodePort, mas a maneira mais direta de acessá-lo no ambiente do Cloud Shell é usar o comando kubectl port-forward. Execute este comando para criar um túnel seguro para o pod do agente.
```
kubectl port-forward $AGENT_POD 8001:8001
```
Acessar a interface da Web do agente: no Cloud Shell, clique no botão Visualização da Web e selecione Visualizar na porta 8001. Uma nova guia do navegador será aberta, mostrando a interface de chat do agente.
Interaja com o agente: faça uma pergunta que invoque a ferramenta get_weather. Exemplo:
```
What's the weather like in Tokyo?
```
Primeiro, o agente vai chamar o LLM para entender a intenção e identificar a necessidade de usar a ferramenta get_weather. Em seguida, ele vai executar a ferramenta com "Tóquio" como parâmetro. Por fim, ele vai usar a saída da ferramenta para gerar uma resposta. Uma resposta semelhante a esta vai aparecer:
```
  The weather in Tokyo is 25°C and sunny.
```
(Opcional) Verifique a chamada de ferramenta nos registros: é possível observar a interação do agente com o LLM e a execução da ferramenta ao visualizar os registros dos pods respectivos.
1. Registros do pod do agente: em um novo terminal, confira os registros do pod adk-agent. Você vai ver a chamada de função e o resultado dela.
```
kubectl logs -f $AGENT_POD
```
  A saída mostra a ferramenta sendo chamada e o resultado sendo processado.
2. Registros do pod de LLM: veja os registros do pod vllm-llama3-deployment para conferir a solicitação recebida do agente.
```
kubectl logs -f $LLM_POD
```
  Os registros mostram o comando completo enviado pelo agente ao LLM, incluindo a mensagem do sistema, sua consulta e a definição da ferramenta get_weather.

Depois de concluir o teste, encerre o processo port-forward voltando à janela do terminal e pressionando Ctrl+C.