SMT für KI-Inferenz

Mit der AI Inference Single Method Transform (SMT) können Sie Vorhersagen zu Pub/Sub-Nachrichten von 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 Agent Platform verfügbar sind. Die Vorhersagen des Modells werden jeder Nachricht hinzugefügt und sind 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 Vermittlungsdienste 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 eine geringere End-to-End-Latenz zu erzielen.

• 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 Editor (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:

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.s3ns-system.iam.gserviceaccount.com) verwendet. Sie können auch ein eigenes Dienstkonto angeben.

Das Dienstkonto benötigt die folgenden Berechtigungen für das Projekt Cloud de Confiance, 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-Dienst-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. Das SMT führt diese Parameter mit den Nachrichtendaten zusammen und sendet das zusammengeführte JSON an den Modellendpunkt.

Beispiel:

• Eingabedaten für die Nachricht: {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
• SMT-Parameter:{"temperature": 0.2}

Die resultierende Nutzlast, die an das Modell gesendet wird, sieht so aus:

{
  "messages": [
    {
      "role": "user",
      "content": "Explain photosynthesis"
    }
  ],
  "temperature": 0.2
}

Wenn ein in der SMT-Konfiguration angegebener Parameter denselben Namen wie ein Feld in den Nachrichtendaten hat, hat der Wert in den Nachrichtendaten Vorrang.

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

Informationen zur korrekten Formatierung der Nachrichtendaten und Modellparameter finden Sie in der Dokumentation für Ihr Modell. Beispiele für Gemini-Basismodelle finden Sie unter Chat Completions API-Beispiele.

Wenn Ihre Publisher-Anwendung Nachrichten nicht in der spezifischen JSON-Struktur formatieren kann, die für das Modell erforderlich ist (z. B. das Format der Chat Completions API), können Sie eine JavaScript-UDF SMT vor der AI Inference-SMT verketten, um die Anfrage-Payload vorzuverarbeiten und zu formatieren. Ein Beispiel finden Sie unter Nutzlasten mit einer JavaScript-UDF vorverarbeiten.

Ausgabe

Wenn der Aufruf des Modellendpunkts erfolgreich ist, reichert die 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 ein 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 Ihrer Bereitstellung zu maximieren. Hinweis: Diese Funktion wird bei Verwendung der unären Pull-API nicht unterstützt.

Sie können eine KI-Inferenz-SMT mit einer oder mehreren JavaScript-UDF-SMTs verketten. Verwenden Sie dieses Muster, um eine Nachricht vorzuverarbeiten, damit sie dem erwarteten Eingabeformat Ihres Modells entspricht, oder um die Ausgabe des Modells nachzubearbeiten, bevor sie an Abonnenten gesendet wird.

Best Practice:Wir empfehlen dringend, für die KI-Inferenz SMTs für Abos anstelle von Themen-SMTs zu verwenden. Wenn der KI-Modellendpunkt gedrosselt wird, es zu Latenzspitzen kommt oder er nicht mehr verfügbar ist, sind die potenziellen Auswirkungen auf Ihre Pipeline bei einem thematischen SMT größer:

• Bei einem Thema-SMT schlägt die Veröffentlichungsanfrage fehl, was sich direkt auf die Verfügbarkeit Ihrer Publisher-Anwendung auswirkt.

• Bei einem Abo-SMT wiederholt Pub/Sub die Zustellung, einschließlich der Ausführung des SMT, gemäß der Wiederholungsrichtlinie des Abos. Sie können auch ein Thema für unzustellbare Nachrichten konfigurieren, um dauerhafte Fehler zu beheben, ohne die Verfügbarkeit der Aufnahme zu beeinträchtigen.

SMT für KI-Inferenz erstellen

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

• Themen-SMTs 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.

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

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

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

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

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:

• Thema mit SMTs erstellen
• Abo mit SMTs erstellen

Beispiele

AI Inference 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.

Payloads mit einer JavaScript-UDF vorverarbeiten

Wenn in Ihrer Publisher-Anwendung Rohtext, Logs oder Ereignisnutzlasten anstelle des strukturierten JSON ausgegeben werden, das für KI-Modelle erforderlich ist (z. B. das OpenAI-kompatible Chat Completions-Format), können Sie eine JavaScript-UDF-SMT vor der AI Inference-SMT verketten. Die UDF fungiert als Übersetzungsebene und wandelt die Rohdaten in das Format um, das das Modell erwartet.

Das folgende JavaScript-UDF-Beispiel zeigt, wie Sie eine Nachricht mit einem Text-Prompt in eine Chat Completions API-Anfrage vorverarbeiten, die mit Gemini 3.5 Flash kompatibel ist:

/**
 * Pre-processes a message containing a text prompt into a
 * Chat Completions API request compatible with Gemini 3.5 Flash.
 */
function prepareGeminiRequest(message, metadata) {
  // Assuming the incoming message data is a raw text prompt
  const promptText = message.data;

  const chatRequest = {
    "model": "google/gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": promptText
      }
    ]
  };

  // Replace the message data with the stringified JSON request
  message.data = JSON.stringify(chatRequest);
  return message;
}

Sie können auch eine JavaScript-UDF für die Nachbearbeitung nach dem AI Inference-SMT verketten, um bestimmte Felder aus der Antwort des Modells zu extrahieren, bevor sie an Abonnenten gesendet wird.

Kompatible MaaS-Modelle

In der folgenden Tabelle sind die Model-as-a-Service-Modelle (MaaS) 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.

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-Foundation-Modelle 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 Batchinferenzen werden nicht unterstützt.

• Die Inferenz darf nicht länger als 60 Sekunden dauern. Wenn die Zeitüberschreitung 60 Sekunden überschreitet, wird der Zustellversuch 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 zugelassen sind.

  Diese Einschränkung gilt auch für Abo-SMTs, wenn die Beschränkung für die Organisationsrichtlinie Ü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:

  • Für ein BigQuery-Abo die Region der Zieltabelle.
  • Bei einem Cloud Storage-Abo die Region des Cloud Storage-Bucket.

• 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 per Push übertragen. 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 für 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 (z. B. aufgrund einer längeren Nichtverfügbarkeit des Modells, einer anhaltenden Erschöpfung des Kontingents oder Fehlern aufgrund ungültiger Argumente), wird die ursprüngliche, unveränderte Nachricht an das konfigurierte Thema für unzustellbare Nachrichten weitergeleitet. So gehen keine Daten verloren. Die weitergeleitete Nachricht enthält ein CloudPubSubDeadLetterSourceSMTErrorMessage-Attribut mit den Details des SMT-Fehlers. 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 integrierte Ablaufsteuerung von Pub/Sub passt die Anforderungsrate 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 ursprünglichen Nachricht 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

• Weitere Informationen zu SMTs
• SMTs für Themen oder Abos auswählen
• Thema mit SMTs erstellen
• Abo mit SMTs erstellen