Implantar modelos com pesos personalizados

A implantação de modelos com ponderações personalizadas é uma oferta em prévia. É possível ajustar modelos com base em um conjunto predefinido de modelos básicos e implantar seus modelos personalizados no Model Garden do Gemini Enterprise Agent Platform. Para implantar seus modelos personalizados, faça o upload dos artefatos do modelo para um bucket do Cloud Storage no seu projeto. Essa é uma experiência de um clique no Agent Platform.

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

Modelos compatíveis

A prévia pública 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
  • Gemma-4: 26B-A4B-it, 31B-it, E2B-it, E4B-it
  • Medgemma: 4B, 27B-text
Qwen
  • Qwen2: 1,5 bilhão
  • Qwen2.5: 0,5B, 1,5B, 7B, 32B
  • Qwen3: 0.6B, 1.7B, 4B, 8B, 32B, Qwen3-Coder-480B-A35B-Instruct, Qwen3-Next-80B-A3B-Instruct, Qwen3-Next-80B-A3B-Thinking, Qwen3-VL-8B-Instruct
  • Qwen3.5: 9B
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 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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform 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

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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform 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

    8.

  8. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

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:

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando: 

    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.

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

    Acessar o Model Garden

  2. Clique em Implantar modelo com ponderações personalizadas. O painel Implantar um modelo com pesos personalizados vai aparecer.

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

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

  5. 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:

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

    Acessar o Model Garden

  2. Clique em Mostrar meus endpoints e modelos.

  3. Na tabela Meus endpoints, verifique o endpoint que você acabou de implantar na coluna Nome. A página Detalhes é exibida.

  4. Clique no modelo na tabela Modelos implantados.

  5. 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 um Private Service Connect (PSC), siga estas etapas:

  1. 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"

  2. Clique em + Conectar endpoint. A página Conectar endpoint é exibida.

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

  4. Na seção Detalhes da segmentação, selecione um valor na lista Escopo e outro na lista Tipo de pacote.

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

  6. Abra a seção Diretório de serviços.

  7. Selecione uma região na lista Região.

  8. Selecione um namespace na lista Namespace.

  9. Clique em Adicionar endpoint. A tabela Endpoints é atualizada com uma linha para seu 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, os pesos personalizados 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:

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

    Model Garden

  2. Clique em Mostrar meus endpoints e modelos.

  3. Selecione sua região na lista Região.

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

  5. 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 consulte 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 amostra envia uma mensagem de chat completa ao modelo e recebe uma resposta em um único bloco depois que toda a resposta é gerada. Isso é 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 unária de conclusão de chat. Ao adicionar "stream": true à solicitação, o modelo envia a resposta parte por parte à medida que ela é gerada. Isso é útil para criar um efeito em tempo real, semelhante a uma máquina de escrever, 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

É possível testar 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 Gemini Enterprise Agent Platform