Usar modelos no Model Garden

Descubra, teste, ajuste e implante modelos usando o Model Garden no consoleGoogle Cloud . Também é possível implantar modelos do Model Garden usando a CLI do Google Cloud.

Enviar comandos de teste

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

    Acessar o Model Garden

  2. Encontre um modelo compatível que você queira testar e clique em Ver detalhes.

  3. Clique em Abrir design de solicitação.

    Você será direcionado à página Design do prompt.

  4. Em Prompt, digite o prompt que você quer testar.

  5. Opcional: configure os parâmetros do modelo.

  6. Clique em Enviar.

Ajustar um modelo

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

    Acessar o Model Garden

  2. Em Pesquisar modelos, digite BERT ou T5-FLAN e clique na lupa.

  3. Clique em Ver detalhes no card do modelo T5-FLAN ou BERT.

  4. Clique em Abrir pipeline de ajuste.

    Você será direcionado para a página de pipelines da Vertex AI.

  5. Para iniciar o ajuste, clique em Criar execução.

Ajustar um notebook

Os cards de modelo para a maioria dos modelos básicos de código aberto e modelos ajustáveis são compatíveis com ajustes em um notebook.

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

    Acessar o Model Garden

  2. Encontre um modelo compatível que você quer ajustar e acesse o card dele.

  3. Clique em Abrir notebook.

Implantar um modelo aberto

É possível implantar um modelo 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 CLI do Google Cloud, consulte a visão geral do SDK da IA generativa do Google ou Instalar a CLI do Google Cloud.

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 filtrá-los por nomes de modelos. A saída não inclui modelos ajustados.

    
    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 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ê.

    gcloud ai model-garden models list
    

    Na saída, encontre o ID do modelo para implantação. 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 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 pode ser usado 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, implante 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.

1. 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=is_deployable(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"
          }
        },
        ...

2. 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 a performance 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 Cloud geral.
    • 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 que 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 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

Implantar um modelo de parceiro e fazer solicitações de previsão

No console do Google Cloud , acesse a página Model Garden e use o filtro Coleções de modelos para ver os Modelos de parceiros de autodeploy. Escolha na lista de modelos de parceiros de autodisponibilização e clique em Ativar para comprar o modelo.

É necessário fazer a implantação nos tipos de máquina exigidos pelo parceiro, conforme descrito na seção "Configuração de hardware recomendada" do card do modelo do Model Garden. Quando implantados, os recursos de veiculação de modelo ficam em um projeto seguro gerenciado pelo Google.

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.

No seu código, substitua os seguintes marcadores:

  • LOCATION: a região em que você planeja implantar o modelo e o endpoint.
  • PROJECT_ID: o ID do projeto.
  • DISPLAY_NAME: um nome descritivo para o recurso associado.
  • PUBLISHER_NAME: o nome do parceiro que fornece o modelo para upload ou implantação.
  • PUBLISHER_MODEL_NAME: o nome do modelo a ser enviado.
  • MACHINE_TYPE: define o conjunto de recursos a serem implantados para seu modelo, como g2-standard-4. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • 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. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • ACCELERATOR_COUNT: o número de aceleradores a serem usados. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • REQUEST_PAYLOAD: os campos e valores a serem incluídos na sua solicitação de previsão. Consulte o card de modelo do Model Garden do parceiro para conferir os campos disponíveis.
from google.cloud import aiplatform

aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Upload a model
model = aiplatform.Model.upload(
    display_name="DISPLAY_NAME_MODEL",
    model_garden_source_model_name = f"publishers/PUBLISHER_NAME/models/PUBLISHER_MODEL_NAME",
)

# Create endpoint
my_endpoint = aiplatform.Endpoint.create(display_name="DISPLAY_NAME_ENDPOINT")

# Deploy model
MACHINE_TYPE = "MACHINE_TYPE"  # @param {type: "string"}
ACCELERATOR_TYPE = "ACCELERATOR_TYPE" # @param {type: "string"}
ACCELERATOR_COUNT = ACCELERATOR_COUNT # @param {type: "number"}

