Implantar e fazer inferência no Gemma usando o Model Garden e os endpoints com suporte de GPU da Vertex AI

Neste tutorial, você usa o Model Garden para implantar o modelo aberto Gemma 1B em um endpoint da Vertex AI acelerado por GPU. Implante um modelo em um endpoint antes de ele ser usado para exibir previsões on-line. A implantação de um modelo associa recursos físicos ao modelo para que ele possa exibir previsões on-line com baixa latência.

Depois de implantar o modelo Gemma 1B, faça a inferência do modelo treinado usando o PredictionServiceClient para receber previsões on-line. As previsões on-line são solicitações síncronas feitas em um modelo implantado em um endpoint.

Implantar o Gemma usando o Model Garden

É possível implantar o Gemma 1B usando o card de modelo no console do Google Cloud ou de forma programática.

Para mais informações sobre como configurar o SDK da IA generativa do Google ou a Google Cloud CLI, consulte a visão geral do SDK da IA generativa do Google ou Instalar a Google Cloud CLI.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

  1. Liste os modelos que podem ser implantados e registre o ID do modelo para implantação. Você pode listar os modelos do Hugging Face com suporte no Model Garden e até mesmo filtrar por nomes de modelos. A saída não inclui nenhum modelo ajustado.

    
    import vertexai
    from vertexai import model_garden
    
    # TODO(developer): Update and un-comment below lines
    # PROJECT_ID = "your-project-id"
    vertexai.init(project=PROJECT_ID, location="us-central1")
    
    # List deployable models, optionally list Hugging Face models only or filter by model name.
    deployable_models = model_garden.list_deployable_models(list_hf_models=False, model_filter="gemma")
    print(deployable_models)
    # Example response:
    # ['google/gemma2@gemma-2-27b','google/gemma2@gemma-2-27b-it', ...]
    
  2. Confira as especificações de implantação de um modelo usando o ID do modelo da etapa anterior. É possível conferir o tipo de máquina, o tipo de acelerador e o URI da imagem do contêiner que o Model Garden verificou para um modelo específico.

    
    import vertexai
    from vertexai import model_garden
    
    # TODO(developer): Update and un-comment below lines
    # PROJECT_ID = "your-project-id"
    # model = "google/gemma3@gemma-3-1b-it"
    vertexai.init(project=PROJECT_ID, location="us-central1")
    
    # For Hugging Face modelsm the format is the Hugging Face model name, as in
    # "meta-llama/Llama-3.3-70B-Instruct".
    # Go to https://console.cloud.google.com/vertex-ai/model-garden to find all deployable
    # model names.
    
    model = model_garden.OpenModel(model)
    deploy_options = model.list_deploy_options()
    print(deploy_options)
    # Example response:
    # [
    #   dedicated_resources {
    #     machine_spec {
    #       machine_type: "g2-standard-12"
    #       accelerator_type: NVIDIA_L4
    #       accelerator_count: 1
    #     }
    #   }
    #   container_spec {
    #     ...
    #   }
    #   ...
    # ]
    
  3. Implante um modelo em um endpoint. O Model Garden usa a configuração de implantação padrão, a menos que você especifique outros argumentos e valores.

    
    import vertexai
    from vertexai import model_garden
    
    # TODO(developer): Update and un-comment below lines
    # PROJECT_ID = "your-project-id"
    vertexai.init(project=PROJECT_ID, location="us-central1")
    
    open_model = model_garden.OpenModel("google/gemma3@gemma-3-12b-it")
    endpoint = open_model.deploy(
        machine_type="g2-standard-48",
        accelerator_type="NVIDIA_L4",
        accelerator_count=4,
        accept_eula=True,
    )
    
    # Optional. Run predictions on the deployed endoint.
    # endpoint.predict(instances=[{"prompt": "What is Generative AI?"}])
    

gcloud

