SMT für KI-Inferenz

Mit der AI Inference Single Method Transform (SMT) können Sie Inferenzen für Pub/Sub-Nachrichten aus Gemini Enterprise Agent Platform-Modellen abrufen. Sie können Ihre eigenen benutzerdefinierten Modelle verwenden, die an Agent Platform-Endpunkten bereitgestellt werden, oder eines der Google- und Partnermodelle, die über die Agent Platform verfügbar sind. Die Inferenz des Modells wird jeder Nachricht hinzugefügt und ist zusammen mit den ursprünglichen Nachrichtendaten für die nachgelagerte Verarbeitung verfügbar.

Anwendungsfälle für die AI Inference SMT:

  • Echtzeit-Anreicherung: Fügen Sie Ereignisdaten, die über Pub/Sub übertragen werden, Kontext, Klassifizierungen, Vorhersagen, Stimmungen oder Einbettungen hinzu.

  • Vereinfachte KI-Pipelines: Es sind keine Zwischenservices mehr erforderlich, um Inferenzen aus KI-Modellen zu erhalten. Pub/Sub ruft das KI-Modell auf und reichert die Nachricht mit der Inferenz an.

  • Geringere Latenz für KI-Pipelines: Entfernen Sie zusätzliche Netzwerk-Hops in Ihrer Architektur, um die End-to-End-Latenz zu verringern.

  • Verbesserte Ablaufsteuerung: Um eine Überlastung von Modellendpunkten zu vermeiden, optimiert Pub/Sub die Rate der Anfragen an das KI-Modell. Weitere Informationen finden Sie in diesem Dokument unter Nachrichtenfluss.

Das AI Inference SMT unterstützt die folgenden Modelltypen:

  • Selbst bereitgestellte Modelle Offene, Partner- und benutzerdefinierte Modelle, die auf einem gemeinsamen oder dedizierten öffentlichen Agent Platform-Endpunkt bereitgestellt werden.

  • Model-as-a-Service-Modelle (MaaS): Modelle, die als Dienst über den Model Garden angeboten werden, z. B. Gemini und Claude, bei denen Sie die Bereitstellung nicht verwalten müssen. Eine Liste der MaaS-Modelle, die mit dem AI Inference SMT kompatibel sind, finden Sie unter Kompatible MaaS-Modelle.

Erforderliche Rollen und Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub-Bearbeiter (roles/pubsub.editor) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Themas oder Abos mit SMTs benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen eines Themas oder Abos mit SMTs erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um ein Thema oder Abo mit SMTs zu erstellen:

  • Thema erstellen: pubsub.topics.create für das Projekt
  • Abo erstellen: pubsub.subscriptions.create für das Projekt

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Dienstkontoberechtigungen

Das AI Inference SMT verwendet ein IAM-Dienstkonto, um den Agent Platform-Endpunkt aufzurufen. Standardmäßig wird das Konto Cloud Pub/Sub Service Agent (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com) verwendet. Sie können auch ein eigenes Dienstkonto angeben.

Das Dienstkonto benötigt die folgenden Berechtigungen für das Projekt Google Cloud, das den Agent Platform-Endpunkt enthält:

  • aiplatform.endpoints.get
  • aiplatform.endpoints.predict

Weisen Sie dem Dienstkonto die folgende IAM-Rolle zu, um diese Berechtigungen zu erteilen:

  • Wenn Sie das Dienstkonto Cloud Pub/Sub Service Agent verwenden, weisen Sie die Rolle Vertex AI Service Agent zu.

  • Wenn Sie ein anderes Dienstkonto verwenden, weisen Sie die Rolle Vertex AI User zu.

Nachrichtenverarbeitung

In diesem Abschnitt wird beschrieben, wie das AI Inference SMT Pub/Sub-Nachrichten verarbeitet.

Eingabe

Die Pub/Sub-Nachrichtendaten müssen eine Anfrage sein, die als JSON-String an das KI-Modell gesendet wird. Sie können auch zusätzliche Modellparameter angeben, die mit jeder Anfrage gesendet werden sollen. Das SMT führt diese Parameter mit den Nachrichtendaten zusammen und sendet das zusammengeführte JSON an den Modellendpunkt.

In der folgenden Tabelle sehen Sie, welche API vom SMT aufgerufen wird, um die Inferenz zu erhalten, basierend auf dem Modelltyp.

Modellbereitstellung Modelltyp API
Selbst bereitgestellt Alle rawPredict
Model-as-a-Service (MaaS)

Gemini-Foundation-Modell

