AI 推理 SMT

借助 AI 推理单条方法转换 (SMT)，您可以从 Gemini Enterprise Agent Platform 模型获取有关 Pub/Sub 消息的推理结果。您可以使用部署在 Agent Platform 端点上的自定义模型，也可以使用通过 Agent Platform 提供的任何 Google 模型和合作伙伴模型。模型的推理结果会添加到每条消息中，以便在下游处理中与原始消息数据一起使用。

AI 推理 SMT 的使用场景包括：

• 实时扩充：在事件数据通过 Pub/Sub 时，向其添加背景信息、分类、预测、情感分析或嵌入内容。

• 简化 AI 流水线：无需使用中介服务即可从 AI 模型中获取推理结果。Pub/Sub 会处理调用 AI 模型并使用推理结果扩充消息。

• 缩短 AI 流水线的延迟时间：移除架构中的额外网络跃点，以实现更低的端到端延迟时间。

• 增强的流控制：为避免模型端点过载，Pub/Sub 会优化向 AI 模型发送请求的速率。如需了解详情，请参阅本文档中的消息流。

AI 推理 SMT 支持以下类型的模型：

• 自行部署的模型。部署到共享或专用公共 Agent Platform 端点的开放模型、合作伙伴模型和自定义模型。

• 模型即服务 (MaaS) 模型。通过 Model Garden 以服务形式提供的模型（例如 Gemini 和 Claude），无需您管理部署。 如需查看与 AI 推理 SMT 兼容的 MaaS 模型列表，请参阅兼容的 MaaS 模型。

所需的角色和权限

如需获得创建具有 SMT 的主题或订阅所需的权限，请让您的管理员为您授予项目的 Pub/Sub Editor (roles/pubsub.editor) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含使用 SMT 创建主题或订阅所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能创建具有 SMT 的主题或订阅：

• 创建主题：项目的 pubsub.topics.create 权限
• 创建订阅：项目的 pubsub.subscriptions.create 权限

您也可以使用自定义角色或其他预定义角色来获取这些权限。

服务账号权限

AI 推理 SMT 使用 IAM 服务账号来调用 Agent Platform 端点。默认情况下，它使用 Cloud Pub/Sub Service Agent 账号 (service-PROJECT_NUMBER@gcp-sa-pubsub.)。您也可以提供自己的服务账号。

该服务账号需要对包含 Agent Platform 端点的 Google Cloud项目具有以下权限：

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

如需授予这些权限，请向服务账号授予以下 IAM 角色：

• 如果您使用的是 Cloud Pub/Sub Service Agent 服务账号，请授予 Vertex AI Service Agent 角色。

• 如果您使用的是其他服务账号，请授予 Vertex AI User 角色。

消息处理

本部分介绍了 AI 推理 SMT 如何处理 Pub/Sub 消息。

输入

Pub/Sub 消息数据必须是发送给 AI 模型的请求，以 JSON 字符串的形式表示。您还可以指定其他模型参数，以便随每个请求一起发送。SMT 会将这些参数与消息数据合并，并将合并后的 JSON 发送到模型端点。

例如，如果您有以下内容：

• 输入消息数据： {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
• SMT 参数： {"temperature": 0.2}

发送给模型的最终载荷为：

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

如果 SMT 配置中指定的参数与消息数据中的字段同名，则消息数据中的值优先。

下表显示了 SMT 根据模型类型调用哪个 API 来获取推理结果。

模型部署	模型类型	API
自行部署	全部	rawPredict
模型即服务 (MaaS)	Gemini 基础模型 示例：gemini-3.0-pro	Chat Completions API
	其他 Gemini 模型 示例：gemini-embeddings	rawPredict
	Anthropic、Mistral AI 或 AI21	rawPredict
	所有其他 MaaS 模型	Chat Completions API

如需正确设置消息数据和模型参数的格式，请参阅相应模型的文档。例如，对于 Gemini 基础模型，请参阅 Chat Completions API 示例。

如果发布者应用无法以模型所需的特定 JSON 结构（例如 Chat Completions API 格式）设置消息格式，您可以在 AI 推理 SMT 之前链接一个 JavaScript UDF SMT ，以预处理请求载荷并设置其格式。如需查看示例，请参阅使用 JavaScript UDF 预处理载荷。

输出

如果对模型端点的调用成功，SMT 会使用模型响应来扩充原始 Pub/Sub 消息。富含信息的 JSON 字符串如下所示，其中 ORIGINAL_MESSAGE 是原始消息数据，INFERENCE_RESULT 是模型返回的响应：

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

消息流

主题 SMT：在主题上定义 AI 推理 SMT 时，Pub/Sub 会按如下方式处理传入的消息：

1. 发布者应用将消息发送到 Pub/Sub 主题。

2. 该消息会发送到配置的模型端点以进行推理。包含原始数据和模型推理结果的富化消息会写入 Pub/Sub 的内部存储空间。

3. Pub/Sub 会将富含数据的消息传递给所有附加的订阅。

订阅 SMT：在订阅中定义 AI 推理 SMT 后，Pub/Sub 会按如下方式处理传入的消息：

1. 发布者应用将消息发送到 Pub/Sub 主题。

2. Pub/Sub 将消息传递给订阅。

3. 该消息会发送到配置的模型端点以进行推理。

4. 订阅将丰富后的消息发送给订阅者应用。

5. Pub/Sub 会根据部署的延迟时间和配额，优化向 AI 模型发送请求的速率，以最大限度地提高吞吐量。注意：使用一元拉取 API 时，不支持此功能。

您可以将 AI 推理 SMT 与一个或多个 JavaScript UDF SMT 链接起来。使用此模式可预处理消息，使其符合模型的预期输入格式，或在将模型输出传送给订阅者之前对其进行后处理。

最佳实践：我们强烈建议您使用订阅 SMT 而不是主题 SMT 进行 AI 推理。如果 AI 模型端点受到限制、出现延迟高峰或变得不可用，那么使用主题 SMT 对流水线的潜在影响会更大：

• 如果使用主题 SMT，发布请求会失败，直接影响发布者应用的可用性。

• 使用订阅 SMT 时，Pub/Sub 会根据订阅的重试政策重试传送（包括执行 SMT）。您还可以配置死信主题来处理持久性故障，而不会影响提取可用性。

创建 AI 推理 SMT

可以在 Pub/Sub 主题或订阅上配置 SMT。

• 主题 SMT 在 Pub/Sub 存储消息之前执行，并且结果可供所有订阅者使用。

• 订阅 SMT 在消息传送之前执行，结果仅适用于相应订阅。

控制台

1. 在 Google Cloud 控制台中，前往 Pub/Sub 主题页面。

   打开“主题”。

2. 创建主题或订阅。

   • 如需创建主题，请点击创建主题。系统会打开创建主题页面。

   • 要创建订阅，请执行以下操作：

     1. 点击您要订阅的主题的名称。

     2. 点击创建订阅。系统会打开向主题添加订阅页面。

3. 在转换下，点击添加转换。

4. 在转换类型部分，选择 AI 推理。

5. 对于端点，请输入模型端点的完整资源名称：

   • 自行部署的模型：projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
   • Model Garden 模型：projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

6. 可选。选择在调用 Agent Platform 端点时要使用的服务账号。如需了解详情，请参阅服务账号权限。

7. 可选。在参数字段中，以 JSON 对象的形式输入模型参数。SMT 会在调用模型之前将这些参数与每条消息合并。示例：

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

8. 如需创建主题或订阅，请点击创建。

gcloud

创建定义文件

创建用于定义推理 AI 的 YAML 或 JSON 文件。

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

替换以下内容：

• ENDPOINT_RESOURCE：模型端点的完整资源名称。请使用以下格式：

  • 自行部署的模型：projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
  • Model Garden 模型：projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME

• MODEL_PARAMETERS：可选。模型参数，以 JSON 对象的形式指定。SMT 会在调用模型之前将这些参数与每条消息合并。示例：

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

• SERVICE_ACCOUNT：可选。调用端点时要使用的服务账号电子邮件地址。如需了解详情，请参阅服务账号权限。

创建主题或订阅

如需创建主题，请运行 gcloud pubsub topics create 命令。

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

替换以下内容：

• TOPIC_ID：您要创建的主题的 ID 或名称。
• TRANSFORMS_FILE：定义文件的路径。

如需创建订阅，请运行 gcloud pubsub subscriptions create 命令。

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

替换以下内容：

• SUBSCRIPTION_ID：要创建的订阅的 ID 或名称。

• PROJECT_ID：包含主题的项目的 ID。

• TOPIC_ID：要订阅的主题的 ID。

• TRANSFORMS_FILE：定义文件的路径。

验证和测试

（可选）在创建主题或订阅之前，您可以验证并测试已配置的 SMT。有关详情，请参阅以下文档：

• 创建包含 SMT 的主题
• 创建包含 SMT 的订阅

注意： 如果您测试 SMT，Pub/Sub 会调用您的 Agent Platform 模型来执行测试。您需要为 Agent Platform 使用情况付费。

示例

使用 AI 推理 SMT

以下示例展示了如何创建具有 AI 推理 SMT 的订阅，然后使用该订阅向 Gemini 发送提示。

gcloud

1. 使用文本编辑器创建一个名为 ai-smt.yaml 的文件，并将以下文本粘贴到其中：

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

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud项目的 ID。
   • LOCATION：要调用的端点的位置。 示例：us-central1。

2. 创建新的 Pub/Sub 主题。

   gcloud pubsub topics create TOPIC_ID
   

   将 TOPIC_ID 替换为要创建的主题的名称。示例：topic-1。

3. 创建具有 AI 推理 SMT 的订阅。

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

4. 向主题发布消息。消息包含针对 Chat Completions API 设置格式的提示。

   gcloud pubsub topics publish TOPIC_ID --message=$'{
     "model":"google/gemini-3.6-flash","messages":[{
       "role": "user",
       "content": "Explain how AI works in a few words"
       }]
     }'
   