Antes de começar, especifique um projeto de cota para executar os comandos a seguir. Os comandos executados são contabilizados nas cotas desse projeto. Para mais informações, consulte Definir o projeto de cota.

  1. Liste os modelos que podem ser implantados executando o comando gcloud ai model-garden models list. Esse comando lista todos os IDs de modelo e quais deles podem ser implantados por você mesmo.

    gcloud ai model-garden models list --model-filter=gemma
    

    Na saída, encontre o ID do modelo a ser implantado. O exemplo a seguir mostra uma saída abreviada.

    MODEL_ID                                      CAN_DEPLOY  CAN_PREDICT
    google/gemma2@gemma-2-27b                     Yes         No
    google/gemma2@gemma-2-27b-it                  Yes         No
    google/gemma2@gemma-2-2b                      Yes         No
    google/gemma2@gemma-2-2b-it                   Yes         No
    google/gemma2@gemma-2-9b                      Yes         No
    google/gemma2@gemma-2-9b-it                   Yes         No
    google/gemma3@gemma-3-12b-it                  Yes         No
    google/gemma3@gemma-3-12b-pt                  Yes         No
    google/gemma3@gemma-3-1b-it                   Yes         No
    google/gemma3@gemma-3-1b-pt                   Yes         No
    google/gemma3@gemma-3-27b-it                  Yes         No
    google/gemma3@gemma-3-27b-pt                  Yes         No
    google/gemma3@gemma-3-4b-it                   Yes         No
    google/gemma3@gemma-3-4b-pt                   Yes         No
    google/gemma3n@gemma-3n-e2b                   Yes         No
    google/gemma3n@gemma-3n-e2b-it                Yes         No
    google/gemma3n@gemma-3n-e4b                   Yes         No
    google/gemma3n@gemma-3n-e4b-it                Yes         No
    google/gemma@gemma-1.1-2b-it                  Yes         No
    google/gemma@gemma-1.1-2b-it-gg-hf            Yes         No
    google/gemma@gemma-1.1-7b-it                  Yes         No
    google/gemma@gemma-1.1-7b-it-gg-hf            Yes         No
    google/gemma@gemma-2b                         Yes         No
    google/gemma@gemma-2b-gg-hf                   Yes         No
    google/gemma@gemma-2b-it                      Yes         No
    google/gemma@gemma-2b-it-gg-hf                Yes         No
    google/gemma@gemma-7b                         Yes         No
    google/gemma@gemma-7b-gg-hf                   Yes         No
    google/gemma@gemma-7b-it                      Yes         No
    google/gemma@gemma-7b-it-gg-hf                Yes         No
    

    A saída não inclui modelos ajustados nem do Hugging Face. Para conferir quais modelos do Hugging Face são compatíveis, adicione a flag --can-deploy-hugging-face-models.

  2. Para conferir as especificações de implantação de um modelo, execute o comando gcloud ai model-garden models list-deployment-config. É possível conferir o tipo de máquina, o tipo de acelerador e o URI da imagem do contêiner que o Model Garden oferece suporte para um modelo específico.

    gcloud ai model-garden models list-deployment-config \
        --model=MODEL_ID
    

    Substitua MODEL_ID pelo ID do modelo do comando de lista anterior, como google/gemma@gemma-2b ou stabilityai/stable-diffusion-xl-base-1.0.

  3. Implante um modelo em um endpoint executando o comando gcloud ai model-garden models deploy. O Model Garden gera um nome de exibição para seu endpoint e usa a configuração de implantação padrão, a menos que você especifique outros argumentos e valores.

    Para executar o comando de forma assíncrona, inclua a flag --asynchronous.

    gcloud ai model-garden models deploy \
        --model=MODEL_ID \
        [--machine-type=MACHINE_TYPE] \
        [--accelerator-type=ACCELERATOR_TYPE] \
        [--endpoint-display-name=ENDPOINT_NAME] \
        [--hugging-face-access-token=HF_ACCESS_TOKEN] \
        [--reservation-affinity reservation-affinity-type=any-reservation] \
        [--reservation-affinity reservation-affinity-type=specific-reservation, key="compute.googleapis.com/reservation-name", values=RESERVATION_RESOURCE_NAME] \
        [--asynchronous]
    

    Substitua os seguintes marcadores:

    • MODEL_ID: o ID do modelo do comando de lista anterior. Para modelos do Hugging Face, use o formato de URL do modelo do Hugging Face, como stabilityai/stable-diffusion-xl-base-1.0.
    • MACHINE_TYPE: define o conjunto de recursos a serem implantados para seu modelo, como g2-standard-4.
    • ACCELERATOR_TYPE: especifica aceleradores a serem adicionados à sua implantação para ajudar a melhorar o desempenho ao trabalhar com cargas de trabalho intensivas, como NVIDIA_L4.
    • ENDPOINT_NAME: um nome para o endpoint implantado da Vertex AI.
    • HF_ACCESS_TOKEN: para modelos do Hugging Face, se o modelo for controlado, forneça um token de acesso.
    • RESERVATION_RESOURCE_NAME: para usar uma reserva do Compute Engine específica, especifique o nome da sua reserva. Se você especificar uma reserva específica, não será possível especificar any-reservation.

    A saída inclui a configuração de implantação usada pelo Model Garden, o ID do endpoint e o ID da operação de implantação, que podem ser usados para verificar o status da implantação.

    Using the default deployment configuration:
     Machine type: g2-standard-12
     Accelerator type: NVIDIA_L4
     Accelerator count: 1
    
    The project has enough quota. The current usage of quota for accelerator type NVIDIA_L4 in region us-central1 is 0 out of 28.
    
    Deploying the model to the endpoint. To check the deployment status, you can try one of the following methods:
    1) Look for endpoint `ENDPOINT_DISPLAY_NAME` at the [Vertex AI] -> [Online prediction] tab in Cloud Console
    2) Use `gcloud ai operations describe OPERATION_ID --region=LOCATION` to find the status of the deployment long-running operation
    
  4. Para ver detalhes sobre sua implantação, execute o comando gcloud ai endpoints list --list-model-garden-endpoints-only:

    gcloud ai endpoints list --list-model-garden-endpoints-only \
        --region=LOCATION_ID
    

    Substitua LOCATION_ID pela região em que você implantou o modelo.

    A saída inclui todos os endpoints criados no Model Garden e informações como ID e nome do endpoint, além de indicar se ele está associado a um modelo implantado. Para encontrar sua implantação, procure o nome do endpoint retornado pelo comando anterior.