Beispiel: gemini-3.0-pro

 Chat Completions API

Andere Gemini-Modelle

Beispiel: gemini-embeddings

 rawPredict
Anthropic, Mistral AI oder AI21 rawPredict
Alle anderen MaaS-Modelle Chat Completions API

Informationen zum korrekten Formatieren der Nachrichtendaten und Modellparameter finden Sie in der Dokumentation zu Ihrem Modell. Beispiele für Gemini-Basismodelle finden Sie unter Beispiele mit der Chat Completions API.

Ausgabe

Wenn der Aufruf des Modellendpunkts erfolgreich ist, reichert das SMT die ursprüngliche Pub/Sub-Nachricht mit der Modellantwort an. Die angereicherte Nachricht ist ein JSON-String wie der folgende, wobei ORIGINAL_MESSAGE die ursprünglichen Nachrichtendaten und INFERENCE_RESULT die Antwort des Modells ist:

{
  "original_message": { ORIGINAL_MESSAGE },
  "model_output": { INFERENCE_RESULT }
}

Nachrichtenfluss

Themen-SMTs:Wenn Sie eine SMT für KI-Inferenz für ein Thema definieren, verarbeitet Pub/Sub eingehende Nachrichten so:

  1. Eine Publisher-Anwendung sendet eine Nachricht an ein Pub/Sub-Thema.

  2. Die Nachricht wird zur Inferenz an den konfigurierten Modellendpunkt gesendet. Die angereicherte Nachricht mit den Originaldaten und der Inferenz des Modells wird in den internen Speicher von Pub/Sub geschrieben.

  3. Pub/Sub stellt die angereicherten Nachrichten an alle zugehörigen Abos zu.

SMTs für Abos:Wenn Sie ein SMT für KI-Inferenz für ein Abo definieren, verarbeitet Pub/Sub eingehende Nachrichten so:

  1. Eine Publisher-Anwendung sendet eine Nachricht an ein Pub/Sub-Thema.

  2. Pub/Sub stellt die Nachricht an das Abo zu.

  3. Die Nachricht wird zur Inferenz an den konfigurierten Modellendpunkt gesendet.

  4. Das Abo sendet die angereicherte Nachricht an die Abonnentenanwendung.

  5. Pub/Sub optimiert die Rate der Anfragen an das KI-Modell, um den Durchsatz basierend auf der Latenz und dem Kontingent Ihres Deployments zu maximieren. Hinweis: Diese Funktion wird bei Verwendung der unären Pull-API nicht unterstützt.

Sie können eine SMT für KI-Inferenz mit einer oder mehreren JavaScript-UDF-SMTs verketten. Mit diesem Muster können Sie eine Nachricht vorverarbeiten, damit sie dem erwarteten Eingabeformat Ihres Modells entspricht, oder die Ausgabe des Modells nachverarbeiten, bevor sie an Abonnenten gesendet wird.

KI-Inferenz-SMT erstellen

SMTs können für Pub/Sub-Themen oder ‑Abos konfiguriert werden.

  • SMTs für Themen werden ausgeführt, bevor Pub/Sub die Nachricht speichert. Die Ergebnisse sind für alle Abonnenten verfügbar.

  • SMTs für Abos werden vor der Zustellung der Nachricht ausgeführt und die Ergebnisse sind nur für dieses Abo verfügbar.

Console

  1. Rufen Sie in der Google Cloud Console die Pub/Sub-Seite Themen auf.

    Themen aufrufen

  2. Erstellen Sie entweder ein Thema oder ein Abo.

    • Klicken Sie auf Thema erstellen, um ein Thema zu erstellen. Die Seite Thema erstellen wird geöffnet.

    • So erstellen Sie ein Abo:

      1. Klicken Sie auf den Namen des Themas, das Sie abonnieren möchten.

      2. Klicken Sie auf Abo erstellen. Die Seite Abo zum Thema hinzufügen wird geöffnet.

  3. Klicken Sie unter Transformationen auf Transformation hinzufügen.

  4. Wählen Sie als Transformationstyp die Option KI-Inferenz aus.

  5. Geben Sie unter Endpunkt den vollständigen Ressourcennamen Ihres Modellendpunkts ein:

    • Selbst bereitgestelltes Modell: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Model Garden-Modell: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  6. Optional. Wählen Sie ein Dienstkonto aus, das beim Aufrufen des Agent Platform-Endpunkts verwendet werden soll. Weitere Informationen finden Sie unter Dienstkontoberechtigungen.

  7. Optional. Geben Sie im Feld Parameter Modellparameter als JSON-Objekt ein. Das SMT führt diese Parameter mit jeder Nachricht zusammen, bevor das Modell aufgerufen wird. Beispiel:

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  8. Klicken Sie auf Erstellen, um das Thema oder Abo zu erstellen.

