O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o vLLM no GKE para executar inferência com gpt-oss-120b

GPUs em cluster

Neste tutorial, mostramos como implantar e disponibilizar um modelo de linguagem gpt-oss-120b usando o framework vLLM. Você implanta esse modelo em um cluster do Autopilot do Google Kubernetes Engine (GKE) e consome uma única máquina virtual (VM) A4 que tem 8 GPUs B200.

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

Acesse o gpt-oss-120b usando o Hugging Face.
Prepare o ambiente.
Criar um cluster do GKE no modo Autopilot.
Crie um secret do Kubernetes para as credenciais do Hugging Face.
Criar um bucket do Cloud Storage.
Faça o download do modelo no bucket do Cloud Storage.
Implante um contêiner vLLM no cluster do GKE.
Interaja com o modelo de linguagem gpt-oss usando curl.
Fazer a limpeza.

Custos

Neste tutorial, usamos componentes faturáveis do Google Cloud, incluindo:

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 conta do Google Cloud . Se você começou a usar o Google Cloudagora, 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 sem custos financeiros.

Instale a CLI do Google Cloud.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um projeto do Google Cloud .

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

Selecionar um projeto: não é necessário ter um papel específico do IAM para selecionar um projeto. É possível selecionar qualquer projeto em que você tenha um papel.
Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.
Selecione o projeto do Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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

Ative a API necessária, se ainda não estiver ativada:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

gcloud services enable container.googleapis.com

Instale a CLI do Google Cloud.

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

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um projeto do Google Cloud .

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

Selecionar um projeto: não é necessário ter um papel específico do IAM para selecionar um projeto. É possível selecionar qualquer projeto em que você tenha um papel.
Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.
Selecione o projeto do Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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

Ative a API necessária, se ainda não estiver ativada:

Funções necessárias para ativar APIs

gcloud services enable container.googleapis.com

Conceda papéis à sua conta de usuário. Execute uma vez o seguinte comando 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.
Faça login ou crie uma conta do Hugging Face.

Acessar o gpt-oss usando o Hugging Face

Para usar o Hugging Face para acessar o gpt-oss, faça o seguinte:

Faça login no Hugging Face e explore o modelo gpt-oss.
Crie um token de acesso read do Hugging Face.
Copie e salve o valor do token read access. Você vai usá-lo mais adiante neste tutorial.

Preparar o ambiente

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

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export GCS_BUCKET="YOUR_GCS_BUCKET"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"
export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

Substitua:

YOUR_PROJECT_ID: o ID do projeto do Google Cloud em que você quer criar o cluster do GKE.
YOUR_RESERVATION_NAME: 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 usá-la: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
YOUR_REGION: a região em que você quer criar o cluster do GKE. Só é possível criar o cluster na região em que sua reserva está.
YOUR_CLUSTER_NAME: o nome do cluster do GKE a ser criado.
YOUR_GCS_BUCKET: o nome do bucket do Cloud Storage em que você faz o download do modelo.
YOUR_HF_TOKEN: o token de acesso do Hugging Face que você criou na seção anterior.
YOUR_NETWORK_NAME: a rede que o cluster do GKE usa. Especifique um dos seguintes valores:
- Se você criou uma rede personalizada, especifique o nome dela.
- Caso contrário, especifique default.
YOUR_SUBNETWORK_NAME: a sub-rede que o cluster do GKE usa. Especifique um dos seguintes valores:
- Se você criou uma sub-rede personalizada, especifique o nome dela. Só é possível especificar uma sub-rede que esteja 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 o Google Cloud concluiu a criação do cluster, acesse Clusters do Kubernetes no console do Google Cloud .

Criar um secret do Kubernetes para as credenciais do Hugging Face

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

Configure kubectl para se comunicar com o cluster do GKE:

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

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 -

Criar um bucket do Cloud Storage

Se você estiver usando um bucket do Cloud Storage, verifique se as seguintes condições são verdadeiras:

O bucket do Cloud Storage está na mesma região que o cluster do GKE.
Sua conta de serviço tem as permissões write necessárias no bucket.

Para armazenar o modelo em um novo bucket do Cloud Storage, siga estas etapas:

Execute o comando a seguir para criar um bucket:

gcloud storage buckets create gs://$GCS_BUCKET --location=$REGION --uniform-bucket-level-access

Conceda permissões de write no bucket do Cloud Storage para a conta de serviço padrão.

gcloud storage buckets add-iam-policy-binding gs://$GCS_BUCKET \
    --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/default" \
    --role="roles/storage.objectAdmin"

Baixar o modelo para o bucket do Cloud Storage

Para fazer o download do modelo para o bucket do Cloud Storage, siga estas etapas:

Crie um arquivo gpt-download-job.yaml:

apiVersion: batch/v1
kind: Job
metadata:
  name: gpt-download-job
  namespace: default
