Guia do usuário de modelos Gemma com vLLM no GDC com isolamento físico

Neste documento, apresentamos instruções detalhadas para implantar modelos de pesos abertos do Google DeepMind, especificamente a família Gemma 4, em ambientes com isolamento físico do Google Distributed Cloud (GDC). Ele aborda o uso do vLLM para disponibilização de alta capacidade de processamento, usando os recursos da plataforma do GDC, incluindo recursos do Kubernetes, do Harbor e de GPU. Selecione o modelo e a opção de GPU na seção "Modelo". Todas as outras etapas são iguais para todas os modelos.

Modelos compatíveis

Modelo Repositório do Hugging Face Parâmetros Licença Opções de GPU
Gemma 4 E2B Instruct google/gemma-4-E2B-it 5,1 bilhões (2 bilhões efetivos) Termos de Uso do Gemma 1 x qualquer GPU
Gemma 4 E4B Instruct google/gemma-4-E4B-it 8B (4B efetivos) Termos de Uso do Gemma 1 x qualquer GPU
Gemma 4 12B Instruct google/gemma-4-12B-it 12B (denso) Termos de Uso do Gemma 1 x qualquer GPU
Gemma 4 26B-A4B Instruct google/gemma-4-26B-A4B-it 25,8 bilhões no total / 4 bilhões ativos (mistura de especialistas) Termos de Uso do Gemma 1 NVIDIA A100 de 80 GB
1 NVIDIA H100 de 94 GB
1 NVIDIA H200 de 141 GB ou B300 de 288 GB
Gemma 4 31B Instruct google/gemma-4-31B-it 31,3 bilhões (denso) Termos de Uso do Gemma 1 NVIDIA A100 de 80 GB
1 NVIDIA H100 de 94 GB
1 NVIDIA H200 de 141 GB ou B300 de 288 GB

Arquitetura

A solução envolve a implantação de um back-end de exibição conteinerizado (vLLM) como uma implantação em um cluster padrão. Os pesos do modelo são armazenados em volumes permanentes, preenchidos com arquivos baixados localmente e enviados usando um pod de carregador. Um Service do Kubernetes do tipo LoadBalancer expõe a API de back-end, e os objetos NetworkPolicy / ProjectNetworkPolicy protegem o acesso a ela.

Antes de começar

Conclua a implementação de referência de modelos de peso aberto com vLLM na estação de trabalho e verifique se você tem acesso ao diretório ${HOME}/gdcag-solutions.

Identity and Access Management

Verifique se as contas, os papéis e as permissões necessários do IAM estão configurados corretamente.

Papéis de usuário do GDC na organização:

  • Opcional: administrador de cluster padrão (visualizar clusters no console)

Papéis de usuário do GDC no projeto:

  • Administrador de cluster padrão (standard-cluster-admin)

Papel de usuário do GDC no cluster padrão:

  • StandardClusterRoleBinding para o StandardClusterRole cluster-admin (criado por um administrador do IAM do projeto, consulte a seção Identity and Access Management da implementação de referência)

Estação de trabalho

Execute todos os comandos deste guia em uma estação de trabalho com as ferramentas e a conectividade necessárias para o ambiente e a Internet, a menos que uma etapa indique o contrário.

