Usar o vLLM no GKE para executar inferência com o Qwen3

Neste tutorial, mostramos como implantar e disponibilizar um Qwen3 modelo de linguagem grande (LLM) com o framework de disponibilização vLLM. Você implanta o modelo em uma única instância de máquina virtual (VM) A4 no Google Kubernetes Engine (GKE).

Este tutorial é destinado a engenheiros de machine learning (ML), administradores e operadores de plataformas e especialistas em dados e IA interessados em usar os recursos de orquestração de contêineres do Kubernetes para processar cargas de trabalho de inferência.

Objetivos

  1. Acessar o Qwen3 usando o Hugging Face.

  2. Preparar o ambiente.

  3. Criar um cluster do GKE no modo Autopilot.

  4. Criar um secret do Kubernetes para as credenciais do Hugging Face.

  5. Implantar um contêiner vLLM no cluster do GKE.

  6. Interagir com o Qwen3 usando curl.

  7. Liberar espaço.

Custos

Neste tutorial, há componentes faturáveis do Google Cloud, entre eles:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Antes de começar

  1. Faça login nasua Google Cloud conta. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a Google Cloud CLI.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Criar um Google Cloud projeto:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

  6. Verifique se o faturamento está ativado para o Google Cloud projeto.

  7. Ative a API necessária:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable container.googleapis.com

  8. Instale a Google Cloud CLI.

  9. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  10. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  11. Crie ou selecione um Google Cloud projeto.

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Criar um Google Cloud projeto:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

  12. Verifique se o faturamento está ativado para o Google Cloud projeto.

  13. Ative a API necessária:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable container.googleapis.com
    14.

  14. Conceda papéis à sua conta de usuário. Execute o seguinte comando uma vez para cada um dos seguintes papéis do IAM: roles/container.admin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • USER_IDENTIFIER: o identificador da sua conta de usuário. Por exemplo, myemail@example.com.
    • ROLE: o papel do IAM que você concede à sua conta de usuário.
  15. Faça login ou crie uma conta do Hugging Face account.

Acessar o Qwen3 usando o Hugging Face

Para usar o Hugging Face para acessar o Qwen3, siga estas etapas:

  1. Faça login no Hugging Face
  2. Crie um token de acesso read do Hugging Face. Clique em Seu perfil > Configurações > Tokens de acesso > +Criar novo token.
  3. Especifique um nome de sua escolha para o token e selecione um papel. O nível mínimo de permissão de papel que você pode selecionar para este tutorial é Ler.
  4. Selecione Criar token.
  5. Copie e salve o token gerado na área de transferência. Você o usará mais tarde neste tutorial.

Preparar o ambiente

Para preparar o ambiente, defina as variáveis de ambiente padrão:

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto em que você quer criar o cluster do GKE.

  • RESERVATION_URL: o URL da reserva que você quer usar para criar o cluster do GKE. Com base no projeto em que a reserva existe, especifique um dos seguintes valores:

    • A reserva existe no seu projeto: RESERVATION_NAME

    • A reserva existe em um projeto diferente, e seu projeto pode usar a reserva: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

  • REGION: a região em que você quer criar o cluster do GKE. Só é possível criar o cluster na região em que a reserva existe.

  • CLUSTER_NAME: o nome do cluster do GKE a ser criado.

  • HUGGING_FACE_TOKEN: o token de acesso do Hugging Face que você criou na seção anterior.

  • NETWORK_NAME: a rede usada pelo cluster do GKE. Especifique um dos seguintes valores:

    • Se você criou uma rede personalizada, especifique o nome dela.

    • Caso contrário, especifique default.

  • SUBNETWORK_NAME: a sub-rede usada pelo cluster do GKE. Especifique um dos seguintes valores:

    • Se você criou uma sub-rede personalizada, especifique o nome dela. Só é possível especificar uma sub-rede que exista na mesma região da reserva.

    • Caso contrário, especifique default.

Criar um cluster do GKE no modo Autopilot

Para criar um cluster do GKE no modo Autopilot, execute o seguinte comando:

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

