Questa guida descrive come importare i modelli nel Model Registry di Gemini Enterprise Agent Platform. Dopo aver importato il modello, questo è visibile in Model Registry. Da Model Registry, puoi eseguire il deployment del modello importato in un endpoint ed eseguire inferenze.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per importare i modelli, chiedi all'amministratore di concederti il ruolo IAM Agent Platform User (roles/aiplatform.user) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Container predefiniti o personalizzati
Quando importi un modello, lo associ a un container per consentire ad Agent Platform di eseguire le richieste di inferenza. Puoi utilizzare i container predefiniti forniti dalla piattaforma Agent o i tuoi container personalizzati che crei e di cui esegui il push ad Artifact Registry.
Puoi utilizzare un container predefinito se il tuo modello soddisfa i seguenti requisiti:
- Addestrato in Python 3.7 o versioni successive
- Addestrato utilizzando TensorFlow, PyTorch, scikit-learn o XGBoost
- Esportato per soddisfare i requisiti specifici del framework per uno dei container di inferenza predefiniti
Se stai importando un modello AutoML tabulare che hai precedentemente esportato, devi utilizzare un container personalizzato specifico fornito da Agent Platform.
In caso contrario, crea un nuovo container personalizzato o utilizzane uno esistente in Artifact Registry.
Carica gli artefatti del modello su Cloud Storage
Devi archiviare gli artefatti del modello in un bucket Cloud Storage, dove la regione del bucket corrisponde all'endpoint di località che stai utilizzando.
Se il tuo bucket Cloud Storage si trova in un progetto Cloud de Confiancediverso, devi concedere l'accesso alla piattaforma dell'agente per leggere gli artefatti del modello.
Se utilizzi un container predefinito, assicurati che i nomi file degli artefatti del modello corrispondano esattamente ai seguenti esempi:
- TensorFlow SavedModel:
saved_model.pb - PyTorch:
model.mar - scikit-learn:
model.joblib - XGBoost:
model.bstomodel.joblib
Scopri di più sull'esportazione degli artefatti del modello per l'inferenza.
Importa un modello utilizzando la console Cloud de Confiance
Per importare un modello utilizzando la console Cloud de Confiance :
Nella console Cloud de Confiance , vai alla pagina Modelli della piattaforma Agent.
Fai clic su Importa.
Seleziona Importa come nuovo modello per importare un nuovo modello.
Seleziona Importa come nuova versione per importare un modello come versione di un modello esistente. Per scoprire di più sul controllo delle versioni dei modelli, consulta Controllo delle versioni dei modelli.
Nome e regione: inserisci un nome per il modello. Seleziona la regione che corrisponde sia alla regione del bucket sia all'endpoint di località della piattaforma dell'agente che stai utilizzando. Fai clic su Continua.
Se espandi Opzioni avanzate, puoi facoltativamente decidere di aggiungere una chiave di crittografia gestita dal cliente.
A seconda del tipo di container che utilizzi, seleziona la scheda appropriata di seguito.
Container predefinito
Seleziona Importa gli artefatti del modello in un nuovo container predefinito.
Seleziona il Framework del modello e la Versione del framework del modello che hai utilizzato per addestrare il modello.
Se vuoi utilizzare le GPU per l'inferenza, imposta Tipo di acceleratore su GPU.
Seleziona il tipo di GPU in un secondo momento, quando esegui il deployment del modello in un endpoint.
Specifica il percorso Cloud Storage della directory che contiene gli artefatti del modello.
Ad esempio,
gs://BUCKET_NAME/models/.Lascia vuoto il campo Schemi di previsione.
Per importare il modello senza le impostazioni di Vertex Explainable AI, fai clic su Importa.
Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli.
In caso contrario, continua a configurare il modello inserendo le impostazioni di spiegabilità nella scheda Spiegabilità. Scopri di più sulle impostazioni di spiegabilità.
Container personalizzato
Seleziona Importa un container personalizzato esistente.
Imposta l'URI dell'immagine container.
Se vuoi fornire artefatti del modello oltre a un'immagine container, specifica il percorso Cloud Storage della directory che contiene gli artefatti del modello.
Ad esempio,
gs://BUCKET_NAME/models/.Specifica i valori per gli altri campi.
Scopri di più su questi campi facoltativi.
Per importare il modello senza le impostazioni di Vertex Explainable AI, fai clic su Importa.
Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli.
In caso contrario, continua a configurare il modello inserendo le impostazioni di spiegabilità nella scheda Spiegabilità. Scopri di più sulle impostazioni di spiegabilità.
Container tabulare AutoML
Seleziona Importa un container personalizzato esistente.
Nel campo Immagine container, inserisci
MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.Sostituisci
MULTI_REGIONconus,europeoasiaper selezionare il repository Docker da cui vuoi eseguire il pull dell'immagine Docker. Ogni repository fornisce la stessa immagine Docker, ma la scelta della località multiregionale di Artifact Registry più vicina alla macchina su cui stai eseguendo Docker potrebbe ridurre la latenza.Nel campo Posizione pacchetto, specifica il percorso Cloud Storage della directory che contiene gli artefatti del modello.
Il percorso è simile al seguente esempio:
gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/Lascia vuoti tutti gli altri campi.
Fai clic su Importa.
Al termine dell'importazione, il modello viene visualizzato nella pagina Modelli. Puoi utilizzare questo modello proprio come gli altri modelli tabulari AutoML, ad eccezione dei modelli tabulari AutoML importati, che non supportano Vertex Explainable AI.
Importa un modello in modo programmatico
I seguenti esempi mostrano come importare un modello utilizzando vari strumenti:
gcloud
L'esempio seguente utilizza il comando gcloud ai models upload:
gcloud ai models upload \
--region=LOCATION \
--display-name=MODEL_NAME \
--container-image-uri=IMAGE_URI \
--artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY
Sostituisci quanto segue:
- LOCATION_ID: la regione in cui utilizzi Agent Platform.
-
MODEL_NAME: un nome visualizzato per
Model. -
IMAGE_URI: L'URI dell'immagine contenitore da utilizzare per la visualizzazione delle inferenze.
Ad esempio,
us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilizza un container predefinito o un container personalizzato. -
PATH_TO_MODEL_ARTIFACT_DIRECTORY: l'URI Cloud Storage (che inizia con
gs://) di una directory in Cloud Storage che contiene gli artefatti del modello.
L'esempio precedente mostra tutti i flag necessari per importare la maggior parte dei modelli. Se non utilizzi un container predefinito per l'inferenza, probabilmente dovrai specificare alcuni flag facoltativi aggiuntivi in modo che Agent Platform possa utilizzare l'immagine container. Questi flag, che iniziano con --container-, corrispondono ai campi di containerSpec di Model.
REST
Utilizza il seguente esempio di codice per caricare un modello utilizzando il metodo upload della risorsa model.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- LOCATION_ID: la regione in cui utilizzi Agent Platform.
- PROJECT_ID: il tuo ID progetto. .
-
MODEL_NAME: un nome visualizzato per
Model. - MODEL_DESCRIPTION: (Facoltativo) Una descrizione del modello.
-
IMAGE_URI: l'URI dell'immagine container da utilizzare per l'inferenza.
Ad esempio,
us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Utilizza un container predefinito o un container personalizzato. -
PATH_TO_MODEL_ARTIFACT_DIRECTORY: l'URI Cloud Storage (che inizia con
gs://) di una directory in Cloud Storage che contiene gli artefatti del modello. Questa variabile e il campoartifactUrisono facoltativi se utilizzi un container personalizzato. labels: (Facoltativo) Qualsiasi insieme di coppie chiave-valore per organizzare i tuoi modelli. Ad esempio:- "env": "prod"
- "tier": "backend"
- Specifica LABEL_NAME e LABEL_VALUE per le etichette che vuoi applicare a questa pipeline di addestramento.
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload
Corpo JSON della richiesta:
{
"model": {
"displayName": "MODEL_NAME",
"predictSchemata": {},
"containerSpec": {
"imageUri": "IMAGE_URI"
},
"artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
"labels": {
"LABEL_NAME_1": "LABEL_VALUE_1",
"LABEL_NAME_2": "LABEL_VALUE_2"
}
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload"
PowerShell
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload" | Select-Object -Expand Content
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Agent Platform per l'utilizzo delle librerie client.
Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Agent Platform per l'utilizzo delle librerie client.
Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Per importare un modello con le impostazioni di Vertex Explainable AI attivate, consulta gli esempi di importazione dei modelli di Vertex Explainable AI.
Ottieni lo stato di attività
Alcune richieste avviano operazioni a lunga esecuzione che richiedono tempo per essere completate. Queste richieste restituiscono un nome di operazione, che puoi utilizzare per visualizzare lo stato dell'operazione o annullarla. Agent Platform fornisce metodi helper per effettuare chiamate per operazioni a lunga esecuzione. Per saperne di più, consulta Utilizzo di operazioni a lunga esecuzione.
Limitazioni
- La dimensione massima del modello supportata da Model Registry è 1 TB.
Passaggi successivi
- Esegui il deployment del modello in un endpoint, in modo programmatico o utilizzando la console Cloud de Confiance .