SMT per l'inferenza AI

La trasformazione di messaggi singoli (SMT) di inferenza AI ti consente di ottenere inferenze sui messaggi Pub/Sub dai modelli Gemini Enterprise Agent Platform. Puoi utilizzare i tuoi modelli personalizzati di cui è stato eseguito il deployment sugli endpoint di Agent Platform oppure utilizzare uno qualsiasi dei modelli di Google e dei partner disponibili tramite Agent Platform. Le inferenze del modello vengono aggiunte a ogni messaggio, rendendole disponibili per l'elaborazione downstream insieme ai dati del messaggio originale.

I casi d'uso per l'SMT di inferenza AI includono:

  • Arricchimento in tempo reale: aggiungi contesto, classificazioni, previsioni, sentiment o incorporamenti ai dati sugli eventi mentre vengono trasferiti tramite Pub/Sub.

  • Pipeline di AI semplificate: elimina la necessità di servizi intermediari per ottenere inferenze dai modelli di AI. Pub/Sub gestisce la chiamata al modello di AI e arricchisce il messaggio con l'inferenza.

  • Latenza ridotta per le pipeline AI: rimuovi gli hop di rete aggiuntivi nella tua architettura per ottenere una latenza end-to-end inferiore.

  • Controllo del flusso avanzato: per evitare di sovraccaricare gli endpoint del modello, Pub/Sub ottimizza la velocità delle richieste al modello di AI. Per maggiori informazioni, consulta la sezione Flusso dei messaggi in questo documento.

L'SMT AI Inference supporta i seguenti tipi di modello:

  • Modelli di cui è stato eseguito il deployment autonomamente. Modelli aperti, di partner e personalizzati di cui è stato eseguito il deployment su un endpoint Agent Platform pubblico condiviso o dedicato.

  • Modelli Model-as-a-Service (MaaS). Modelli offerti as a service tramite Model Garden, come Gemini e Claude, che non richiedono la gestione del deployment. Per un elenco dei modelli MaaS compatibili con la SMT di inferenza AI, vedi Modelli MaaS compatibili.

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per creare un argomento o una sottoscrizione con SMT, chiedi all'amministratore di concederti il ruolo IAM Pub/Sub Editor (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un argomento o una sottoscrizione con SMT. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un argomento o un abbonamento con SMT sono necessarie le seguenti autorizzazioni:

  • Per creare un argomento: pubsub.topics.create sul progetto
  • Creare una sottoscrizione: pubsub.subscriptions.create sul progetto

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Autorizzazioni service account

L'SMT AI Inference utilizza un account di servizio IAM per chiamare l'endpoint della piattaforma dell'agente. Per impostazione predefinita, utilizza l'account Cloud Pub/Sub Service Agent (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com). Puoi anche fornire il tuo account di servizio.

Il account di servizio deve disporre delle seguenti autorizzazioni per il progetto Google Cloud che contiene l'endpoint della piattaforma dell'agente:

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

Per concedere queste autorizzazioni, assegna il ruolo Utente piattaforma agente al account di servizio (indipendentemente dal fatto che utilizzi il service account Agente di servizio Cloud Pub/Sub o un account di servizio personalizzato).

Elaborazione dei messaggi

Questa sezione descrive come l'SMT di inferenza AI elabora i messaggi Pub/Sub.

Input

I dati del messaggio Pub/Sub devono essere una richiesta da inviare al modello di AI, come stringa JSON. Puoi anche specificare parametri del modello aggiuntivi da inviare con ogni richiesta. L'SMT unisce questi parametri ai dati del messaggio e invia il JSON unito all'endpoint del modello.

