1. Introdução
Os modelos de linguagem grandes (LLMs) estão mudando a forma como criamos aplicativos inteligentes. Mas preparar esses modelos eficientes para uso no mundo real pode ser complicado. Eles precisam de muita capacidade de computação, especialmente placas gráficas (GPUs), e maneiras inteligentes de lidar com muitas solicitações de uma só vez. Além disso, você quer manter os custos baixos e o aplicativo funcionando sem problemas ou atrasos.
Este codelab vai mostrar como enfrentar esses desafios. Vamos usar duas ferramentas principais:
- vLLM: pense nisso como um mecanismo super-rápido para LLMs. Isso faz com que seus modelos sejam executados de maneira muito mais eficiente, processando mais solicitações de uma só vez e reduzindo o uso da memória.
- Google Cloud Run: é a plataforma sem servidor do Google. É ótimo para implantar aplicativos porque lida com todo o escalonamento para você, de zero a milhares de usuários e vice-versa. O melhor de tudo é que o Cloud Run agora oferece suporte a GPUs, que são essenciais para hospedar LLMs.
Juntos, o vLLM e o Cloud Run oferecem uma maneira eficiente, flexível e econômica de veicular seus LLMs. Neste guia, você vai implantar um modelo aberto, disponibilizando-o como uma API da Web padrão.
O que você vai aprender
- Como escolher o tamanho e a variante certos do modelo para disponibilização.
- Como configurar o vLLM para veicular endpoints de API compatíveis com a OpenAI.
- Como conteinerizar o servidor vLLM com o Docker.
- Como enviar a imagem do contêiner para o Google Artifact Registry.
- Como implantar o contêiner no Cloud Run com aceleração de GPU.
- Como testar o modelo implantado.
O que é necessário
- Um navegador, como o Chrome, para acessar o console do Google Cloud
- Uma conexão de Internet confiável
- Ter um projeto do Google Cloud com o faturamento ativado
- Um token de acesso do Hugging Face. Crie um aqui se ainda não tiver.
- Conhecimentos básicos sobre Python, Docker e a interface de linha de comando
- Uma mente curiosa e vontade de aprender
2. Antes de começar
Configurar o projeto do Google Cloud
Este codelab requer um projeto do Google Cloud com uma conta de faturamento ativa.
- Para sessões com instrutor:se você estiver em uma sala de aula, o instrutor vai fornecer as informações necessárias sobre projeto e faturamento. Siga as instruções do instrutor para concluir a configuração.
- Para estudantes independentes:se você estiver fazendo isso por conta própria e não tiver uma conta de faturamento ativa, configure uma usando suas informações de pagamento. Consulte a documentação do Cloud Billing do Google Cloud para criar uma conta de faturamento e ativá-la no seu projeto.
Criar um projeto na nuvem do Google
Para manter todo o seu trabalho neste codelab organizado e separado de outros projetos, comece criando um novo projeto na nuvem do Google.
Para abrir a página de criação de projetos, clique em:
Insira as informações necessárias na página de criação do projeto:
- Nome do projeto: você pode inserir qualquer nome que quiser (por exemplo, genai-workshop).
- Local: deixe como Nenhuma organização.
- Conta de faturamento: se essa opção aparecer, selecione "Conta de faturamento de teste do Google Cloud Platform" ou sua própria conta de faturamento, se preferir. Se essa opção não aparecer, siga para a próxima etapa.
Copie o ID do projeto gerado. Ele será necessário mais tarde. 
Se tudo estiver certo, clique no botão Criar.
Configurar o Cloud Shell
O Cloud Shell é um ambiente pré-configurado com todas as ferramentas necessárias para este codelab. Depois que o projeto for criado, siga estas etapas para configurar o Cloud Shell.
Iniciar o Cloud Shell
Para iniciar o Cloud Shell, clique em:
Se um pop-up aparecer pedindo autorização, clique em Autorizar.
Definir ID do projeto
Substitua replace-with-your-project-id pelo ID do projeto da etapa de criação acima. Execute o seguinte comando no terminal do Cloud Shell para definir o ID do projeto correto.
gcloud config set project replace-with-your-project-id
Agora você vai ver que o projeto correto está selecionado no terminal do Cloud Shell. O ID do projeto selecionado é destacado em amarelo.
Ative as APIs necessárias
Para usar serviços do Google Cloud, como o Cloud Run, primeiro é necessário ativar as APIs respectivas para seu projeto. Execute os comandos a seguir no Cloud Shell para ativar os serviços necessários para este codelab:
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com
3. Como escolher o modelo certo
Você pode encontrar muitos modelos de código aberto em sites como o Hugging Face Hub e o Kaggle. Quando você quer usar um desses modelos em um serviço como o Google Cloud Run, é necessário escolher um que se ajuste aos recursos disponíveis (por exemplo, GPU NVIDIA L4).
Além do tamanho, considere o que o modelo pode fazer. Eles não são todos iguais, cada um tem vantagens e desvantagens. Por exemplo, alguns modelos podem processar diferentes tipos de entrada (como imagens e texto, conhecidos como recursos multimodais), enquanto outros podem lembrar e processar mais informações de uma só vez (ou seja, têm janelas de contexto maiores). Muitas vezes, modelos maiores têm recursos mais avançados, como chamada de função e pensamento.
Também é importante verificar se o modelo desejado é compatível com a ferramenta de veiculação (vLLM, neste caso). Confira todos os modelos compatíveis com o vLLM aqui.
Agora, vamos conhecer o Gemma 3, a mais nova família de modelos de linguagem grandes (LLMs) abertos do Google. O Gemma 3 está disponível em quatro escalas diferentes com base na complexidade, medida em parâmetros: 1 bilhão, 4 bilhões, 12 bilhões e 27 bilhões.
Para cada um desses tamanhos, há dois tipos principais:
- Uma versão básica (pré-treinada): é o modelo de fundação que aprendeu com uma grande quantidade de dados.
- Uma versão ajustada por instruções: essa versão foi refinada para entender e seguir melhor instruções ou comandos específicos.
Os modelos maiores (4 bilhões, 12 bilhões e 27 bilhões de parâmetros) são multimodais, o que significa que eles podem entender e trabalhar com imagens e texto. No entanto, a menor variante de 1 bilhão de parâmetros se concentra apenas no texto.
Neste codelab, vamos usar 1 bilhão de variantes da Gemma 3: gemma-3-1b-it. Usar um modelo menor também ajuda a aprender a trabalhar com recursos limitados, o que é importante para manter os custos baixos e garantir que o app funcione sem problemas na nuvem.
4. Variáveis de ambiente e secrets
Criar um arquivo de ambiente
Antes de prosseguir, é recomendável ter todas as configurações que você vai usar neste codelab em um só lugar. Para começar, abra o terminal e siga estas etapas:
- Crie uma pasta para esse projeto.
- Acesse a pasta recém-criada.
- Crie um arquivo .env vazio nessa pasta. Ele vai conter suas variáveis de ambiente.
Este é o comando para realizar essas etapas:
mkdir vllm-gemma3 && cd vllm-gemma3 && cloudshell edit .env
Em seguida, copie as variáveis listadas abaixo e cole-as no arquivo.env que você acabou de criar.
PROJECT_ID=your_project_id
REGION=your_region
MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}
AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}
SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Não se esqueça de substituir os valores do marcador de posição (your_project_id e your_region) pelas informações específicas do projeto. Por exemplo, PROJECT_ID=unique-ai-project e REGION=us-central1. Confira aqui a lista de regiões que oferecem suporte a GPUs no Cloud Run.
Depois que o arquivo.env for editado e salvo, digite este comando para carregar essas variáveis de ambiente na sessão do terminal:
source .env
Para testar se as variáveis foram carregadas com sucesso, repita uma delas. Exemplo:
echo $SERVICE_NAME
Se você receber o mesmo valor atribuído no arquivo.env, as variáveis serão carregadas com sucesso.
Armazenar um secret no Secret Manager
Para dados sensíveis, incluindo códigos de acesso, credenciais e senhas, a abordagem recomendada é usar um gerenciador de secrets.
Antes de usar os modelos da Gemma 3, você precisa confirmar os Termos e Condições, já que eles são restritos. Você pode confirmar os termos e condições no Card do modelo Gamma 3 no Hugging Face Hub.
Depois de ter o token de acesso do Hugging Face, acesse a página do Secret Manager e crie um secret seguindo estas instruções:
- Acesse o console do Google Cloud
- Selecione o projeto na barra de menu suspenso no canto superior esquerdo.
- Pesquise Secret Manager na barra de pesquisa e clique nessa opção quando ela aparecer.
Quando você estiver na página do Secret Manager:
- Clique no botão +Criar secret.
- Preencha estas informações:
- Nome: HF_TOKEN
- Valor da chave secreta: <your_hf_access_token>
- Clique no botão Criar secret quando terminar.
Agora você tem o token de acesso do Hugging Face como um secret no Google Cloud Secret Manager.
Para testar seu acesso ao secret, execute o comando abaixo no terminal. Ele vai extrair o secret do Secret Manager:
gcloud secrets versions access latest --secret=HF_TOKEN
O token de acesso será recuperado e mostrado na janela do terminal.
Conceder acesso ao secret à conta de serviço do Cloud Build
Como o secret agora está armazenado com segurança no Secret Manager,
Execute estes comandos no terminal para fazer isso:
# Get the project number
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
# Grant Cloud Build access to the Hugging Face Token secret
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
5. Criar uma conta de serviço
Para aumentar a segurança e gerenciar o acesso de maneira eficaz em um ambiente de produção, os serviços precisam operar em contas de serviço dedicadas, que são estritamente limitadas às permissões necessárias para as tarefas específicas.
Execute este comando para criar uma conta de serviço
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
O comando a seguir anexa a permissão necessária
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Criar uma imagem no Artifact Registry
Essa etapa envolve a criação de uma imagem Docker que inclui os pesos do modelo e um vLLM pré-instalado.
1. Criar um repositório do Docker no Artifact Registry
Vamos criar um repositório do Docker no Artifact Registry para enviar as imagens criadas. Execute o seguinte comando no terminal:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Armazenar o modelo
Com base na documentação de práticas recomendadas de GPU, é possível armazenar modelos de ML dentro de imagens de contêiner ou otimizar o carregamento deles do Cloud Storage.
É claro que cada abordagem tem vantagens e desvantagens. Leia a documentação para saber mais sobre eles. Para simplificar, vamos armazenar o modelo na imagem do contêiner. Você vai fazer isso na próxima sessão.
3. Crie um arquivo Docker
Crie um arquivo chamado Dockerfile e copie o conteúdo abaixo nele:
FROM vllm/vllm-openai:v0.16.0
ARG MODEL_NAME
ARG HF_TOKEN
ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}
# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
huggingface-cli download ${MODEL_NAME}
# Prevent vLLM from trying to download the model again at runtime
ENV HF_HUB_OFFLINE=1
EXPOSE 8080
ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
--port ${PORT:-8080} \
--model ${MODEL_NAME} \
--gpu-memory-utilization 0.90 \
${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}
4. Criar um arquivo yaml para implantação
Em seguida, crie um arquivo chamado cloudbuild.yaml no mesmo diretório. Esse arquivo define as etapas que o Cloud Build precisa seguir. Copie e cole o conteúdo a seguir em cloudbuild.yaml:
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args:
- '-c'
- |
docker build \
--build-arg MODEL_NAME=${_MODEL_NAME} \
--build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
-t ${_IMAGE_NAME} .
secretEnv: ['HF_TOKEN_SECRET']
images:
- '${_IMAGE_NAME}'
availableSecrets:
secretManager:
- versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
env: 'HF_TOKEN_SECRET'
5. Envie o build para o Cloud Build
Copie e cole o código a seguir e execute no terminal:
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
Esse comando faz upload do seu código (Dockerfile e cloudbuild.yaml), transmite as variáveis do shell como substituições (_MODEL_NAME e _IMAGE_NAME) e inicia a build.
O Cloud Build vai executar as etapas definidas em cloudbuild.yaml. É possível acompanhar os registros no terminal ou clicar no link para os detalhes do build no console do Cloud. Quando terminar, a imagem do contêiner vai estar disponível no repositório do Artifact Registry, pronta para implantação.
6. Implantar no Cloud Run
Agora você está pronto para implantar o serviço no Cloud Run. Execute este comando no terminal:
gcloud run deploy ${SERVICE_NAME} \
--image ${IMAGE_NAME} \
--region ${REGION} \
--service-account ${SERVICE_ACC_EMAIL} \
--gpu 1 \
--gpu-type nvidia-l4 \
--cpu 4 \
--memory 16Gi \
--max-instances 3 \
--concurrency 80 \
--no-allow-unauthenticated
7. Testar o serviço
Execute o comando a seguir no terminal para criar um proxy e acessar o serviço enquanto ele é executado em localhost:
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
Em uma nova janela de terminal, execute este comando curl para testar a conexão:
curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-1b-it",
"prompt": "Cloud Run is a ",
"max_tokens": 128,
"temperature": 0.90
}'
Se você vir uma saída semelhante à abaixo:
{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:** This means Google handles the underlying infrastructure, including scaling, patching, and maintenance. You don't need to worry about managing Kubernetes clusters.\n* **Serverless:** You only pay for the compute time your application actually uses. No charges when your code isn't running.\n* **Scalability:** Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}
8. Conclusão
Parabéns! Você concluiu este codelab. Você aprendeu a:
- Escolha um tamanho de modelo adequado para uma implantação de destino.
- Configure o vLLM para veicular uma API compatível com a OpenAI.
- Coloque o servidor vLLM e os pesos do modelo em contêineres de forma segura com o Docker.
- Envie uma imagem de contêiner para o Google Artifact Registry.
- Implante um serviço acelerado por GPU no Cloud Run.
- Testar um modelo autenticado e implantado.
Não deixe de conferir outros modelos interessantes, como Llama, Mistral ou Qwen, para continuar sua jornada de aprendizado.
9. Limpeza
Para evitar cobranças futuras, é importante excluir os recursos criados. Execute os comandos a seguir para limpar o projeto.
1. Exclua o serviço do Cloud Run:
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Exclua o repositório do Artifact Registry:
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Exclua a conta de serviço:
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Exclua o secret do Secret Manager:
gcloud secrets delete HF_TOKEN --quiet