model.deploy(
    endpoint=my_endpoint,
    deployed_model_display_name="DISPLAY_NAME_DEPLOYED_MODEL",
    traffic_split={"0": 100},
    machine_type=MACHINE_TYPE,
    accelerator_type=ACCELERATOR_TYPE,
    accelerator_count=ACCELERATOR_COUNT,
    min_replica_count=1,
    max_replica_count=1,
)

# Unary call for predictions
PAYLOAD = {
    REQUEST_PAYLOAD
}

request = json.dumps(PAYLOAD)

response = my_endpoint.raw_predict(
    body = request,
    headers = {'Content-Type':'application/json'}
)

print(response)

# Streaming call for predictions
PAYLOAD = {
    REQUEST_PAYLOAD
}

request = json.dumps(PAYLOAD)

for stream_response in my_endpoint.stream_raw_predict(
    body = request,
    headers = {'Content-Type':'application/json'}
):
    print(stream_response)

REST

Liste todos os modelos implantáveis e receba o ID do modelo a ser implantado. Em seguida, implante 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.

Nos comandos curl de exemplo, substitua os seguintes marcadores:

  • LOCATION: a região em que você planeja implantar o modelo e o endpoint.
  • PROJECT_ID: o ID do projeto.
  • DISPLAY_NAME: um nome descritivo para o recurso associado.
  • PUBLISHER_NAME: o nome do parceiro que fornece o modelo para upload ou implantação.
  • PUBLISHER_MODEL_NAME: o nome do modelo a ser enviado.
  • ENDPOINT_ID: o ID do endpoint.
  • MACHINE_TYPE: define o conjunto de recursos a serem implantados para seu modelo, como g2-standard-4. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • 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. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • ACCELERATOR_COUNT: o número de aceleradores a serem usados. Você precisa corresponder a uma das configurações fornecidas pelo parceiro.
  • REQUEST_PAYLOAD: os campos e valores a serem incluídos na sua solicitação de previsão. Consulte o card de modelo do Model Garden do parceiro para conferir os campos disponíveis.
  1. Faça upload de um modelo para adicioná-lo ao Model Registry.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapi.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/models:upload \
    -d '{
    "model": {
      "displayName": "DISPLAY_NAME_MODEL",
      "baseModelSource": {
        "modelGardenSource": {
          "publicModelName": f"publishers/PUBLISHER_NAME/models/PUBLISHER_MODEL_NAME",
        }
      }
    }
    }'
    
  2. Crie um endpoint

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapi.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints \
    -d '{
    "displayName": "DISPLAY_NAME_ENDPOINT"
    }'
    
  3. Implante o modelo enviado no endpoint.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapi.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID:deployModel \
    -d '{
    "deployedModel": {
      "model": f"projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID",
      "displayName": "DISPLAY_NAME_DEPLOYED_MODEL",
      "dedicatedResources": {
       "machineSpec": {
          "machineType": "MACHINE_TYPE",
          "acceleratorType": "ACCELERATOR_TYPE",
          "acceleratorCount":"ACCELERATOR_COUNT",
       },
       "minReplicaCount": 1,
       "maxReplicaCount": 1
      },
    },
    "trafficSplit": {
      "0": 100
    }
    }'
    
  4. Depois que o modelo é implantado, é possível fazer uma chamada unária ou de streaming para previsões. Consulte o card de modelo do Model Garden do parceiro para saber quais métodos de API são compatíveis.

    • Exemplo de chamada unária:
    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapi.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID:rawPredict \
    -d 'REQUEST_PAYLOAD'
    
    • Exemplo de chamada de streaming:
    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapi.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID:streamRawPredict \
    -d 'REQUEST_PAYLOAD'
    

Console

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

    Acessar o Model Garden

  2. Para encontrar um modelo específico, digite o nome dele na caixa de pesquisa do Model Garden.

  3. Para conferir todos os modelos que podem ser autoimplantados, na seção Coleções de modelos do painel de filtros, selecione Modelos de parceiros para autoimplantação. A lista resultante inclui todos os modelos de parceiros autodeployáveis.

  4. Clique no nome do modelo para implantar, o que abre o card dele.

  5. Clique em Opções de implantação.

  6. No painel Implantar na Vertex AI, configure a implantação, como local e tipo de máquina.

  7. Clique em Implantar.