REST

Liste todos os modelos implantáveis e receba o ID do modelo a ser implantado. Em seguida, é possível implantar o modelo com a configuração e o endpoint padrão. Ou você pode personalizar a implantação, como definir um tipo de máquina específico ou usar um endpoint dedicado.

Listar modelos que podem ser implantados

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • QUERY_PARAMETERS: para listar modelos do Model Garden, adicione os seguintes parâmetros de consulta listAllVersions=True&filter=can_deploy(true). Para listar modelos do Hugging Face, defina o filtro como alt=json&is_hf_wildcard(true)+AND+labels.VERIFIED_DEPLOYMENT_CONFIG%3DVERIFIED_DEPLOYMENT_SUCCEED&listAllVersions=True.

Método HTTP e URL:

GET https://us-central1-aiplatform.googleapis.com/v1/publishers/*/models?QUERY_PARAMETERS

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
"https://us-central1-aiplatform.googleapis.com/v1/publishers/*/models?QUERY_PARAMETERS"

PowerShell

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/publishers/*/models?QUERY_PARAMETERS" | Select-Object -Expand Content

Você vai receber uma resposta JSON semelhante a esta:

{
  "publisherModels": [
    {
      "name": "publishers/google/models/gemma3",
      "versionId": "gemma-3-1b-it",
      "openSourceCategory": "GOOGLE_OWNED_OSS_WITH_GOOGLE_CHECKPOINT",
      "supportedActions": {
        "openNotebook": {
          "references": {
            "us-central1": {
              "uri": "https://colab.research.google.com/github/GoogleCloudPlatform/vertex-ai-samples/blob/main/notebooks/community/model_garden/model_garden_gradio_streaming_chat_completions.ipynb"
            }
          },
          "resourceTitle": "Notebook",
          "resourceUseCase": "Chat Completion Playground",
          "resourceDescription": "Chat with deployed Gemma 2 endpoints via Gradio UI."
        },
        "deploy": {
          "modelDisplayName": "gemma-3-1b-it",
          "containerSpec": {
            "imageUri": "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250312_0916_RC01",
            "args": [
              "python",
              "-m",
              "vllm.entrypoints.api_server",
              "--host=0.0.0.0",
              "--port=8080",
              "--model=gs://vertex-model-garden-restricted-us/gemma3/gemma-3-1b-it",
              "--tensor-parallel-size=1",
              "--swap-space=16",
              "--gpu-memory-utilization=0.95",
              "--disable-log-stats"
            ],
            "env": [
              {
                "name": "MODEL_ID",
                "value": "google/gemma-3-1b-it"
              },
              {
                "name": "DEPLOY_SOURCE",
                "value": "UI_NATIVE_MODEL"
              }
            ],
            "ports": [
              {
                "containerPort": 8080
              }
            ],
            "predictRoute": "/generate",
            "healthRoute": "/ping"
          },
          "dedicatedResources": {
            "machineSpec": {
              "machineType": "g2-standard-12",
              "acceleratorType": "NVIDIA_L4",
              "acceleratorCount": 1
            }
          },
          "publicArtifactUri": "gs://vertex-model-garden-restricted-us/gemma3/gemma3.tar.gz",
          "deployTaskName": "vLLM 128K context",
          "deployMetadata": {
            "sampleRequest": "{\n    \"instances\": [\n        {\n          \"@requestFormat\": \"chatCompletions\",\n          \"messages\": [\n              {\n                  \"role\": \"user\",\n                  \"content\": \"What is machine learning?\"\n              }\n          ],\n          \"max_tokens\": 100\n        }\n    ]\n}\n"
          }
        },
        ...

Implantar um modelo

Implante um modelo do Model Garden ou do Hugging Face. Também é possível personalizar a implantação especificando outros campos JSON.

Implante um modelo com a configuração padrão.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: uma região em que o modelo é implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL_ID: o ID do modelo a ser implantado, que pode ser obtido listando todos os modelos implantáveis. O ID usa o seguinte formato: publishers/PUBLISHER_NAME/models/ MODEL_NAME@MODEL_VERSION.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy

Corpo JSON da solicitação:

{
  "publisher_model_name": "MODEL_ID",
  "model_config": {
    "accept_eula": "true"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "publisher_model_name": "MODEL_ID",
  "model_config": {
    "accept_eula": "true"
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "publisher_model_name": "MODEL_ID",
  "model_config": {
    "accept_eula": "true"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy" | Select-Object -Expand Content

Você vai receber uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-03-13T21:44:44.538780Z",
      "updateTime": "2025-03-13T21:44:44.538780Z"
    },
    "publisherModel": "publishers/google/models/gemma3@gemma-3-1b-it",
    "destination": "projects/PROJECT_ID/locations/LOCATION",
    "projectNumber": "PROJECT_ID"
  }
}

Implantar um modelo do Hugging Face

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: uma região em que o modelo é implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL_ID: o ID do modelo do Hugging Face a ser implantado, que pode ser obtido listando todos os modelos implantáveis. O ID usa o seguinte formato: PUBLISHER_NAME/MODEL_NAME.
  • ACCESS_TOKEN: se o modelo for restrito, forneça um token de acesso.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy

Corpo JSON da solicitação:

{
  "hugging_face_model_id": "MODEL_ID",
  "hugging_face_access_token": "ACCESS_TOKEN",
  "model_config": {
    "accept_eula": "true"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "hugging_face_model_id": "MODEL_ID",
  "hugging_face_access_token": "ACCESS_TOKEN",
  "model_config": {
    "accept_eula": "true"
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "hugging_face_model_id": "MODEL_ID",
  "hugging_face_access_token": "ACCESS_TOKEN",
  "model_config": {
    "accept_eula": "true"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy" | Select-Object -Expand Content

Você vai receber uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/us-central1LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-03-13T21:44:44.538780Z",
      "updateTime": "2025-03-13T21:44:44.538780Z"
    },
    "publisherModel": "publishers/PUBLISHER_NAME/model/MODEL_NAME",
    "destination": "projects/PROJECT_ID/locations/LOCATION",
    "projectNumber": "PROJECT_ID"
  }
}

Implantar um modelo com personalizações

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: uma região em que o modelo é implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL_ID: o ID do modelo a ser implantado, que pode ser obtido listando todos os modelos implantáveis. O ID usa o seguinte formato: publishers/PUBLISHER_NAME/models/ MODEL_NAME@MODEL_VERSION, como google/gemma@gemma-2b ou stabilityai/stable-diffusion-xl-base-1.0.
  • MACHINE_TYPE: define o conjunto de recursos a serem implantados para o modelo, como g2-standard-4.
  • ACCELERATOR_TYPE: especifica os aceleradores a serem adicionados à implantação para melhorar o desempenho ao trabalhar com cargas de trabalho intensivas, como NVIDIA_L4.
  • ACCELERATOR_COUNT: o número de aceleradores a serem usados na implantação.
  • reservation_affinity_type: para usar uma reserva do Compute Engine na sua implantação, especifique qualquer reserva ou uma específica. Se você especificar esse valor, não especifique spot.
  • spot: se é necessário usar VMs do Spot na implantação.
  • IMAGE_URI: o local da imagem do contêiner a ser usada, como us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20241016_0916_RC00_maas
  • CONTAINER_ARGS: argumentos a serem transmitidos ao contêiner durante a implantação.
  • CONTAINER_PORT: um número de porta para o contêiner.
  • fast_tryout_enabled: ao testar um modelo, você pode usar uma implantação mais rápida. Essa opção está disponível apenas para os modelos mais usados com determinados tipos de máquinas. Se ativada, não é possível especificar configurações de modelo ou implantação.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy

Corpo JSON da solicitação:

{
  "publisher_model_name": "MODEL_ID",
  "deploy_config": {
    "dedicated_resources": {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE",
        "accelerator_type": "ACCELERATOR_TYPE",
        "accelerator_count": ACCELERATOR_COUNT,
        "reservation_affinity": {
          "reservation_affinity_type": "ANY_RESERVATION"
        }
      },
      "spot": "false"
    }
  },
  "model_config": {
    "accept_eula": "true",
    "container_spec": {
      "image_uri": "IMAGE_URI",
      "args": [CONTAINER_ARGS ],
      "ports": [
        {
          "container_port": CONTAINER_PORT
        }
      ]
    }
  },
  "deploy_config": {
    "fast_tryout_enabled": false
  },
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "publisher_model_name": "MODEL_ID",
  "deploy_config": {
    "dedicated_resources": {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE",
        "accelerator_type": "ACCELERATOR_TYPE",
        "accelerator_count": ACCELERATOR_COUNT,
        "reservation_affinity": {
          "reservation_affinity_type": "ANY_RESERVATION"
        }
      },
      "spot": "false"
    }
  },
  "model_config": {
    "accept_eula": "true",
    "container_spec": {
      "image_uri": "IMAGE_URI",
      "args": [CONTAINER_ARGS ],
      "ports": [
        {
          "container_port": CONTAINER_PORT
        }
      ]
    }
  },
  "deploy_config": {
    "fast_tryout_enabled": false
  },
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "publisher_model_name": "MODEL_ID",
  "deploy_config": {
    "dedicated_resources": {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE",
        "accelerator_type": "ACCELERATOR_TYPE",
        "accelerator_count": ACCELERATOR_COUNT,
        "reservation_affinity": {
          "reservation_affinity_type": "ANY_RESERVATION"
        }
      },
      "spot": "false"
    }
  },
  "model_config": {
    "accept_eula": "true",
    "container_spec": {
      "image_uri": "IMAGE_URI",
      "args": [CONTAINER_ARGS ],
      "ports": [
        {
          "container_port": CONTAINER_PORT
        }
      ]
    }
  },
  "deploy_config": {
    "fast_tryout_enabled": false
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:deploy" | Select-Object -Expand Content

Você vai receber uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-03-13T21:44:44.538780Z",
      "updateTime": "2025-03-13T21:44:44.538780Z"
    },
    "publisherModel": "publishers/google/models/gemma3@gemma-3-1b-it",
    "destination": "projects/PROJECT_ID/locations/LOCATION",
    "projectNumber": "PROJECT_ID"
  }
}

Console

  1. No console Google Cloud , acesse a página Model Garden.

    Acessar o Model Garden

  2. Encontre um modelo com suporte que você quer implantar e clique no card dele.

  3. Clique em Implantar para abrir o painel Implantar modelo.

  4. No painel Implantar modelo, especifique os detalhes da implantação.

    1. Use ou modifique os nomes gerados para o modelo e o endpoint.
    2. Selecione um local para criar o endpoint do modelo.
    3. Selecione um tipo de máquina para usar em cada nó da implantação.
    4. Para usar uma reserva do Compute Engine, na seção Configurações de implantação, selecione Avançado.

      No campo Tipo de reserva, selecione uma opção. A reserva precisa corresponder às especificações da máquina selecionada.

      • Usar automaticamente a reserva criada: a Vertex AI seleciona automaticamente uma reserva permitida com propriedades correspondentes. Se não houver capacidade na reserva selecionada automaticamente, a Vertex AI usará o pool de recursos Google Cloudgeral.
      • Selecionar reservas específicas: a Vertex AI usa uma reserva específica. Se não houver capacidade para a reserva selecionada, um erro será gerado.
      • Não usar (padrão): a Vertex AI usa o pool de recursosGoogle Cloud geral. Esse valor tem o mesmo efeito de não especificar uma reserva.
  5. Clique em Implantar.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Implantar um modelo

O exemplo a seguir implanta o modelo gemma-3-1b-it em um novo endpoint da Vertex AI em us-central1 usando as configurações padrão.

terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = "6.45.0"
    }
  }
}

provider "google" {
  region  = "us-central1"
}

resource "google_vertex_ai_endpoint_with_model_garden_deployment" "gemma_deployment" {
  publisher_model_name = "publishers/google/models/gemma3@gemma-3-1b-it"
  location = "us-central1"
  model_config {
    accept_eula = True
  }
}

Para implantar um modelo com personalização, consulte Endpoint da Vertex AI com implantação do Model Garden para mais detalhes.

Aplicar a configuração

terraform init
terraform plan
terraform apply

Depois de aplicar a configuração, o Terraform provisiona um novo endpoint da Vertex AI e implanta o modelo aberto especificado.

Limpeza

Para excluir o endpoint e a implantação do modelo, execute o seguinte comando:

terraform destroy

Fazer inferência do Gemma 1B com o PredictionServiceClient

Depois de implantar o Gemma 1B, use o PredictionServiceClient para receber previsões on-line para o comando: "Por que o céu é azul?"

Parâmetros de código

As amostras de código PredictionServiceClient exigem que você atualize o seguinte.

  • PROJECT_ID: para encontrar o ID do projeto, siga estas etapas.

    1. Acesse a página Boas-vindas no console do Google Cloud .

      Acessar "Boas-vindas"

    2. No seletor de projetos na parte de cima da página, selecione seu projeto.

      O nome, o número e o ID do projeto aparecem depois do título Bem-vindo.

  • ENDPOINT_REGION: a região em que você implantou o endpoint.

  • ENDPOINT_ID: para encontrar o ID do endpoint, consulte-o no console ou execute o comando gcloud ai endpoints list. Você vai precisar do nome e da região do endpoint no painel Implantar modelo.

    Console

    Para conferir os detalhes do endpoint, clique em Previsão on-line > Endpoints e selecione sua região. Anote o número que aparece na coluna ID.

    Acessar o Endpoints

    gcloud

    Para conferir os detalhes do endpoint, execute o comando gcloud ai endpoints list.

    gcloud ai endpoints list \
      --region=ENDPOINT_REGION \
      --filter=display_name=ENDPOINT_NAME
    

    A saída é semelhante a esta:

    Using endpoint [https://us-central1-aiplatform.googleapis.com/]
    ENDPOINT_ID: 1234567891234567891
    DISPLAY_NAME: gemma2-2b-it-mg-one-click-deploy
    

Código de amostra

No exemplo de código da sua linguagem, atualize PROJECT_ID, ENDPOINT_REGION e ENDPOINT_ID. Em seguida, execute o código.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

"""
Sample to run inference on a Gemma2 model deployed to a Vertex AI endpoint with GPU accellerators.
"""

from google.cloud import aiplatform
from google.protobuf import json_format
from google.protobuf.struct_pb2 import Value

# TODO(developer): Update & uncomment lines below
# PROJECT_ID = "your-project-id"
# ENDPOINT_REGION = "your-vertex-endpoint-region"
# ENDPOINT_ID = "your-vertex-endpoint-id"

# Default configuration
config = {"max_tokens": 1024, "temperature": 0.9, "top_p": 1.0, "top_k": 1}

# Prompt used in the prediction
prompt = "Why is the sky blue?"

# Encapsulate the prompt in a correct format for GPUs
# Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.9}}]
input = {"inputs": prompt, "parameters": config}

# Convert input message to a list of GAPIC instances for model input
instances = [json_format.ParseDict(input, Value())]

# Create a client
api_endpoint = f"{ENDPOINT_REGION}-aiplatform.googleapis.com"
client = aiplatform.gapic.PredictionServiceClient(
    client_options={"api_endpoint": api_endpoint}
)

# Call the Gemma2 endpoint
gemma2_end_point = (
    f"projects/{PROJECT_ID}/locations/{ENDPOINT_REGION}/endpoints/{ENDPOINT_ID}"
)
response = client.predict(
    endpoint=gemma2_end_point,
    instances=instances,
)
text_responses = response.predictions
print(text_responses[0])

Node.js

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

async function gemma2PredictGpu(predictionServiceClient) {
  // Imports the Google Cloud Prediction Service Client library
  const {
    // TODO(developer): Uncomment PredictionServiceClient before running the sample.
    // PredictionServiceClient,
    helpers,
  } = require('@google-cloud/aiplatform');
  /**
   * TODO(developer): Update these variables before running the sample.
   */
  const projectId = 'your-project-id';
  const endpointRegion = 'your-vertex-endpoint-region';
  const endpointId = 'your-vertex-endpoint-id';

  // Default configuration
  const config = {maxOutputTokens: 1024, temperature: 0.9, topP: 1.0, topK: 1};
  // Prompt used in the prediction
  const prompt = 'Why is the sky blue?';

  // Encapsulate the prompt in a correct format for GPUs
  // Example format: [{inputs: 'Why is the sky blue?', parameters: {temperature: 0.9}}]
  const input = {
    inputs: prompt,
    parameters: config,
  };

  // Convert input message to a list of GAPIC instances for model input
  const instances = [helpers.toValue(input)];

  // TODO(developer): Uncomment apiEndpoint and predictionServiceClient before running the sample.
  // const apiEndpoint = `${endpointRegion}-aiplatform.googleapis.com`;

  // Create a client
  // predictionServiceClient = new PredictionServiceClient({apiEndpoint});

  // Call the Gemma2 endpoint
  const gemma2Endpoint = `projects/${projectId}/locations/${endpointRegion}/endpoints/${endpointId}`;

  const [response] = await predictionServiceClient.predict({
    endpoint: gemma2Endpoint,
    instances,
  });

  const predictions = response.predictions;
  const text = predictions[0].stringValue;

  console.log('Predictions:', text);
  return text;
}

