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

Para disponibilizar modelos de linguagem grandes (LLMs) Mistral no Google Kubernetes Engine (GKE) com o framework vLLM usando GPUs, é necessário provisionar 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 do modelo. Os pesos serão carregados dos 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 a 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 veicular cargas de trabalho de IA/ML em hardware de GPU H100.

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

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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 console do Cloud de Confiance , 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 console do Cloud de Confiance , 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, adicione-os clicando em Adicionar outro papel.
    7. Clique em Salvar.

Preparar o ambiente

Neste tutorial, você vai usar o 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 KUBERNETES_SERVICEACCOUNT=KUBERNETES_SERVICEACCOUNT
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: o ID do projeto do Cloud de Confiance.
  • REGION: região u-france-east1 que oferece suporte à GPU H100. Você pode conferir quais regiões têm quais GPUs disponíveis.
  • CLUSTER_NAME: o nome do cluster.
  • KUBERNETES_SERVICEACCOUNT: o nome da ServiceAccount do Kubernetes. Por exemplo, mistral-small-sa.
  • 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 recursos Cloud de Confiance

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: o Cloud de Confiance ID do projeto.
  • 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:

    Você precisa obter os pesos do modelo Mistral Small 4 para as versões que pretende disponibilizar (por exemplo, do Hugging Face ou de outras fontes oficiais). Organize os arquivos baixados localmente em diretórios. Exemplo:

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

    Faça 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 o acesso ao Cloud Storage

Para permitir que seus pods do Kubernetes acessem o bucket do Cloud Storage que contém as ponderações do modelo, configure a federação de identidade da carga de trabalho para GKE.

  1. Crie a ServiceAccount do Kubernetes:

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

  2. Verifique se a ServiceAccount existe:

    kubectl get serviceaccounts --namespace ${NAMESPACE}

  3. Conceda à conta de serviço do Kubernetes o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket:

    if [[ $PROJECT_ID == *:* ]]; then
  DOMAIN=$(echo $PROJECT_ID | cut -d: -f1)
  PROJ_NAME=$(echo $PROJECT_ID | cut -d: -f2)
  export WI_MEMBER="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJ_NAME}.${DOMAIN}.s3ns.svc.id.goog/subject/ns/${NAMESPACE}/sa/${KUBERNETES_SERVICEACCOUNT}"
else
  export WI_MEMBER="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.s3ns.svc.id.goog/subject/ns/${NAMESPACE}/sa/${KUBERNETES_SERVICEACCOUNT}"
fi

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

Implantar o modelo Mistral Small 4 no vLLM

Para implantar o modelo Mistral Small 4, crie buckets do Cloud Storage para cada modelo armazenar os pesos e aplique um manifesto de implantação do Kubernetes para o tamanho selecionado. Uma implantação é um objeto da API 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 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 --max-model-len=16384 do vLLM. Se você quiser um tamanho maior de janela de contexto (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 download do modelo foi concluído antes de prosseguir.

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 realizar 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 encaminhamento de portas está ativo.

Observar a performance do modelo

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

  1. No console do Cloud de Confiance , 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 métricas de utilização.
    • O painel DCGM mostra as métricas do DCGM.
    • Se você estiver usando o vLLM, o painel Performance do modelo vai estar disponível e mostrará métricas de desempenho do modelo vLLM.

Também é possível ver as métricas na integração do painel do vLLM no Cloud Monitoring. Essas métricas são agregadas para todas as implantações de 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 e coletar métricas do seu modelo, consulte as orientações de capacidade de observação 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 conta do Cloud de Confiance 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