A transformação de método único (SMT, na sigla em inglês) de inferência de IA permite receber inferências em mensagens do Pub/Sub de modelos da Gemini Enterprise Agent Platform. É possível usar seus próprios modelos personalizados implantados em endpoints da Agent Platform ou 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, disponibilizando-as para processamento downstream 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 embeddings aos dados de eventos conforme 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 chama o 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 do modelo, o Pub/Sub otimiza a taxa de solicitações para o 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 como serviço (MaaS). Modelos oferecidos como serviço pelo Model Garden, como o Gemini e o Claude, que não exigem que você gerencie a implantação. Para uma lista de modelos MaaS compatíveis com o SMT de inferência de IA, consulte Modelos 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:
Permissões necessárias
As seguintes permissões são necessárias para criar um tópico ou uma assinatura com SMTs:
-
Criar um tópico:
pubsub.topics.createno projeto -
Criar uma assinatura:
pubsub.subscriptions.createno projeto
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Permissões de conta de serviço
A SMT de inferência de IA usa uma conta de serviço do IAM para chamar o
endpoint da plataforma de agentes. Por padrão, ele usa
a conta do agente de serviço do Cloud Pub/Sub
(service-PROJECT_NUMBER@gcp-sa-pubsub.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 do Google Cloud que contém o endpoint da plataforma de agentes:
aiplatform.endpoints.getaiplatform.endpoints.predict
Para conceder essas permissões, atribua o papel Usuário da plataforma de agentes à conta de serviço (seja usando a conta de serviço Agente de serviço do Cloud Pub/Sub ou uma conta de serviço personalizada).
Processamento de mensagens
Nesta seção, descrevemos 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 de modelo para enviar com cada solicitação. A SMT mescla esses parâmetros com os dados da mensagem e envia o JSON mesclado para o 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 da 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.
| Implantação do modelo | Tipo de modelo | API |
|---|---|---|
| Autoimplantado | Todos |
rawPredict
|
| Modelo como serviço (MaaS) |
Modelo de fundação Gemini Exemplo: |
Chat Completions API
|
|
Outros modelos do Gemini Exemplo: |
rawPredict
|
|
| Anthropic, Mistral AI ou AI21 |
rawPredict
|
|
| Todos os outros modelos de MaaS |
Chat Completions API
|
Para formatar os dados da mensagem e os parâmetros do modelo corretamente, consulte a documentação do modelo. Por exemplo, para modelos de fundação do Gemini, consulte Exemplos da API Chat Completions.
Se o aplicativo do editor não puder formatar mensagens na estrutura JSON específica exigida pelo modelo (como o formato da API Chat Completions), será possível encadear uma SMT de UDF do JavaScript antes da SMT de inferência de IA para pré-processar e formatar o payload da solicitação. Para ver um exemplo, consulte Pré-processar payloads com uma UDF em JavaScript.
Saída
Se a chamada para o endpoint do modelo for bem-sucedida, a SMT vai enriquecer a mensagem original do Pub/Sub com a resposta do modelo. A mensagem enriquecida é uma
string JSON como a seguinte, 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:
Um aplicativo de editor envia uma mensagem para um tópico do Pub/Sub.
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.
O Pub/Sub entrega a mensagem enriquecida a todas as assinaturas anexadas.
SMTs de assinatura: quando você define uma SMT de inferência de IA em uma assinatura, o Pub/Sub processa as mensagens recebidas da seguinte maneira:
Um aplicativo de editor envia uma mensagem para um tópico do Pub/Sub.
O Pub/Sub entrega a mensagem à assinatura.
A mensagem é enviada ao endpoint do modelo configurado para inferência.
A assinatura envia a mensagem enriquecida para o aplicativo do assinante.
O Pub/Sub otimiza a taxa de solicitações para o modelo de IA para maximizar a capacidade de processamento, com base na latência e na cota da implantação. Observação: esse recurso não é compatível com o uso da API de pull unário.
É possível encadear uma SMT de inferência de IA com uma ou mais SMTs de UDF do JavaScript. Use esse padrão para pré-processar uma mensagem de acordo com o formato de entrada esperado do modelo ou pós-processar a saída do modelo antes que ela seja 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, tiver picos de latência ou ficar indisponível, o impacto potencial no pipeline será maior com uma SMT de tópico:
Com um SMT de tópico, a solicitação de publicação falha, afetando diretamente a disponibilidade do aplicativo do editor.
Com uma SMT de assinatura, o Pub/Sub tenta novamente a entrega, incluindo a execução da SMT, de acordo com a política de repetição da assinatura. Também é possível 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.
As SMTs de assinatura são executadas antes da entrega da mensagem, e os resultados só ficam disponíveis para essa assinatura.
Console
No console do Google Cloud , acesse a página Tópicos do Pub/Sub.
Crie um tópico ou uma assinatura.
Para criar um tópico, clique em Criar tópico. A página Criar tópico é aberta.
Para criar uma assinatura:
Clique no nome do tópico em que você quer a assinatura.
Clique em Criar assinatura. A página Adicionar assinatura ao tópico é aberta.
Em Transformações, clique em Adicionar uma transformação.
Em Tipo de transformação, selecione Inferência de IA.
Em Endpoint, insira o nome completo do recurso do endpoint do modelo:
- Modelo autoimplantado:
projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT - Modelo do Model Garden:
projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME
- Modelo autoimplantado:
Opcional. Selecione uma conta de serviço para usar ao chamar o endpoint da plataforma de agentes. Para mais informações, consulte Permissões de contas de serviço.
Opcional. No campo Parâmetros, insira os parâmetros do modelo como um objeto JSON. A SMT mescla esses parâmetros com cada mensagem antes de chamar o modelo. Exemplo:
{ "temperature": 0.5, "max_tokens": 1000 }Para criar o tópico ou a assinatura, clique em Criar.
gcloud
Criar um arquivo de definição
Crie um arquivo YAML ou JSON que defina a IA de inferência.
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
}
}
Substitua:
ENDPOINT_RESOURCE: o nome completo do recurso do endpoint do modelo. Use o seguinte formato:
- Modelo autoimplantado:
projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT - Modelo do Model Garden:
projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME
- Modelo autoimplantado:
MODEL_PARAMETERS: opcional. Parâmetros do modelo, especificados como um objeto JSON. A SMT mescla esses parâmetros com cada mensagem antes de chamar o modelo. Exemplo:
{ "temperature": 0.5, "max_tokens": 1000 }SERVICE_ACCOUNT: opcional. Um e-mail de conta de serviço a ser usado ao chamar o endpoint. Para mais informações, consulte Permissões de contas de serviço.
Criar um tópico ou uma assinatura
Para criar um tópico, execute o comando gcloud pubsub topics create.
gcloud pubsub topics create TOPIC_ID \
--message-transforms-file=TRANSFORMS_FILE
Substitua:
- TOPIC_ID: o ID ou nome do tópico que você quer criar.
- TRANSFORMS_FILE: o caminho para o arquivo de definição.
Para criar uma assinatura, execute o comando gcloud pubsub subscriptions create.
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
--topic=projects/PROJECT_ID/topics/TOPIC_ID \
--message-transforms-file=TRANSFORMS_FILE
Substitua:
SUBSCRIPTION_ID: o ID ou nome da assinatura a ser criada.
PROJECT_ID: o ID do projeto que contém o tópico.
TOPIC_ID: o ID do tópico em que você quer se inscrever.
TRANSFORMS_FILE: o caminho para o arquivo de definição.
Validação e teste
Se quiser, valide e teste a SMT configurada antes de criar o tópico ou a assinatura. Para mais informações, consulte estes documentos:
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á-la para enviar um comando ao Gemini.
gcloud
Usando um editor de texto, crie um arquivo chamado
ai-smt.yamle cole o seguinte texto:- aiInference: endpoint: projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-3.8-flash unstructuredInference: { parameters: { "max_tokens": 25000 } }Substitua:
- PROJECT_ID: ID do seu Google Cloud projeto.
- LOCATION: o local do endpoint a ser chamado.
Exemplo:
us-central1.
Criar um novo tópico do Pub/Sub
gcloud pubsub topics create TOPIC_IDSubstitua TOPIC_ID pelo nome do tópico a ser criado. Exemplo:
topic-1.Crie uma assinatura que tenha uma SMT de inferência de IA.
gcloud pubsub subscriptions create TOPIC_ID-sub \ --ack-deadline=600 \ --topic TOPIC_ID \ --message-transforms-file ai-smt.yamlPublique uma mensagem no tópico. A mensagem contém um comando formatado para a API 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" }] }'Receba uma mensagem da assinatura.
gcloud pubsub subscriptions pull TOPIC_ID-subSe a chamada para a plataforma de agentes for bem-sucedida, a mensagem será enriquecida com a saída do comando.
Pré-processar payloads com uma UDF em JavaScript
Se o aplicativo do editor emitir texto bruto, registros ou payloads de eventos em vez do JSON estruturado exigido pelos modelos de IA (como o formato de preenchimento de chat compatível com a OpenAI), é possível encadear uma SMT de UDF do JavaScript 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 de pós-processamento em JavaScript 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 modelo como serviço (MaaS) que o Google testou com o SMT de inferência de IA e que são compatíveis. Essa lista está sujeita a alterações, já que os modelos podem ser descontinuados ou novos modelos de MaaS podem ser adicionados.
| Modelo | Chamada de API |
|---|---|
google/gemini-3.8-flash |
API Chat Completions |
google/gemini-3.7-flash |
API Chat Completions |
google/gemini-3.6-flash |
API Chat Completions |
google/gemini-3.5-flash |
API Chat Completions |
google/gemini-3.5-flash-lite |
API Chat Completions |
google/gemini-3.1-flash-lite |
API Chat Completions |
google/gemini-3.1-pro-preview |
API Chat Completions |
google/gemini-3-flash-preview |
API Chat Completions |
google/gemini-3.1-flash-image |
API Chat Completions |
google/gemini-3-pro-image |
API Chat Completions |
google/gemini-2.5-flash-image |
API Chat Completions |
google/gemini-2.5-pro |
API Chat Completions |
google/gemini-2.5-flash-lite |
API Chat Completions |
google/gemini-2.5-flash |
API Chat Completions |
google/gemini-2.0-flash-lite-001 |
API Chat Completions |
google/gemini-2.0-flash-001 |
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 |
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-6 |
rawPredict |
anthropic/claude-sonnet-4-5 |
rawPredict |
anthropic/claude-opus-4-6 |
rawPredict |
anthropic/claude-opus-4-5 |
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 |
Limitações
Só é permitido um SMT de inferência de IA por tópico ou assinatura.
Não há suporte para endpoints particulares. Os modelos autoimplantados precisam ser hospedados em endpoints públicos da plataforma de agentes.
O endpoint global só é compatível com os modelos de fundação do Gemini. Para outros modelos, é necessário usar 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 lote do lado do cliente não é realizado.
Não há suporte para 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 expirará e o Pub/Sub tentará novamente, até a duração de 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 houver um configurado.
Modelos não compatíveis
A SMT de inferência de IA não é compatível com os seguintes modelos de MaaS. Muitos desses modelos têm versões de autoimplantação disponíveis que podem ser usadas.
google/gemini-embedding-2-previewgoogle/lyria-002google/lyria-3-clip-previewgoogle/lyria-3-pro-previewgoogle/veo-3.1-fast-generate-001google/veo-3.1-generate-001
Restrições regionais
As restrições a seguir se aplicam aos SMTs de inferência de IA com base na região do endpoint da plataforma de agente.
Se uma SMT de inferência de IA for definida 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 às SMTs de assinatura se a restrição da política da organização Aplicar regiões em trânsito para mensagens do Pub/Sub estiver em vigor.
Se uma SMT de inferência de IA for definida 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 do Cloud Storage, 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 uma 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 o uso de um endpoint de local para assinaturas por pull. Essa restrição se aplica tanto à extração de streaming quanto à extração unária.
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 do editor.
Erros de SMT de assinatura. Se a inferência falhar quando a mensagem for entregue (por exemplo, devido à indisponibilidade prolongada do modelo, ao esgotamento contínuo da cota ou a erros de argumento inválido), a mensagem original 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
CloudPubSubDeadLetterSourceSMTErrorMessageque contém os detalhes da falha de 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 de 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 plataforma de agentes. O controle de fluxo integrado do Pub/Sub ajusta automaticamente a taxa de solicitação para evitar sobrecarregar o endpoint, mas a taxa não pode exceder a cota do modelo.
O tamanho final da mensagem transformada, incluindo a mensagem original e a saída de inferência, precisa ser menor que o limite de tamanho de 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ópico ou assinatura
- Criar um tópico com SMTs
- Criar uma assinatura com SMTs