SMT de inferencia de IA

La transformación de mensajes únicos (SMT) de inferencia de IA te permite obtener inferencias sobre mensajes de Pub/Sub a partir de modelos de Gemini Enterprise Agent Platform. Puedes usar tus propios modelos personalizados implementados en los extremos de Agent Platform o cualquiera de los modelos de Google y sus socios disponibles a través de Agent Platform. Las inferencias del modelo se agregan a cada mensaje, lo que las hace disponibles para el procesamiento posterior junto con los datos del mensaje original.

Los casos de uso para el SMT de inferencia de IA incluyen los siguientes:

• Enriquecimiento en tiempo real: Agrega contexto, clasificaciones, predicciones, opiniones o incorporaciones a los datos de eventos a medida que fluyen a través de Pub/Sub.

• Canalizaciones de IA simplificadas: Elimina la necesidad de servicios intermediarios para obtener inferencias de los modelos de IA. Pub/Sub se encarga de llamar al modelo de IA y enriquecer el mensaje con la inferencia.

• Latencia reducida para las canalizaciones de IA: Elimina los saltos de red adicionales en tu arquitectura para lograr una menor latencia de extremo a extremo.

• Control de flujo mejorado: Para evitar la sobrecarga de los extremos del modelo, Pub/Sub optimiza la frecuencia de las solicitudes al modelo de IA. Para obtener más información, consulta Flujo de mensajes en este documento.

El SMT de inferencia de IA admite los siguientes tipos de modelos:

• Modelos implementados automáticamente Modelos abiertos, de socios y personalizados implementados en un extremo público compartido o dedicado de Agent Platform

• Modelos de Modelos como servicio (MaaS). Modelos que se ofrecen como servicio a través de Model Garden, como Gemini y Claude, que no requieren que administres la implementación. Para obtener una lista de los modelos de MaaS que son compatibles con el SMT de inferencia de IA, consulta Modelos de MaaS compatibles.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear un tema o una suscripción con SMT, pídele a tu administrador que te otorgue el rol de IAM de editor de Pub/Sub (roles/pubsub.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear un tema o una suscripción con SMT. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Permisos de las cuentas de servicio

El SMT de AI Inference usa una cuenta de servicio de IAM para llamar al extremo de Agent Platform. De forma predeterminada, se usa la cuenta del agente de servicio de Cloud Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com). También puedes proporcionar tu propia cuenta de servicio.

La cuenta de servicio necesita los siguientes permisos en el proyecto Cloud de Confianceque contiene el extremo de Agent Platform:

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

Para otorgar estos permisos, asigna el siguiente rol de IAM a la cuenta de servicio:

• Si usas la cuenta de servicio del agente de servicio de Cloud Pub/Sub, otorga el rol de agente de servicio de Vertex AI.

• Si usas una cuenta de servicio diferente, otorga el rol de usuario de Vertex AI.

Procesamiento de mensajes

En esta sección, se describe cómo el SMT de inferencia de IA procesa los mensajes de Pub/Sub.

Entrada

Los datos del mensaje de Pub/Sub deben ser una solicitud para enviar al modelo de IA, como una cadena JSON. También puedes especificar parámetros adicionales del modelo para enviar con cada solicitud. El SMT combina estos parámetros con los datos del mensaje y envía el JSON combinado al extremo del modelo.

Por ejemplo, si tienes lo siguiente:

