Disponibilizar o Mistral Small 4 usando GPUs no GKE com o vLLM

Para disponibilizar Mistral (LLMs) do Mistral no Google Kubernetes Engine (GKE) com o framework vLLM usando GPUs, provisione um cluster do GKE com aceleradores compatíveis, como GPUs NVIDIA H100.

Para disponibilizar o modelo Mistral Small 4, o contêiner vLLM pré-criado é configurado para carregar pesos de modelo. Os pesos serão carregados de buckets do Cloud Storage (especificados pelo argumento --model).

Depois que os pesos são carregados, o contêiner vLLM expõe um endpoint de API compatível com o OpenAI para inferência de alta capacidade de processamento.

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 disponibilizar cargas de trabalho de IA/ML em hardware de GPU H100.

Antes de ler esta página, confira se você conhece os seguintes conceitos:

Objetivos

Este tutorial oferece uma base para entender e explorar a implantação prática de LLMs para inferência em um ambiente gerenciado do Kubernetes.

  1. Prepare seu ambiente com um cluster do GKE no modo Autopilot.
  2. Implante um contêiner vLLM no seu cluster.
  3. Use o vLLM para disponibilizar o modelo Mistral pela interface curl.

Antes de começar

  • In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  • Verify that billing is enabled for your Cloud de Confiance project.

  • Enable the required API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  • Verifique se você tem os seguintes papéis no projeto: roles/container.admin, roles/iam.serviceAccountAdmin

    Verificar os papéis

    1. No Cloud de Confiance console, acesse a página IAM.

      Acessar IAM
    2. Selecione o projeto.

    3. Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.

    4. Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.

    Conceder os papéis

    1. No Cloud de Confiance console, acesse a página IAM.

      Acessar IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.

    4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o identificador de um usuário em um pool de identidades de força de trabalho. Saiba mais em Representar usuários do pool de força de trabalho nas políticas do IAM ou entre em contato com seu administrador.

    5. Clique em Selecionar um papel e pesquise o papel.
    6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
    7. Clique em Salvar.

Preparar o ambiente

Neste tutorial, você vai usar kubectl e a CLI gcloud para gerenciar recursos hospedados no Cloud de Confiance by S3NS. É possível autorizar com a CLI gcloud para acessar Cloud de Confiance by S3NS.

Para configurar seu ambiente com a CLI gcloud, defina as variáveis de ambiente padrão na CLI gcloud:

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export REGION=u-france-east1
export CLUSTER_NAME=CLUSTER_NAME
export GSA_NAME=GSA_NAME
export KSA_NAME=KSA_NAME
export NAMESPACE=NAMESPACE
export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
export MODEL_BUCKET_NAME=MODEL_BUCKET_NAME

Substitua os seguintes valores:

  • PROJECT_ID: ID do projeto. Cloud de Confiance
  • REGION: região u-france-east1 que oferece suporte à GPU H100. É possível encontrar qual região tem quais GPUs disponíveis.
  • CLUSTER_NAME: o nome do cluster.
  • GSA_NAME: o nome da conta de serviço do Google, por exemplo, mistral-small-gsa.
  • KSA_NAME: o nome da conta de serviço do Kubernetes, por exemplo, mistral-small-ksa.
  • NAMESPACE: o namespace do Kubernetes, por exemplo, default.
  • MODEL_BUCKET_NAME: o nome do bucket do Cloud Storage em que os pesos do modelo serão armazenados. Ele pode ter o mesmo nome do modelo selecionado, como mistral-small-4-119b-weights.

Criar e configurar Cloud de Confiance recursos

Siga estas instruções para criar os recursos necessários.

Criar um cluster do GKE e um pool de nós

É possível disponibilizar o Mistral em GPUs em um cluster do GKE Autopilot. O cluster do Autopilot oferece uma experiência totalmente gerenciada do Kubernetes.

Na CLI gcloud, execute o seguinte comando:

gcloud container clusters create-auto CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --release-channel=rapid

Substitua os seguintes valores:

  • PROJECT_ID: ID do projeto. Cloud de Confiance
  • CLUSTER_NAME: o nome do cluster.
  • REGION: a região em que o cluster está localizado.