module.exports = gemma2PredictGpu;

// TODO(developer): Uncomment below lines before running the sample.
// gemma2PredictGpu(...process.argv.slice(2)).catch(err => {
//   console.error(err.message);
//   process.exitCode = 1;
// });

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.gson.Gson;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Gemma2PredictGpu {

  private final PredictionServiceClient predictionServiceClient;

  // Constructor to inject the PredictionServiceClient
  public Gemma2PredictGpu(PredictionServiceClient predictionServiceClient) {
    this.predictionServiceClient = predictionServiceClient;
  }

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "YOUR_PROJECT_ID";
    String endpointRegion = "us-east4";
    String endpointId = "YOUR_ENDPOINT_ID";

    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder()
            .setEndpoint(String.format("%s-aiplatform.googleapis.com:443", endpointRegion))
            .build();
    PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings);
    Gemma2PredictGpu creator = new Gemma2PredictGpu(predictionServiceClient);

    creator.gemma2PredictGpu(projectId, endpointRegion, endpointId);
  }

  // Demonstrates how to run inference on a Gemma2 model
  // deployed to a Vertex AI endpoint with GPU accelerators.
  public String gemma2PredictGpu(String projectId, String region,
               String endpointId) throws IOException {
    Map<String, Object> paramsMap = new HashMap<>();
    paramsMap.put("temperature", 0.9);
    paramsMap.put("maxOutputTokens", 1024);
    paramsMap.put("topP", 1.0);
    paramsMap.put("topK", 1);
    Value parameters = mapToValue(paramsMap);

    // Prompt used in the prediction
    String instance = "{ \"inputs\": \"Why is the sky blue?\"}";
    Value.Builder instanceValue = Value.newBuilder();
    JsonFormat.parser().merge(instance, instanceValue);
    // Encapsulate the prompt in a correct format for GPUs
    // Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.8}}]
    List<Value> instances = new ArrayList<>();
    instances.add(instanceValue.build());

    EndpointName endpointName = EndpointName.of(projectId, region, endpointId);

    PredictResponse predictResponse = this.predictionServiceClient
        .predict(endpointName, instances, parameters);
    String textResponse = predictResponse.getPredictions(0).getStringValue();
    System.out.println(textResponse);
    return textResponse;
  }

  private static Value mapToValue(Map<String, Object> map) throws InvalidProtocolBufferException {
    Gson gson = new Gson();
    String json = gson.toJson(map);
    Value.Builder builder = Value.newBuilder();
    JsonFormat.parser().merge(json, builder);
    return builder.build();
  }
}