• Datos del mensaje de entrada: {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
• Parámetros de SMT: {"temperature": 0.2}

La carga útil resultante que se envía al modelo es la siguiente:

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

Si un parámetro especificado en la configuración del SMT tiene el mismo nombre que un campo en los datos del mensaje, el valor en los datos del mensaje tendrá prioridad.

En la siguiente tabla, se muestra a qué API llama el SMT para obtener la inferencia, según el tipo de modelo.

Para dar formato correcto a los datos del mensaje y a los parámetros del modelo, consulta la documentación de tu modelo. Por ejemplo, para los modelos básicos de Gemini, consulta los ejemplos de la API de Chat Completions.

Si tu aplicación de publicador no puede dar formato a los mensajes en la estructura JSON específica que requiere el modelo (como el formato de la API de Chat Completions), puedes encadenar una UDF de JavaScript de SMT antes de la SMT de inferencia de IA para realizar el procesamiento previo y dar formato a la carga útil de la solicitud. Para ver un ejemplo, consulta Cómo procesar previamente cargas útiles con una UDF de JavaScript.

Salida

Si la llamada al extremo del modelo se realiza correctamente, el SMT enriquece el mensaje original de Pub/Sub con la respuesta del modelo. El mensaje enriquecido es una cadena JSON como la siguiente, en la que ORIGINAL_MESSAGE son los datos del mensaje original y INFERENCE_RESULT es la respuesta del modelo:

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

Flujo de mensajes

SMT de temas: Cuando defines un SMT de inferencia de IA en un tema, Pub/Sub controla los mensajes entrantes de la siguiente manera:

1. Una aplicación de publicador envía un mensaje a un tema de Pub/Sub.

2. El mensaje se envía al extremo del modelo configurado para la inferencia. El mensaje enriquecido, que contiene los datos originales y la inferencia del modelo, se escribe en el almacenamiento interno de Pub/Sub.

3. Pub/Sub entrega el mensaje enriquecido a todas las suscripciones adjuntas.

SMT de suscripción: Cuando defines un SMT de inferencia de IA en una suscripción, Pub/Sub controla los mensajes entrantes de la siguiente manera:

1. Una aplicación de publicador envía un mensaje a un tema de Pub/Sub.

2. Pub/Sub entrega el mensaje a la suscripción.

3. El mensaje se envía al extremo del modelo configurado para la inferencia.

4. La suscripción envía el mensaje enriquecido a la aplicación de suscriptor.

5. Pub/Sub optimiza la frecuencia de solicitudes al modelo de IA para maximizar la capacidad de procesamiento, según la latencia y la cuota de tu implementación. Nota: Esta capacidad no se admite cuando se usa la API de extracción unaria.

Puedes encadenar una SMT de inferencia de IA con una o más SMT de UDF de JavaScript. Usa este patrón para procesar previamente un mensaje y que se ajuste al formato de entrada esperado de tu modelo, o bien para procesar posteriormente la salida del modelo antes de que se entregue a los suscriptores.

Práctica recomendada: Te recomendamos que uses SMTs de suscripción en lugar de SMTs de temas para la inferencia de IA. Si se limita el extremo del modelo de IA, se producen picos de latencia en las experiencias o deja de estar disponible, el impacto potencial en tu canalización es mayor con un SMT de tema:

• Con un SMT de tema, la solicitud de publicación falla, lo que afecta directamente la disponibilidad de tu aplicación de publicador.

• Con un SMT de suscripción, Pub/Sub reintenta la entrega, incluida la ejecución del SMT, según la política de reintento de la suscripción. También puedes configurar un tema de mensajes no entregados para controlar las fallas persistentes sin afectar la disponibilidad de la transferencia.

Crea una SMT de inferencia de IA

Los SMT se pueden configurar en temas o suscripciones de Pub/Sub.

• Los SMT de temas se ejecutan antes de que Pub/Sub almacene el mensaje, y los resultados están disponibles para todos los suscriptores.

• Los SMT de suscripción se ejecutan antes de que se entregue el mensaje, y los resultados solo están disponibles para esa suscripción.

- 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

Valida y realiza pruebas

De manera opcional, puedes validar y probar el SMT configurado antes de crear el tema o la suscripción. Para obtener más información, consulta los siguientes documentos:

• Crea un tema con SMT
• Crea una suscripción con SMT

Ejemplos

Cómo usar la SMT de inferencia de IA

En el siguiente ejemplo, se muestra cómo crear una suscripción con un SMT de inferencia de IA y, luego, usarlo para enviar una instrucción a Gemini.

Cómo realizar un procesamiento previo de cargas útiles con una UDF de JavaScript

Si tu aplicación de publicador emite texto sin procesar, registros o cargas útiles de eventos en lugar del JSON estructurado que requieren los modelos de IA (como el formato de Chat Completions compatible con OpenAI), puedes encadenar una UDF de JavaScript de SMT antes de la SMT de inferencia de IA. La UDF actúa como una capa de traducción, ya que transforma el mensaje sin procesar en el formato que espera el modelo.

En el siguiente ejemplo de UDF de JavaScript, se muestra cómo preprocesar un mensaje que contiene una instrucción de texto en una solicitud a la API de Chat Completions compatible 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;
}

También puedes encadenar una UDF de JavaScript de procesamiento posterior después del SMT de inferencia de IA para extraer campos específicos de la respuesta del modelo antes de entregarla a los suscriptores.

Modelos de MaaS compatibles

En la siguiente tabla, se enumeran los modelos de Model-as-a-Service (MaaS) que Google probó con el SMT de inferencia de IA y que se sabe que son compatibles. Esta lista está sujeta a cambios, ya que los modelos pueden quedar obsoletos o se pueden agregar nuevos modelos de MaaS.

Limitaciones

• Solo se permite un SMT de inferencia de IA por tema o suscripción.

• No se admiten los extremos privados. Los modelos de implementación propia deben alojarse en extremos públicos de Agent Platform.

