Esegui il deployment di modelli con ponderazioni personalizzate

Il deployment di modelli con pesi personalizzati è un'offerta in anteprima. Puoi ottimizzare i modelli in base a un insieme predefinito di modelli di base ed eseguire il deployment dei modelli personalizzati su Vertex AI Model Garden. Puoi eseguire il deployment dei tuoi modelli personalizzati utilizzando l'importazione di pesi personalizzati caricando gli artefatti del modello in un bucket Cloud Storage nel tuo progetto, un'esperienza con un solo clic in Vertex AI.

È disponibile il supporto dei Controlli di servizio VPC per i pesi personalizzati.

Modelli supportati

L'anteprima pubblica di Esegui il deployment di modelli con pesi personalizzati è supportata dai seguenti modelli di base:

Nome modello Versione
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 miliardi
  • Qwen2.5: 0,5 miliardi, 1,5 miliardi, 7 miliardi, 32 miliardi
  • Qwen3: 0,6 B, 1,7 B, 8 B, 32 B, 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
OpenAI OSS
  • gpt-oss: 20B, 120B

Limitazioni

I pesi personalizzati non supportano l'importazione di modelli quantizzati.

File del modello

Devi fornire i file del modello nel formato dei pesi di Hugging Face. Per ulteriori informazioni sul formato dei pesi di Hugging Face, consulta Utilizzare i modelli Hugging Face.

Se i file richiesti non vengono forniti, il deployment del modello potrebbe non riuscire.

Questa tabella elenca i tipi di file del modello, che dipendono dall'architettura del modello:

Contenuti del file modello Tipo di file
Configurazione del modello
  • config.json
Pesi del modello
  • *.safetensors
  • *.bin
Indice di pesi
  • *.index.json
File del tokenizzatore
  • tokenizer.model
  • tokenizer.json
  • tokenizer_config.json

Località

Puoi eseguire il deployment di modelli personalizzati in tutte le regioni dai servizi Model Garden.

Prerequisiti

Questa sezione mostra come eseguire il deployment del modello personalizzato.

