Una guida pratica agli endpoint serverless di GCP Vertex AI: dalla fase iniziale alla produzione

Per prima cosa, assicurati che l'API di Vertex AI sia abilitata nel tuo progetto.

# Abilita l'API di Vertex AI
gcloud services enable aiplatform.googleapis.com

Questa operazione può richiedere uno o due minuti per essere completata.

In un progetto reale, porteresti il tuo modello addestrato. Per questa guida, addestreremo un classificatore di sentiment "giocattolo". Un errore comune che vedo è il pickling di un modello e del suo pre-processore (come un tokenizer o un vettorizzatore) separatamente. Questo crea un incubo di dipendenze durante la distribuzione. L'approccio corretto è combinarli in un singolo oggetto sklearn.pipeline.Pipeline e farne il pickling.

Crea un file chiamato create_model.py:

# create_model.py
import pickle
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.pipeline import Pipeline

# Dati di esempio
corpus = [
    "I love this product, it's amazing!",
    "This is terrible, I hate it.",
    "It's okay, nothing special.",
    "Absolutely fantastic experience."
]
labels = [1, 0, 0, 1]  # 1 per positivo, 0 per negativo/neutro

# Crea una pipeline scikit-learn
# Questa raggruppa il vettorizzatore e il modello in un singolo artefatto
pipeline = Pipeline([
    ('tfidf', TfidfVectorizer()),
    ('clf', LogisticRegression())
])

# Addestra la pipeline
pipeline.fit(corpus, labels)

# Salva l'intera pipeline in un singolo file
with open('model.pkl', 'wb') as f:
    pickle.dump(pipeline, f)

print("Pipeline saved as model.pkl")

Esegui lo script per generare il tuo file model.pkl.

python3.12 create_model.py
# Output atteso: Pipeline saved as model.pkl

Insisto sull'Infrastructure as Code (IaC) per tutte le risorse cloud. Garantisce che le distribuzioni siano ripetibili, versionate e verificabili. Utilizzeremo Terraform per definire il nostro endpoint di Vertex AI.

Crea un file main.tf:

# main.tf
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.50.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

variable "project_id" {
  description = "The GCP project ID."
  type        = string
}

variable "region" {
  description = "The GCP region for Vertex AI resources."
  type        = string
  default     = "europe-west1"
}

resource "google_vertex_ai_endpoint" "sentiment_endpoint" {
  name         = "sentiment-analysis-endpoint"
  display_name = "Sentiment Analysis Serverless Endpoint"
  description  = "Managed serverless endpoint for sentiment analysis."
  project      = var.project_id
  location     = var.region

  labels = {
    environment = "production"
    service     = "sentiment-analysis"
  }
}

output "endpoint_resource_name" {
  description = "The full resource name of the created Vertex AI Endpoint."
  value       = google_vertex_ai_endpoint.sentiment_endpoint.name
}

Successivamente, crea un file terraform.tfvars per contenere il tuo ID specifico del progetto. Ricorda di sostituire il placeholder con il tuo ID progetto GCP effettivo.

# terraform.tfvars
project_id = "your-gcp-project-id"

Ora, inizializza Terraform e applica la configurazione:

terraform init
terraform apply --auto-approve

Dopo un momento, Terraform restituirà il nome completo della risorsa del tuo endpoint. Annotalo; ti servirà a breve.

Per lo stesso schema del Passaggio 3 con europe-west4 (Paesi Bassi) come predefinito, usa il blocco seguente. europe-west1 (Belgio) è un’alternativa frequente; vedi le regioni Vertex AI. Dopo terraform apply, mantieni la stessa regione per il bucket GCS, il Model Registry e gli script dei Passaggi 4–5.

# ---------------------------------------------------------------------------
# Vertex AI online prediction endpoint — EU West (default: europe-west4)
# Locations: https://cloud.google.com/vertex-ai/docs/general/locations
# Provider: hashicorp/google — same pattern as Step 3 in this article.
# Upload and deploy the model (Steps 4–5) in the SAME region.
# ---------------------------------------------------------------------------

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.50.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

variable "project_id" {
  description = "The GCP project ID."
  type        = string
}

variable "region" {
  description = "Vertex AI region (EU West). Default europe-west4 (Netherlands); europe-west1 (Belgium) is a common alternative."
  type        = string
  default     = "europe-west4"
}

resource "google_vertex_ai_endpoint" "sentiment_endpoint_eu" {
  name         = "sentiment-analysis-endpoint-euw4"
  display_name = "Sentiment Analysis Serverless Endpoint (EU)"
  description  = "Managed Vertex AI endpoint — EU West module (Terraform)."
  project      = var.project_id
  location     = var.region

  labels = {
    environment = "production"
    service     = "sentiment-analysis"
    eu_module   = "europe-west4"
  }
}

output "endpoint_resource_name" {
  description = "Full resource name of the Vertex AI endpoint (use in SDK / gcloud deploy steps)."
  value       = google_vertex_ai_endpoint.sentiment_endpoint_eu.name
}

