Esta página foi traduzida pela API Cloud Translation.

Implantar modelos com pesos personalizados

A implantação de modelos com pesos personalizados é uma oferta em prévia. É possível ajustar modelos com base em um conjunto predefinido de modelos de base e implantar os modelos personalizados no Model Garden da Vertex AI. É possível implantar seus modelos personalizados usando a importação de ponderações personalizadas. Para isso, faça upload dos artefatos do modelo para um bucket do Cloud Storage no seu projeto, o que é uma experiência de um clique na Vertex AI.

O suporte do VPC Service Controls para ponderações personalizadas está disponível.

Modelos compatíveis

O pré-lançamento público de Implantar modelos com ponderações personalizadas é compatível com os seguintes modelos de base:

Nome do modelo	Versão
Llama	Llama-2: 7B, 13B Llama-3.1: 8B, 70B Llama-3.2: 1B, 3B Llama-4: Scout-17B, Maverick-17B CodeLlama-13B
Gemma	Gemma-2: 9B, 27B Gemma-3: 1B, 4B, 3-12B, 27B Medgemma: 4B, 27B-text
Qwen	Qwen2: 1,5 bilhão Qwen2.5: 0,5B, 1,5B, 7B, 32B Qwen3: 0,6B, 1,7B, 8B, 32B, Qwen3-Coder-480B-A35B-Instruct, Qwen3-Next-80B-A3B-Instruct, Qwen3-Next-80B-A3B-Thinking
Deepseek	Deepseek-R1 Deepseek-V3 DeepSeek-V3.1
Mistral e Mixtral	Mistral-7B-v0.1 Mixtral-8x7B-v0.1 Mistral-Nemo-Base-2407
Phi-4	Phi-4-reasoning
OSS da OpenAI	gpt-oss: 20B, 120B

Limitações

As ponderações personalizadas não são compatíveis com a importação de modelos quantizados.

Arquivos de modelo

Você precisa fornecer os arquivos do modelo no formato de pesos do Hugging Face. Para mais informações sobre o formato de pesos do Hugging Face, consulte Usar modelos do Hugging Face.

Se os arquivos obrigatórios não forem fornecidos, a implantação do modelo poderá falhar.

Esta tabela lista os tipos de arquivos de modelo, que dependem da arquitetura do modelo:

Conteúdo do arquivo do modelo	Tipo de arquivo
Configuração do modelo	`config.json`
Pesos do modelo	`.safetensors` `.bin`
Índice de pesos	`*.index.json`
Arquivos do tokenizador	`tokenizer.model` `tokenizer.json` `tokenizer_config.json`

Locais

É possível implantar modelos personalizados em todas as regiões usando os serviços do Model Garden.

Pré-requisitos