spec:
  template:
    metadata:
      labels:
        app: gpt-oss-downloader
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      restartPolicy: OnFailure
      containers:
      - name: downloader
        image: python:3.11-slim
        resources:
          requests:
            cpu: "4"
            memory: "16Gi"
          limits:
            cpu: "4"
            memory: "16Gi"
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        - name: HF_HUB_ENABLE_HF_TRANSFER
          value: "0"
        - name: HF_HOME
          value: "/tmp/hf_cache"
        command: ["/bin/sh", "-c"]
        args:
        - |
          echo "Installing Hugging Face Hub library..."
          pip install -U "huggingface_hub"

          echo "Beginning model snapshot download to GCS Fuse..."
          hf download openai/gpt-oss-120b \
            --token "$HUGGING_FACE_HUB_TOKEN" \
            --local-dir /mnt/gcs/gpt-oss-120b \
            --max-workers 1

          DOWNLOAD_STATUS=$?

          if [ $DOWNLOAD_STATUS -eq 0 ]; then
            echo "Download Complete!"
          else 
            echo "ERROR: Model download failed with exit code $DOWNLOAD_STATUS"
            exit $DOWNLOAD_STATUS
          fi

        volumeMounts:
        - mountPath: /mnt/gcs
          name: gcs-bucket-volume
      volumes:
      - name: gcs-bucket-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: $GCS_BUCKET
            mountOptions: "implicit-dirs"

Para inicializar o job de download, aplique o manifesto gpt-download-job.yaml.
```
envsubst '$GCS_BUCKET' < gpt-download-job.yaml | kubectl apply -f -
```
O recurso de job faz o download dos pesos do modelo gpt-oss-120b do Hugging Face para o bucket do Cloud Storage. O download leva cerca de 30 minutos para ser concluído. Quando o download terminar, prossiga para a próxima seção para iniciar a implantação do modelo.
Para ver o status de conclusão, execute o seguinte comando:
```
kubectl wait \
    --for=condition=Complete \
    --timeout=7200s job/gpt-download-job
```
A flag --timeout especifica por quanto tempo o comando monitora o job antes de atingir o tempo limite.
Para excluir o job, execute o seguinte comando:
```
kubectl delete job gpt-download-job
```

Implantar um contêiner vLLM no cluster do GKE

Depois de fazer o download do modelo para o bucket do Cloud Storage, implante um contêiner vLLM no cluster do GKE:

Crie um arquivo vllm-gpt-oss-120b.yaml com a implantação do vLLM escolhida:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gpt-oss-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gpt-oss
  template:
    metadata:
      labels:
        app: gpt-oss
        ai.gke.io/model: gpt-oss-120b
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      containers:
      - name: vllm-inference
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250822_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=/mnt/gcs/gpt-oss-120b
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        - mountPath: /mnt/gcs
          name: gcs-bucket-volume
          readOnly: true
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 900
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 900
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      - name: gcs-bucket-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: $GCS_BUCKET
            mountOptions: "implicit-dirs,file-cache:max-size-mb:-1,file-cache:enable-parallel-downloads:true,file-cache:max-parallel-downloads:32,file-cache:parallel-downloads-per-file:8,file-cache:download-chunk-size-mb:16"
      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: oss-service
spec:
  selector:
    app: gpt-oss
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8000
    targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-gpt-oss-monitoring
spec:
  selector:
    matchLabels:
      app: gpt-oss
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

Aplique o arquivo vllm-gpt-oss-120b.yaml ao cluster do GKE:

envsubst < vllm-gpt-oss-120b.yaml | kubectl apply -f -

Para ver o status de conclusão, execute o seguinte comando:
```
kubectl wait \
    --for=condition=Available \
    --timeout=7200s deployment/vllm-gpt-oss-deployment
```
A flag --timeout permite que o comando monitore a implantação pelo período especificado.

Interagir com o modelo `gpt-oss` usando curl

Para verificar o modelo gpt-oss que você implantou, faça o seguinte:

Configure o encaminhamento de portas para o modelo gpt-oss:
```
kubectl port-forward service/oss-service 8000:8000
```

Abra uma nova janela do terminal. Em seguida, converse com o modelo usando curl:

curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "openai/gpt-oss-120b",
  "messages": [
    {
      "role": "user",
      "content": "Describe a sailboat in one short sentence?"
    }
  ]
}' | jq .

A saída será semelhante a esta:

{
  "id": "chatcmpl-2235c39759c040daae23ce2addc40c0a",
  "object": "chat.completion",
  "created": 1756831629,
  "model": "openai/gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A sleek vessel gliding on water, its cloth sails billowing like captured wind.",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning_content": "User asks: \"Describe a sailboat in one short sentence?\" We need to produce a short sentence description. Should comply with policy. It's fine. Provide a short sentence."
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 80,
    "total_tokens": 142,
    "completion_tokens": 62,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "kv_transfer_params": null
}

Observar o desempenho do modelo

Para observar o desempenho do modelo, use a integração do painel do vLLM no Cloud Monitoring. Esse painel ajuda a visualizar métricas de performance críticas para seu 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.

Limpar

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 os recursos

Depois de concluir o tutorial, exclua os recursos que não são mais necessários.

Para excluir a implantação e o serviço definidos no arquivo vllm-gpt-oss-120b.yaml e o secret do Kubernetes do cluster do GKE, execute o seguinte comando:
```
envsubst < vllm-gpt-oss-120b.yaml | kubectl delete -f -
kubectl delete secret hf-secret
```
Para excluir o bucket do Cloud Storage, execute o seguinte comando:
```
gcloud storage rm --recursive gs://$GCS_BUCKET
```

Para excluir o cluster do GKE, faça o seguinte:

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

Excluir o projeto

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID