Guía de campo para los puntos de conexión sin servidor de Vertex AI de GCP: de cero a producción

Primero, asegúrese de que la API de Vertex AI esté habilitada en su proyecto.

# Enable the Vertex AI API
gcloud services enable aiplatform.googleapis.com

Esta operación puede tardar uno o dos minutos en completarse.

En un proyecto real, usted traería su propio modelo entrenado. Para esta guía, entrenaremos un clasificador de sentimientos de juguete. Un error común que veo es serializar (pickle) un modelo y su preprocesador (como un tokenizador o vectorizador) por separado. Esto crea una pesadilla de dependencias durante el despliegue. El enfoque correcto es combinarlos en un único objeto sklearn.pipeline.Pipeline y serializarlo.

Cree un archivo llamado 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

# Sample data
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 for positive, 0 for negative/neutral

# Create a scikit-learn pipeline
# This bundles the vectorizer and the model into a single artifact
pipeline = Pipeline([
    ('tfidf', TfidfVectorizer()),
    ('clf', LogisticRegression())
])

# Train the pipeline
pipeline.fit(corpus, labels)

# Save the entire pipeline to a single file
with open('model.pkl', 'wb') as f:
    pickle.dump(pipeline, f)

print("Pipeline saved as model.pkl")

Ejecute el script para generar su archivo model.pkl.

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

Insisto en la Infraestructura como Código (IaC) para todos los recursos en la nube. Esto garantiza que los despliegues sean repetibles, controlados por versiones y auditables. Utilizaremos Terraform para definir nuestro punto de conexión de Vertex AI.

Cree un archivo llamado 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
}

A continuación, cree un archivo terraform.tfvars para guardar su ID de proyecto específico. Recuerde reemplazar el marcador de posición con su ID de proyecto real de GCP.

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

Ahora, inicialice Terraform y aplique la configuración:

terraform init
terraform apply --auto-approve

Después de un momento, Terraform mostrará el nombre completo del recurso de su punto de conexión. Anótelo; lo necesitará en breve.

Si quieres el mismo patrón del Paso 3 con europe-west4 (Países Bajos) por defecto, usa el bloque siguiente. europe-west1 (Bélgica) es otra opción habitual; consulta las regiones de Vertex AI. Tras terraform apply, usa la misma región en el bucket de GCS, el Model Registry y los scripts de los Pasos 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 nuestro punto de conexión aprovisionado, necesitamos registrar nuestro modelo. Subiremos model.pkl a un bucket de Google Cloud Storage (GCS) y luego crearemos un recurso de Modelo en el Registro de modelos de Vertex AI que apunte a él.

Primero, cree un bucket de GCS (si no tiene uno) y suba su modelo. Los nombres de los buckets deben ser globalmente únicos.

# Replace with your unique bucket name
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

Ahora, usaremos el SDK de Python para registrar este artefacto como una nueva versión del modelo. Apuntaremos a Vertex AI a un contenedor de servicio preconfigurado de scikit-learn, que sabe cómo cargar y servir un modelo serializado.

Cree un archivo llamado upload_model.py:

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

# --- Configuration ---
# Please update these with your own values
PROJECT_ID = os.getenv("GCLOUD_PROJECT")
REGION = "europe-west1"
BUCKET_NAME = "your-unique-model-bucket-ew1" # The bucket you just created
MODEL_DISPLAY_NAME = "sentiment-analysis-model"
# --- End Configuration ---

# The GCS path to the directory containing the model artifact
ARTIFACT_URI = f"gs://{BUCKET_NAME}/sentiment_model/"

# Official Google pre-built container for scikit-learn 1.4
SERVING_CONTAINER_IMAGE = "europe-docker.pkg.dev/vertex-ai/prediction/sklearn-cpu.1-4:latest"

# Initialize the Vertex AI SDK
aiplatform.init(project=PROJECT_ID, location=REGION)

# Upload the model to 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}")

# To see the model in the console, visit:
# https://console.cloud.google.com/vertex-ai/models?project={PROJECT_ID}

Ejecute el script. Asegúrese de reemplazar your-unique-model-bucket-ew1 con el nombre del bucket que creó.

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

Esto registrará su modelo y mostrará su nombre de recurso completo, que necesitaremos para el paso final del despliegue.

Este es el paso final donde todo se une. Tomaremos el punto de conexión creado por Terraform y el modelo que acabamos de registrar, y desplegaremos el modelo en él. Esta es la acción que activa a Vertex AI para provisionar la infraestructura sin servidor.

Cree deploy_model.py:

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

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

# Use the endpoint resource name from your terraform output
ENDPOINT_RESOURCE_NAME = f"projects/{PROJECT_ID}/locations/{REGION}/endpoints/your-endpoint-numeric-id"

# Use the model resource name from the upload_model.py output
MODEL_RESOURCE_NAME = f"projects/{PROJECT_ID}/locations/{REGION}/models/your-model-numeric-id"