Esta seção demonstra como implantar seu modelo personalizado.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

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

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

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

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Neste tutorial, presumimos que você esteja usando o Cloud Shell para interagir com Google Cloud. Se você quiser usar um shell diferente em vez do Cloud Shell, execute a seguinte configuração extra:

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```

Implantar o modelo personalizado

Esta seção demonstra como implantar seu modelo personalizado.

Se você estiver usando a interface de linha de comando (CLI), Python ou JavaScript, substitua as seguintes variáveis por um valor para que as amostras de código funcionem:

REGION: sua região. Por exemplo, uscentral1.
MODEL_GCS: seu modelo do Google Cloud . Por exemplo, gs://custom-weights-fishfooding/meta-llama/Llama-3.2-1B-Instruct.
PROJECT_ID: o ID do projeto.
MODEL_ID: o ID do modelo.
MACHINE_TYPE: o tipo de máquina. Por exemplo, g2-standard-12.
ACCELERATOR_TYPE: o tipo de acelerador. Por exemplo, NVIDIA_L4.
ACCELERATOR_COUNT: a contagem de aceleradores.
PROMPT: seu comando de texto.

Console

As etapas a seguir mostram como usar o console do Google Cloud para implantar seu modelo com ponderações personalizadas.

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

Acessar o Model Garden
Clique em Implantar modelo com ponderações personalizadas. O painel Implantar um modelo com pesos personalizados vai aparecer.
Na seção Origem do modelo, faça o seguinte:
1. Clique em Procurar, escolha o bucket em que o modelo está armazenado e clique em Selecionar.
2. Opcional: insira o nome do modelo no campo Nome do modelo.
Na seção Configurações de implantação, faça o seguinte:
1. No campo Região, selecione sua região e clique em OK.
2. No campo Especificação da máquina, selecione a especificação da máquina, que é usada para implantar o modelo.
3. Opcional: no campo Nome do endpoint, o endpoint do modelo aparece por padrão. No entanto, é possível inserir um nome de endpoint diferente no campo.
4. Se o projeto exigir o VPC-SC ou se você preferir o acesso particular, selecione Particular (Private Service Connect) no campo Acesso ao endpoint. Caso contrário, selecione Público.
5. Se você usa um Private Service Connect, insira os IDs dos projetos no campo IDs dos projetos em que os clientes de consulta são executados ou clique em Selecionar IDs dos projetos para mostrar uma caixa de diálogo com os IDs.
  
  Se você clicar em Selecionar IDs do projeto, faça o seguinte:
  1. Encontre o projeto que contém o código que está tentando acessar o modelo.
  2. Clique na caixa de seleção do projeto.
  3. Clique em Selecionar.
Clique em Implantar.

CLI da gcloud

Este comando demonstra como implantar o modelo em uma região específica.

gcloud ai model-garden models deploy --model=${MODEL_GCS} --region ${REGION}

Esse comando demonstra como implantar o modelo em uma região específica com o tipo de máquina, o tipo de acelerador e a contagem de aceleradores. Se você quiser selecionar uma configuração de máquina específica, defina todos os três campos.

gcloud ai model-garden models deploy --model=${MODEL_GCS} --machine-type=${MACHINE_TYE} --accelerator-type=${ACCELERATOR_TYPE} --accelerator-count=${ACCELERATOR_COUNT} --region ${REGION}

Python

import vertexai
from google.cloud import aiplatform
from vertexai.preview import model_garden

vertexai.init(project=${PROJECT_ID}, location=${REGION})
custom_model = model_garden.CustomModel(
  gcs_uri=GCS_URI,
)
endpoint = custom_model.deploy(
  machine_type="${MACHINE_TYPE}",
  accelerator_type="${ACCELERATOR_TYPE}",
  accelerator_count="${ACCELERATOR_COUNT}",
  model_display_name="custom-model",
  endpoint_display_name="custom-model-endpoint")

endpoint.predict(instances=[{"prompt": "${PROMPT}"}], use_dedicated_endpoint=True)

Como alternativa, não é necessário transmitir um parâmetro para o método custom_model.deploy().

import vertexai
from google.cloud import aiplatform
from vertexai.preview import model_garden

vertexai.init(project=${PROJECT_ID}, location=${REGION})
custom_model = model_garden.CustomModel(
  gcs_uri=GCS_URI,
)
endpoint = custom_model.deploy()

endpoint.predict(instances=[{"prompt": "${PROMPT}"}], use_dedicated_endpoint=True)

curl


curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}:deploy" \
  -d '{
    "custom_model": {
    "gcs_uri": "'"${MODEL_GCS}"'"
  },
  "destination": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'",
  "model_config": {
     "model_user_id": "'"${MODEL_ID}"'",
  },
}'

Como alternativa, use a API para definir explicitamente o tipo de máquina.


curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}:deploy" \
  -d '{
    "custom_model": {
    "gcs_uri": "'"${MODEL_GCS}"'"
  },
  "destination": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'",
  "model_config": {
     "model_user_id": "'"${MODEL_ID}"'",
  },
  "deploy_config": {
    "dedicated_resources": {
      "machine_spec": {
        "machine_type": "'"${MACHINE_TYPE}"'",
        "accelerator_type": "'"${ACCELERATOR_TYPE}"'",
        "accelerator_count": '"${ACCELERATOR_COUNT}"'
      },
      "min_replica_count": 1
    }
  }
}'

Implantar usando a API

O VPC Service Controls só funciona com o endpoint dedicado particular. Portanto, defina o private_service_connect_config no exemplo de código a seguir, que demonstra como fazer a implantação usando a API:

curl

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT/locations/us-central1:deploy" \
    -d '{
      "custom_model": {
        "model_id": "test-mg-deploy-092301",
        "gcs_uri": "gs://YOUR_GCS_BUCKET"
      },
      "destination": "projects/YOUR_PROJECT/locations/us-central1",
      "endpoint_config": {
        "endpoint_display_name": "psc-ep1",
        "private_service_connect_config": {
          "enablePrivateServiceConnect": true,
          "projectAllowlist": ["YOUR_PROJECT"]
        }
      },
      "deploy_config": {
        "dedicated_resources": {
          "machine_spec": {
            "machine_type": "g2-standard-24",
            "accelerator_type": "NVIDIA_L4",
            "accelerator_count": 2
          },
          "min_replica_count": 1,
          "max_replica_count": 1
        }
      }
    }'

Receber o ID do endpoint e do modelo usando o console Google Cloud

Depois que a implantação for concluída, siga estas etapas:

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

Acessar o Model Garden
Clique em Mostrar meus endpoints e modelos.
Na tabela Meus endpoints, verifique o endpoint que você acabou de implantar na coluna Nome. A página Detalhes é exibida.
Clique no modelo na tabela Modelos implantados.
Selecione a página Detalhes da versão. O ID do modelo aparece na linha Variáveis de ambiente da tabela.

Configurar um Private Service Connect

Você está adicionando um novo endpoint para acessar as APIs Google . Esse endpoint pode ser usado em todas as regiões da rede VPC selecionada. Além disso, considere o seguinte:

Os clientes em redes conectadas à rede VPC do endpoint usando conectividade híbrida podem acessar o endpoint. Para mais informações, consulte Acessar APIs doGoogle por endpoints.
Os clientes em redes VPC com peering não podem acessar o endpoint.

Listar endpoint para receber o anexo de serviço

Este exemplo de código demonstra como listar um endpoint para receber um anexo de serviço.

curl

$ curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT/locations/us-central1/endpoints/YOUR_ENDPOINT_ID"

Esta é a resposta do endpoint de lista.

  {
  "name": "projects/440968033208/locations/us-central1/endpoints/mg-endpoint-2c6ae2be-1491-43fe-b179-cb5a63e2c955",
  "displayName": "psc-ep1",
  "deployedModels": [
    {
      "id": "4026753529031950336",
      "model": "projects/440968033208/locations/us-central1/models/mg-custom-1758645924",
      "displayName": "null-null-null-1758645933",
      "createTime": "2025-09-23T16:45:45.169195Z",
      "dedicatedResources": {
        "machineSpec": {
          "machineType": "g2-standard-24",
          "acceleratorType": "NVIDIA_L4",
          "acceleratorCount": 2
        },
        "minReplicaCount": 1,
        "maxReplicaCount": 1
      },
      "enableContainerLogging": true,
      "privateEndpoints": {
        "serviceAttachment": "projects/qdb392d34e2a11149p-tp/regions/us-central1/serviceAttachments/gkedpm-fbbc4061323c91c14ab4d961a2f8b0"
      },
      "modelVersionId": "1",
      "status": {
        "lastUpdateTime": "2025-09-23T17:26:10.031652Z",
        "availableReplicaCount": 1
      }
    }
  ],
  "trafficSplit": {
    "4026753529031950336": 100
  },
  "etag": "AMEw9yPIWQYdbpHu6g6Mhpu1_10J062_oR9Jw9txrp8dFFbel7odLgSK8CGIogAUkR_r",
  "createTime": "2025-09-23T16:45:45.169195Z",
  "updateTime": "2025-09-23T17:13:36.320873Z",
  "privateServiceConnectConfig": {
    "enablePrivateServiceConnect": true,
    "projectAllowlist": [
      "ucaip-vpc-s-1605069239-dut-24"
    ]
  }
}

Fazer uma conexão do Private Service Connect

Para fazer uma conexão do Private Service Connect (PSC), siga estas etapas:

No console do Google Cloud , acesse a página Private Service Connect. A página Endpoints conectados é exibida.

Acessar a página "Private Service Connect"
Clique em + Conectar endpoint. A página Conectar endpoint é exibida.
Selecione uma opção no campo Destino. Você pode escolher APIs do Google que oferecem acesso à maioria das APIs e serviços do Google ou Serviço publicado que oferece acesso a um serviço publicado.
Na seção Detalhes da segmentação, selecione um valor na lista Escopo e outro na lista Tipo de pacote.
Na seção Detalhes do endpoint, faça o seguinte:
1. Insira um nome no campo Nome do endpoint.
2. Selecione um valor na lista Rede. Selecione uma rede VPC no seu projeto. Se você precisar criar um endpoint do PSC em um projeto de serviço que use uma rede VPC compartilhada em um projeto host, use a Google Cloud CLI ou envie uma solicitação de API.
3. Selecione um valor na lista Endereço IP.
Expanda a seção Diretório de serviços.
Selecione uma região na lista Região.
Selecione um namespace na lista Namespace.
Clique em Adicionar endpoint. A tabela Endpoints é atualizada com uma linha para o novo endpoint.

Fazer uma consulta

Nesta seção, explicamos como criar um endpoint público e um endpoint particular.

Fazer uma consulta a um endpoint público

Depois que o modelo for implantado, as ponderações personalizadas vão oferecer suporte ao endpoint público dedicado. É possível enviar consultas usando a API ou o SDK.

Antes de enviar consultas, você precisa receber o URL do endpoint, o ID do endpoint e o ID do modelo, que estão disponíveis no console do Google Cloud .

Siga estas etapas para acessar as informações:

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

Model Garden
Clique em Mostrar meus endpoints e modelos.
Selecione sua região na lista Região.
Para acessar o ID e o URL do endpoint, clique no endpoint na seção Meus endpoints.

O ID do endpoint é exibido no campo ID do endpoint.

O URL do endpoint público é exibido no campo Endpoint dedicado.
Para receber o ID do modelo, encontre seu modelo na seção Modelos implantados e siga estas etapas:
1. Clique no nome do modelo implantado no campo Modelo.
2. Clique em Detalhes da versão. O ID do modelo aparece no campo ID do modelo.

Depois de receber as informações do endpoint e do modelo implantado, consulte os exemplos de código a seguir para saber como enviar uma solicitação de inferência ou acesse Enviar uma solicitação de inferência on-line para um endpoint público dedicado.

API

Os exemplos de código a seguir demonstram diferentes maneiras de usar a API com base no seu caso de uso.

Conclusão de chat (unária)

Esta solicitação de exemplo envia uma mensagem de chat completa ao modelo e recebe uma resposta em um único bloco depois que toda a resposta é gerada. É semelhante a enviar uma mensagem de texto e receber uma única resposta completa.

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT_ID}/chat/completions" \
    -d '{
    "model": "'"${MODEL_ID}"'",
    "temperature": 0,
    "top_p": 1,
    "max_tokens": 154,
    "ignore_eos": true,
    "messages": [
      {
        "role": "user",
        "content": "How to tell the time by looking at the sky?"
      }
    ]
  }'

Conclusão de chat (streaming)

Essa solicitação é a versão de streaming da solicitação de conclusão de chat unária. Ao adicionar "stream": true à solicitação, o modelo envia a resposta parte por parte à medida que ela é gerada. Isso é útil para criar um efeito de máquina de escrever em tempo real em um aplicativo de chat.

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \  "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT_ID}/chat/completions" \
    -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "temperature": 0,
    "top_p": 1,
    "max_tokens": 154,
    "ignore_eos": true,
    "messages": [
      {
        "role": "user",
        "content": "How to tell the time by looking at the sky?"
      }
    ]
  }'

Previsão

Essa solicitação envia um comando direto para receber uma inferência de um modelo. Isso é usado com frequência para tarefas que não são necessariamente conversacionais, como resumo ou classificação de texto.

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT_ID}:predict" \
    -d '{
    "instances": [
      {
        "prompt": "How to tell the time by looking at the sky?",
        "temperature": 0,
        "top_p": 1,
        "max_tokens": 154,
        "ignore_eos": true
      }
    ]
  }'

Previsão bruta

Essa solicitação é uma versão de streaming da solicitação Predict. Ao usar o endpoint :streamRawPredict e incluir "stream": true, essa solicitação envia um comando direto e recebe a saída do modelo como um fluxo contínuo de dados à medida que são gerados, o que é semelhante à solicitação de conclusão de chat por streaming.

  curl -X POST \
    -N \
    --output - \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT_ID}:streamRawPredict" \
    -d '{
    "instances": [
      {
        "prompt": "How to tell the time by looking at the sky?",
        "temperature": 0,
        "top_p": 1,
        "max_tokens": 154,
        "ignore_eos": true,
        "stream": true
      }
    ]
  }'

SDK

Este exemplo de código usa o SDK para enviar uma consulta a um modelo e receber uma resposta dele.

  from google.cloud import aiplatform

  project_id = ""
  location = ""
  endpoint_id = "" # Use the short ID here

  aiplatform.init(project=project_id, location=location)

  endpoint = aiplatform.Endpoint(endpoint_id)

  prompt = "How to tell the time by looking at the sky?"
  instances=[{"text": prompt}]
  response = endpoint.predict(instances=instances, use_dedicated_endpoint=True)
  print(response.predictions)

Fazer uma consulta para um endpoint particular

Teste sua consulta usando um notebook ou uma VM no projeto permitido.

Com esta consulta de exemplo, você pode substituir variáveis pelo seu IP, projeto, ID do endpoint e ID do modelo (obtido na etapa de implantação acima).

curl

Conclusão de chat

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" 'https://YOUR_IP/v1beta1/projects/YOUR_PROJECT_ID/locations/YOUR_LOCATION/endpoints/YOUR_ENDPOINT_ID/chat/completions' -d '{ "model": "YOUR_MODEL_ID", "max_tokens": 300, "messages": [{ "role": "user", "content": "how to tell the time by looking at sky?" }]}'

Prever

$ curl -k -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" 'https:/YOUR_IP/v1beta1/projects/YOUR_PROJECT_ID/locations/YOUR_LOCATION/endpoints/YOUR_ENDPOINT_ID:predict' -d '{
  "instances": [
    {
      "prompt": "Summarize Goog stock performance",
      "temperature": 0,
      "top_p": 1,
      "max_tokens": 154,
      "ignore_eos": true
    }
  ]
}'

Para outro exemplo de como usar a API, consulte o notebook Importar ponderações personalizadas.

Saiba mais sobre os modelos autoimplantados na Vertex AI

Para mais informações sobre endpoints particulares dedicados de previsão on-line da Vertex AI, consulte Usar endpoints particulares dedicados com base no Private Service Connect para inferência on-line.
Para mais informações sobre modelos autogerenciados, consulte Visão geral dos modelos autogerenciados.
Para mais informações sobre o Model Garden, consulte Visão geral do Model Garden.
Para mais informações sobre a implantação de modelos, consulte Usar modelos no Model Garden.
Usar modelos abertos do Gemma
Usar modelos abertos de Llama
Usar modelos abertos do Hugging Face

Implantar modelos com pesos personalizados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Modelos compatíveis

Limitações

Arquivos de modelo

Locais

Pré-requisitos

Antes de começar

Implantar o modelo personalizado

Console

CLI da gcloud

Python

curl

Implantar usando a API

curl

Receber o ID do endpoint e do modelo usando o console Google Cloud

Configurar um Private Service Connect

Listar endpoint para receber o anexo de serviço

curl

Fazer uma conexão do Private Service Connect

Fazer uma consulta

Fazer uma consulta a um endpoint público

API

SDK

Fazer uma consulta para um endpoint particular

curl

Saiba mais sobre os modelos autoimplantados na Vertex AI

Implantar modelos com pesos personalizados