SMT de inferência de IA

Com a transformação de método único (SMT, na sigla em inglês) de inferência de IA, é possível receber inferências em mensagens do Pub/Sub de modelos da Gemini Enterprise Agent Platform. Você pode usar seus próprios modelos personalizados implantados em endpoints da Agent Platform ou usar qualquer um dos modelos do Google e de parceiros disponíveis na Agent Platform. As inferências do modelo são adicionadas a cada mensagem, ficando disponíveis para processamento downstream junto com os dados da mensagem original.

Os casos de uso da SMT de inferência de IA incluem:

• Enriquecimento em tempo real: adicione contexto, classificações, previsões, sentimentos ou incorporações aos dados de eventos à medida que eles fluem pelo Pub/Sub.

• Pipelines de IA simplificados: elimine a necessidade de serviços intermediários para receber inferências de modelos de IA. O Pub/Sub processa a chamada do modelo de IA e enriquece a mensagem com a inferência.

• Latência reduzida para pipelines de IA: remova saltos de rede extras na sua arquitetura para reduzir a latência de ponta a ponta.

• Controle de fluxo aprimorado: para evitar a sobrecarga dos endpoints de modelo, o Pub/Sub otimiza a taxa de solicitações ao modelo de IA. Para mais informações, consulte Fluxo de mensagens neste documento.

A SMT de inferência de IA é compatível com os seguintes tipos de modelo:

• Modelos autoimplantados. Modelos abertos, de parceiros e personalizados implantados em um endpoint público compartilhado ou dedicado da Agent Platform.

• Modelos de modelo como serviço (MaaS). Modelos oferecidos como um serviço pelo Model Garden, como o Gemini e o Claude, que não exigem que você gerencie a implantação. Para conferir uma lista de modelos de MaaS compatíveis com o SMT de inferência de IA, consulte Modelos de MaaS compatíveis.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar um tópico ou uma assinatura com SMTs, peça ao administrador para conceder a você o papel do IAM de Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar um tópico ou uma assinatura com SMTs. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Permissões de conta de serviço

O SMT de inferência de IA usa uma conta de serviço do IAM para chamar o endpoint da Agent Platform. Por padrão, ele usa a conta Agente de serviço do Cloud Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com). Também é possível fornecer sua própria conta de serviço.

A conta de serviço precisa das seguintes permissões no projeto Cloud de Confianceque contém o endpoint da Agent Platform:

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

Para conceder essas permissões, atribua o seguinte papel do IAM à conta de serviço:

• Se você estiver usando a conta de serviço Agente de serviço do Cloud Pub/Sub, conceda o papel de Agente de serviço da Vertex AI.

• Se você estiver usando uma conta de serviço diferente, conceda o papel de Usuário da Vertex AI.

Processamento de mensagens

Esta seção descreve como o SMT de inferência de IA processa mensagens do Pub/Sub.

Entrada

Os dados da mensagem do Pub/Sub precisam ser uma solicitação para enviar ao modelo de IA, como uma string JSON. Também é possível especificar outros parâmetros do modelo para enviar com cada solicitação. O SMT mescla esses parâmetros com os dados da mensagem e envia o JSON mesclado ao endpoint do modelo.

Por exemplo, se você tiver:

