Ein Praxisleitfaden zu GCP Vertex AI Serverless Endpoints: Von Null zur Produktion

Stellen Sie zunächst sicher, dass die Vertex AI API in Ihrem Projekt aktiviert ist.

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

Dieser Vorgang kann ein bis zwei Minuten dauern.

In einem realen Projekt würden Sie Ihr eigenes trainiertes Modell verwenden. Für diesen Leitfaden werden wir einen spielerischen Sentiment-Klassifikator trainieren. Ein häufiger Fehler, den ich sehe, ist das separate Pickling eines Modells und seines Präprozessors (wie eines Tokenizers oder Vektorisierers). Dies führt zu einem Abhängigkeitsalbtraum während der Bereitstellung. Der richtige Ansatz besteht darin, sie in ein einziges sklearn.pipeline.Pipeline-Objekt zu kombinieren und dieses zu pickeln.

Erstellen Sie eine Datei namens 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")

Führen Sie das Skript aus, um Ihre model.pkl-Datei zu generieren.

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

Ich bestehe auf Infrastructure as Code (IaC) für alle Cloud-Ressourcen. Dies stellt sicher, dass Bereitstellungen wiederholbar, versionskontrolliert und auditierbar sind. Wir werden Terraform verwenden, um unseren Vertex AI Endpoint zu definieren.

Erstellen Sie eine main.tf-Datei:

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

Als Nächstes erstellen Sie eine terraform.tfvars-Datei, um Ihre projektspezifische ID zu speichern. Denken Sie daran, den Platzhalter durch Ihre tatsächliche GCP-Projekt-ID zu ersetzen.

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

Initialisieren Sie nun Terraform und wenden Sie die Konfiguration an:

terraform init
terraform apply --auto-approve

Nach einem Moment wird Terraform den vollständigen Ressourcennamen Ihres Endpunkts ausgeben. Notieren Sie sich diesen; Sie werden ihn in Kürze benötigen.

Wenn Sie dasselbe Muster wie in Schritt 3 wünschen, aber mit Standard europe-west4 (Niederlande), nutzen Sie den folgenden Block. europe-west1 (Belgien) ist ebenfalls üblich; siehe Vertex AI-Regionen. Nach terraform apply müssen GCS, Model Registry und die Skripte aus den Schritten 4–5 dieselbe Region verwenden.

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

Da unser Endpunkt provisioniert ist, müssen wir unser Modell registrieren. Wir laden model.pkl in einen Google Cloud Storage (GCS) Bucket hoch und erstellen dann eine Model-Ressource im Vertex AI Model Registry, die darauf verweist.

Erstellen Sie zunächst einen GCS-Bucket (falls Sie noch keinen haben) und laden Sie Ihr Modell hoch. Bucket-Namen müssen global eindeutig sein.

# 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

Nun verwenden wir das Python SDK, um dieses Artefakt als neue Modellversion zu registrieren. Wir weisen Vertex AI auf einen vorgefertigten scikit-learn Serving-Container hin, der weiß, wie ein gepickeltes Modell geladen und bereitgestellt wird.

Erstellen Sie eine Datei namens 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}

Führen Sie das Skript aus. Stellen Sie sicher, dass Sie your-unique-model-bucket-ew1 durch den von Ihnen erstellten Bucket-Namen ersetzen.

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

Dadurch wird Ihr Modell registriert und sein vollständiger Ressourcennamen ausgegeben, den wir für den letzten Bereitstellungsschritt benötigen.

Dies ist der letzte Schritt, in dem alles zusammenkommt. Wir nehmen den von Terraform erstellten Endpunkt und das gerade registrierte Modell und stellen das Modell darauf bereit. Dies ist die Aktion, die Vertex AI dazu veranlasst, die serverlose Infrastruktur zu provisionieren.

Erstellen Sie 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}")

Vor der Ausführung müssen Sie your-endpoint-numeric-id und your-model-numeric-id durch die tatsächlichen IDs aus den vorherigen Schritten ersetzen. Sie finden diese in Ihrer Terminalausgabe oder in der GCP-Konsole.

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

Dieser Schritt dauert mehrere Minuten, da Vertex AI Ressourcen provisioniert, das Container-Image zieht und das Modell bereitstellt. Seien Sie geduldig.