gcloud

Definitionsdatei erstellen

Erstellen Sie eine YAML- oder JSON-Datei, in der die Inference AI definiert ist.

YAML 

- aiInference:
    endpoint: "ENDPOINT_RESOURCE"
    unstructuredInference: {
        parameters:
          MODEL_PARAMETERS
    }
    service_account_email: SERVICE_ACCOUNT

JSON 

{
  "aiInference": {
    "endpoint": "ENDPOINT_RESOURCE",
    "unstructuredInference": {
        "parameters": {
          MODEL_PARAMETERS
        }
    }
    "service_account_email": SERVICE_ACCOUNT
  }
}

Ersetzen Sie Folgendes:

  • ENDPOINT_RESOURCE: Der vollständige Ressourcenname des Modellendpunkts. Verwenden Sie das folgende Format:

    • Selbst bereitgestelltes Modell: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Model Garden-Modell: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  • MODEL_PARAMETERS: Optional. Modellparameter, die als JSON-Objekt angegeben werden. Das SMT führt diese Parameter mit jeder Nachricht zusammen, bevor das Modell aufgerufen wird. Beispiel:

    {
  "temperature": 0.5,
  "max_tokens": 1000
}

  • SERVICE_ACCOUNT: Optional. Eine E-Mail-Adresse für das Dienstkonto, die beim Aufrufen des Endpunkts verwendet werden soll. Weitere Informationen finden Sie unter Dienstkontoberechtigungen.

Thema oder Abo erstellen

Führen Sie den Befehl gcloud pubsub topics create aus, um ein Thema zu erstellen.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ersetzen Sie Folgendes:

  • TOPIC_ID: Die ID oder der Name des Themas, das Sie erstellen möchten.
  • TRANSFORMS_FILE: Der Pfad zur Definitionsdatei.

Führen Sie den Befehl gcloud pubsub subscriptions create aus, um ein Abo zu erstellen.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ersetzen Sie Folgendes:

  • SUBSCRIPTION_ID: Die ID oder der Name des zu erstellenden Abos.

  • PROJECT_ID: Die ID des Projekts, das das Thema enthält.

  • TOPIC_ID: Die ID des Themas, das abonniert werden soll.

  • TRANSFORMS_FILE: Der Pfad zur Definitionsdatei.

Validieren und testen

Optional können Sie das konfigurierte SMT validieren und testen, bevor Sie das Thema oder Abo erstellen. Weitere Informationen finden Sie in folgenden Dokumenten:

Beispiel: KI-Inferenz-SMT verwenden

Im folgenden Beispiel wird gezeigt, wie Sie ein Abo mit einem SMT für KI-Inferenz erstellen und dann damit einen Prompt an Gemini senden.

gcloud

  1. Erstellen Sie mit einem Texteditor eine Datei namens ai-smt.yaml und fügen Sie den folgenden Text ein:

    - aiInference:
    endpoint: projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash
    unstructuredInference: {
        parameters: {
            "max_tokens": 25000
        }
    }

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Die ID Ihres Google Cloud-Projekts.
    • LOCATION: Der Speicherort des aufzurufenden Endpunkts. Beispiel: us-central1.

  2. Erstellen Sie ein neues Pub/Sub-Thema.

    gcloud pubsub topics create TOPIC_ID

    Ersetzen Sie TOPIC_ID durch den Namen des Themas, das Sie erstellen möchten. Beispiel: topic-1.

  3. Erstellen Sie ein Abo mit einem SMT für KI-Inferenz.

    gcloud pubsub subscriptions create TOPIC_ID-sub \
  --ack-deadline=600 \
  --topic TOPIC_ID \
  --message-transforms-file ai-smt.yaml

  4. Veröffentlichen Sie eine Nachricht zum Thema. Die Nachricht enthält einen Prompt, der für die Chat Completions API formatiert ist.

    gcloud pubsub topics publish TOPIC_ID --message=$'{
  "model":"google/gemini-2.5-flash","messages":[{
    "role": "user",
    "content": "Explain how AI works in a few words"
    }]
  }'

  5. Nachrichten aus dem Abo empfangen

    gcloud pubsub subscriptions pull TOPIC_ID-sub

    Wenn der Aufruf der Agent Platform erfolgreich ist, wird die Nachricht mit der Ausgabe des Prompts angereichert.

