Usar o vLLM no GKE para executar inferências com o DeepSeek-V3.2-Speciale

Neste tutorial, mostramos como implantar e disponibilizar um modelo de linguagem DeepSeek-V3.2-Speciale usando o framework vLLM. Você implanta esse modelo em um cluster do Google Kubernetes Engine (GKE) Autopilot e consome uma única máquina virtual (VM) A4 com oito GPUs B200.

Este tutorial pressupõe que você analisou o modelo de linguagem DeepSeek-V3.2-Speciale e verificou se os recursos dele atendem aos requisitos do seu caso de uso.

Importante: para concluir este tutorial, você precisa ter reservado a capacidade de criar uma VM A4. Para saber mais sobre as opções de reserva de capacidade no Hipercomputador de IA para uma data e hora futuras, consulte Escolher uma opção de consumo.

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

Objetivos

1. Acessar o DeepSeek-V3.2-Speciale 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 DeepSeek-V3.2-Speciale usando curl.

7. Liberar espaço.

Custos

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

• Preços do Google Kubernetes Engine
• Preços do GPU

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

Antes de começar

Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a Google Cloud CLI.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto do que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

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

Instale a Google Cloud CLI.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto do que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

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

1. 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, [e-mail].
   • ROLE: o papel do IAM que você concede à sua conta de usuário.
2. Faça login ou crie uma conta do Hugging Face account.

Acessar o DeepSeek-V3.2-Speciale usando o Hugging Face

Para usar o Hugging Face para acessar o modelo DeepSeek-V3.2-Speciale, faça o seguinte:

1. Faça login no Hugging Face.
2. Crie um token de acesso read do Hugging Face.
3. Copie e salve o valor do token de acesso read. Você o usará mais tarde neste tutorial.

Preparar o ambiente

Para preparar o ambiente, defina as seguintes variáveis:

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 e configurar Google Cloud recursos

Siga estas instruções nesta seção para criar os recursos necessários.

Observação: talvez seja necessário criar uma reserva de capacidade para usar alguns aceleradores. Para saber como reservar e consumir recursos reservados, consulte Como consumir recursos por zona reservados.

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 ser concluída. Para verificar se o Google Cloud terminou de criar o cluster, acesse Clusters do Kubernetes no Google Cloud console.

Criar um secret do Kubernetes para armazenar as credenciais do Hugging Face

Para criar um Secret do Kubernetes para armazenar as credenciais do Hugging Face, faça o seguinte:

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

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

2. Crie um secret do Kubernetes que contenha o token de read access do Hugging Face criado em uma etapa anterior:

   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 deepseek-ai/DeepSeek-V3.2-Speciale, faça o seguinte:

1. Crie um arquivo vllm-deepseek3-2.yaml com a implantação do vLLM escolhida:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: deepseek3-2-deploy
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: deepseek
     template:
       metadata:
         labels:
           app: deepseek
           ai.gke.io/model: deepseek-v3-2
           ai.gke.io/inference-server: vllm
           examples.ai.gke.io/source: user-guide
       spec:
         containers:
         - name: vllm-inference
           image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:model-garden.pytorch-vllm-serve-release_20251126.00_p0
           resources:
             requests:
               cpu: "10"
               memory: "1000Gi"
               ephemeral-storage: "1Ti"
               nvidia.com/gpu: "8"
             limits:
               cpu: "10"
               memory: "1000Gi"
               ephemeral-storage: "1Ti"
               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=131072
           - --max-num-seqs=16
           - --enable-chunked-prefill
           - --gpu-memory-utilization=0.90
           - --enforce-eager
           - --trust-remote-code
           env:
           - name: MODEL_ID
             value: deepseek-ai/DeepSeek-V3.2-Speciale
           - 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: 1800
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 1800
             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: deepseek-service
   spec:
     selector:
       app: deepseek
     type: ClusterIP
     ports:
       - protocol: TCP
         port: 8000
         targetPort: 8000
   ---
   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: deepseek-monitoring
   spec:
     selector:
       matchLabels:
         app: deepseek
     endpoints:
     - port: 8000
       path: /metrics
       interval: 30s
   

2. Aplique o arquivo vllm-deepseek3-2.yaml ao cluster do GKE:

     envsubst < vllm-deepseek3-2.yaml | kubectl apply -f -
   

   Durante o processo de implantação, o contêiner precisa fazer o download do modelo deepseek-ai/DeepSeek-V3.2-Speciale do Hugging Face. Por esse motivo, a implantação do contêiner pode levar até 30 minutos para ser concluída.

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

     kubectl wait \
         --for=condition=Available \
         --timeout=1800s deployment/deepseek3-2-deploy
   

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

Interagir com o DeepSeek-V3.2-Speciale usando curl

Para verificar o modelo DeepSeek-V3.2-Speciale implantado, faça o seguinte:

1. Configure o encaminhamento de portas para o DeepSeek-V3.2-Speciale:

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

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

   time curl http://127.0.0.1:8000/v1/completions \
      -X POST \
      -H "Content-Type: application/json" \
      -d '{
        "model": "deepseek-ai/DeepSeek-V3.2-Speciale",
        "prompt": "<|im_start|>user\nExplain the ReAct (Reasoning + Acting) pattern in Agentic AI. Provide a concise Python pseudocode example showing the loop. Keep the explanation under 300 words.<|im_end|>\n<|im_start|>assistant\n",
        "max_tokens": 1024,
        "temperature": 0.7,
        "stream": false,
        "stop": ["<|im_end|>"]
      }'
   

3. A saída exibida é semelhante a esta:

   {
   "id": "cmpl-be345f0499e949ed8500e533be2cfe3f",
   "object": "text_completion",
   "created": 1764803171,
   "model": "deepseek-ai/DeepSeek-V3.2-Speciale",
   "choices": [
     {
       "index": 0,
       "text": "The ReAct pattern integrates reasoning (thoughts) and actions (tool calls) within an agentic loop... [TRUNCATED FOR BREVITY] ...ReAct improves transparency and reliability by explicit reasoning steps.",
       "logprobs": null,
       "finish_reason": "stop",
       "stop_reason": "<|im_end|>",
       "token_ids": null,
       "prompt_logprobs": null,
       "prompt_token_ids": null
     }
   ],
   "service_tier": null,
   "system_fingerprint": null,
   "usage": {
     "prompt_tokens": 57,
     "total_tokens": 317,
     "completion_tokens": 260,
     "prompt_tokens_details": null
   },
   "kv_transfer_params": null
   }
   

Observar a performance do modelo

Para observar a performance do modelo, use a integração do painel do vLLM no Cloud Monitoring. Você pode usar esse painel para conferir métricas de performance críticas, como capacidade de processamento de tokens, latência de solicitação e taxas de erro.

Para informações sobre como usar o Google Cloud Managed Service para Prometheus para coletar métricas do modelo, consulte as vLLM do vLLM na documentação do Cloud 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

Cuidado: a exclusão de um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Excluir um Google Cloud projeto do:

gcloud projects delete PROJECT_ID

Excluir os recursos

1. Para excluir a implantação e o serviço no arquivo vllm-deepseek3-2.yaml e o secret do Kubernetes do cluster do GKE, execute o seguinte comando:

   kubectl delete -f vllm-deepseek3-2.yaml
   kubectl delete secret hf-secret
   

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

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

A seguir

• Gerenciar clusters do GKE otimizados para IA