A configuração do ambiente é em camadas:

  • ${HOME}/gdcag-solutions/env.sh carrega as configurações da plataforma e do registro.
  • ${HOME}/gdcag-solutions/open-weight-models/vllm/env.sh adiciona as configurações do vLLM.

  • Este guia do usuário adiciona env.d/model.sh (o modelo) e env.d/accelerator.sh (a opção de GPU e as configurações de ambiente de execução), que você escreve na seção "Modelo", e env.d/model-common.sh (os valores derivados deles).

  1. Crie a estrutura de diretórios do guia do usuário:

    mkdir -p ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d
    
  2. Crie o arquivo de configuração do ambiente de modelo comum. Ele deriva todos os caminhos e nomes de recursos de GDCS_HF_MODEL, então é o mesmo para todos os modelos:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model-common.sh && echo "Successfully created." || echo "Failed to create!"
    # Model (derived from env.d/model.sh)
    export GDCS_HF_DOWNLOAD_PATH="${GDCS_USER_GUIDE_HOME}/hf-models"
    export GDCS_HF_MODEL_LOWERCASE="${GDCS_HF_MODEL,,}"
    export GDCS_HF_MODEL_DOWNLOAD_DIR="${GDCS_HF_DOWNLOAD_PATH}/${GDCS_HF_MODEL_LOWERCASE}"
    export GDCS_HF_PV_MOUNT_PATH="/mnt/hf-model"
    
    GDCS_HF_MODEL_KUBERNETES="${GDCS_HF_MODEL_LOWERCASE//\//-}"
    export GDCS_HF_MODEL_KUBERNETES="${GDCS_HF_MODEL_KUBERNETES//./-}"
    
    # Workload
    export GDCS_WORKLOAD_NAMESPACE="vllm-gemma"
    export GDCS_WORKLOAD_NAME="${GDCS_HF_MODEL_KUBERNETES}"
    export GDCS_MODEL_LOADER_POD_NAME="loader-${GDCS_HF_MODEL_KUBERNETES}"
    EOF
    
  3. Crie o arquivo do carregador de ambiente do guia do usuário:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.sh && echo "Successfully created." || echo "Failed to create!"
    source "${HOME}/gdcag-solutions/open-weight-models/vllm/env.sh"
    
    export GDCS_USER_GUIDE_HOME="${HOME}/gdcag-solutions/open-weight-models/vllm/gemma"
    echo "GDCS_USER_GUIDE_HOME=${GDCS_USER_GUIDE_HOME}"
    
    # Sourced in dependency order: the model selection, the accelerator and runtime settings, then the values derived from them
    source "${GDCS_USER_GUIDE_HOME}/env.d/model.sh"
    source "${GDCS_USER_GUIDE_HOME}/env.d/accelerator.sh"
    source "${GDCS_USER_GUIDE_HOME}/env.d/model-common.sh"
    echo "GDCS_HF_MODEL=${GDCS_HF_MODEL} (${GDCS_WORKLOAD_ACCELERATOR_COUNT} x ${GDCS_WORKLOAD_ACCELERATOR_TYPE:-unset})"
    EOF
    

Modelo

Selecione o modelo e a opção de GPU que correspondem aos nós de GPU do cluster padrão. O GDC com isolamento físico oferece as seguintes GPUs (consulte Tipos de máquina de nó de cluster). O tipo de recurso do acelerador é o nome sob o qual os nós expõem a GPU ao Kubernetes.

GPU Memória Tipos de máquina Tipo de recurso do acelerador
NVIDIA A100 40 GB a2-highgpu-1g-gdc nvidia.com/gpu-pod-NVIDIA_A100_PCIE_40GB
NVIDIA A100 80 GB a2-ultragpu-1g-gdc, a2-ultragpu-2g-gdc nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE
NVIDIA H100 94 GB a3-highgpu-1g-gdc (pré-lançamento), a3-highgpu-2g-gdc (pré-lançamento), a3-highgpu-4g-gdc nvidia.com/gpu-pod-NVIDIA_H100_NVL
NVIDIA H200 141 GB a3-ultragpu-8g-gdc nvidia.com/gpu-pod-NVIDIA_H200
NVIDIA B300 288 GB a4-ultragpu-8g-gdc nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC

Cada guia lista os fatos do modelo, o comando que grava o arquivo de ambiente do modelo env.d/model.sh e as guias aninhadas que gravam o arquivo de ambiente do acelerador env.d/accelerator.sh para a opção de GPU escolhida com tipos de recursos pré-preenchidos e configurações de vLLM. Para trocar de modelo ou de opção de GPU mais tarde, escreva arquivos de ambiente diferentes, configure o ambiente novamente e repita a seção de implementação. As cargas de trabalho de vários modelos podem ser executadas lado a lado no mesmo namespace, porque cada nome de recurso é derivado do nome do modelo.

  1. Crie os arquivos de ambiente do modelo e do acelerador para o modelo e a opção de GPU que você quer implantar.

    Gemma 4 E2B Instruct

    Atributo Valor
    Repositório do Hugging Face google/gemma-4-E2B-it
    Parâmetros 5,1 bilhões (2 bilhões efetivos)
    Licença Termos de Uso do Gemma
    Pesos usados pelo vLLM Formato Hugging Face (model-*.safetensors), cerca de 10,2 GB
    Tamanho do contexto 128 mil tokens. Este guia serve para --max-model-len 32768

    Crie o arquivo de ambiente do modelo:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model.sh && echo "Successfully created." || echo "Failed to create!"
    # Model: Gemma 4 E2B Instruct
    export GDCS_HF_MODEL="google/gemma-4-E2B-it"
    export GDCS_HF_MODEL_REVISION="main"  # Hugging Face branch, tag, or commit to download
    export GDCS_HF_DOWNLOAD_EXCLUDE=""
    EOF
    

    Crie o arquivo de ambiente do acelerador para sua opção de GPU:

    NVIDIA A100 40 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 40 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_PCIE_40GB"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="60"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA A100 80 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 80 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="60"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H100 94 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H100 94 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H100_NVL"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="60"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H200 141 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H200 141 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H200"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="60"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA B300 288 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA B300 288 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="60"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    Gemma 4 E4B Instruct

    Atributo Valor
    Repositório do Hugging Face google/gemma-4-E4B-it
    Parâmetros 8B (4B efetivos)
    Licença Termos de Uso do Gemma
    Pesos usados pelo vLLM Formato Hugging Face (model-*.safetensors), cerca de 16,0 GB
    Tamanho do contexto 128 mil tokens. Este guia serve para --max-model-len 32768

    Crie o arquivo de ambiente do modelo:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model.sh && echo "Successfully created." || echo "Failed to create!"
    # Model: Gemma 4 E4B Instruct
    export GDCS_HF_MODEL="google/gemma-4-E4B-it"
    export GDCS_HF_MODEL_REVISION="main"  # Hugging Face branch, tag, or commit to download
    export GDCS_HF_DOWNLOAD_EXCLUDE=""
    EOF
    

    Crie o arquivo de ambiente do acelerador para sua opção de GPU:

    NVIDIA A100 40 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 40 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_PCIE_40GB"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="120"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA A100 80 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 80 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="120"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H100 94 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H100 94 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H100_NVL"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="120"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H200 141 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H200 141 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H200"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="120"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA B300 288 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA B300 288 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="120"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    Gemma 4 12B Instruct

    Atributo Valor
    Repositório do Hugging Face google/gemma-4-12B-it
    Parâmetros 12B (denso)
    Licença Termos de Uso do Gemma
    Pesos usados pelo vLLM Formato Hugging Face (model-*.safetensors), cerca de 23,9 GB
    Tamanho do contexto 256 mil tokens. Este guia usa --max-model-len 32768

    Crie o arquivo de ambiente do modelo:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model.sh && echo "Successfully created." || echo "Failed to create!"
    # Model: Gemma 4 12B Instruct
    export GDCS_HF_MODEL="google/gemma-4-12B-it"
    export GDCS_HF_MODEL_REVISION="main"  # Hugging Face branch, tag, or commit to download
    export GDCS_HF_DOWNLOAD_EXCLUDE=""
    EOF
    

    Crie o arquivo de ambiente do acelerador para sua opção de GPU:

    NVIDIA A100 40 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 40 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_PCIE_40GB"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="180"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA A100 80 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 80 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="180"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H100 94 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H100 94 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H100_NVL"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="180"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H200 141 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H200 141 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H200"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="180"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA B300 288 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA B300 288 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="180"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    Gemma 4 26B-A4B Instruct

    Atributo Valor
    Repositório do Hugging Face google/gemma-4-26B-A4B-it
    Parâmetros 25,8 bilhões no total / 4 bilhões ativos (mistura de especialistas)
    Licença Termos de Uso do Gemma
    Pesos usados pelo vLLM Formato Hugging Face (model-*.safetensors), cerca de 51,6 GB
    Tamanho do contexto 256 mil tokens. Este guia usa --max-model-len 32768

    Crie o arquivo de ambiente do modelo:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model.sh && echo "Successfully created." || echo "Failed to create!"
    # Model: Gemma 4 26B-A4B Instruct
    export GDCS_HF_MODEL="google/gemma-4-26B-A4B-it"
    export GDCS_HF_MODEL_REVISION="main"  # Hugging Face branch, tag, or commit to download
    export GDCS_HF_DOWNLOAD_EXCLUDE=""
    EOF
    

    Crie o arquivo de ambiente do acelerador para sua opção de GPU:

    NVIDIA A100 80 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 80 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="300"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H100 94 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H100 94 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H100_NVL"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="300"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H200 141 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H200 141 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H200"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="300"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA B300 288 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA B300 288 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="300"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    Gemma 4 31B Instruct

    Atributo Valor
    Repositório do Hugging Face google/gemma-4-31B-it
    Parâmetros 31,3 bilhões (denso)
    Licença Termos de Uso do Gemma
    Pesos usados pelo vLLM Formato Hugging Face (model-*.safetensors), cerca de 62,5 GB
    Tamanho do contexto 256 mil tokens. Este guia usa --max-model-len 32768

    Crie o arquivo de ambiente do modelo:

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/model.sh && echo "Successfully created." || echo "Failed to create!"
    # Model: Gemma 4 31B Instruct
    export GDCS_HF_MODEL="google/gemma-4-31B-it"
    export GDCS_HF_MODEL_REVISION="main"  # Hugging Face branch, tag, or commit to download
    export GDCS_HF_DOWNLOAD_EXCLUDE=""
    EOF
    

    Crie o arquivo de ambiente do acelerador para sua opção de GPU:

    NVIDIA A100 80 GB

    A exibição em uma GPU de 80 GB deixa pouca memória para o cache de chave-valor, então essa opção define --max-model-len 16384.

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA A100 80 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_A100_80GB_PCIE"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="16384"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="360"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H100 94 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H100 94 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H100_NVL"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="360"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA H200 141 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA H200 141 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_H200"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="360"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    

    NVIDIA B300 288 GB

    cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.d/accelerator.sh && echo "Successfully created." || echo "Failed to create!"
    # Accelerator: NVIDIA B300 288 GB
    export GDCS_WORKLOAD_ACCELERATOR_TYPE="nvidia.com/gpu-pod-NVIDIA_B300_SXM6_AC"
    export GDCS_WORKLOAD_ACCELERATOR_COUNT="1"
    
    # vLLM
    export GDCS_VLLM_MAX_MODEL_LEN="32768"
    export GDCS_VLLM_EXTRA_ARGS=""
    export GDCS_VLLM_STARTUP_FAILURE_THRESHOLD="360"
    export GDCS_VLLM_TEST_MAX_TOKENS="128"
    EOF
    
  2. Use o comando source no arquivo de ambiente:

    source ${HOME}/gdcag-solutions/open-weight-models/vllm/gemma/env.sh
    

    O resultado será o seguinte:

    GDCS_ROOT_HOME=HOME_DIRECTORY_PATH/gdcag-solutions
    GDCS_IMPLEMENTATION_HOME=HOME_DIRECTORY_PATH/gdcag-solutions/open-weight-models/vllm
    GDCS_USER_GUIDE_HOME=HOME_DIRECTORY_PATH/gdcag-solutions/open-weight-models/vllm/gemma
    GDCS_HF_MODEL=HUGGING_FACE_REPOSITORY (ACCELERATOR_COUNT x ACCELERATOR_RESOURCE_TYPE)
    

