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 usuários a milhares e vice-versa. O melhor de tudo é que o Cloud Run agora é compatível com 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.
- 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.
- Conhecimento básico de Python, Docker e 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 ministradas por instrutor:se você estiver em uma sala de aula, o instrutor vai fornecer as informações necessárias sobre o projeto e o faturamento. Siga as instruções do instrutor para concluir a configuração.
- Para estudantes independentes:se você estiver fazendo isso por conta própria, crie um projeto e ative uma conta de faturamento de teste. Siga as etapas abaixo para começar.
- Abra uma janela anônima pressionando Ctrl + Shift + N ou Cmd + Shift + N.
- Acesse este portal de resgate na janela anônima
- Faça login e receba uma conta de faturamento de teste com sua conta pessoal do Gmail
- Siga as instruções neste conjunto de slides para concluir a configuração.
Configurar o Cloud Shell
Agora vamos configurar o Cloud Shell, uma interface de linha de comando prática diretamente no console do Google Cloud.
Iniciar o Cloud Shell
No canto superior direito do Console do Google Cloud, clique no ícone que parece um terminal (>_) para ativar o Cloud Shell.
Autorizar acesso
Se for preciso, clique em Autorizar para conceder ao Cloud Shell as permissões necessárias para interagir com seu projeto do Google Cloud.
Verificar o ID do projeto
Confira o Project ID no terminal. Ele vai aparecer em amarelo, como mostrado na imagem abaixo. Verifique se é o mesmo ID que você registrou ao criar o projeto.
Se o Project ID for refletido corretamente no terminal, siga para a etapa Ativar as APIs necessárias.
ID do projeto correto (se necessário)
Se o Project ID estiver errado ou não aparecer por completo, use este comando para corrigir. Substitua o texto your-project-id pelo Project ID correto antes de executar o comando.
gcloud config set project your-project-id
Ativar as APIs necessárias
Para usar serviços do Google Cloud, como o Cloud Run, primeiro é necessário ativar as APIs respectivas no 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, você vai encontrar 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 este projeto.
- Acesse a pasta recém-criada.
- Crie um arquivo .env vazio nessa pasta. Esse arquivo vai conter suas variáveis de ambiente mais tarde.
Este é o comando para realizar essas etapas:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
Em seguida, copie as variáveis listadas abaixo e cole-as no arquivo.env que você acabou de criar. 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.
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
Depois que o arquivo.env for editado e salvo, digite este comando para carregar as 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. Acesse o card do modelo Gamma3 no Hugging Face Hub e aceite os Termos e Condições.
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.
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 com 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
Esta etapa envolve a criação de uma imagem do 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.
3. Criar um arquivo Docker
Crie um arquivo chamado Dockerfile e copie o conteúdo abaixo nele:
FROM vllm/vllm-openai:v0.9.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}
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. Crie um arquivo cloudbuild.yaml
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 estará disponível no repositório do Artifact Registry, pronta para implantação.
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 a esta:
{"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. Agora você já sabe:
- Escolha um tamanho de modelo adequado para uma implantação de destino.
- Configure o vLLM para veicular uma API compatível com a OpenAI.
- Contêinerize com segurança o servidor vLLM e os pesos do modelo 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