Con il provisioning del nostro endpoint, dobbiamo registrare il nostro modello. Caricheremo model.pkl in un bucket Google Cloud Storage (GCS) e quindi creeremo una risorsa Model nel Vertex AI Model Registry che vi punti.

Innanzitutto, crea un bucket GCS (se non ne hai uno) e carica il tuo modello. I nomi dei bucket devono essere globalmente unici.

# Sostituisci con il nome del tuo bucket unico
BUCKET_NAME="your-unique-model-bucket-ew1"
PROJECT_ID=$(gcloud config get-value project)

gcloud storage buckets create gs://${BUCKET_NAME} --project=${PROJECT_ID} --location=europe-west1
gcloud storage cp model.pkl gs://${BUCKET_NAME}/sentiment_model/model.pkl

Ora useremo l'SDK Python per registrare questo artefatto come una nuova versione del modello. Indicheremo a Vertex AI un container di servizio scikit-learn pre-costruito, che sa come caricare e servire un modello in formato pickle.

Crea un file chiamato upload_model.py:

# upload_model.py
import os
from google.cloud import aiplatform

# --- Configurazione ---
# Si prega di aggiornare questi valori con i propri
PROJECT_ID = os.getenv("GCLOUD_PROJECT")
REGION = "europe-west1"
BUCKET_NAME = "your-unique-model-bucket-ew1" # Il bucket che hai appena creato
MODEL_DISPLAY_NAME = "sentiment-analysis-model"
# --- Fine configurazione ---

# Il percorso GCS alla directory contenente l'artefatto del modello
ARTIFACT_URI = f"gs://{BUCKET_NAME}/sentiment_model/"

# Container ufficiale pre-costruito di Google per scikit-learn 1.4
SERVING_CONTAINER_IMAGE = "europe-docker.pkg.dev/vertex-ai/prediction/sklearn-cpu.1-4:latest"

# Inizializza l'SDK di Vertex AI
aiplatform.init(project=PROJECT_ID, location=REGION)

# Carica il modello nel Vertex AI Model Registry
model = aiplatform.Model.upload(

    display_name=MODEL_DISPLAY_NAME,
    artifact_uri=ARTIFACT_URI,
    serving_container_image_uri=SERVING_CONTAINER_IMAGE,
)

print(f"Model uploaded. Resource name: {model.resource_name}")

# Per vedere il modello nella console, visita:
# https://console.cloud.google.com/vertex-ai/models?project={PROJECT_ID}

Esegui lo script. Assicurati di sostituire your-unique-model-bucket-ew1 con il nome del bucket che hai creato.

export GCLOUD_PROJECT=$(gcloud config get-value project)
python3.12 upload_model.py

Questo registrerà il tuo modello e ne restituirà il nome completo della risorsa, di cui avremo bisogno per il passaggio finale della distribuzione.

Questo è il passaggio finale in cui tutto si unisce. Prenderemo l'endpoint creato da Terraform e il modello che abbiamo appena registrato, e distribuiremo il modello ad esso. Questa è l'azione che innesca Vertex AI a effettuare il provisioning dell'infrastruttura serverless.

Crea deploy_model.py:

# deploy_model.py
import os
from google.cloud import aiplatform

# --- Configurazione ---
PROJECT_ID = os.getenv("GCLOUD_PROJECT")
REGION = "europe-west1"

# Usa il nome della risorsa dell'endpoint dall'output di terraform
ENDPOINT_RESOURCE_NAME = f"projects/{PROJECT_ID}/locations/{REGION}/endpoints/your-endpoint-numeric-id"

# Usa il nome della risorsa del modello dall'output di upload_model.py
MODEL_RESOURCE_NAME = f"projects/{PROJECT_ID}/locations/{REGION}/models/your-model-numeric-id"

DEPLOYED_MODEL_DISPLAY_NAME = "sentiment-model-v1-prod"
# --- Fine configurazione ---

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

# Ottieni un riferimento all'endpoint esistente
endpoint = aiplatform.Endpoint(ENDPOINT_RESOURCE_NAME)

print("Deploying model to endpoint...")
# Questo può richiedere 10-15 minuti
endpoint.deploy(
    model=MODEL_RESOURCE_NAME,
    deployed_model_display_name=DEPLOYED_MODEL_DISPLAY_NAME,
    # Per serverless, definisci la 'forma' della macchina, non un tipo specifico
    machine_type="n1-standard-2",
    min_replica_count=1, # Può essere 0 per puro serverless, 1 per avvio a caldo
    max_replica_count=3,
    traffic_split={"0": 100}, # Invia il 100% del traffico a questo nuovo modello
    sync=True, # Attendi il completamento della distribuzione
)

print(f"Model deployed successfully to endpoint: {endpoint.display_name}")

Prima di eseguire, devi sostituire your-endpoint-numeric-id e your-model-numeric-id con gli ID effettivi dei passaggi precedenti. Puoi trovarli nell'output del tuo terminale o nella console GCP.