Cluster

  1. Configurar gdcloud:

    gdcloud config set core/account "default-user"
    gdcloud config set core/organization_console_url "${GDC_ZONAL_CONSOLE_URL}"
    gdcloud config set core/project "${GDC_PROJECT}"
    gdcloud config set core/zone "${GDC_ZONE}"
    
  2. Autentique-se no ambiente do GDC:

    gdcloud auth login
    
  3. Recupere as credenciais do cluster:

    gdcloud clusters get-credentials "${GDC_STANDARD_CLUSTER_NAME}" \
    --project="${GDC_PROJECT}" \
    --standard \
    --zone="${GDC_ZONE}"
    
  4. Verifique a conectividade com o cluster:

    kubectl get nodes -L node.cluster.private.gdc.goog/machine-class
    
  5. Verifique se o tipo de recurso do arquivo de ambiente do acelerador está disponível no cluster. O comando lista os tipos de recursos de acelerador que os nós expõem (o nome depende do modelo de GPU instalado; ele fica vazio em clusters sem nós de GPU) e o valor configurado:

    kubectl get nodes --output=json | jq -r '[.items[].status.allocatable | keys[] | select(startswith("nvidia.com/"))] | unique[]'
    echo "GDCS_WORKLOAD_ACCELERATOR_TYPE=${GDCS_WORKLOAD_ACCELERATOR_TYPE}"
    

Implementação