• Dados da mensagem de entrada:{"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
• Parâmetros de SMT:{"temperature": 0.2}

O payload resultante enviado ao modelo é:

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

Se um parâmetro especificado na configuração do SMT tiver o mesmo nome de um campo nos dados da mensagem, o valor nos dados da mensagem terá precedência.

A tabela a seguir mostra qual API o SMT chama para receber a inferência, com base no tipo de modelo.

Para formatar corretamente os dados da mensagem e os parâmetros do modelo, consulte a documentação do seu modelo. Por exemplo, para modelos de base do Gemini, consulte Exemplos da API Chat Completions.

Se o aplicativo editor não puder formatar mensagens na estrutura JSON específica exigida pelo modelo (como o formato da API Chat Completions), encadeie uma UDF JavaScript SMT antes da SMT de inferência de IA para pré-processar e formatar a carga útil da solicitação. Para um exemplo, consulte Pré-processar payloads com uma UDF em JavaScript.

Saída

Se a chamada para o endpoint do modelo for bem-sucedida, o SMT vai enriquecer a mensagem original do Pub/Sub com a resposta do modelo. A mensagem enriquecida é uma string JSON como esta, em que ORIGINAL_MESSAGE são os dados da mensagem original e INFERENCE_RESULT é a resposta do modelo:

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

Fluxo de mensagens

SMTs de tópico:quando você define uma SMT de inferência de IA em um tópico, o Pub/Sub processa as mensagens recebidas da seguinte maneira:

1. Um aplicativo editor envia uma mensagem para um tópico do Pub/Sub.

2. A mensagem é enviada ao endpoint do modelo configurado para inferência. A mensagem enriquecida, que contém os dados originais e a inferência do modelo, é gravada no armazenamento interno do Pub/Sub.

3. O Pub/Sub entrega a mensagem enriquecida a todas as assinaturas anexadas.

SMTs de assinatura:quando você define um SMT de inferência de IA em uma assinatura, o Pub/Sub processa as mensagens recebidas da seguinte maneira:

1. Um aplicativo editor envia uma mensagem para um tópico do Pub/Sub.

2. O Pub/Sub entrega a mensagem à assinatura.

3. A mensagem é enviada ao endpoint do modelo configurado para inferência.

4. A assinatura envia a mensagem enriquecida para o aplicativo do assinante.

5. O Pub/Sub otimiza a taxa de solicitações ao modelo de IA para maximizar a capacidade de processamento com base na latência e na cota da sua implantação. Observação: esse recurso não é compatível com a API unary pull.

É possível encadear uma SMT de inferência de IA com uma ou mais SMTs de UDF em JavaScript. Use esse padrão para pré-processar uma mensagem e adequá-la ao formato de entrada esperado do modelo ou pós-processar a saída do modelo antes de ela ser entregue aos assinantes.

Prática recomendada:recomendamos usar SMTs de assinatura em vez de SMTs de tópico para inferência de IA. Se o endpoint do modelo de IA for limitado, as experiências vão ter picos de latência ou ficar indisponíveis. O impacto potencial no pipeline é maior com uma SMT de tópico:

• Com uma SMT de tópico, a solicitação de publicação falha, afetando diretamente a disponibilidade do aplicativo do publisher.

• Com um SMT de assinatura, o Pub/Sub tenta novamente a entrega, incluindo a execução do SMT, de acordo com a política de repetição da assinatura. Você também pode configurar um tópico de mensagens inativas para lidar com falhas persistentes sem afetar a disponibilidade de ingestão.

Criar um SMT de inferência de IA

As SMTs podem ser configuradas em tópicos ou assinaturas do Pub/Sub.

• As SMTs de tópico são executadas antes que o Pub/Sub armazene a mensagem, e os resultados ficam disponíveis para todos os assinantes.

• Os SMTs de assinatura são executados antes da entrega da mensagem, e os resultados estão disponíveis apenas para essa assinatura.

- 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ção e teste

Se quiser, valide e teste o SMT configurado antes de criar o tópico ou a assinatura. Para mais informações, consulte estes documentos:

• Criar um tópico com SMTs
• Criar uma assinatura com SMTs

Exemplos

Usar o SMT de inferência de IA

O exemplo a seguir mostra como criar uma assinatura com um SMT de inferência de IA e usá-lo para enviar um comando ao Gemini.

Pré-processar payloads com uma UDF em JavaScript

Se o aplicativo editor emitir texto bruto, registros ou payloads de eventos em vez do JSON estruturado exigido pelos modelos de IA (como o formato de conclusão de chat compatível com a OpenAI), você poderá encadear uma UDF JavaScript SMT antes da SMT de inferência de IA. A UDF atua como uma camada de tradução, transformando a mensagem bruta no formato esperado pelo modelo.

O exemplo de UDF em JavaScript a seguir mostra como pré-processar uma mensagem que contém um comando de texto em uma solicitação de API Chat Completions compatível com o 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;
}

Também é possível encadear uma UDF JavaScript de pós-processamento após a SMT de inferência de IA para extrair campos específicos da resposta do modelo antes de entregá-la aos assinantes.

Modelos de MaaS compatíveis

A tabela a seguir lista os modelos de Model-as-a-Service (MaaS) que o Google testou com a SMT de inferência de IA e que são conhecidos por serem compatíveis. Essa lista está sujeita a mudanças à medida que os modelos são descontinuados ou novos modelos de MaaS são adicionados.

Limitações

• Só é permitida uma SMT de inferência de IA por tópico ou assinatura.

• Endpoints particulares não são aceitos. Os modelos com implantação própria precisam ser hospedados em endpoints públicos da Agent Platform.

• O endpoint global só é compatível com modelos de base do Gemini. Para outros modelos, use um endpoint regional.