DEPLOYED_MODEL_DISPLAY_NAME = "sentiment-model-v1-prod"
# --- End Configuration ---

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

# Get a reference to the existing endpoint
endpoint = aiplatform.Endpoint(ENDPOINT_RESOURCE_NAME)

print("Deploying model to endpoint...")
# This can take 10-15 minutes
endpoint.deploy(
    model=MODEL_RESOURCE_NAME,
    deployed_model_display_name=DEPLOYED_MODEL_DISPLAY_NAME,
    # For serverless, you define the 'shape' of the machine, not a specific type
    machine_type="n1-standard-2",
    min_replica_count=1, # Can be 0 for pure serverless, 1 for warm start
    max_replica_count=3,
    traffic_split={"0": 100}, # Send 100% of traffic to this new model
    sync=True, # Wait for the deployment to complete
)

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

Antes de ejecutar, debe reemplazar your-endpoint-numeric-id y your-model-numeric-id con los ID reales de los pasos anteriores. Puede encontrarlos en la salida de su terminal o en la consola de GCP.

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

Este paso toma varios minutos ya que Vertex AI aprovisiona recursos, descarga la imagen del contenedor y despliega el modelo. Sea paciente.

Una vez completado el despliegue, su punto de conexión estará activo. Enviémosle algunos datos de muestra.

Cree predict_sentiment.py:

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

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

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

# Get a reference to the 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."
]

# The predict method takes a list of instances
# The pre-built container returns a simple list of predictions
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")

De nuevo, actualice your-endpoint-numeric-id y ejecute el script.

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

Debería ver las predicciones del modelo para sus entradas de muestra.

1. Permiso denegado: Si ve un 403 Permission 'aiplatform.endpoints.deployModel' denied, su usuario o cuenta de servicio carece del rol de IAM Vertex AI User (roles/aiplatform.user). Concédeselo e inténtalo de nuevo.

2. El modelo desplegado no se inició: Este es un error genérico, que usualmente significa que el contenedor está entrando en un bucle de fallo. La causa casi siempre se encuentra en los registros. Las razones comunes incluyen:

   • Incompatibilidad de la versión de Pickle: La versión de scikit-learn utilizada para el entrenamiento local es incompatible con la versión dentro del contenedor preconfigurado. Asegúrese de que coincidan.
   • Ruta de artefacto incorrecta: El artifact_uri en Model.upload debe apuntar al directorio de GCS que contiene model.pkl, no al archivo en sí.

3. Excesos de coste: Si establece min_replica_count en 1 o más, se le facturará por esa computación 24/7, incluso sin tráfico. Para puntos de conexión de desarrollo o no críticos, establezca min_replica_count=0 para permitir que el servicio se reduzca completamente y evitar costes por inactividad.

• Sin servidor es el predeterminado: Para la mayoría de las cargas de trabajo de inferencia en tiempo real, empiece con los puntos de conexión sin servidor de Vertex AI. Ofrecen el mejor equilibrio entre rendimiento, coste y simplicidad operativa.
• IaC es innegociable: Siempre aprovisione recursos centrales como los puntos de conexión con Terraform. Esto proporciona una base repetible y auditable para su plataforma MLOps.
• Empaquete modelos correctamente: Use herramientas como Pipeline de scikit-learn para agrupar los pasos de preprocesamiento y modelado en un único artefacto portátil. Esto simplifica drásticamente el despliegue.
• Gobierne sus puntos de conexión: Use etiquetas para rastrear el coste y la propiedad. Establezca min_replica_count=0 para cargas de trabajo no productivas para gestionar el gasto.

Con un punto de conexión desplegado, el siguiente paso es integrarlo en una aplicación real. Más allá de eso, puede explorar funciones más avanzadas como:

• División de tráfico: Despliegue una nueva versión del modelo en el mismo punto de conexión y cambie gradualmente el tráfico para realizar pruebas A/B o lanzamientos canary.
• Explicabilidad de Vertex AI: Integre la explicabilidad del modelo para comprender por qué su modelo está realizando ciertas predicciones.
• Automatización CI/CD: Construya un pipeline en Cloud Build o GitHub Actions para entrenar, registrar y desplegar automáticamente nuevas versiones del modelo tras cambios en el código.

Para una inmersión más profunda en las implicaciones más amplias de la infraestructura de IA gestionada, quizás desee consultar el Análisis Técnico del Sector de Semiconductores en Clear Signals.

• Código fuente completo: Puede encontrar el código completo y las configuraciones de Terraform utilizadas en esta guía en [enlace a un repositorio público de GitHub con el código fuente completo].
• Ejemplos oficiales de GCP: Para casos de uso más avanzados, el repositorio oficial GoogleCloudPlatform/vertex-ai-samples en GitHub es un excelente recurso.