Namespace

  1. Crie o namespace:

    kubectl create namespace "${GDCS_WORKLOAD_NAMESPACE}" \
    --dry-run=client \
    --output=yaml | kubectl apply -f -
    
  2. Adicione o imagePullSecret:

    kubectl create secret docker-registry "${GDCS_HARBOR_K8S_PULL_SECRET}" \
    --dry-run=client \
    --from-file=.dockerconfigjson=${GDCS_HARBOR_K8S_DOCKER_CONFIG}/config.json \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}" \
    --output=yaml | kubectl apply -f -
    

Pesos do modelo

  1. Faça o download dos pesos do modelo (somente os arquivos que o vLLM precisa para o modelo selecionado, GDCS_HF_DOWNLOAD_EXCLUDE ignora o restante) e remova o diretório .cache:

    EXCLUDE_ARGS=()
    if [[ -n "${GDCS_HF_DOWNLOAD_EXCLUDE:-}" ]]; then
      read -r -a EXCLUDE_PATTERNS <<< "${GDCS_HF_DOWNLOAD_EXCLUDE}"
      EXCLUDE_ARGS=(--exclude "${EXCLUDE_PATTERNS[@]}")
    fi
    hf download "${GDCS_HF_MODEL}" --revision "${GDCS_HF_MODEL_REVISION}" --local-dir "${GDCS_HF_MODEL_DOWNLOAD_DIR}" "${EXCLUDE_ARGS[@]}" && \
    rm -rf "${GDCS_HF_MODEL_DOWNLOAD_DIR}/.cache"
    
  2. Calcule o tamanho necessário de PersistentVolumeClaim com base nos pesos do modelo transferidos por download com 25% de sobrecarga (arredondado para o próximo GiB inteiro):

    MODEL_KIB=$(du -sk "${GDCS_HF_MODEL_DOWNLOAD_DIR}" | awk '{print $1}')
    export GDCS_MODEL_PVC_SIZE="$(( (MODEL_KIB * 125 / 100 + 1048575) / 1048576 ))Gi"
    echo "GDCS_MODEL_PVC_SIZE=${GDCS_MODEL_PVC_SIZE}"
    
  3. Crie o manifesto para o PersistentVolumeClaim ReadWriteOnce para os pesos do modelo:

    cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_WORKLOAD_NAME}-rwo-pvc.yaml"
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: ${GDCS_WORKLOAD_NAME}-rwo
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: ${GDCS_MODEL_PVC_SIZE}
      storageClassName: standard-rwo
      volumeMode: Filesystem
    EOF
    
  4. Aplique o manifesto do PersistentVolumeClaim para os pesos do modelo:

    kubectl apply \
    --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_WORKLOAD_NAME}-rwo-pvc.yaml" \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}"
    
  5. Aguarde até que o PersistentVolumeClaim vincule e mostre os valores que o operador de infraestrutura precisa para ajustar a política de qualidade de serviço (QoS) de E/S:

    kubectl wait \
    --for=jsonpath='{.status.phase}'=Bound \
    "pvc/${GDCS_WORKLOAD_NAME}-rwo" \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}" \
    --timeout=120s
    BACKING_PVC=$(kubectl get pvc "${GDCS_WORKLOAD_NAME}-rwo" \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}" \
    --output=jsonpath='{.spec.volumeName}')
    echo "BACKING_PVC=${BACKING_PVC} ORG=${GDC_ORG}"
    
  6. Se performance-rwo não estiver disponível no cluster, peça ao operador de infraestrutura para aplicar a política de QoS de alto desempenho (system-performance-<ORG>-admin, 30 IOPS por GiB com um mínimo de 6.148 IOPS) ao volume que apoia o PersistentVolumeClaim. Forneça os valores de BACKING_PVC e ORG que a etapa anterior exibiu. O operador de infraestrutura aplica a política conforme descrito em FILE-R0097. Ela entra em vigor no volume ativo, então você pode continuar com as próximas etapas.

  7. Crie o manifesto para o pod do carregador de modelos:

    cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_MODEL_LOADER_POD_NAME}-pod.yaml"
    apiVersion: v1
    kind: Pod
    metadata:
      name: ${GDCS_MODEL_LOADER_POD_NAME}
    spec:
      containers:
        - name: uploader
          image: ${GDCS_HARBOR_PROJECT_URI}/library/busybox:${GDCS_BUSYBOX_IMAGE_TAG}
          command: ["sleep", "infinity"]
          volumeMounts:
            - name: model-data
              mountPath: ${GDCS_HF_PV_MOUNT_PATH}
      imagePullSecrets:
        - name: ${GDCS_HARBOR_K8S_PULL_SECRET}
      volumes:
        - name: model-data
          persistentVolumeClaim:
            claimName: ${GDCS_WORKLOAD_NAME}-rwo
    EOF
    
  8. Aplique o manifesto para o pod do carregador de modelos:

    kubectl apply \
    --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_MODEL_LOADER_POD_NAME}-pod.yaml" \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}"
    
  9. Aguarde até que o pod do carregador de modelos esteja em execução:

    watch --color --interval 5 --no-title \
    "kubectl get pod/${GDCS_MODEL_LOADER_POD_NAME} \
    --namespace=${GDCS_WORKLOAD_NAMESPACE} | GREP_COLORS='mt=01;92' grep -E --color=always -e '^' -e 'Running'"
    
  10. Faça upload dos pesos do modelo para o PersistentVolume (o script ignora arquivos que já existem com o mesmo tamanho, para que possa ser executado novamente):

    export LOCAL_MODEL_DIR="${GDCS_HF_MODEL_DOWNLOAD_DIR}"
    export REMOTE_MODEL_DIR="${GDCS_HF_PV_MOUNT_PATH}/${GDCS_HF_MODEL_LOWERCASE}"
    export REMOTE_MOUNT_DIR="${GDCS_HF_PV_MOUNT_PATH}"
    
    ${GDCS_IMPLEMENTATION_HOME}/model_weight_upload.sh
    
  11. Exclua o pod do carregador de modelos:

    kubectl delete pod/${GDCS_MODEL_LOADER_POD_NAME} \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}"
    

