1. Introdução
Visão geral
Neste laboratório, você vai implantar um agente do Kit de Desenvolvimento de Agente (ADK) pronto para produção com um back-end do Gemma acelerado por GPU. O foco está nos padrões de implantação críticos: configuração de serviços do Cloud Run habilitados para GPU, integração de back-ends de modelos com agentes do ADK e observação do comportamento de escalonamento automático sob carga.
Atividades deste laboratório
Neste laboratório, você vai se concentrar nos aspectos críticos da implantação de produção:
- Implantar o Gemma no Cloud Run com GPU: configurar um back-end de modelo do Gemma de alta performance
- Integrar a implantação do Gemma a um agente do ADK: conecte seu agente ao modelo acelerado por GPU.
- Teste com a interface da Web do ADK: valide se o agente de conversação funciona corretamente.
- Realizar teste de carga: observe como as duas instâncias do Cloud Run fazem escalonamento automático sob carga.
A ênfase está nos padrões de implantação de produção, e não no desenvolvimento extenso de agentes.
O que você vai aprender
- Implantar modelos da Gemma acelerados por GPU no Cloud Run para uso em produção
- Integrar implantações de modelos externos com agentes do ADK
- Configure e teste implantações de agentes de IA prontas para produção
- Entender o comportamento do escalonamento automático do Cloud Run sob carga
- Observe como várias instâncias do Cloud Run se coordenam durante picos de tráfego
- Aplicar teste de carga para validar a performance e o escalonamento automático
2. Configuração do projeto
- Se você ainda não tiver uma Conta do Google, crie uma.
- Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
- Faça login no Console do Google Cloud.
- Ative o faturamento no Console do Cloud.
- A conclusão deste laboratório custa menos de US $1 em recursos do Cloud.
- Siga as etapas no final deste laboratório para excluir recursos e evitar mais cobranças.
- Novos usuários podem aproveitar a avaliação sem custo financeiro de US$300.
- Crie um projeto ou reutilize um projeto existente.
3. Abrir editor do Cloud Shell
- Clique neste link para acessar diretamente o editor do Cloud Shell.
- Se for preciso autorizar em algum momento hoje, clique em Autorizar para continuar.
- Se o terminal não aparecer na parte de baixo da tela, abra-o:
- Clique em Visualizar.
- Clique em Terminal
.
- No terminal, defina o projeto com este comando:
- Formato:
gcloud config set project [PROJECT_ID]
- Exemplo:
gcloud config set project lab-project-id-example
- Se você não se lembrar do ID do projeto:
- Para listar todos os IDs de projeto, use:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- Para listar todos os IDs de projeto, use:
- Formato:
- Você vai receber esta mensagem:
Se você vir umUpdated property [core/project].
WARNING
e for perguntadoDo you want to continue (Y/n)?
, provavelmente inseriu o ID do projeto incorretamente. Pressionen
,Enter
e tente executar o comandogcloud config set project
novamente.
4. Ativar APIs e definir a região padrão
Antes de implantar serviços do Cloud Run com suporte a GPU, precisamos ativar as APIs necessárias do Google Cloud e configurar as definições do projeto.
- No terminal, ative as APIs:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com
Se for preciso autorizar, clique em Autorizar para continuar.
Esse comando pode levar alguns minutos para ser concluído, mas vai gerar uma mensagem de sucesso semelhante a esta:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
- Defina sua região padrão do Cloud Run.
gcloud config set run/region europe-west1
5. Preparar seu projeto Python
Vamos configurar o código inicial que contém a estrutura básica dos serviços de back-end da Gemma e do agente do ADK.
- Clone o repositório inicial:
cd ~ git clone https://github.com/amitkmaraj/accelerate-ai-lab3-starter.git cd accelerate-ai-lab3-starter
- Examine a estrutura do projeto:
Você vai ver a seguinte estrutura inicial:ls -R
accelerate-ai-lab3-starter/ ├── README.md # Project overview ├── ollama-backend/ # Ollama backend (separate deployment) │ └── Dockerfile # Backend container (🚧 to implement) └── adk-agent/ # ADK agent (separate deployment) ├── pyproject.toml # Python dependencies (✅ completed) ├── server.py # FastAPI server (🚧 to implement) ├── Dockerfile # Container config (🚧 to implement) ├── load_test.py # Load testing (🚧 to implement) └── production_agent/ # Agent implementation ├── __init__.py # Package init (✅ completed) └── agent.py # Agent logic (🚧 to implement)
6. Visão geral da arquitetura
Antes de implementar, vamos entender a arquitetura de dois serviços:
Insight principal: durante o teste de carga, você vai observar que os dois serviços são escalonados de forma independente. O back-end da GPU (serviço de gargalo) é escalonado para 1 a 3 instâncias para carga de inferência, enquanto o agente do ADK permanece em uma instância para processamento de solicitações.
7. Implantar o back-end do Gemma no Cloud Run com GPU
A primeira etapa essencial é implantar um modelo da Gemma acelerado por GPU, que vai servir como o cérebro do seu agente do ADK. Ter um LLM desacoplado e implantado pode ser favorável em arquiteturas em que você precisa de um modelo ajustado separado ou exige escalonamento isolado.
- Navegue até o diretório de back-end do Ollama:
cd ollama-backend
- Abra e implemente o Dockerfile do Ollama:
Substitua o comentário TODO por:cloudshell edit Dockerfile
🔧 O que isso faz:FROM ollama/ollama:latest # Listen on all interfaces, port 8080 ENV OLLAMA_HOST 0.0.0.0:8080 # Store model weight files in /models ENV OLLAMA_MODELS /models # Reduce logging verbosity ENV OLLAMA_DEBUG false # Never unload model weights from the GPU ENV OLLAMA_KEEP_ALIVE -1 # Store the model weights in the container image ENV MODEL gemma3:270m RUN ollama serve & sleep 5 && ollama pull $MODEL # Start Ollama ENTRYPOINT ["ollama", "serve"]
- Usa a imagem oficial do Ollama como base
- Define
OLLAMA_HOST
para aceitar conexões de qualquer endereço IP - Expõe a porta 8080
- Implante o back-end do Gemma com suporte a GPU:
gcloud run deploy ollama-gemma3-270m-gpu \
--source . \
--region europe-west1 \
--concurrency 4 \
--cpu 8 \
--set-env-vars OLLAMA_NUM_PARALLEL=4 \
--gpu 1 \
--gpu-type nvidia-l4 \
--max-instances 3 \
--memory 16Gi \
--allow-unauthenticated \
--no-cpu-throttling \
--no-gpu-zonal-redundancy \
--timeout 600 \
--labels dev-tutorial=codelab-agent-gpu
Se você receber a mensagem "A implantação da origem exige um repositório do Docker do Artifact Registry para armazenar contêineres criados. Uma mensagem "Um repositório chamado [cloud-run-source-deploy] na região [europe-west1] será criado", continue.
⚙️ Explicação da configuração principal:
- GPU: NVIDIA L4 escolhida pela excelente relação custo-benefício para cargas de trabalho de inferência. A L4 oferece 24 GB de memória de GPU e operações de tensor otimizadas, o que a torna ideal para modelos de 270 milhões de parâmetros, como o Gemma.
- Memória: 16 GB de memória do sistema para lidar com o carregamento de modelos, operações CUDA e gerenciamento de memória do Ollama
- CPU: 8 núcleos para processamento ideal de E/S e tarefas de pré-processamento
- Simultaneidade: quatro solicitações por instância equilibram a taxa de transferência com o uso da memória da GPU.
- Tempo limite: 600 segundos para acomodar o carregamento inicial do modelo e a inicialização do contêiner
💰 Consideração de custo: as instâncias de GPU são significativamente mais caras do que as instâncias somente de CPU (US$ 2 a US$ 4/hora contra US$ 0,10/hora). A configuração --max-instances 1
ajuda a controlar os custos, evitando o escalonamento desnecessário de instâncias de GPU.
- Aguarde a conclusão da implantação e anote o URL do serviço:
export OLLAMA_URL=$(gcloud run services describe ollama-gemma3-270m-gpu \ --region=europe-west1 \ --format='value(status.url)') echo "🎉 Gemma backend deployed at: $OLLAMA_URL"
8. Implementar a integração do agente do ADK
Agora vamos criar um agente ADK mínimo que se conecta ao back-end do Gemma implantado.
- Navegue até o diretório do agente do ADK:
cd ../adk-agent
- Abra e implemente a configuração do agente:
Substitua todos os comentários TODO por esta implementação mínima:cloudshell edit production_agent/agent.py
🔧 O que isso faz:import os from pathlib import Path from dotenv import load_dotenv from google.adk.agents import Agent from google.adk.models.lite_llm import LiteLlm import google.auth # Load environment variables root_dir = Path(__file__).parent.parent dotenv_path = root_dir / ".env" load_dotenv(dotenv_path=dotenv_path) # Configure Google Cloud try: _, project_id = google.auth.default() os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id) except Exception: pass os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "europe-west1") # Configure model connection gemma_model_name = os.getenv("GEMMA_MODEL_NAME", "gemma3:270m") # Production Gemma Agent - GPU-accelerated conversational assistant gemma_agent = Agent( model=LiteLlm(model=f"ollama_chat/{gemma_model_name}"), name="gemma_agent", description="A production-ready conversational assistant powered by GPU-accelerated Gemma.", instruction="""You are 'Gem', a friendly, knowledgeable, and enthusiastic zoo tour guide. Your main goal is to make a zoo visit more fun and educational for guests by answering their questions. You can provide general information and interesting facts about different animal species, such as: - Their natural habitats and diet. 🌲🍓 - Typical lifespan and behaviors. - Conservation status and unique characteristics. IMPORTANT: You do NOT have access to any tools. This means you cannot look up real-time, specific information about THIS zoo. You cannot provide: - The names or ages of specific animals currently at the zoo. - The exact location or enclosure for an animal. - The daily schedule for feedings or shows. Always answer based on your general knowledge about the animal kingdom. Keep your tone cheerful, engaging, and welcoming for visitors of all ages. 🦁✨""", tools=[], # Gemma focuses on conversational capabilities ) # Set as root agent root_agent = gemma_agent
- Conecta-se ao back-end do Gemma implantado via LiteLlm.
- Cria um agente de conversação simples
- Configura a integração com o Google Cloud.
- Abra e implemente o servidor FastAPI:
Substitua todos os comentários TODO por:cloudshell edit server.py
🔧 O que isso faz:import os from dotenv import load_dotenv from fastapi import FastAPI from google.adk.cli.fast_api import get_fast_api_app # Load environment variables load_dotenv() AGENT_DIR = os.path.dirname(os.path.abspath(__file__)) app_args = {"agents_dir": AGENT_DIR, "web": True} # Create FastAPI app with ADK integration app: FastAPI = get_fast_api_app(**app_args) # Update app metadata app.title = "Production ADK Agent - Lab 3" app.description = "Gemma agent with GPU-accelerated backend" app.version = "1.0.0" @app.get("/health") def health_check(): return {"status": "healthy", "service": "production-adk-agent"} @app.get("/") def root(): return { "service": "Production ADK Agent - Lab 3", "description": "GPU-accelerated Gemma agent", "docs": "/docs", "health": "/health" } if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8080, log_level="info")
- Cria um servidor FastAPI com integração do ADK.
- Ativa a interface da Web para testes.
- Fornece endpoints de verificação de integridade
- Abra e implemente o Dockerfile:
Substitua todos os comentários TODO por:cloudshell edit Dockerfile
Explicação das opções de tecnologia:FROM python:3.13-slim # Copy uv from the official image COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv # Install system dependencies RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* # Set working directory WORKDIR /app # Copy all files COPY . . # Install Python dependencies RUN uv sync # Expose port EXPOSE 8080 # Run the application CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
- uv: gerenciador de pacotes Python moderno que é de 10 a 100 vezes mais rápido que o pip. Ele usa um cache global e downloads paralelos, reduzindo significativamente os tempos de build de contêineres.
- Python 3.13-slim: a versão mais recente do Python com dependências mínimas do sistema, reduzindo o tamanho do contêiner e a superfície de ataque.
- Build de várias etapas: copiar o uv da imagem oficial garante que vamos receber o binário otimizado mais recente.
9. Configurar o ambiente e implantar o agente
Agora vamos configurar o agente do ADK para se conectar ao back-end da Gemma implantado e implantá-lo como um serviço do Cloud Run. Isso envolve configurar variáveis de ambiente e implantar o agente com a configuração certa.
- Configure a configuração do ambiente:
cat << EOF > .env GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project) GOOGLE_CLOUD_LOCATION=europe-west1 GEMMA_MODEL_NAME=gemma3:270m OLLAMA_API_BASE=$OLLAMA_URL EOF
Como entender as variáveis de ambiente no Cloud Run
As variáveis de ambiente são pares de chave-valor que configuram seu aplicativo durante a execução. Eles são especialmente úteis para:
- Endpoints de API e URLs de serviço (como nosso back-end do Ollama)
- Configuração que muda entre ambientes (desenvolvimento, preparo e produção)
- Dados sensíveis que não devem ser codificados
Implante o agente do ADK:
export PROJECT_ID=$(gcloud config get-value project)
gcloud run deploy production-adk-agent \
--source . \
--region europe-west1 \
--allow-unauthenticated \
--memory 4Gi \
--cpu 2 \
--max-instances 1 \
--concurrency 10 \
--timeout 300 \
--set-env-vars GOOGLE_CLOUD_PROJECT=$PROJECT_ID \
--set-env-vars GOOGLE_CLOUD_LOCATION=europe-west1 \
--set-env-vars GEMMA_MODEL_NAME=gemma3:270m \
--set-env-vars OLLAMA_API_BASE=$OLLAMA_URL \
--labels dev-tutorial=codelab-agent-gpu
⚙️ Configuração principal:
- Escalonamento automático: fixado em uma instância (processamento de solicitações leves)
- Simultaneidade: 10 solicitações por instância
- Memória: 4 GB para o agente do ADK
- Ambiente: conecta-se ao back-end do Gemma
🔒 Observação de segurança: este laboratório usa --allow-unauthenticated
para simplificar. Em produção, implemente a autenticação adequada usando:
- Autenticação de serviço a serviço do Cloud Run com contas de serviço
- Políticas de gerenciamento de identidade e acesso (IAM)
- Chaves de API ou OAuth para acesso externo
- Considere usar
gcloud run services add-iam-policy-binding
para controlar o acesso
Consiga o URL do serviço do agente:
export AGENT_URL=$(gcloud run services describe production-adk-agent \
--region=europe-west1 \
--format='value(status.url)')
echo "🎉 ADK Agent deployed at: $AGENT_URL"
✅ Práticas recomendadas de variáveis de ambiente com base na documentação de variáveis de ambiente do Cloud Run:
- Evite variáveis reservadas: não defina
PORT
(o Cloud Run faz isso automaticamente) nem variáveis que comecem comX_GOOGLE_
. - Use nomes descritivos: adicione um prefixo às variáveis para evitar conflitos (por exemplo,
GEMMA_MODEL_NAME
em vez deMODEL
) - Faça o escape de vírgulas: se os valores contiverem vírgulas, use um delimitador diferente:
--set-env-vars "^@^KEY1=value1,value2@KEY2=..."
- Atualizar x substituir: use
--update-env-vars
para adicionar/mudar variáveis específicas sem afetar outras.
Como definir variáveis no Cloud Run:
- De arquivo:
gcloud run deploy SERVICE_NAME --env-vars-file .env --labels dev-tutorial codelab-adk
(carrega várias variáveis de um arquivo) - Várias flags: repita
--set-env-vars
para valores complexos que não podem ser separados por vírgulas.
10. Testar com a interface da Web do ADK
Com os dois serviços implantados, é hora de validar se o agente do ADK consegue se comunicar com o back-end do Gemma acelerado por GPU e responder às consultas do usuário.
- Teste o endpoint de integridade:
Você vai ver:curl $AGENT_URL/health
{ "status": "healthy", "service": "production-adk-agent" }
- Interaja com seu agente inserindo o URL do seu
production-adk-agent
em uma nova guia do navegador. A interface da Web do ADK vai aparecer. - Teste seu agente com estas conversas de exemplo:
- "O que os pandas-vermelhos costumam comer na natureza?"
- "Você pode me contar uma curiosidade sobre os leopardos-das-neves?"
- "Por que os sapos venenosos são tão coloridos?"
- "Onde posso encontrar o novo canguru bebê no zoológico?"
- O agente responde usando o modelo Gemma implantado. Para verificar isso, observe os registros do serviço Gemma implantado. Vamos fazer isso na próxima seção.
- As respostas são geradas pelo back-end acelerado por GPU.
- A interface da Web oferece uma experiência de chat limpa
11. Implementar e executar testes de carga
Para entender como sua implantação de produção lida com o tráfego real, vamos implementar testes de carga abrangentes que vão acionar o escalonamento automático no agente do ADK e nos serviços de back-end da GPU.
- Abra e implemente o script de teste de carga:
Substitua o comentário TODO por:cloudshell edit load_test.py
🔧 O que isso faz:import random import uuid from locust import HttpUser, task, between class ProductionAgentUser(HttpUser): """Load test user for the Production ADK Agent.""" wait_time = between(1, 3) # Faster requests to trigger scaling def on_start(self): """Set up user session when starting.""" self.user_id = f"user_{uuid.uuid4()}" self.session_id = f"session_{uuid.uuid4()}" # Create session for the Gemma agent using proper ADK API format session_data = {"state": {"user_type": "load_test_user"}} self.client.post( f"/apps/production_agent/users/{self.user_id}/sessions/{self.session_id}", headers={"Content-Type": "application/json"}, json=session_data, ) @task(4) def test_conversations(self): """Test conversational capabilities - high frequency to trigger scaling.""" topics = [ "What do red pandas typically eat in the wild?", "Can you tell me an interesting fact about snow leopards?", "Why are poison dart frogs so brightly colored?", "Where can I find the new baby kangaroo in the zoo?", "What is the name of your oldest gorilla?", "What time is the penguin feeding today?" ] # Use proper ADK API format for sending messages message_data = { "app_name": "production_agent", "user_id": self.user_id, "session_id": self.session_id, "new_message": { "role": "user", "parts": [{ "text": random.choice(topics) }] } } self.client.post( "/run", headers={"Content-Type": "application/json"}, json=message_data, ) @task(1) def health_check(self): """Test the health endpoint.""" self.client.get("/health")
- Criação de sessão: usa o formato correto da API ADK com POST para
/apps/production_agent/users/{user_id}/sessions/{session_id}
. Depois de criar umsession_id
e umuser_id
, é possível fazer uma solicitação ao agente. - Formato da mensagem: segue a especificação do ADK com
app_name
,user_id
,session_id
e objetonew_message
estruturado. - Endpoint de conversa: usa o endpoint
/run
para coletar todos os eventos de uma só vez (recomendado para teste de carga). - Carga realista: cria carga de conversação com tempos de espera mais curtos para acionar o escalonamento automático.
- Criação de sessão: usa o formato correto da API ADK com POST para
- Instale as dependências:
uv sync pip install locust
- O Locust é uma ferramenta de teste de carga de código aberto baseada em Python projetada para testes de desempenho e carga de aplicativos da Web e outros sistemas. A principal característica é que os cenários de teste e o comportamento do usuário são definidos usando código Python padrão, oferecendo alta flexibilidade e expressividade em comparação com ferramentas que dependem de interfaces gráficas do usuário ou linguagens específicas do domínio. Vamos usar o Locust para simular o tráfego de usuários nos nossos serviços.Execute o teste de carga.
Tente mudar os parâmetros no teste e observe a saída. Você vai notar que o# Run a load test to trigger autoscaling locust -f load_test.py \ -H $AGENT_URL \ --headless \ -t 50s \ -u 3 \ -r 1
ollama-gemma3-270m-gpu
aumenta para duas ou três instâncias. Os 📊 parâmetros de teste de carga- Duração: 50 segundos
- Usuários: três usuários simultâneos
- Taxa de geração: 1 usuário por segundo
- Destino: acionar o escalonamento automático nos dois serviços
12. Observar o comportamento do Auto Scaling
À medida que o teste de carga é executado, você pode observar o escalonamento automático do Cloud Run em ação. É aqui que você vai conferir os principais benefícios arquitetônicos de separar o agente do ADK do back-end da GPU.
Durante o teste de carga, monitore como os dois serviços do Cloud Run escalonam no console.
- No Console do Cloud, navegue até:
- Cloud Run → production-adk-agent → Métricas
- Cloud Run → ollama-gemma3-270m-gpu → Métricas
👀 O que você precisa observar:
🤖 Serviço do agente do ADK:
- Deve permanecer estável em uma instância enquanto o tráfego aumenta
- Pico de uso de CPU e memória durante tráfego intenso
- Processa o gerenciamento de sessões e o encaminhamento de solicitações com eficiência.
🎮 Serviço de back-end do Gemma (gargalo):
- Escalonamento de 1 a 3 instâncias com base na demanda de inferência
- O uso da GPU aumenta significativamente sob carga
- Esse serviço se torna o gargalo devido à inferência de modelo com uso intensivo de GPU.
- Os tempos de inferência do modelo permanecem consistentes devido à aceleração da GPU
💡 Insights importantes:
- O back-end da GPU é o gargalo e faz escalonamento de maneira mais agressiva (1 a 3 instâncias).
- O agente do ADK permanece consistente
- Os dois serviços são escalonados de forma independente com base nas características de carga individuais.
- O escalonamento automático ajuda a manter o desempenho em diferentes condições de carga
13. Conclusão
Parabéns! Você implantou um agente do ADK pronto para produção com um back-end do Gemma acelerado por GPU e observou o comportamento de escalonamento automático.
✅ O que você realizou
- ✅ Implantou um back-end de modelo Gemma acelerado por GPU no Cloud Run
- ✅ Criou e implantou um agente do ADK que se integra ao back-end da Gemma
- ✅ Testou o agente usando a interface da Web do ADK
- ✅ Observou o comportamento do escalonamento automático em dois serviços coordenados do Cloud Run
💡 Principais insights deste laboratório
- 🎮 Aceleração de GPU: a GPU NVIDIA L4 melhora significativamente o desempenho da inferência do modelo.
- 🔗 Coordenação de serviços: dois serviços do Cloud Run podem trabalhar juntos sem problemas
- 📈 Escalonamento independente: cada serviço é escalonado com base nas características de carga individuais.
- 🚀 Prontidão para produção: a arquitetura lida com padrões de tráfego do mundo real de maneira eficaz.
🔄 Próximas etapas
- Teste diferentes padrões de carga e observe o comportamento de escalonamento
- Teste diferentes tamanhos de modelo da Gemma (ajuste a memória e a GPU de acordo com o necessário)
- Implementar monitoramento e alertas para implantações de produção
- Conheça as implantações multirregionais para disponibilidade global
🧹 Limpar
Para evitar cobranças, exclua os recursos quando terminar:
gcloud run services delete production-adk-agent --region=europe-west1
gcloud run services delete ollama-gemma3-270m-gpu --region=europe-west1
📖 Recursos
- Repositório inicial
- Solução completa
- Documentação do Google ADK
- Guia de testes do ADK: referência completa para endpoints da API ADK e padrões de teste.
- Teste de carga no Cloud Run
- Documentação do Agent Development Kit (ADK)
- Documentação sobre GPUs do Cloud Run
- Biblioteca de modelos do Ollama
- Documentação do Google Cloud Trace
- Práticas recomendadas de segurança do Cloud Run
- Gerenciador de pacotes Python UV
- Framework de teste de carga do Locust