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 della piattaforma agentica Gemini Enterprise. 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 AI Inference 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 una sottoscrizione con SMT. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

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 Agent. Per impostazione predefinita, utilizza l'account Agente di servizio Cloud Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com). Puoi anche fornire il tuo account di servizio.

Il account di servizio deve disporre delle seguenti autorizzazioni per il progetto Cloud de Confiance 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:

• Se utilizzi il account di servizio Agente di servizio Cloud Pub/Sub, concedi il ruolo Agente di servizio Vertex AI.

• Se utilizzi un account di servizio diverso, concedi il ruolo Utente Vertex AI.

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

Ad esempio, se hai:

• Inserisci i dati del messaggio: {"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.

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, 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 UDF JavaScript SMT prima della SMT AI Inference per pre-elaborare e formattare il payload della richiesta. Per un esempio, consulta Pre-elaborare i payload con una UDF JavaScript.

Output

Se la chiamata all'endpoint del modello va a buon fine, la SMT arricchisce il messaggio Pub/Sub originale con la risposta del modello. Il messaggio arricchito è una stringa JSON simile alla 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 di funzioni definite dall'utente 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.

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

• Con un SMT dell'argomento, la richiesta di pubblicazione non va a buon fine, il che influisce direttamente sulla disponibilità della tua applicazione publisher.

• Con una SMT di abbonamento, Pub/Sub ritenta il recapito, inclusa l'esecuzione della SMT, in base al criterio di ripetizione dei tentativi dell'abbonamento. Puoi anche configurare un argomento messaggi non recapitabili per gestire gli errori permanenti senza influire sulla disponibilità dell'importazione.

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.

- 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

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:

• Creare un argomento con le SMT
• Creare un abbonamento con SMT

Esempi

Utilizzare la 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.

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 della SMT AI Inference. La UDF 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 di testo in una richiesta dell'API Chat Completions compatibile con Gemini 3.5 Flash:

/**
 * 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;
}

Puoi anche concatenare una UDF JavaScript di post-elaborazione dopo l'SMT di inferenza AI per estrarre campi specifici dalla risposta del modello prima di inviarla agli abbonati.

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.

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 configurata e alle impostazioni dei criteri di riprova. Se il tentativo scade, il messaggio viene inoltrato all'argomento messaggi non recapitabili, se ne è stato configurato uno.

Modelli non supportati

La trasformazione AI Inference non supporta i seguenti modelli MaaS. Molti di questi modelli hanno versioni con deployment automatico 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 di Agent Platform.

• Se su un argomento è definito un SMT di inferenza AI, la regione dell'endpoint deve trovarsi all'interno delle regioni consentite dal criterio di archiviazione dei messaggi dell'argomento.

  Questo vincolo si applica anche alle SMT delle sottoscrizioni se è attivo il vincolo relativo al criterio dell'organizzazione per l'applicazione delle regioni in transito per i messaggi Pub/Sub.

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

  • Per una sottoscrizione BigQuery, la regione della tabella di destinazione.
  • Per un abbonamento per l'archiviazione Cloud Storage, la regione del bucket Cloud Storage.

• Se viene effettuata una richiesta di pubblicazione a 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 localizzazione per gli abbonamenti pull. Questo vincolo si applica sia al pull di streaming sia al pull unario.

• Quando una sottoscrizione push ha un SMT di inferenza AI, la sottoscrizione esegue il push dei messaggi dalla regione dell'endpoint. Se si verifica una violazione del vincolo regionale, Pub/Sub interrompe il push 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 una mancata disponibilità prolungata del modello, dell'esaurimento della quota o di errori di argomenti non validi), il messaggio originale e non modificato viene inoltrato all'argomento messaggi non recapitabili configurato. In questo modo, nessun dato viene perso. Il messaggio inoltrato include un attributo CloudPubSubDeadLetterSourceSMTErrorMessage contenente i dettagli dell'errore SMT. Ti consigliamo di configurare un argomento messaggi non recapitabili quando utilizzi 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 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 di Agent Platform. 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 del messaggio trasformato finale, inclusi il messaggio originale e l'output di inferenza, devono essere inferiori al limite di dimensioni dei messaggi di Pub/Sub. Se il messaggio trasformato supera il limite, la trasformazione non va a buon fine.

Passaggi successivi

• Scopri di più sulle trasformazioni SMT
• Scegliere le SMT per argomenti o abbonamenti
• Creare un argomento con le SMT
• Creare un abbonamento con SMT