Depois que a implantação for concluída, você poderá solicitar previsões usando o SDK ou a API. Outras instruções estão disponíveis na seção "Documentação" do card do modelo.

Ver ou gerenciar um endpoint

Para visualizar e gerenciar seu endpoint, acesse a página Previsão on-line da Vertex AI.

Acessar a previsão on-line

A Vertex AI lista todos os endpoints do seu projeto em uma região específica. Clique em um endpoint para conferir os detalhes, como os modelos implantados no endpoint.

Remover a implantação de modelos e excluir recursos

Para impedir que um modelo implantado use recursos no seu projeto, remova a implantação do modelo do endpoint. É preciso cancelar a implantação de um modelo antes de excluir o endpoint e o modelo.

Cancelar implantação do modelo

Remover a implantação de um modelo do endpoint.

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.

No seu código, substitua:

  • PROJECT_ID pelo ID do projeto;
  • LOCATION com sua região, por exemplo, "us-central1".
  • ENDPOINT_ID com o ID do endpoint
from google.cloud import aiplatform

aiplatform.init(project=PROJECT_ID, location=LOCATION)

# To find out which endpoints are available, un-comment the line below:
# endpoints = aiplatform.Endpoint.list()

endpoint = aiplatform.Endpoint(ENDPOINT_ID)
endpoint.undeploy_all()

gcloud