export GCLOUD_PROJECT=$(gcloud config get-value project)
python3.12 deploy_model.py

Questo passaggio richiede diversi minuti poiché Vertex AI effettua il provisioning delle risorse, scarica l'immagine del container e distribuisce il modello. Sii paziente.

Una volta completata la distribuzione, il tuo endpoint è attivo. Inviagliamo alcuni dati di esempio.

Crea predict_sentiment.py:

# predict_sentiment.py
import os
from google.cloud import aiplatform

# --- Configurazione ---
PROJECT_ID = os.getenv("GCLOUD_PROJECT")
REGION = "europe-west1"
ENDPOINT_RESOURCE_NAME = f"projects/{PROJECT_ID}/locations/{REGION}/endpoints/your-endpoint-numeric-id"
# --- Fine configurazione ---

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

# Ottieni un riferimento all'endpoint
endpoint = aiplatform.Endpoint(ENDPOINT_RESOURCE_NAME)

instances = [
    "This service is incredible, highly recommend!",
    "I'm very disappointed with the slow response.",
    "The food was average, nothing to write home about."
]

# Il metodo predict accetta una lista di istanze
# Il container pre-costruito restituisce una semplice lista di previsioni
response = endpoint.predict(instances=instances)

print("Prediction Response:")
print(response)

print("\n--- Results ---")
for i, instance in enumerate(instances):
    prediction = response.predictions[i]
    sentiment = "Positive" if prediction == 1 else "Negative/Neutral"
    print(f"Input: '{instance}'\n  -> Prediction: {sentiment} ({prediction})\n")

Ancora una volta, aggiorna your-endpoint-numeric-id ed esegui lo script.

export GCLOUD_PROJECT=$(gcloud config get-value project)
python3.12 predict_sentiment.py

Dovresti vedere le previsioni del modello per i tuoi input di esempio.

1. Permesso negato: Se vedi un 403 Permission 'aiplatform.endpoints.deployModel' denied, il tuo utente o account di servizio non ha il ruolo IAM Vertex AI User (roles/aiplatform.user). Concedilo e riprova.

2. Il modello distribuito non è riuscito ad avviarsi: Questo è un errore generico, di solito significa che il container è in un ciclo di crash. La causa è quasi sempre nei log. I motivi comuni includono:

   • Mancata corrispondenza della versione di Pickle: La versione di scikit-learn utilizzata per l'addestramento locale è incompatibile con la versione all'interno del container pre-costruito. Assicurati che corrispondano.
   • Percorso dell'artefatto errato: L'artifact_uri in Model.upload deve puntare alla directory GCS contenente model.pkl, non al file stesso.

3. Sforamento dei costi: Se imposti min_replica_count a 1 o più, ti verranno addebitati i costi per quel computing 24 ore su 24, 7 giorni su 7, anche senza traffico. Per lo sviluppo o gli endpoint non critici, imposta min_replica_count=0 per consentire al servizio di scalare completamente e evitare costi di inattività.

• Serverless è il valore predefinito: Per la maggior parte dei carichi di lavoro di inferenza in tempo reale, inizia con gli endpoint serverless di Vertex AI. Forniscono il miglior equilibrio tra prestazioni, costi e semplicità operativa.
• IaC è irrinunciabile: Effettua sempre il provisioning delle risorse principali come gli endpoint con Terraform. Ciò fornisce una base ripetibile e verificabile per la tua piattaforma MLOps.
• Impacchetta correttamente i modelli: Usa strumenti come la Pipeline di scikit-learn per raggruppare i passaggi di pre-elaborazione e modellazione in un unico artefatto portatile. Questo semplifica drasticamente la distribuzione.
• Governa i tuoi endpoint: Usa le etichette per tenere traccia dei costi e della proprietà. Imposta min_replica_count=0 per i carichi di lavoro non di produzione per gestire la spesa.

Con un endpoint distribuito, il prossimo passo è integrarlo in un'applicazione reale. Oltre a ciò, puoi esplorare funzionalità più avanzate come:

• Divisione del traffico: Distribuisci una nuova versione del modello allo stesso endpoint e sposta gradualmente il traffico per eseguire test A/B o rilasci canary.
• Spiegabilità di Vertex AI: Integra la spiegabilità del modello per capire perché il tuo modello sta producendo determinate previsioni.
• Automazione CI/CD: Costruisci una pipeline in Cloud Build o GitHub Actions per addestrare, registrare e distribuire automaticamente nuove versioni del modello in caso di modifiche al codice.

Per un approfondimento sulle più ampie implicazioni dell'infrastruttura AI gestita, potresti voler consultare l'Analisi Tecnica del Settore dei Semiconduttori su Clear Signals.

• Codice sorgente completo: Puoi trovare il codice completo e le configurazioni Terraform utilizzate in questa guida nel [link a un repository GitHub pubblico con il codice sorgente completo].
• Esempi ufficiali di GCP: Per casi d'uso più avanzati, il repository ufficiale GoogleCloudPlatform/vertex-ai-samples su GitHub è un'ottima risorsa.