SMT de inferencia de IA

La transformación de método único (SMT) de inferencia de IA te permite obtener inferencias en mensajes de Pub/Sub de modelos de Gemini Enterprise Agent Platform. Puedes usar tus propios modelos personalizados implementados en los extremos de Agent Platform o usar cualquiera de los modelos de Google y de 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.

Entre los casos de uso de la SMT de inferencia de IA, se 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 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: Quita los saltos de red adicionales en tu arquitectura para lograr una latencia de extremo a extremo más baja.

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

La SMT de AI Inference admite los siguientes tipos de modelos:

• Modelos autoimplementados. 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 la 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:

Permisos necesarios

Se requieren los siguientes permisos para crear un tema o una suscripción con SMT:

• Para crear un tema, haz lo siguiente: pubsub.topics.create en el proyecto.
• Para crear una suscripción, haz lo siguiente: pubsub.subscriptions.create en el proyecto.

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, usa la cuenta del agente de servicio de Cloud Pub/Sub ([e-mail]). También puedes proporcionar tu propia cuenta de servicio.

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

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

Para otorgar estos permisos, asigna el rol de usuario de Agent Platform a la cuenta de servicio (ya sea que uses la cuenta de servicio del agente de servicio de Cloud Pub/Sub o una cuenta de servicio personalizada).

Procesamiento de mensajes

En esta sección, se describe cómo la 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 de modelo adicionales para enviar con cada solicitud. La 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 de SMT tiene el mismo nombre que un campo en los datos del mensaje, el valor en los datos del mensaje tiene prioridad.

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

Implementación del modelo	Tipo de modelo	API
Implementación propia	Todos	rawPredict
Model-as-a-Service (MaaS)	Modelo de base de Gemini Ejemplo: gemini-3.0-pro	Chat Completions API
	Otros modelos de Gemini Ejemplo: gemini-embeddings	rawPredict
	Anthropic, Mistral AI o AI21	rawPredict
	Todos los demás modelos de MaaS	Chat Completions API

Para dar formato correctamente a los datos del mensaje y a los parámetros del modelo, consulta la documentación de tu modelo. Por ejemplo, para los modelos de base de Gemini, consulta 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 SMT de UDF de JavaScript antes de la SMT de AI Inference para procesar previamente 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 de forma correcta, la 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 una 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 del suscriptor.

5. Pub/Sub optimiza la tasa 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 preprocesar un mensaje y adaptarlo al formato de entrada esperado de tu modelo, o bien para posprocesar el resultado del modelo antes de que se entregue a los suscriptores.

Práctica recomendada: Te recomendamos que uses SMT de suscripción en lugar de SMT de tema para la inferencia de IA. Si se limita el extremo del modelo de IA, se producen picos de latencia en las experiencias o el extremo 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 vuelve a intentar la entrega, incluida la ejecución del SMT, según la política de reintentos 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.

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

Console

1. En la consola de Google Cloud , ve a la página Temas de Pub/Sub.

   Ir a temas

2. Crea un tema o una suscripción.

   • Para crear un tema, haz clic en Crear tema. Se abrirá la página Crear tema.

   • Sigue los pasos a continuación para crear una suscripción:

     1. Haz clic en el nombre del tema al que te quieres suscribir.

     2. Haz clic en Crear suscripción. Se abrirá la página Agregar suscripción al tema.

3. En Transformaciones, haz clic en Agregar una transformación.

4. En Tipo de transformación, selecciona Inferencia de IA.

5. En Endpoint, ingresa el nombre completo del recurso del extremo de tu modelo:

   • Modelo implementado por el usuario: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
   • Modelo de Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

6. Es opcional. Selecciona una cuenta de servicio para usar cuando llames al extremo de Agent Platform. Para obtener más información, consulta Permisos de cuentas de servicio.

7. Es opcional. En el campo Parámetros, ingresa los parámetros del modelo como un objeto JSON. La SMT combina estos parámetros con cada mensaje antes de llamar al modelo. Ejemplo:

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

8. Para crear el tema o la suscripción, haz clic en Crear.

gcloud

Crea un archivo de definición

Crea un archivo YAML o JSON que defina la IA de inferencia.

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

Reemplaza lo siguiente:

• ENDPOINT_RESOURCE: Es el nombre completo del recurso del extremo del modelo. Usa el siguiente formato:

  • Modelo implementado por el usuario: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
  • Modelo de Model Garden: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

• MODEL_PARAMETERS: Opcional Parámetros del modelo, especificados como un objeto JSON. El SMT combina estos parámetros con cada mensaje antes de llamar al modelo. Ejemplo:

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

• SERVICE_ACCOUNT: Opcional Es la dirección de correo electrónico de una cuenta de servicio que se usará cuando se llame al extremo. Para obtener más información, consulta Permisos de cuentas de servicio.

Crea un tema o una suscripción

Para crear un tema, ejecuta el comando gcloud pubsub topics create.

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

Reemplaza lo siguiente:

• TOPIC_ID: Es el ID o el nombre del tema que deseas crear.
• TRANSFORMS_FILE: Es la ruta de acceso al archivo de definición.

Para crear una suscripción, ejecuta el comando gcloud pubsub subscriptions create.

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

Reemplaza lo siguiente:

• SUBSCRIPTION_ID: Es el ID o el nombre de la suscripción que se creará.

• PROJECT_ID: Es el ID del proyecto que contiene el tema.

• TOPIC_ID: Es el ID del tema al que se suscribirá.

• TRANSFORMS_FILE: Es la ruta de acceso al archivo de definición.

Valida y realiza pruebas

De manera opcional, puedes validar y probar la SMT configurada 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

Nota: Si pruebas el SMT, Pub/Sub llamará a tu modelo de Agent Platform para realizar la prueba. Se te factura por el uso de Agent Platform.

Ejemplos

Usa 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, usarla para enviar una instrucción a Gemini.

gcloud

1. Con un editor de texto, crea un archivo llamado ai-smt.yaml y pega el siguiente texto:

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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud.
   • LOCATION: Es la ubicación del extremo al que se llamará. Ejemplo: us-central1.

2. Crea un tema de Pub/Sub nuevo.

   gcloud pubsub topics create TOPIC_ID
   

   Reemplaza TOPIC_ID por el nombre del tema que deseas crear. Ejemplo: topic-1.

3. Crea una suscripción que tenga un SMT de inferencia de IA.

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

4. Publica un mensaje en el tema. El mensaje contiene una instrucción que se formatea para la API de 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. Recibe un mensaje de la suscripción.

   gcloud pubsub subscriptions pull TOPIC_ID-sub
   

   Si la llamada a Agent Platform se realiza correctamente, el mensaje se enriquece con el resultado de la instrucción.

Procesa previamente las 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 finalizaciones de chat compatible con OpenAI), puedes encadenar una SMT de UDF de JavaScript 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 procesar previamente 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 de la 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

Nota: Te recomendamos que migres a los modelos más recientes disponibles cuando sea posible, en especial para los modelos de Gemini, ya que la compatibilidad y la disponibilidad de los modelos están sujetas a cambios. Para obtener orientación sobre la migración, consulta Migra a los modelos nuevos.

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 se vuelven obsoletos o se agregan nuevos modelos de MaaS.

Modelo	Llamada a la API
google/gemini-3.8-flash	API de Chat Completions
google/gemini-3.7-flash	API de Chat Completions
google/gemini-3.6-flash	API de Chat Completions
google/gemini-3.5-flash	API de Chat Completions
google/gemini-3.5-flash-lite	API de Chat Completions
google/gemini-3.1-flash-lite	API de Chat Completions
google/gemini-3.1-pro-preview	API de Chat Completions
google/gemini-3-flash-preview	API de Chat Completions
google/gemini-3.1-flash-image	API de Chat Completions
google/gemini-3-pro-image	API de Chat Completions
google/gemini-2.5-flash-image	API de Chat Completions
google/gemini-2.5-pro	API de Chat Completions
google/gemini-2.5-flash-lite	API de Chat Completions
google/gemini-2.5-flash	API de Chat Completions
google/gemini-2.0-flash-lite-001	API de Chat Completions
google/gemini-2.0-flash-001	API de Chat Completions
meta/llama-4-maverick-17b-128e-instruct-maas	API de Chat Completions
meta/llama-4-scout-17b-16e-instruct-maas	API de Chat Completions
meta/llama-3.3-70b-instruct-maas	API de Chat Completions
deepseek-ai/deepseek-r1-0528-maas	API de Chat Completions
deepseek-ai/deepseek-v3.1-maas	API de Chat Completions
qwen/qwen3-235b-a22b-instruct-2507-maas	API de Chat Completions
qwen/qwen3-coder-480b-a35b-instruct-maas	API de Chat Completions
openai/gpt-oss-20b-maas	API de Chat Completions
openai/gpt-oss-120b-maas	API de 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

Limitaciones

• Solo se permite una 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 es compatible con los modelos de base de Gemini. En el caso de otros modelos, debes usar un extremo regional.

• Pub/Sub no valida los datos de los mensajes de entrada. Tú eres responsable de asegurarte de 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, el intento de entrega se agota y Pub/Sub vuelve a intentarlo, hasta 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 hay uno configurado.

Modelos no compatibles

El SMT de inferencia de IA no admite los siguientes modelos de MaaS. Muchos de estos modelos tienen versiones autoimplementadas 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

Las siguientes restricciones se aplican a los SMT de AI Inference según la región del extremo de la plataforma del agente.

• 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 está vigente la restricción de la política de la organización Aplica regiones en tránsito para los mensajes de Pub/Sub.

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

  • Para una suscripción de BigQuery, la región de la tabla de destino.
  • Para una suscripción de Cloud Storage, 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 de una suscripción con una SMT de inferencia de IA y la solicitud de extracción se realiza a una región que no es la 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 por tema. 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 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 pierda ningún dato. El mensaje reenviado incluye un atributo CloudPubSubDeadLetterSourceSMTErrorMessage que contiene los detalles del error de SMT. Te recomendamos que configures 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 el 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, la SMT de inferencia de IA está sujeta a las cuotas y los límites de frecuencia del extremo de Agent Platform. El control de flujo integrado de Pub/Sub ajusta automáticamente el porcentaje de solicitudes para evitar sobrecargar el extremo, pero el porcentaje 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 del 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 SMT de tema o de suscripción
• Crea un tema con SMT
• Crea una suscripción con SMT