Prima di iniziare

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

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

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

    8.

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

    9. Questo tutorial presuppone che tu stia utilizzando Cloud Shell per interagire con Google Cloud. Se vuoi utilizzare una shell diversa da Cloud Shell, esegui la seguente configurazione aggiuntiva:

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    Esegui il deployment del modello personalizzato

    Questa sezione mostra come eseguire il deployment del modello personalizzato.

    Se utilizzi l'interfaccia a riga di comando (CLI), Python o JavaScript, sostituisci le seguenti variabili con un valore per far funzionare gli esempi di codice:

    • REGION: la tua regione. Ad esempio: uscentral1.
    • MODEL_GCS: il tuo modello Google Cloud . Ad esempio: gs://custom-weights-fishfooding/meta-llama/Llama-3.2-1B-Instruct.
    • PROJECT_ID: il tuo ID progetto.
    • MODEL_ID: il tuo ID modello.
    • MACHINE_TYPE: il tipo di macchina. Ad esempio g2-standard-12.
    • ACCELERATOR_TYPE: il tipo di acceleratore. Ad esempio NVIDIA_L4.
    • ACCELERATOR_COUNT: il numero di acceleratori.

    • PROMPT: il prompt di testo.

    Console

    I seguenti passaggi mostrano come utilizzare la console Google Cloud per eseguire il deployment del modello con pesi personalizzati.

    1. Nella console Google Cloud , vai alla pagina Model Garden.

      Vai a Model Garden

    2. Fai clic su Esegui il deployment del modello con pesi personalizzati. Viene visualizzato il riquadro Esegui il deployment di un modello con pesi personalizzati.

    3. Nella sezione Origine modello, segui questi passaggi:

      1. Fai clic su Sfoglia, scegli il bucket in cui è memorizzato il modello e fai clic su Seleziona.

      2. (Facoltativo) Inserisci il nome del modello nel campo Nome modello.

    4. Nella sezione Impostazioni di deployment, segui questi passaggi:

      1. Nel campo Regione, seleziona la tua regione e fai clic su Ok.

      2. Nel campo Specifica macchina, seleziona la specifica della macchina, che viene utilizzata per il deployment del modello.

      3. (Facoltativo) Nel campo Nome endpoint, l'endpoint del modello viene visualizzato per impostazione predefinita. Tuttavia, puoi inserire un nome endpoint diverso nel campo.

      4. Se il tuo progetto applica VPC-SC o se preferisci l'accesso privato, seleziona Privato (Private Service Connect) dal campo Accesso all'endpoint. In caso contrario, seleziona Pubblico.

      5. Se utilizzi Private Service Connect, inserisci gli ID progetto nel campo ID progetto, ovvero i progetti in cui vengono eseguiti i client di query, oppure fai clic su Seleziona ID progetto per visualizzare una finestra di dialogo contenente gli ID progetto.

        Se fai clic su Seleziona ID progetto:

        1. Trova il progetto contenente il codice che tenta di accedere al modello.
        2. Fai clic sulla casella di controllo del progetto.
        3. Fai clic su Seleziona.

    5. Fai clic su Esegui il deployment.

    Interfaccia a riga di comando gcloud

    Questo comando mostra come eseguire il deployment del modello in una regione specifica.

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

    Questo comando mostra come eseguire il deployment del modello in una regione specifica con il tipo di macchina, il tipo di acceleratore e il numero di acceleratori. Se vuoi selezionare una configurazione specifica della macchina, devi impostare tutti e tre i campi.

    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)

    In alternativa, non devi passare un parametro al metodo 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}"'",
  },
}'

    In alternativa, puoi utilizzare l'API per impostare esplicitamente il tipo di macchina.

    
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
    }
  }
}'

    Esegui il deployment utilizzando l'API

    I Controlli di servizio VPC funzionano solo con l'endpoint privato dedicato. Pertanto, devi impostare private_service_connect_config nel seguente esempio di codice, che mostra come eseguire il deployment utilizzando l'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
        }
      }
    }'

    Recupera l'ID endpoint e l'ID modello utilizzando la console Google Cloud

    Al termine del deployment, segui questi passaggi:

    1. Nella console Google Cloud , vai alla pagina Model Garden.

      Vai a Model Garden

    2. Fai clic su Visualizza i miei endpoint e i miei modelli.

    3. Nella tabella I miei endpoint, controlla l'endpoint che hai appena implementato dalla colonna Nome. Viene visualizzata la pagina Dettagli.

    4. Fai clic sul modello nella tabella Modelli di cui è stato eseguito il deployment.

    5. Seleziona la pagina Dettagli della versione. L'ID modello viene visualizzato nella riga Variabili di ambiente della tabella.

    Configura un Private Service Connect

    Stai aggiungendo un nuovo endpoint per accedere alle API Google . Questo endpoint può essere utilizzato in tutte le regioni della rete VPC selezionata. Inoltre, tieni presente quanto segue:

    • I client nelle reti connesse alla rete VPC dell'endpoint tramite connettività ibrida possono accedere all'endpoint. Per saperne di più, consulta Accedere alle APIGoogle tramite endpoint.
    • I client nelle reti VPC in peering non possono accedere all'endpoint.

    Elenca l'endpoint per ottenere il collegamento al servizio

    Questo esempio di codice mostra come elencare un endpoint per ottenere un collegamento del servizio.

    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"

    Questa è la risposta dell'endpoint di elenco.

      {
  "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"
    ]
  }
}

    Crea un Private Service Connect

    Per creare un Private Service Connect (PSC):

    1. Nella console Google Cloud , vai alla pagina Private Service Connect. Viene visualizzata la pagina Endpoint connessi.

      Vai a Private Service Connect

    2. Fai clic su + Connetti endpoint. Viene visualizzata la pagina Connetti endpoint.

    3. Seleziona un'opzione dal campo Destinazione. Puoi scegliere API di Google che forniscono l'accesso alla maggior parte Google delle API e dei servizi o servizio pubblicato che fornisce l'accesso a un servizio pubblicato.

    4. Nella sezione Dettagli target, seleziona un valore dall'elenco Ambito e un valore dall'elenco Tipo di bundle.

    5. Nella sezione Dettagli endpoint:

      1. Inserisci un nome nel campo Nome endpoint.
      2. Seleziona un valore dall'elenco Rete. Seleziona una rete VPC nel tuo progetto. Se devi creare un endpoint PSC in un progetto di servizio che utilizza una rete VPC condiviso in un progetto host, utilizza Google Cloud CLI o invia una richiesta API.
      3. Seleziona un valore dall'elenco Indirizzo IP.

    6. Espandi la sezione Service Directory.

    7. Seleziona una regione dall'elenco Regione.

    8. Seleziona uno spazio dei nomi dall'elenco Spazio dei nomi.

    9. Fai clic su Aggiungi endpoint. La tabella Endpoint viene aggiornata con una riga per il nuovo endpoint.

    Eseguire una query

    Questa sezione spiega come creare un endpoint pubblico e un endpoint privato.

    Eseguire una query su un endpoint pubblico

    Una volta eseguito il deployment del modello, i pesi personalizzati supportano l'endpoint pubblico dedicato. Puoi inviare query utilizzando l'API o l'SDK.

    Prima di inviare query, devi ottenere l'URL dell'endpoint, l'ID endpoint e l'ID modello, disponibili nella console Google Cloud .

    Per ottenere le informazioni, segui questi passaggi:

    1. Nella console Google Cloud , vai alla pagina Model Garden.

      Model Garden

    2. Fai clic su Visualizza i miei endpoint e i miei modelli.

    3. Seleziona la tua regione dall'elenco Regione.

    4. Per ottenere l'ID endpoint e l'URL endpoint, fai clic sull'endpoint nella sezione I miei endpoint.

      Il tuo ID endpoint viene visualizzato nel campo ID endpoint.

      L'URL dell'endpoint pubblico viene visualizzato nel campo Endpoint dedicato.

    5. Per ottenere l'ID modello, trova il tuo modello elencato nella sezione Modelli implementati e segui questi passaggi:

      1. Fai clic sul nome del modello di cui è stato eseguito il deployment nel campo Modello.
      2. Fai clic su Dettagli della versione. L'ID modello viene visualizzato nel campo ID modello.

    Dopo aver ottenuto le informazioni sull'endpoint e sul modello di cui è stato eseguito il deployment, consulta i seguenti esempi di codice per scoprire come inviare una richiesta di inferenza oppure consulta Invia una richiesta di inferenza online a un endpoint pubblico dedicato.

    API

    I seguenti esempi di codice mostrano diversi modi di utilizzare l'API in base al tuo caso d'uso.

    Completamento della chat (unario)

    Questa richiesta di esempio invia un messaggio di chat completo al modello e riceve una risposta in un unico blocco dopo che l'intera risposta è stata generata. È simile all'invio di un messaggio e alla ricezione di una singola risposta 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?"
      }
    ]
  }'

    Completamento della chat (streaming)

    Questa richiesta è la versione di streaming della richiesta di completamento della chat unaria. Se aggiungi "stream": true alla richiesta, il modello invia la risposta pezzo per pezzo man mano che viene generata. Ciò è utile per creare un effetto in tempo reale, simile a quello di una macchina da scrivere in un'applicazione di 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?"
      }
    ]
  }'

    Previsione

    Questa richiesta invia un prompt diretto per ottenere un'inferenza da un modello. Viene spesso utilizzato per attività che non sono necessariamente conversazionali, come il riepilogo o la classificazione del testo.

      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
      }
    ]
  }'

    Raw predict

    Questa richiesta è una versione di streaming della richiesta Predict. Utilizzando l'endpoint :streamRawPredict e includendo "stream": true, questa richiesta invia un prompt diretto e riceve l'output del modello come flusso continuo di dati man mano che vengono generati, in modo simile alla richiesta di completamento della chat in 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

    Questo esempio di codice utilizza l'SDK per inviare una query a un modello e ricevere una risposta da quel modello.

      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)

    Eseguire una query per un endpoint privato

    Puoi testare la query utilizzando un notebook o una VM nel progetto consentito.

    Questa query di esempio ti consente di sostituire le variabili con il tuo IP, progetto, ID endpoint e ID modello (ottenuto dal passaggio di deployment precedente).

    curl

    Completamento della 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?" }]}'

    Previsione

    $ 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
    }
  ]
}'

    Per un altro esempio di utilizzo dell'API, consulta il notebook Importa pesi personalizzati.

    Scopri di più sui modelli con deployment automatico in Vertex AI