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 di 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 a valle insieme ai dati del messaggio originale.

I casi d'uso per l'AI Inference SMT includono:

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

  • Pipeline AI semplificate: elimina la necessità di servizi intermedi 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 di inferenza AI supporta i seguenti tipi di modello:

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

  • Modelli Model-as-a-Service (MaaS). Modelli offerti come servizio 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 un abbonamento 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 un abbonamento con SMT. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

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

  • Crea un argomento: pubsub.topics.create sul progetto
  • Crea un abbonamento: 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 service agent Cloud Pub/Sub (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 Agent Platform:

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

Per concedere queste autorizzazioni, assegna il seguente ruolo IAM al account di servizio:

Elaborazione dei messaggi

Questa sezione descrive come la 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, sotto forma di stringa JSON. Puoi anche specificare parametri del modello aggiuntivi da inviare con ogni richiesta. SMT unisce questi parametri ai dati del messaggio e invia il JSON unito all'endpoint del modello.

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)

Modello di base 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 modelli di base Gemini, vedi Esempi di API Chat Completions.

Output

Se la chiamata all'endpoint del modello ha esito positivo, SMT arricchisce il messaggio Pub/Sub originale con la risposta del modello. Il messaggio arricchito è una stringa JSON come la seguente, in cui 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 dell'argomento: quando definisci un SMT di inferenza AI su un argomento, Pub/Sub gestisce i messaggi in entrata nel seguente modo:

  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 velocità delle richieste al modello di AI per massimizzare il throughput, in base alla latenza e alla quota del deployment. Nota: Questa funzionalità non è supportata quando si utilizza l'API unary pull.

Puoi concatenare una SMT di inferenza AI con una o più SMT UDF JavaScript. Utilizza questo pattern per pre-elaborare un messaggio in modo che corrisponda al formato di input previsto dal modello o post-elaborare l'output del modello prima che venga inviato agli abbonati.

Crea una SMT di inferenza AI

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

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

  • I test SMT delle sottoscrizioni vengono eseguiti 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. Si apre la pagina Crea argomento.

    • Per creare una sottoscrizione:

      1. Fai clic sul nome dell'argomento a cui vuoi abbonarti.

      2. Fai clic su Crea sottoscrizione. Si apre la pagina Aggiungi sottoscrizione all'argomento.

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

  4. In Tipo di trasformazione, seleziona Inferenza AI.

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

    • Modello autogestito: 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 agent. 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'IA per l'inferenza.

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 autogestito: 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. 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 quando chiami 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 un abbonamento, 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 dell'abbonamento da creare.

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

  • TOPIC_ID: l'ID dell'argomento a cui iscriversi.

  • TRANSFORMS_FILE: il percorso del file di definizione.

Convalida e testa

Se vuoi, puoi convalidare e testare l'SMT configurato prima di creare l'argomento o l'abbonamento. Per saperne di più, consulta i seguenti documenti:

Esempio: utilizzo della SMT di inferenza AI

L'esempio seguente mostra come creare un abbonamento con un SMT AI Inference e poi utilizzarlo per inviare un prompt a Gemini.

gcloud

  1. Con 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-2.5-flash
    unstructuredInference: {
        parameters: {
            "max_tokens": 25000
        }
    }

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • 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 un abbonamento 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-2.5-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.

Modelli MaaS compatibili

La tabella seguente elenca i modelli Model-as-a-Service (MaaS) che Google ha testato con l'SMT 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.

ModelloAPI chiamata
google/gemini-2.0-flash-001 API Chat Completions
google/gemini-2.0-flash-lite-001 API Chat Completions
google/gemini-2.5-flash API Chat Completions
google/gemini-2.5-flash-lite API Chat Completions
google/gemini-2.5-pro API Chat Completions
google/gemini-2.5-flash-image API Chat Completions
google/gemini-3-pro-preview API Chat Completions
google/gemini-3-pro-image-preview API Chat Completions
google/gemini-3-flash-preview API Chat Completions
google/gemini-3.1-pro-preview API Chat Completions
google/gemini-3.1-flash-image-preview API Chat Completions
google/gemini-3.1-flash-lite-preview API Chat Completions
meta/llama-3.3-70b-instruct-maas 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
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 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

Limitazioni

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

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

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

  • Pub/Sub non convalida i dati dei messaggi di input. Sei responsabile di assicurarti che il formato dei dati sia corretto.

  • La trasformazione invia una richiesta di inferenza per ogni messaggio Pub/Sub. Il batch 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 riprova configurate. Se il tentativo scade, il messaggio viene inoltrato all'argomento messaggi non recapitabili, se ne è stato configurato uno.

Modelli non supportati

L'SMT AI Inference non supporta i seguenti modelli MaaS. Molti di questi modelli hanno versioni autogestite disponibili che puoi utilizzare al loro posto.

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

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 riesce quando il messaggio viene consegnato, il messaggio può essere inoltrato a un argomento messaggi non recapitabili. Ti consigliamo di configurare un argomento messaggi non recapitabili quando utilizzi le notifiche di monitoraggio dello stato su 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 l'endpoint viene eliminato, il test SMT non va a buon fine.

Quote e limiti

  • Oltre alle quote e ai limiti di Pub/Sub, l'SMT di inferenza AI è soggetto alle quote e ai limiti di frequenza dell'endpoint della piattaforma dell'agente. Il controllo del 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 finali del messaggio trasformato, 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