Go

Antes de testar esse exemplo, siga as instruções de configuração para Go no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Go.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/protobuf/types/known/structpb"
)

// predictGPU demonstrates how to run interference on a Gemma2 model deployed to a Vertex AI endpoint with GPU accelerators.
func predictGPU(w io.Writer, client PredictionsClient, projectID, location, endpointID string) error {
	ctx := context.Background()

	// Note: client can be initialized in the following way:
	// apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	// client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	// if err != nil {
	// 	return fmt.Errorf("unable to create prediction client: %v", err)
	// }
	// defer client.Close()

	gemma2Endpoint := fmt.Sprintf("projects/%s/locations/%s/endpoints/%s", projectID, location, endpointID)
	prompt := "Why is the sky blue?"
	parameters := map[string]interface{}{
		"temperature":     0.9,
		"maxOutputTokens": 1024,
		"topP":            1.0,
		"topK":            1,
	}

	// Encapsulate the prompt in a correct format for TPUs.
	// Pay attention that prompt should be set in "inputs" field.
	// Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.9}}]
	promptValue, err := structpb.NewValue(map[string]interface{}{
		"inputs":     prompt,
		"parameters": parameters,
	})
	if err != nil {
		fmt.Fprintf(w, "unable to convert prompt to Value: %v", err)
		return err
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint:  gemma2Endpoint,
		Instances: []*structpb.Value{promptValue},
	}

	resp, err := client.Predict(ctx, req)
	if err != nil {
		return err
	}

	prediction := resp.GetPredictions()
	value := prediction[0].GetStringValue()
	fmt.Fprintf(w, "%v", value)

	return nil
}