Ad esempio, se hai:

  • Dati del messaggio di input: {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
  • Parametri SMT: {"temperature": 0.2}

Il payload risultante inviato al modello è:

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

Se un parametro specificato nella configurazione SMT ha lo stesso nome di un campo nei dati del messaggio, il valore nei dati del messaggio ha la precedenza.

La tabella seguente mostra quale API chiama SMT per ottenere l'inferenza, in base al tipo di modello.

Deployment del modello Tipo di modello API
Deployment autonomo Tutti rawPredict
Model-as-a-Service (MaaS)

Foundation model Gemini

Esempio: gemini-3.0-pro

 Chat Completions API

Altri modelli Gemini

Esempio: gemini-embeddings

 rawPredict
Anthropic, Mistral AI o AI21 rawPredict
Tutti gli altri modelli MaaS Chat Completions API

Per formattare correttamente i dati dei messaggi e i parametri del modello, consulta la documentazione del modello. Ad esempio, per i foundation model di Gemini, consulta Esempi di API Chat Completions.

Se la tua applicazione publisher non riesce a formattare i messaggi nella struttura JSON specifica richiesta dal modello (ad esempio il formato dell'API Chat Completions), puoi concatenare una trasformazione di messaggi singoli (SMT) UDF JavaScript prima della SMT di inferenza AI per pre-elaborare e formattare il payload della richiesta. Per un esempio, consulta Pre-elabora i payload con una funzione definita dall'utente JavaScript.

Output

Se la chiamata all'endpoint del modello va a buon fine, l'SMT arricchisce il messaggio Pub/Sub originale con la risposta del modello. Il messaggio arricchito è una stringa JSON simile alla seguente, dove ORIGINAL_MESSAGE sono i dati del messaggio originale e INFERENCE_RESULT è la risposta del modello:

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

Flusso di messaggi

SMT degli argomenti: quando definisci un SMT di inferenza AI su un argomento, Pub/Sub gestisce i messaggi in arrivo come segue:

  1. Un'applicazione publisher invia un messaggio a un argomento Pub/Sub.

  2. Il messaggio viene inviato all'endpoint del modello configurato per l'inferenza. Il messaggio arricchito, contenente i dati originali e l'inferenza del modello, viene scritto nella memoria interna di Pub/Sub.

  3. Pub/Sub recapita il messaggio arricchito a tutte le sottoscrizioni collegate.

SMT di sottoscrizione: quando definisci un SMT di inferenza AI per una sottoscrizione, Pub/Sub gestisce i messaggi in arrivo nel seguente modo:

  1. Un'applicazione publisher invia un messaggio a un argomento Pub/Sub.

  2. Pub/Sub recapita il messaggio alla sottoscrizione.

  3. Il messaggio viene inviato all'endpoint del modello configurato per l'inferenza.

  4. La sottoscrizione invia il messaggio arricchito all'applicazione del sottoscrittore.

  5. Pub/Sub ottimizza la frequenza delle richieste al modello di AI per massimizzare la velocità effettiva, in base alla latenza e alla quota del deployment. Nota: questa funzionalità non è supportata quando si utilizza l'API di pull unario.

Puoi concatenare una SMT di inferenza AI con una o più SMT di funzioni definite dall'utente JavaScript. Utilizza questo pattern per pre-elaborare un messaggio in modo che si adatti al formato di input previsto del modello o per post-elaborare l'output del modello prima che venga consegnato agli iscritti.

Best practice: ti consigliamo vivamente di utilizzare gli SMT di abbonamento anziché gli SMT di argomento per l'inferenza AI. Se l'endpoint del modello di AI viene limitato, si verificano picchi di latenza o diventa non disponibile, l'impatto potenziale sulla pipeline è maggiore con un SMT di argomento:

  • Con un SMT per l'argomento, la richiesta di pubblicazione non va a buon fine, con un impatto diretto sulla disponibilità dell'applicazione publisher.

  • Con una SMT di sottoscrizione, Pub/Sub riprova la consegna, inclusa l'esecuzione della SMT, in base al criterio di ripetizione della sottoscrizione. Puoi anche configurare un argomento messaggi non recapitabili per gestire gli errori persistenti senza influire sulla disponibilità dell'importazione.

Crea una SMT di inferenza AI

Le SMT possono essere configurate su argomenti o sottoscrizioni Pub/Sub.

  • Le trasformazioni SMT dell'argomento vengono eseguite prima che Pub/Sub memorizzi il messaggio e i risultati sono disponibili per tutti i sottoscrittori.

  • Le SMT della sottoscrizione vengono eseguite prima del recapito del messaggio e i risultati sono disponibili solo per quella sottoscrizione.

Console

  1. Nella console Google Cloud , vai alla pagina Argomenti di Pub/Sub.

    Vai ad Argomenti

  2. Crea un argomento o una sottoscrizione.

    • Per creare un argomento, fai clic su Crea argomento. Viene visualizzata la pagina Crea argomento.

    • Per creare una sottoscrizione:

      1. Fai clic sul nome dell'argomento in cui vuoi creare la sottoscrizione.

      2. Fai clic su Crea sottoscrizione. Viene visualizzata la pagina Aggiungi sottoscrizione all'argomento.

  3. In Trasformazioni, fai clic su Aggiungi una trasformazione.

  4. In Tipo di trasformazione, seleziona Inferenza AI.

  5. In Endpoint, inserisci il nome completo della risorsa dell'endpoint del modello:

    • Modello autodeploy: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Modello Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  6. Facoltativo. Seleziona un service account da utilizzare quando chiami l'endpoint della piattaforma dell'agente. Per saperne di più, consulta Autorizzazioni dei service account.

  7. Facoltativo. Nel campo Parametri, inserisci i parametri del modello come oggetto JSON. L'SMT unisce questi parametri a ogni messaggio prima di chiamare il modello. Esempio:

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

  8. Per creare l'argomento o l'abbonamento, fai clic su Crea.

gcloud

Crea un file di definizione

Crea un file YAML o JSON che definisca l'Inference AI.

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

Sostituisci quanto segue:

  • ENDPOINT_RESOURCE: il nome completo della risorsa dell'endpoint del modello. Utilizza il formato seguente:

    • Modello di cui è stato eseguito il deployment autonomo: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
    • Modello Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

  • MODEL_PARAMETERS: (Facoltativo) Parametri del modello, specificati come oggetto JSON. L'SMT unisce questi parametri a ogni messaggio prima di chiamare il modello. Esempio:

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

  • SERVICE_ACCOUNT: (Facoltativo) Un indirizzo email del account di servizio da utilizzare per chiamare l'endpoint. Per saperne di più, consulta Autorizzazioni dei service account.

Crea un argomento o una sottoscrizione

Per creare un argomento, esegui il comando gcloud pubsub topics create.

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

Sostituisci quanto segue:

  • TOPIC_ID: l'ID o il nome dell'argomento che vuoi creare.
  • TRANSFORMS_FILE: il percorso del file di definizione.

Per creare una sottoscrizione, esegui il comando gcloud pubsub subscriptions create.

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

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID o il nome della sottoscrizione da creare.

  • PROJECT_ID: l'ID del progetto che contiene l'argomento.

  • TOPIC_ID: l'ID dell'argomento a cui vuoi iscriverti.

  • TRANSFORMS_FILE: il percorso del file di definizione.

Convalida e testa

Facoltativamente, puoi convalidare e testare l'SMT configurata prima di creare l'argomento o la sottoscrizione. Per saperne di più, consulta i seguenti documenti:

Esempi

Utilizza l'SMT di inferenza AI

L'esempio seguente mostra come creare una sottoscrizione con un SMT di AI Inference e poi utilizzarla per inviare un prompt a Gemini.

gcloud

  1. Tramite un editor di testo, crea un file denominato ai-smt.yaml e incolla il seguente testo:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • LOCATION: la posizione dell'endpoint da chiamare. Esempio: us-central1.

  2. Crea un nuovo argomento Pub/Sub.

    gcloud pubsub topics create TOPIC_ID

    Sostituisci TOPIC_ID con il nome dell'argomento da creare. Esempio: topic-1.

  3. Crea una sottoscrizione con un SMT di inferenza AI.

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

  4. Pubblica un messaggio nell'argomento. Il messaggio contiene un prompt formattato per l'API Chat Completions.

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

  5. Ricevi un messaggio dalla sottoscrizione.

    gcloud pubsub subscriptions pull TOPIC_ID-sub

    Se la chiamata alla piattaforma dell'agente va a buon fine, il messaggio viene arricchito con l'output del prompt.

Preelaborare i payload con una funzione JavaScript definita dall'utente

Se la tua applicazione publisher emette testo non elaborato, log o payload di eventi anziché il JSON strutturato richiesto dai modelli di AI (come il formato Chat Completions compatibile con OpenAI), puoi concatenare una UDF JavaScript SMT prima dell'SMT di inferenza dell'AI. La funzione definita dall'utente funge da livello di traduzione, trasformando il messaggio non elaborato nel formato previsto dal modello.

Il seguente esempio di UDF JavaScript mostra come pre-elaborare un messaggio contenente un prompt testuale in una richiesta dell'API Chat Completions compatibile con Gemini 3.8 Flash:

/**
 * Pre-processes a message containing a text prompt into a
 * Chat Completions API request compatible with Gemini 3.8 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.8-flash",
    "messages": [
      {
        "role": "user",
        "content": promptText
      }
    ]
  };

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

Puoi anche concatenare una funzione definita dall'utente JavaScript di post-elaborazione dopo l'SMT di AI Inference per estrarre campi specifici dalla risposta del modello prima di inviarla agli iscritti.

Modelli MaaS compatibili

La tabella seguente elenca i modelli Model-as-a-Service (MaaS) che Google ha testato con l'SMT di AI Inference e che sono noti per essere compatibili. Questo elenco è soggetto a modifiche, poiché i modelli diventano obsoleti o vengono aggiunti nuovi modelli MaaS.

ModelloChiamata API
google/gemini-3.8-flash API Chat Completions
google/gemini-3.7-flash API Chat Completions
google/gemini-3.6-flash API Chat Completions
google/gemini-3.5-flash API Chat Completions
google/gemini-3.5-flash-lite API Chat Completions
google/gemini-3.1-flash-lite API Chat Completions
google/gemini-3.1-pro-preview API Chat Completions
google/gemini-3-flash-preview API Chat Completions
google/gemini-3.1-flash-image API Chat Completions
google/gemini-3-pro-image API Chat Completions
google/gemini-2.5-flash-image API Chat Completions
google/gemini-2.5-pro API Chat Completions
google/gemini-2.5-flash-lite API Chat Completions
google/gemini-2.5-flash API Chat Completions
google/gemini-2.0-flash-lite-001 API Chat Completions
google/gemini-2.0-flash-001 API Chat Completions
meta/llama-4-maverick-17b-128e-instruct-maas API Chat Completions
meta/llama-4-scout-17b-16e-instruct-maas API Chat Completions
meta/llama-3.3-70b-instruct-maas API Chat Completions
deepseek-ai/deepseek-r1-0528-maas API Chat Completions
deepseek-ai/deepseek-v3.1-maas API Chat Completions
qwen/qwen3-235b-a22b-instruct-2507-maas API Chat Completions
qwen/qwen3-coder-480b-a35b-instruct-maas API Chat Completions
openai/gpt-oss-20b-maas API Chat Completions
openai/gpt-oss-120b-maas API Chat Completions
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-6 rawPredict
anthropic/claude-sonnet-4-5 rawPredict
anthropic/claude-sonnet-4 rawPredict
anthropic/claude-opus-4-6 rawPredict
anthropic/claude-opus-4-5 rawPredict
anthropic/claude-opus-4-1 rawPredict
anthropic/claude-opus-4 rawPredict
anthropic/claude-haiku-4-5 rawPredict
mistralai/mistral-ocr-2505 rawPredict
mistralai/mistral-small-2503 rawPredict
mistralai/mistral-medium-3 rawPredict
mistralai/codestral-2 rawPredict

Limitazioni

  • È consentita una sola SMT di inferenza AI per argomento o sottoscrizione.

  • Gli endpoint privati non sono supportati. I modelli con deployment autonomo devono essere ospitati su endpoint Agent Platform pubblici.

  • L'endpoint globale è supportato solo per i foundation model di Gemini. Per gli altri modelli, devi utilizzare un endpoint regionale.

  • Pub/Sub non convalida i dati dei messaggi di input. È tua responsabilità assicurarti che il formato dei dati sia corretto.

  • La trasformazione invia una richiesta di inferenza per messaggio Pub/Sub. Il raggruppamento lato client non viene eseguito.

  • Le inferenze in batch asincrone non sono supportate.

  • L'inferenza non deve richiedere più di 60 secondi. Se supera i 60 secondi, il tentativo di consegna scade e Pub/Sub riprova, fino alla durata di conservazione dei messaggi e alle impostazioni dei criteri di ripetizione dei tentativi configurate. Se il tentativo scade, il messaggio viene inoltrato all'argomento messaggi non recapitabili, se ne è stato configurato uno.

Modelli non supportati

L'SMT di AI Inference non supporta i seguenti modelli MaaS. Molti di questi modelli hanno versioni con deployment autonomo che puoi utilizzare.

  • 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

Vincoli regionali

I seguenti vincoli si applicano agli SMT di AI Inference in base alla regione dell'endpoint della piattaforma dell'agente.

  • Se per un argomento è definita una SMT di AI Inference, la regione dell'endpoint deve rientrare nelle regioni consentite dalla policy di archiviazione dei messaggi dell'argomento.

    Questo vincolo si applica anche alle SMT delle sottoscrizioni se è attivo il vincolo della policy dell'organizzazione Applica le regioni in transito per i messaggi Pub/Sub.

  • Se un SMT di inferenza AI è definito in un abbonamento di esportazione, la regione dell'endpoint deve trovarsi nella regione della risorsa associata:

  • Se viene effettuata una richiesta di pubblicazione in una regione diversa da quella dell'endpoint, Pub/Sub reindirizza automaticamente la richiesta alla regione dell'endpoint.

  • Se esegui il pull da una sottoscrizione con un SMT di inferenza AI e la richiesta di pull viene effettuata in una regione diversa da quella dell'endpoint, Pub/Sub rifiuta la richiesta. Ti consigliamo di utilizzare un endpoint di località per le sottoscrizioni pull. Questo vincolo si applica sia al pull di streaming sia al pull unario.

  • Quando una sottoscrizione push ha un SMT di AI Inference, la sottoscrizione esegue il push dei messaggi dalla regione dell'endpoint. Se si verifica una violazione del vincolo regionale, Pub/Sub interrompe l'invio dei messaggi da quella sottoscrizione.

Risoluzione dei problemi

Questa sezione fornisce suggerimenti per la risoluzione dei problemi relativi alla SMT di inferenza AI.

  • Errori SMT relativi agli argomenti. Se l'inferenza non riesce quando il messaggio viene pubblicato, l'intera richiesta di pubblicazione non va a buon fine. Le informazioni sull'errore vengono restituite al client publisher.

  • Errori SMT relativi all'abbonamento. Se l'inferenza non va a buon fine quando il messaggio viene recapitato (ad esempio a causa di un'indisponibilità prolungata del modello, di un esaurimento della quota o di errori di argomenti non validi), il messaggio originale non modificato viene inoltrato all'argomento messaggi non recapitabili configurato. In questo modo, non vengono persi dati. Il messaggio inoltrato include un attributo CloudPubSubDeadLetterSourceSMTErrorMessage contenente i dettagli dell'errore SMT. Ti consigliamo di configurare un argomento messaggi non recapitabili quando utilizzi le trasformazioni SMT in un abbonamento.

  • Errori di inferenza del modello. Se l'inferenza non va a buon fine e restituisce un errore, controlla quanto segue:

    • Verifica che l'endpoint configurato sia corretto.

    • Verifica che i dati del messaggio Pub/Sub contengano una richiesta di inferenza valida per il tuo modello.

    • Verifica che tutti i parametri del modello siano validi.

    L'inferenza potrebbe non riuscire per altri motivi, ad esempio problemi di connettività.

  • Errori di autorizzazione o endpoint. Se il account di servizio configurato perde l'autorizzazione per l'endpoint o se l'endpoint viene eliminato, l'SMT non va a buon fine.

Quote e limiti

  • Oltre alle quote e ai limiti di Pub/Sub, l'SMT di AI Inference è soggetto alle quote e ai limiti di frequenza dell'endpoint della piattaforma agente. Il controllo di flusso integrato di Pub/Sub regola automaticamente il tasso di richieste per evitare di sovraccaricare l'endpoint, ma il tasso non può superare la quota del modello.

  • Le dimensioni del messaggio trasformato finale, inclusi il messaggio originale e l'output dell'inferenza, devono essere inferiori al limite di dimensioni del messaggio di Pub/Sub. Se il messaggio trasformato supera il limite, la trasformazione non va a buon fine.

Passaggi successivi