• El extremo global solo se admite para los modelos básicos de Gemini. Para otros modelos, debes usar un extremo regional.

• Pub/Sub no valida los datos del mensaje de entrada. Eres responsable de garantizar que el formato de los datos sea correcto.

• La transformación envía una solicitud de inferencia por mensaje de Pub/Sub. No se realiza el procesamiento por lotes del cliente.

• No se admiten las inferencias por lotes asíncronas.

• La inferencia no debe tardar más de 60 segundos. Si supera los 60 segundos, se agota el tiempo de espera del intento de entrega y Pub/Sub vuelve a intentarlo hasta alcanzar la duración de retención de mensajes y la configuración de la política de reintentos configuradas. Si se agota el tiempo de espera del intento, el mensaje se reenvía al tema de mensajes no entregados, si se configuró uno.

Modelos no compatibles

El SMT de inferencia de IA no admite los siguientes modelos de MaaS. Muchos de estos modelos tienen versiones autodeployadas disponibles que puedes usar en su lugar.

• 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

Restricciones regionales

Se aplican las siguientes restricciones a los SMT de inferencia de IA según la región del extremo de la Agent Platform.

• Si se define un SMT de inferencia de IA en un tema, la región del extremo debe estar dentro de las regiones permitidas por la política de almacenamiento de mensajes del tema.

  Esta restricción también se aplica a las SMT de suscripción si la restricción de la política de la organización Enforce in-transit regions for Pub/Sub messages está vigente.

• Si se define un SMT de inferencia de IA en una suscripción de exportación, la región del extremo debe ser la misma que la del recurso asociado:

  • En el caso de una suscripción de BigQuery, es la región de la tabla de destino.
  • Para una suscripción a Cloud Storage, es la región del bucket de Cloud Storage.

• Si se realiza una solicitud de publicación a una región que no es la del extremo, Pub/Sub redirecciona automáticamente la solicitud a la región del extremo.

• Si extraes datos de una suscripción con un SMT de inferencia de IA y la solicitud de extracción se realiza a una región que no es la región del extremo, Pub/Sub rechaza la solicitud. Te recomendamos que uses un endpoint de ubicación para las suscripciones de extracción. Esta restricción se aplica tanto a la extracción de transmisión como a la extracción unaria.

• Cuando una suscripción de envío tiene un SMT de inferencia de IA, la suscripción envía mensajes desde la región del extremo. Si se produce un incumplimiento de restricción regional, Pub/Sub dejará de enviar mensajes desde esa suscripción.

Soluciona problemas

En esta sección, se proporcionan sugerencias para solucionar problemas relacionados con la SMT de inferencia de IA.

• Errores de SMT de temas Si la inferencia falla cuando se publica el mensaje, falla toda la solicitud de publicación. La información del error se devuelve al cliente del publicador.

• Errores de SMT de suscripción. Si la inferencia falla cuando se entrega el mensaje (por ejemplo, debido a la falta de disponibilidad prolongada del modelo, el agotamiento sostenido de la cuota o errores de argumentos no válidos), el mensaje original sin modificar se reenvía al tema de mensajes no entregados configurado. Esto garantiza que no se pierdan datos. El mensaje reenviado incluye un atributo CloudPubSubDeadLetterSourceSMTErrorMessage que contiene los detalles del error de SMT. Recomendamos configurar un tema de mensajes no entregados cuando uses SMT en una suscripción.

• Errores de inferencia del modelo Si la inferencia falla y muestra un error, verifica lo siguiente:

  • Verifica que el extremo configurado sea correcto.

  • Verifica que los datos del mensaje de Pub/Sub contengan una solicitud de inferencia válida para tu modelo.

  • Verifica que todos los parámetros del modelo sean válidos.

  La inferencia puede fallar por otros motivos, como problemas de conectividad.

• Errores de permisos o de extremos. Si la cuenta de servicio configurada pierde permiso para el extremo o si se borra el extremo, la SMT falla.

Cuotas y límites

• Además de las cuotas y los límites de Pub/Sub, el SMT de inferencia de IA está sujeto a las cuotas y los límites de frecuencia del endpoint de Agent Platform. El control de flujo integrado de Pub/Sub ajusta automáticamente la frecuencia de solicitudes para evitar la sobrecarga del extremo, pero la frecuencia no puede exceder la cuota del modelo.

• El tamaño final del mensaje transformado, incluido el mensaje original y el resultado de la inferencia, debe ser inferior al límite de tamaño de mensaje de Pub/Sub. Si el mensaje transformado supera el límite, la transformación falla.

¿Qué sigue?

• Más información sobre las SMT
• Elige los SMT de temas o suscripciones
• Crea un tema con SMT
• Crea una suscripción con SMT