Kompatible MaaS-Modelle

In der folgenden Tabelle sind die MaaS-Modelle (Model-as-a-Service) aufgeführt, die Google mit dem AI Inference SMT getestet hat und die bekanntermaßen kompatibel sind. Diese Liste kann sich ändern, wenn Modelle eingestellt oder neue MaaS-Modelle hinzugefügt werden.

ModellAufgerufene API
google/gemini-2.0-flash-001 Chat Completions API
google/gemini-2.0-flash-lite-001 Chat Completions API
google/gemini-2.5-flash Chat Completions API
google/gemini-2.5-flash-lite Chat Completions API
google/gemini-2.5-pro Chat Completions API
google/gemini-2.5-flash-image Chat Completions API
google/gemini-3-pro-preview Chat Completions API
google/gemini-3-pro-image-preview Chat Completions API
google/gemini-3-flash-preview Chat Completions API
google/gemini-3.1-pro-preview Chat Completions API
google/gemini-3.1-flash-image-preview Chat Completions API
google/gemini-3.1-flash-lite-preview Chat Completions API
meta/llama-3.3-70b-instruct-maas Chat Completions API
meta/llama-4-maverick-17b-128e-instruct-maas Chat Completions API
meta/llama-4-scout-17b-16e-instruct-maas Chat Completions API
deepseek-ai/deepseek-r1-0528-maas Chat Completions API
deepseek-ai/deepseek-v3.1-maas Chat Completions API
qwen/qwen3-235b-a22b-instruct-2507-maas Chat Completions API
qwen/qwen3-coder-480b-a35b-instruct-maas Chat Completions API
openai/gpt-oss-20b-maas Chat Completions API
openai/gpt-oss-120b-maas Chat Completions API
google/text-multilingual-embedding-002 rawPredict
google/text-embedding-005 rawPredict
google/text-embedding-large-exp-03-07 rawPredict
google/gemini-embedding-001 rawPredict
google/multimodalembedding rawPredict
anthropic/claude-sonnet-4 rawPredict
anthropic/claude-sonnet-4-5 rawPredict
anthropic/claude-sonnet-4-6 rawPredict
anthropic/claude-opus-4 rawPredict
anthropic/claude-opus-4-1 rawPredict
anthropic/claude-opus-4-5 rawPredict
anthropic/claude-opus-4-6 rawPredict
anthropic/claude-haiku-4-5 rawPredict
mistralai/mistral-small-2503 rawPredict
mistralai/mistral-medium-3 rawPredict
mistralai/mistral-ocr-2505 rawPredict
mistralai/codestral-2 rawPredict

Beschränkungen

  • Pro Thema oder Abo ist nur ein SMT für KI-Inferenz zulässig.

  • Private Endpunkte werden nicht unterstützt. Selbst bereitgestellte Modelle müssen auf öffentlichen Agent Platform-Endpunkten gehostet werden.

  • Der globale Endpunkt wird nur für Gemini-Basismodelle unterstützt. Für andere Modelle müssen Sie einen regionalen Endpunkt verwenden.

  • Pub/Sub validiert die Eingabenachrichtendaten nicht. Sie sind dafür verantwortlich, dass das Datenformat korrekt ist.

  • Die Transformation sendet eine Inferenzanfrage pro Pub/Sub-Nachricht. Clientseitiges Batching wird nicht ausgeführt.

  • Asynchrone Batch-Inferenz wird nicht unterstützt.

  • Die Inferenz darf nicht länger als 60 Sekunden dauern. Wenn die Zeitüberschreitung 60 Sekunden überschreitet, wird der Zustellungsversuch abgebrochen und Pub/Sub versucht es noch einmal, bis zur konfigurierten Aufbewahrungsdauer für Nachrichten und den Einstellungen für die Wiederholungsrichtlinie. Wenn es zu einer Zeitüberschreitung kommt, wird die Nachricht an das Thema für unzustellbare Nachrichten weitergeleitet, sofern eines konfiguriert ist.

Nicht unterstützte Modelle