A criação do cluster do GKE pode levar algum tempo. Para verificar se Google Cloud o cluster foi criado, acesse Clusters do Kubernetes no Google Cloud console.

Criar um secret do Kubernetes para as credenciais do Hugging Face

Para criar um secret do Kubernetes para as credenciais do Hugging Face, siga estas etapas:

  1. Configure o kubectl para se comunicar com o cluster do GKE:

    gcloud container clusters get-credentials $CLUSTER_NAME \
    --location=$REGION

  2. Crie um secret do Kubernetes para armazenar o token do Hugging Face:

    kubectl create secret generic hf-secret \
    --from-literal=hf_token=${HUGGING_FACE_TOKEN} \
    --dry-run=client -o yaml | kubectl apply -f -

Implantar um contêiner vLLM no cluster do GKE

Para implantar o contêiner vLLM para disponibilizar o modelo Qwen3 usando implantações do Kubernetes, faça o seguinte:

  1. Crie um arquivo qwen3-235b-deploy.yaml com a implantação do vLLM escolhida. :

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-qwen3-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: qwen3-server
  template:
    metadata:
      labels:
        app: qwen3-server
        ai.gke.io/model: Qwen3-235B-A22B-Instruct-2507
        ai.gke.io/inference-server: vllm
    spec:
      containers:
      - name: qwen-inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250801_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        - --dtype=bfloat16
        env:
        - name: MODEL_ID
          value: "Qwen/Qwen3-235B-A22B-Instruct-2507"
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1320
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1320
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: RESERVATION_URL
        cloud.google.com/reservation-affinity: "specific"
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: qwen3-service
spec:
  selector:
    app: qwen3-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-qwen3-monitoring
spec:
  selector:
    matchLabels:
      app: qwen3-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

  2. Aplique o arquivo qwen3-235b-deploy.yaml ao cluster do GKE:

    kubectl apply -f qwen3-235b-deploy.yaml

    Durante o processo de implantação, o contêiner precisa fazer o download do modelo Qwen3-235B-A22B-Instruct-2507 do Hugging Face. Por esse motivo, a implantação do contêiner pode levar até 30 minutos.

  3. Para conferir o status de conclusão, execute o seguinte comando:

    kubectl wait \
    --for=condition=Available \
    --timeout=1500s deployment/vllm-qwen3-deployment

    A flag --timeout=1500s permite que o comando monitore a implantação por até 25 minutos.

Interagir com o Qwen3 usando curl

Para verificar o modelo Qwen3 implantado, faça o seguinte:

  1. Configure o encaminhamento de portas para o Qwen3:

    kubectl port-forward service/qwen3-service 8000:8000

  2. Abra uma nova janela do terminal. Em seguida, você pode conversar com o modelo usando curl:

    curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "messages": [
    {
      "role": "user",
      "content": "Describe a GPU in one short sentence?"
    }
  ]
}'

    O resultado será assim:

    {
  "id": "chatcmpl-a926ddf7ef2745ca832bda096e867764",
  "object": "chat.completion",
  "created": 1755023619,
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A GPU is a specialized electronic circuit designed to rapidly process and render graphics and perform parallel computations.",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning_content": null
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 16,
    "total_tokens": 36,
    "completion_tokens": 20,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "kv_transfer_params": null
}

Observar o desempenho do modelo

Se você quiser observar o desempenho do modelo, use a integração do painel do vLLM em Cloud Monitoring. Esse painel ajuda a visualizar métricas de desempenho críticas para o modelo, como capacidade de processamento de tokens, latência de rede e taxas de erro. Para mais informações, consulte vLLM na documentação do Monitoring.

Liberar espaço

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

Excluir um Google Cloud projeto:

gcloud projects delete PROJECT_ID

Excluir o cluster do GKE

Para excluir o cluster do GKE, execute o seguinte comando:

gcloud container clusters delete $CLUSTER_NAME \
    --region=$REGION

Excluir os recursos

Para excluir o arquivo qwen3-235b-deploy.yaml e o secret do Kubernetes do cluster do GKE, execute os seguintes comandos:

kubectl delete -f qwen3-235b-deploy.yaml
kubectl delete secret hf-secret

A seguir