O GKE cria um cluster do Autopilot com nós de CPU e GPU conforme solicitado pelas cargas de trabalho implantadas.

Criar um bucket do Cloud Storage

  1. Na CLI gcloud, execute o seguinte comando:

    gcloud storage buckets create gs://${MODEL_BUCKET_NAME} \
  --project=${PROJECT_ID} \
  --location=${REGION} \
  --uniform-bucket-level-access

    Isso cria um bucket do Cloud Storage para armazenar os arquivos de modelo transferidos por download do Hugging Face.

  2. Fazer o download e o upload dos pesos do modelo:

    É necessário receber os pesos do modelo Mistral Small 4 para as versões que você pretende disponibilizar (por exemplo, do Hugging Face ou de outras fontes oficiais). Organize os arquivos transferidos por download localmente em diretórios. Exemplo:

    • ./mistral-small-4-119b-weights-local/ (contém todos os arquivos do modelo Mistral Small 4)

    Faça o upload desses diretórios para o bucket do Cloud Storage com os prefixos específicos esperados pelos manifestos de implantação:

    # Upload files for the mistral-small-4 model
gcloud storage cp --recursive ./mistral-small-4-119b-weights-local/* gs://${MODEL_BUCKET_NAME}

    Essa estrutura de comando garante que os arquivos de modelo estejam localizados em caminhos como gs://${MODEL_BUCKET_NAME}/config.json etc.

Configurar a Federação de Identidade da Carga de Trabalho para GKE para acesso ao Cloud Storage

Para permitir que os pods do Kubernetes acessem com segurança o bucket do Cloud Storage que contém os pesos do modelo, configure a Federação de Identidade da Carga de Trabalho para GKE.

  1. Crie a conta de serviço do Google (GSA):

    gcloud iam service-accounts create ${GSA_NAME} \
  --project=${PROJECT_ID}

  2. Determine e exporte o e-mail da GSA:

    O formato do e-mail depende se o ${PROJECT_ID} tem escopo de domínio (contém dois pontos).

    if [[ $PROJECT_ID == *:* ]]; then
  DOMAIN=$(echo $PROJECT_ID | cut -d: -f1)
  PROJ_NAME=$(echo $PROJECT_ID | cut -d: -f2)
  export GSA_EMAIL="${GSA_NAME}@${PROJ_NAME}.${DOMAIN}.s3ns.iam.gserviceaccount.com"
else
  export GSA_EMAIL="${GSA_NAME}@${PROJECT_ID}.s3ns.iam.gserviceaccount.com"
fi
  echo "Using GSA Email: ${GSA_EMAIL}"

  3. Crie a conta de serviço do Kubernetes (KSA):

    Essa KSA é usada no manifesto de implantação.

    kubectl create serviceaccount ${KSA_NAME} --namespace ${NAMESPACE}

    Execute o seguinte comando para verificar a criação

    kubectl get serviceaccounts --namespace ${NAMESPACE}

  4. Anote a KSA para vinculá-la à GSA:

    Essa anotação informa ao GKE qual GSA a KSA pode representar.

    kubectl annotate serviceaccount ${KSA_NAME} \
  --namespace ${NAMESPACE} \
  iam.gke.io/gcp-service-account=${GSA_EMAIL}

  5. Conceda permissão à KSA para representar a GSA:

    Essa vinculação do IAM na GSA permite que a KSA atue como a GSA.

    if [[ $PROJECT_ID == *:* ]]; then
  DOMAIN=$(echo $PROJECT_ID | cut -d: -f1)
  PROJ_NAME=$(echo $PROJECT_ID | cut -d: -f2)
  export WI_MEMBER="serviceAccount:${PROJ_NAME}.${DOMAIN}.s3ns.svc.id.goog[${NAMESPACE}/${KSA_NAME}]"
else
  export WI_MEMBER="serviceAccount:${PROJECT_ID}.s3ns.svc.id.goog[${NAMESPACE}/${KSA_NAME}]"
fi

gcloud iam service-accounts add-iam-policy-binding ${GSA_EMAIL} \
  --role roles/iam.workloadIdentityUser \
  --member="${WI_MEMBER}" \
  --project=${PROJECT_ID}

  6. Conceda permissão à GSA para ler no bucket:

    Conceda à GSA o papel storage.objectViewer no bucket. 

    gcloud storage buckets add-iam-policy-binding gs://${MODEL_BUCKET_NAME} \
  --member="serviceAccount:${GSA_EMAIL}" \
  --role="roles/storage.objectViewer" \
  --project=${PROJECT_ID}

Implantar o modelo Mistral Small 4 no vLLM

Para implantar o modelo Mistral Small 4, crie buckets do Cloud Storage para cada modelo para armazenar pesos de modelo e aplique um manifesto de implantação do Kubernetes para o tamanho do modelo selecionado. Uma implantação é um objeto de API do Kubernetes que permite executar várias réplicas de pods distribuídos entre os nós de um cluster.

Procedimento

A aplicação desse manifesto extrai a imagem do contêiner vLLM, solicita uma GPU NVIDIA e se conecta automaticamente aos pesos do modelo dos buckets do Cloud Storage para iniciar o mecanismo de inferência do vLLM.

Mistral Small 4

Siga estas instruções para implantar o modelo ajustado por instruções do Mistral Small 4.

  1. Crie o seguinte manifesto vllm-mistral-small.yaml:

    apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: a3-edgegpu-8g-nolssd
spec:
  priorities:
  - machineType: a3-edgegpu-8g-nolssd
    gpu:
      count: 8
      type: nvidia-h100-80gb
  nodePoolAutoCreation:
    enabled: true
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-mistral-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mistral-server
  template:
    metadata:
      labels:
        app: mistral-server
        ai.gke.io/model: mistral-small-4-119b-weights
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
        resources:
          requests:
            cpu: "48"
            memory: "200Gi"
            ephemeral-storage: "250Gi"
            nvidia.com/gpu: "2"
          limits:
            cpu: "48"
            memory: "200Gi"
            ephemeral-storage: "250Gi"
            nvidia.com/gpu: "2"
        command: ["./entrypoint.sh"] # Use the image's entrypoint
        args:
        - "python"
        - "-m"
        - "vllm.entrypoints.api_server"
        - "--host=0.0.0.0"
        - "--port=8080"
        - "--model=gs://mistral-small-4-119b-weights" # YOUR Cloud Storage PATH
        - "--tensor-parallel-size=2"
        - "--enable-log-requests"
        - "--enable-chunked-prefill"
        - "--enable-prefix-caching"
        - "--enable-auto-tool-choice"
        - "--generation-config=auto"
        - "--tool-call-parser=mistral"
        - "--dtype=bfloat16"
        - "--max-num-seqs=256"
        - "--max-model-len=8192"
        - "--gpu-memory-utilization=0.90"
        - "--reasoning-parser=mistral"
        - "--trust-remote-code"
        ports:
        - containerPort: 8080
        env:
        - name: GOOGLE_CLOUD_UNIVERSE_DOMAIN
          value: ""
        - name: CLOUDSDK_CORE_UNIVERSE_DOMAIN
          value: ""
        - name: GCS_URI_ARG_KEY
          value: "model"
        - name: GCS_URI_ENV_KEY
          value: "AIP_STORAGE_URI"
        - name: LORA_ADAPTER_ARG_KEY
          value: "lora-modules"
        - name: HF_HUB_ENABLE_HF_TRANSFER
          value: "1"
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/compute-class: a3-edgegpu-8g-nolssd
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: mistral-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080

  2. Aplique o manifesto:

    kubectl apply -f vllm-mistral-small.yaml

    Se quiser, limite o tamanho da janela de contexto em 16 K usando a opção vLLM --max-model-len=16384. Se você quiser um tamanho de janela de contexto maior (até 128 K), ajuste o manifesto e a configuração do pool de nós com mais capacidade de GPU.

Verificação

  1. Aguarde até que a implantação esteja disponível:

    kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-mistral-deployment

  2. Confira os registros da implantação em execução:

    kubectl logs -f -l app=mistral-server

    O recurso de implantação faz o download dos dados do modelo Mistral Small 4. O processo pode levar alguns minutos. O resultado será o seguinte:

      ...
  ...
  (APIServer pid=1) INFO:     Started server process [1]
  (APIServer pid=1) INFO:     Waiting for application startup.
  (APIServer pid=1) INFO:     Application startup complete.

Depois que a implantação estiver disponível, configure o encaminhamento de portas para interagir com o modelo.

Disponibilizar o modelo

Nesta seção, você vai interagir com o modelo. Verifique se o modelo foi transferido por download antes de continuar.

Configurar o encaminhamento de portas

Execute o seguinte comando para configurar o encaminhamento de portas para o modelo:

kubectl port-forward svc/llm-service 8080:8080 --namespace default &

O resultado será assim:

Forwarding from 127.0.0.1:8080 -> 8080

Interagir com o modelo usando curl

Nesta seção, mostramos como executar um teste preliminar básico para verificar os modelos ajustados por instruções do Mistral implantados. Para outros modelos, substitua mistral-small-4-119b-weights pelo nome do modelo respectivo.

Este exemplo mostra como testar o modelo ajustado por instruções do Mistral com entrada somente de texto.

Em uma nova sessão do terminal, use curl para conversar com seu modelo:

curl http://127.0.0.1:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-Small-4-119B-2603-eagle",
    "prompt": "What is the capital of France?",
    "max_tokens": 50,
    "temperature": 0.7
  }'

A saída será assim:

{
  "id": "cmpl-b5d649b6a2d7a330",
  "object": "text_completion",
  "created": 1781137490,
  "model": "openapi",
  "choices": [
    {
      "index": 0,
      "text": " This question is likely to have been asked millions of times, 
      and the answer is always the same: Paris. But why is Paris the capital 
      of France? The answer to this question is not as simple as 
      it may seem, as it involves a complex",
      "logprobs": null,
      "finish_reason": "length",
      "stop_reason": null,
      "token_ids": null,
      "prompt_logprobs": null,
      "prompt_token_ids": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 58,
    "completion_tokens": 50,
    "prompt_tokens_details": null
  },
  "kv_transfer_params": null
}

Resolver problemas

  • Se você receber a mensagem Empty reply from server, é possível que o contêiner não tenha concluído o download dos dados do modelo. Verifique os registros do pod novamente para ver a mensagem Connected, que indica que o modelo está pronto para ser disponibilizado.
  • Se você vir Connection refused, verifique se o seu encaminhamento de portas está ativo.

Observar o desempenho do modelo

Para conferir os painéis de métricas de observabilidade de um modelo, siga estas etapas:

  1. No Cloud de Confiance console, acesse a página Modelos implantados.

    Acessar modelos implantados

  2. Para conferir detalhes sobre a implantação específica, incluindo métricas, registros e painéis, clique no nome do modelo na lista.

  3. Na página de detalhes do modelo, clique na guia Observabilidade para conferir os seguintes painéis. Se solicitado, clique em Ativar para ativar a coleta de métricas do cluster.

    • O painel Uso da infraestrutura mostra as métricas de utilização.
    • O painel DCGM mostra as métricas do DCGM.
    • Se você estiver usando o vLLM, o painel Desempenho do modelo estará disponível e mostrará métricas de desempenho do modelo vLLM.

Também é possível conferir as métricas na integração do painel do vLLM em Cloud Monitoring. Essas métricas são agregadas para todas as implantações do vLLM sem filtros predefinidos.

O vLLM expõe métricas no formato do Prometheus por padrão. Não é necessário instalar um exportador adicional. 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.

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 implantados

Para evitar cobranças na sua Cloud de Confiance conta do pelos recursos criados neste guia, execute o seguinte comando:

gcloud container clusters delete CLUSTER_NAME \
    --location=REGION

Substitua os seguintes valores:

  • REGION: a região do cluster.
  • CLUSTER_NAME: o nome do cluster.

A seguir