Servidor de inferência

  1. Crie o manifesto para a implantação do vLLM. O ConfigMap carrega as configurações de vLLM específicas do modelo do ambiente, então o manifesto é o mesmo para cada modelo e opção de GPU:

    cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_WORKLOAD_NAME}-deployment.yaml"
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: ${GDCS_WORKLOAD_NAME}
    data:
      MAX_MODEL_LEN: "${GDCS_VLLM_MAX_MODEL_LEN}"
      MODEL: "${GDCS_HF_PV_MOUNT_PATH}/${GDCS_HF_MODEL_LOWERCASE}"
      PORT: "8000"
      TENSOR_PARALLEL_SIZE: "${GDCS_WORKLOAD_ACCELERATOR_COUNT}"
      VLLM_EXTRA_ARGS: "${GDCS_VLLM_EXTRA_ARGS}"
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ${GDCS_WORKLOAD_NAME}
      labels:
        app: ${GDCS_WORKLOAD_NAME}
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: ${GDCS_WORKLOAD_NAME}
      strategy:
        type: Recreate
      template:
        metadata:
          labels:
            app: ${GDCS_WORKLOAD_NAME}
        spec:
          containers:
            - command:
                - /bin/sh
                - -c
              args:
                - exec vllm serve "\$MODEL" --port="\$PORT" --tensor-parallel-size="\$TENSOR_PARALLEL_SIZE" --max-model-len="\$MAX_MODEL_LEN" \$VLLM_EXTRA_ARGS
              envFrom:
                - configMapRef:
                    name: ${GDCS_WORKLOAD_NAME}
              image: ${GDCS_HARBOR_PROJECT_URI}/vllm/vllm-openai:${GDCS_VLLM_IMAGE_TAG}-fips
              livenessProbe:
                failureThreshold: 3
                httpGet:
                  path: /health
                  port: 8000
                periodSeconds: 20
                timeoutSeconds: 5
              name: vllm
              ports:
                - containerPort: 8000
              readinessProbe:
                failureThreshold: 3
                httpGet:
                  path: /health
                  port: 8000
                periodSeconds: 10
                successThreshold: 1
                timeoutSeconds: 5
              resources:
                limits:
                  ${GDCS_WORKLOAD_ACCELERATOR_TYPE}: "${GDCS_WORKLOAD_ACCELERATOR_COUNT}"
                requests:
                  ${GDCS_WORKLOAD_ACCELERATOR_TYPE}: "${GDCS_WORKLOAD_ACCELERATOR_COUNT}"
              startupProbe:
                httpGet:
                  path: /health
                  port: 8000
                failureThreshold: ${GDCS_VLLM_STARTUP_FAILURE_THRESHOLD}
                periodSeconds: 10
                timeoutSeconds: 5
              volumeMounts:
                - name: model-weights
                  mountPath: ${GDCS_HF_PV_MOUNT_PATH}
                - name: shm
                  mountPath: /dev/shm
          securityContext:
            seLinuxOptions:
              type: spc_t
          imagePullSecrets:
            - name: ${GDCS_HARBOR_K8S_PULL_SECRET}
          volumes:
            - name: model-weights
              persistentVolumeClaim:
                claimName: ${GDCS_WORKLOAD_NAME}-rwo
            - name: shm
              emptyDir:
                medium: Memory
                sizeLimit: "8Gi"
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: ${GDCS_WORKLOAD_NAME}
    spec:
      ports:
        - name: vllm-http
          port: 80
          protocol: TCP
          targetPort: 8000
      selector:
        app: ${GDCS_WORKLOAD_NAME}
      type: LoadBalancer
    EOF
    
  2. Aplique o manifesto para a implantação do vLLM:

    kubectl apply \
    --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_WORKLOAD_NAME}-deployment.yaml" \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}"
    
  3. Crie o manifesto para o vLLM NetworkPolicy:

    cat << EOF > "${GDCS_USER_GUIDE_HOME}/vllm-networkpolicy.yaml" && echo "Successfully created." || echo "Failed to create!"
    apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: allow-vllm-ingress
      namespace: ${GDCS_WORKLOAD_NAMESPACE}
    spec:
      ingress:
      - from:
        - ipBlock:
            cidr: 0.0.0.0/0
        - namespaceSelector: {}
        ports:
        - port: 8000
          protocol: TCP
      podSelector: {}
      policyTypes:
      - Ingress
    EOF
    
  4. Aplique o manifesto para o vLLM NetworkPolicy:

    kubectl apply \
    --filename="${GDCS_USER_GUIDE_HOME}/vllm-networkpolicy.yaml"
    
  1. Aguarde até que o pod esteja em execução:

    watch --color --interval 5 --no-title \
    "kubectl get pods --selector=app=${GDCS_WORKLOAD_NAME} \
    --namespace=${GDCS_WORKLOAD_NAMESPACE} | GREP_COLORS='mt=01;92' grep -E --color=always -e '^' -e 'Running'"
    
  2. Aguarde até que a implantação esteja pronta:

    watch --color --interval 5 --no-title \
    "kubectl get deployment/${GDCS_WORKLOAD_NAME} \
    --namespace=${GDCS_WORKLOAD_NAMESPACE} | GREP_COLORS='mt=01;92' grep -E --color=always -e '^' -e '1/1     1            1'"
    
  3. Opcional: transmita os registros do contêiner para monitorar o progresso da inicialização:

    kubectl logs deployment/${GDCS_WORKLOAD_NAME} \
    --follow \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}"
    