Nesses comandos, substitua:

  • PROJECT_ID pelo nome do projeto;
  • LOCATION_ID pela região em que você implantou o modelo e o endpoint.
  • ENDPOINT_ID com o ID do endpoint
  • MODEL_ID com o ID do modelo do comando "list model"
  • DEPLOYED_MODEL_ID com o ID do modelo implantado
  1. Encontre o ID do endpoint associado à sua implantação executando o comando gcloud ai endpoints list.

    gcloud ai endpoints list \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    
  2. Encontre o ID do modelo executando o comando gcloud ai models list.

    gcloud ai models list \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    
  3. Use o ID do modelo do comando anterior para receber o ID do modelo implantado executando o comando gcloud ai models describe.

    gcloud ai models describe MODEL_ID \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    

    A saída abreviada é parecida com o exemplo a seguir. Na saída, o ID é chamado de deployedModelId.

    Using endpoint [https://us-central1-aiplatform.googleapis.com/]
    artifactUri: [URI removed]
    baseModelSource:
      modelGardenSource:
        publicModelName: publishers/google/models/gemma2
    ...
    deployedModels:
    -   deployedModelId: '1234567891234567891'
      endpoint: projects/12345678912/locations/us-central1/endpoints/12345678912345
    displayName: gemma2-2b-it-12345678912345
    etag: [ETag removed]
    modelSourceInfo:
      sourceType: MODEL_GARDEN
    name: projects/123456789123/locations/us-central1/models/gemma2-2b-it-12345678912345
    ...
    
  4. Execute o comando gcloud ai endpoints undeploy-model para desfazer a implantação do modelo do endpoint usando o ID do endpoint e o ID do modelo implantado dos comandos anteriores.

    gcloud ai endpoints undeploy-model ENDPOINT_ID \
        --project=PROJECT_ID \
        --region=LOCATION_ID \
        --deployed-model-id=DEPLOYED_MODEL_ID
    

    Esse comando não produz saída.

Console

  1. No console Google Cloud , acesse a guia Endpoints na página Previsão on-line.

    Acessar o Endpoints

  2. Na lista suspensa Região, escolha a região em que seu endpoint está localizado.

  3. Clique no nome do endpoint para abrir a página de detalhes.

  4. Na linha do modelo, clique em Ações e selecione Cancelar a implantação do modelo no endpoint.

  5. Na caixa de diálogo Cancelar a implantação do modelo do endpoint, clique em Cancelar a implantação.

Excluir endpoints

Exclua o endpoint da Vertex AI associado à implantação do modelo.

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.

No seu código, substitua:

  • PROJECT_ID pelo ID do projeto;
  • LOCATION com sua região, por exemplo, "us-central1".
  • ENDPOINT_ID com o ID do endpoint
from google.cloud import aiplatform

aiplatform.init(project=PROJECT_ID, location=LOCATION)

# To find out which endpoints are available, un-comment the line below:
# endpoints = aiplatform.Endpoint.list()

endpoint = aiplatform.Endpoint(ENDPOINT_ID)
endpoint.delete()

gcloud

Nesses comandos, substitua:

  • PROJECT_ID pelo nome do projeto;
  • LOCATION_ID pela região em que você implantou o modelo e o endpoint.
  • ENDPOINT_ID com o ID do endpoint
  1. Para excluir o ID do endpoint, execute o comando gcloud ai endpoints list. Esse comando lista os IDs de todos os endpoints no seu projeto.

    gcloud ai endpoints list \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    
  2. Execute o comando gcloud ai endpoints delete para excluir o endpoint.

    gcloud ai endpoints delete ENDPOINT_ID \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    

    Quando solicitado, digite y para confirmar. Esse comando não produz saída.

Console

  1. No console Google Cloud , acesse a guia Endpoints na página Previsão on-line.

    Acessar o Endpoints

  2. Na lista suspensa Região, escolha a região em que seu endpoint está localizado.

  3. No final da linha do endpoint, clique em Ações e selecione Excluir endpoint.

  4. No prompt de confirmação, clique em Confirmar.

Excluir modelos

Exclua o recurso de modelo associado à implantação.

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.

No seu código, substitua:

  • PROJECT_ID pelo ID do projeto;
  • LOCATION com sua região, por exemplo, "us-central1".
  • MODEL_ID com o ID do modelo
from google.cloud import aiplatform

aiplatform.init(project=PROJECT_ID, location=LOCATION)

# To find out which models are available in Model Registry, un-comment the line below:
# models = aiplatform.Model.list()

model = aiplatform.Model(MODEL_ID)
model.delete()

gcloud

Nesses comandos, substitua:

  • PROJECT_ID pelo nome do projeto;
  • LOCATION_ID pela região em que você implantou o modelo e o endpoint.
  • MODEL_ID com o ID do modelo do comando "list model"
  1. Para encontrar o ID do modelo a ser excluído, execute o comando gcloud ai models list.

    gcloud ai models list \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    
  2. Execute o comando gcloud ai models delete para excluir o modelo informando o ID e o local dele.

    gcloud ai models delete MODEL_ID \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    

Console

  1. Acesse a página Registro de modelo na seção "Vertex AI" do console Google Cloud .

    Acessar a página "Modelo de registro"

  2. Na lista suspensa Região, escolha a região em que você implantou o modelo.

  3. Na linha do seu modelo, clique em Ações e selecione Excluir modelo.

    Quando você exclui o modelo, todas as versões e avaliações de modelo associadas são excluídas do seu projeto Google Cloud .

  4. No prompt de confirmação, clique em Excluir.

Confira exemplos de código

A maioria dos cards de modelos de soluções específicas de tarefas contém amostras de código que podem ser copiadas e testadas.

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

    Acessar o Model Garden

  2. Encontre um modelo compatível para ver amostras de código e clique na guia Documentação.

  3. A página rola para a seção de documentação com o código de amostra incorporado.

Criar um app Vision

Os cartões para modelos de visão computacional aplicáveis são compatíveis com a criação de um aplicativo de visão.

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

    Acessar o Model Garden

  2. Na seção "Soluções específicas para tarefas", encontre um modelo de visão que você queira usar para criar um aplicativo de visão e clique em Visualizar detalhes.

  3. Clique em Criar app.

    Você será levado à Vertex AI Vision.

  4. Em Nome do aplicativo, insira um nome para seu aplicativo e clique em Continuar.

  5. Selecione um plano de faturamento e clique em Criar.

    Você será levado ao Vertex AI Vision Studio, onde poderá continuar criando seu aplicativo de visão computacional.