Das AI Inference SMT unterstützt die folgenden MaaS-Modelle nicht. Viele dieser Modelle sind auch als selbst bereitgestellte Versionen verfügbar, die Sie stattdessen verwenden können.

  • deepseek-ai/deepseek-ocr-maas
  • deepseek-ai/deepseek-v3.2-maas
  • google/gemini-embedding-2-preview
  • google/lyria-002
  • google/lyria-3-clip-preview
  • google/lyria-3-pro-preview
  • google/veo-3.1-fast-generate-001
  • google/veo-3.1-generate-001
  • intfloat/multilingual-e5-large-instruct-maas
  • intfloat/multilingual-e5-small-instruct-maas
  • minimaxai/minimax-m2-maas
  • moonshotai/kimi-k2-thinking-maas
  • qwen/qwen3-next-80b-a3b-instruct-maas
  • qwen/qwen3-next-80b-a3b-thinking-maas
  • zai-org/glm-4.7-maas
  • zai-org/glm-5-maas

Regionale Einschränkungen

Die folgenden Einschränkungen gelten für AI Inference-SMTs basierend auf der Region des Agent Platform-Endpunkts.

  • Wenn für ein Thema ein AI Inference-SMT definiert ist, muss sich die Endpunktregion in den Regionen befinden, die durch die Nachrichtenspeicherrichtlinie des Themas zulässig sind.

    Diese Einschränkung gilt auch für SMTs für Abos, wenn die Organisationsrichtlinienbeschränkung Übertragungsregionen für Pub/Sub-Nachrichten erzwingen in Kraft ist.

  • Wenn ein AI Inference-SMT für ein Exportabo definiert ist, muss sich die Endpunktregion in der Region der zugehörigen Ressource befinden:

  • Wenn eine Veröffentlichungsanfrage an eine andere Region als die Endpunktregion gesendet wird, leitet Pub/Sub die Anfrage automatisch an die Endpunktregion weiter.

  • Wenn Sie Daten aus einem Abo mit einem SMT für KI-Inferenz abrufen und die Pull-Anfrage an eine andere Region als die Endpunktregion gesendet wird, lehnt Pub/Sub die Anfrage ab. Wir empfehlen, für Pull-Abos einen Standortendpunkt zu verwenden. Diese Einschränkung gilt sowohl für Streaming- als auch für Unary-Pull.

  • Wenn ein Push-Abo ein AI Inference-SMT hat, werden Nachrichten aus der Endpunktregion gepusht. Wenn ein Verstoß gegen eine regionale Einschränkung auftritt, werden keine Nachrichten mehr aus diesem Abo gepusht.

Fehlerbehebung

In diesem Abschnitt finden Sie Tipps zur Fehlerbehebung für das SMT für KI-Inferenz.

  • SMT-Fehler bei Themen Wenn die Inferenz beim Veröffentlichen der Nachricht fehlschlägt, schlägt die gesamte Veröffentlichungsanfrage fehl. Die Fehlerinformationen werden an den Publisher-Client zurückgegeben.

  • SMT-Fehler bei Abos: Wenn die Inferenz bei der Zustellung der Nachricht fehlschlägt, kann die Nachricht an ein Thema für unzustellbare Nachrichten weitergeleitet werden. Wir empfehlen, ein Thema für unzustellbare Nachrichten einzurichten, wenn Sie SMTs für ein Abo verwenden.

  • Fehler bei der Modellinferenz: Wenn die Inferenz fehlschlägt und ein Fehler zurückgegeben wird, prüfen Sie Folgendes:

    • Prüfen Sie, ob der konfigurierte Endpunkt korrekt ist.

    • Prüfen Sie, ob die Pub/Sub-Nachrichtendaten eine gültige Inferenzanfrage für Ihr Modell enthalten.

    • Prüfen Sie, ob alle Modellparameter gültig sind.

    Die Inferenz kann auch aus anderen Gründen fehlschlagen, z. B. aufgrund von Verbindungsproblemen.

  • Berechtigungs- oder Endpunktfehler: Wenn das konfigurierte Dienstkonto die Berechtigung für den Endpunkt verliert oder der Endpunkt gelöscht wird, schlägt der SMT fehl.

Kontingente und Limits

  • Zusätzlich zu den Pub/Sub-Kontingenten und -Limits unterliegt das SMT für KI-Inferenz den Kontingenten und Ratenlimits des Agent Platform-Endpunkts. Die in Pub/Sub integrierte Ablaufsteuerung passt die Anfragerate automatisch an, um eine Überlastung des Endpunkts zu vermeiden. Die Rate darf jedoch das Kontingent des Modells nicht überschreiten.

  • Die endgültige Größe der transformierten Nachricht, einschließlich der Originalnachricht und der Inferenz-Ausgabe, muss unter dem Pub/Sub-Nachrichtengrößenlimit liegen. Wenn die transformierte Nachricht das Limit überschreitet, schlägt die Transformation fehl.

Nächste Schritte