• O Pub/Sub não valida os dados da mensagem de entrada. Você é responsável por garantir que o formato dos dados esteja correto.

• A transformação envia uma solicitação de inferência por mensagem do Pub/Sub. O agrupamento em lote do lado do cliente não é realizado.

• Não é possível fazer inferências em lote assíncronas.

• A inferência não pode levar mais de 60 segundos. Se exceder 60 segundos, a tentativa de entrega vai atingir o tempo limite, e o Pub/Sub vai tentar de novo, até a duração da retenção de mensagens e as configurações da política de repetição configuradas. Se a tentativa expirar, a mensagem será encaminhada para o tópico de mensagens inativas, se um estiver configurado.

Modelos sem suporte

A SMT de inferência de IA não é compatível com os seguintes modelos de MaaS. Muitos desses modelos têm versões autogerenciadas disponíveis que você pode usar.

• 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

Restrições regionais

As seguintes restrições se aplicam a SMTs de inferência de IA com base na região do endpoint da Agent Platform.

• Se um SMT de inferência de IA for definido em um tópico, a região do endpoint precisará estar dentro das regiões permitidas pela política de armazenamento de mensagens do tópico.

  Essa restrição também se aplica a SMTs de assinatura se a restrição da política da organização Aplicar regiões em trânsito a mensagens do Pub/Sub estiver em vigor.

• Se um SMT de inferência de IA for definido em uma assinatura de exportação, a região do endpoint precisará estar na região do recurso associado:

  • Para uma assinatura do BigQuery, a região da tabela de destino.
  • Para uma assinatura de armazenamento, a região do bucket do Cloud Storage.

• Se uma solicitação de publicação for feita para uma região diferente da região do endpoint, o Pub/Sub vai redirecionar automaticamente a solicitação para a região do endpoint.

• Se você extrair de uma assinatura com um SMT de inferência de IA e a solicitação de envio for feita para uma região diferente da região do endpoint, o Pub/Sub vai rejeitar a solicitação. Recomendamos usar um endpoint de localização para assinaturas de extração. Essa restrição se aplica ao pull de streaming e ao pull unário.

• Quando uma assinatura por push tem um SMT de inferência de IA, ela envia mensagens da região do endpoint. Se ocorrer uma violação de restrição regional, o Pub/Sub vai parar de enviar mensagens dessa assinatura.

Solução de problemas

Nesta seção, você encontra dicas de solução de problemas para o SMT de inferência de IA.

• Erros de SMT de tópicos. Se a inferência falhar quando a mensagem for publicada, toda a solicitação de publicação vai falhar. As informações de erro são retornadas ao cliente da editora.

• Erros de SMT de assinatura. Se a inferência falhar quando a mensagem for entregue (por exemplo, devido à indisponibilidade prolongada do modelo, esgotamento sustentado da cota ou erros de argumento inválido), a mensagem original e não modificada será encaminhada para o tópico de mensagens inativas configurado. Isso garante que nenhum dado seja perdido. A mensagem encaminhada inclui um atributo CloudPubSubDeadLetterSourceSMTErrorMessage com os detalhes da falha no SMT. Recomendamos configurar um tópico de mensagens inativas ao usar SMTs em uma assinatura.

• Erros de inferência de modelo. Se a inferência falhar e retornar um erro, verifique o seguinte:

  • Verifique se o endpoint configurado está correto.

  • Verifique se os dados da mensagem do Pub/Sub contêm uma solicitação de inferência válida para seu modelo.

  • Verifique se todos os parâmetros do modelo são válidos.

  A inferência pode falhar por outros motivos, como problemas de conectividade.

• Erros de permissão ou endpoint. Se a conta de serviço configurada perder a permissão para o endpoint ou se o endpoint for excluído, a SMT vai falhar.

Cotas e limites

• Além das cotas e limites do Pub/Sub, a SMT de inferência de IA está sujeita às cotas e aos limites de taxa do endpoint da Agent Platform. O controle de fluxo integrado do Pub/Sub ajusta automaticamente a taxa de solicitações para evitar sobrecarregar o endpoint, mas ela não pode exceder a cota do modelo.

• O tamanho da mensagem transformada final, incluindo a mensagem original e a saída da inferência, precisa ser menor que o limite de tamanho da mensagem do Pub/Sub. Se a mensagem transformada exceder o limite, a transformação vai falhar.

A seguir

• Saiba mais sobre SMTs
• Escolher SMTs de tópicos ou assinaturas
• Criar um tópico com SMTs
• Criar uma assinatura com SMTs