Sobald die Bereitstellung abgeschlossen ist, ist Ihr Endpunkt live. Senden wir ihm einige Beispieldaten.

Erstellen Sie 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")

Ersetzen Sie erneut your-endpoint-numeric-id und führen Sie das Skript aus.

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

Sie sollten die Vorhersagen des Modells für Ihre Beispieleingaben sehen.

1. Berechtigungsfehler: Wenn Sie eine 403 Permission 'aiplatform.endpoints.deployModel' denied Meldung sehen, fehlt Ihrem Benutzer oder Dienstkonto die IAM-Rolle Vertex AI User (roles/aiplatform.user). Weisen Sie diese zu und versuchen Sie es erneut.

2. Bereitgestelltes Modell konnte nicht gestartet werden: Dies ist ein generischer Fehler, der normalerweise bedeutet, dass der Container in einer Absturzschleife steckt. Die Ursache liegt fast immer in den Protokollen. Häufige Gründe sind:

   • Pickle-Versionskonflikt: Die für das lokale Training verwendete scikit-learn-Version ist inkompatibel mit der Version im vorgefertigten Container. Stellen Sie sicher, dass sie übereinstimmen.
   • Falscher Artefaktpfad: Der artifact_uri in Model.upload muss auf das GCS-Verzeichnis zeigen, das model.pkl enthält, nicht auf die Datei selbst.

3. Kostenüberschreitungen: Wenn Sie min_replica_count auf 1 oder mehr setzen, werden Ihnen die Rechenkosten rund um die Uhr berechnet, auch ohne Datenverkehr. Für Entwicklungs- oder nicht-kritische Endpunkte setzen Sie min_replica_count=0, damit der Dienst vollständig heruntergefahren und Leerlaufkosten vermieden werden können.

• Serverless ist der Standard: Für die meisten Echtzeit-Inferenz-Workloads beginnen Sie mit Vertex AI Serverless Endpoints. Sie bieten die beste Balance aus Leistung, Kosten und operativer Einfachheit.
• IaC ist nicht verhandelbar: Provisionieren Sie Kernressourcen wie Endpunkte immer mit Terraform. Dies bietet eine wiederholbare, auditierbare Grundlage für Ihre MLOps-Plattform.
• Modelle korrekt verpacken: Verwenden Sie Tools wie scikit-learns Pipeline, um Vorverarbeitungs- und Modellierungsschritte in einem einzigen, portablen Artefakt zu bündeln. Dies vereinfacht die Bereitstellung erheblich.
• Endpunkte verwalten: Verwenden Sie Labels, um Kosten und Verantwortlichkeiten zu verfolgen. Setzen Sie min_replica_count=0 für nicht-produktionsbezogene Workloads, um Ausgaben zu steuern.

Mit einem bereitgestellten Endpunkt ist der nächste Schritt, ihn in eine reale Anwendung zu integrieren. Darüber hinaus können Sie erweiterte Funktionen erkunden wie:

• Traffic Splitting (Datenverkehrsaufteilung): Stellen Sie eine neue Modellversion auf demselben Endpunkt bereit und verlagern Sie den Datenverkehr schrittweise, um A/B-Tests oder Canary Releases durchzuführen.
• Vertex AI Explainability (Erklärbarkeit): Integrieren Sie die Modellerklärbarkeit, um zu verstehen, warum Ihr Modell bestimmte Vorhersagen trifft.
• CI/CD-Automatisierung: Erstellen Sie eine Pipeline in Cloud Build oder GitHub Actions, um neue Modellversionen bei Codeänderungen automatisch zu trainieren, zu registrieren und bereitzustellen.

Für einen tieferen Einblick in die umfassenderen Implikationen einer verwalteten KI-Infrastruktur könnten Sie die Technische Analyse des Halbleitersektors auf Clear Signals lesen.

• Vollständiger Quellcode: Den vollständigen Code und die Terraform-Konfigurationen, die in diesem Leitfaden verwendet werden, finden Sie unter [Link zu einem öffentlichen GitHub-Repository mit dem vollständigen Quellcode].
• Offizielle GCP-Beispiele: Für fortgeschrittenere Anwendungsfälle ist das offizielle GoogleCloudPlatform/vertex-ai-samples-Repository auf GitHub eine ausgezeichnete Ressource.