Validação

  1. Recupere o endereço IP do LoadBalancer para vLLM:

    export VLLM_LB_IP=$(kubectl get service/${GDCS_WORKLOAD_NAME} --namespace="${GDCS_WORKLOAD_NAMESPACE}" --output=jsonpath='{.status.loadBalancer.ingress[*].ip}')
    echo "VLLM_LB_IP=${VLLM_LB_IP}"
    
  2. Envie uma solicitação de teste para o vLLM. O valor de max_tokens é GDCS_VLLM_TEST_MAX_TOKENS de env.d/accelerator.sh:

    curl http://${VLLM_LB_IP}/v1/models
    
    curl http://${VLLM_LB_IP}/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "'${GDCS_HF_PV_MOUNT_PATH}/${GDCS_HF_MODEL_LOWERCASE}'",
      "messages": [
        {"role": "user", "content": "Explain Google Distributed Cloud air-gapped briefly."}
      ],
      "max_tokens": '${GDCS_VLLM_TEST_MAX_TOKENS}'
    }'
    
  3. Se o endereço IP do LoadBalancer não puder ser acessado na estação de trabalho, por exemplo, porque nenhum ProjectNetworkPolicy o admite ainda, envie as solicitações por encaminhamento de portas:

    kubectl port-forward service/${GDCS_WORKLOAD_NAME} \
    --namespace="${GDCS_WORKLOAD_NAMESPACE}" 8000:80 &
    PF_PID=$!
    
    sleep 1
    
    curl http://127.0.0.1:8000/v1/models
    
    kill ${PF_PID}