5. 接收来自订阅的消息。

   gcloud pubsub subscriptions pull TOPIC_ID-sub
   

   如果对 Agent Platform 的调用成功，系统会使用提示的输出内容来丰富消息。

使用 JavaScript UDF 预处理载荷

如果您的发布商应用发出的是原始文本、日志或事件载荷，而不是 AI 模型（例如与 OpenAI 兼容的 Chat Completions 格式）所需的结构化 JSON，您可以在 AI 推理 SMT 之前链接一个 JavaScript UDF SMT 。UDF 充当转换层，将原始消息转换为模型所需的格式。

以下 JavaScript UDF 示例展示了如何将包含文本提示的消息预处理为与 Gemini 3.6 Flash 兼容的 Chat Completions API 请求：

/**
 * Pre-processes a message containing a text prompt into a
 * Chat Completions API request compatible with Gemini 3.6 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.6-flash",
    "messages": [
      {
        "role": "user",
        "content": promptText
      }
    ]
  };

  // Replace the message data with the stringified JSON request
  message.data = JSON.stringify(chatRequest);
  return message;
}

您还可以在 AI 推理 SMT 之后链接一个后处理 JavaScript UDF，以便在将模型响应传送给订阅者之前从中提取特定字段。

兼容的 MaaS 模型

注意： 我们建议您尽可能迁移到最新可用的模型，尤其是 Gemini 模型，因为模型支持和可用性可能会发生变化。如需迁移指南，请参阅迁移到新模型。

下表列出了 Google 已使用 AI 推理 SMT 测试过且已知兼容的 Model-as-a-Service (MaaS) 模型。此列表可能会发生变化，因为模型可能会被弃用，或者会添加新的 MaaS 模型。

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

限制

• 每个主题或订阅只能有一个 AI 推理 SMT。

• 不支持专用端点。自行部署的模型必须托管在公共 Agent Platform 端点上。

• 全球端点仅适用于 Gemini 基础模型。对于其他模型，您必须使用区域端点。

• Pub/Sub 不会验证输入的消息数据。您有责任确保数据格式正确无误。

• 该转换会针对每条 Pub/Sub 消息发送一个推理请求。不执行客户端批处理。

• 不支持异步批量推理。

• 推理时间不得超过 60 秒。如果超过 60 秒，传送尝试会超时，Pub/Sub 会重试，直到达到配置的消息保留时长和重试政策设置。如果尝试超时，系统会将消息转发到死信主题（如果已配置）。

不支持的型号

AI 推理 SMT 不支持以下 MaaS 模型。其中许多模型都有可供您改用的自行部署版本。

• 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

区域限制

以下限制适用于基于 Agent Platform 端点区域的 AI 推理 SMT。

• 如果主题上定义了 AI 推理 SMT，则端点区域必须位于主题的消息存储政策允许的区域内。

  如果对 Pub/Sub 消息强制执行传输中区域 组织政策限制条件生效，此限制条件也适用于订阅 SMT。

• 如果 AI 推理 SMT 是在导出订阅上定义的，则端点区域必须与关联资源的区域相同：

  • 对于 BigQuery 订阅，指目标表的区域。
  • 对于 Cloud Storage 存储空间订阅，这是 Cloud Storage 存储桶的区域。

• 如果向端点区域以外的区域发出发布请求，Pub/Sub 会自动将该请求重定向到端点区域。

• 如果您从具有 AI 推理 SMT 的订阅中拉取消息，并且拉取请求是向端点区域以外的区域发出的，则 Pub/Sub 会拒绝该请求。我们建议为拉取订阅使用位置端点。此限制适用于流式拉取和一元拉取。

• 如果推送订阅具有 AI 推理 SMT，则该订阅会推送来自端点区域的消息。如果发生区域限制违规行为，Pub/Sub 会停止推送相应订阅中的消息。

问题排查

本部分提供有关 AI 推理 SMT 的问题排查提示。

• 主题 SMT 错误。如果发布消息时推理失败，则整个发布请求都会失败。错误信息会返回给发布商客户端。

• 订阅 SMT 错误。如果消息在传送时推理失败（例如，由于模型长时间不可用、配额持续耗尽或出现无效实参错误），系统会将未经修改的原始消息转发到配置的死信主题。这样可确保不会丢失任何数据。转发的消息包含一个 CloudPubSubDeadLetterSourceSMTErrorMessage 属性，其中包含 SMT 失败的详细信息。建议在订阅上使用 SMT 时设置死信主题。

• 模型推理错误。如果推理失败并返回错误，请检查以下各项：

  • 验证配置的端点是否正确。

  • 验证 Pub/Sub 消息数据是否包含针对模型的有效推理请求。

  • 验证所有模型参数是否有效。

  推理也可能会因其他原因（例如连接问题）而失败。

• 权限或端点错误。如果配置的服务账号失去对端点的权限，或者端点被删除，则 SMT 会失败。

配额和限制

• 除了 Pub/Sub 配额和限制之外，AI 推理 SMT 还受 Agent Platform 端点的配额和速率限制的约束。Pub/Sub 的内置流控制功能会自动调整请求速率，以避免端点过载，但该速率不能超过模型的配额。

• 最终转换后的消息大小（包括原始消息和推理输出）必须小于 Pub/Sub 消息大小限制。如果转换后的消息超出限制，转换会失败。

后续步骤

• 详细了解 SMT
• 选择主题或订阅 SMT
• 创建包含 SMT 的主题
• 创建包含 SMT 的订阅