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 Inference SMT 相容的 MaaS 模型清單，請參閱「相容的 MaaS 模型」。

必要角色和權限

如要取得使用 SMT 建立主題或訂閱項目所需的權限，請要求管理員授予您專案的 Pub/Sub 編輯者 (roles/pubsub.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備使用 SMT 建立主題或訂閱項目所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

服務帳戶權限

AI Inference SMT 會使用 IAM 服務帳戶呼叫 Agent Platform 端點。根據預設，系統會使用 Cloud Pub/Sub 服務代理帳戶 (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com)。您也可以提供自己的服務帳戶。

服務帳戶必須具備下列權限，才能存取包含 Agent Platform 端點的 Google Cloud專案：

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

如要授予這些權限，請將 Agent Platform 使用者角色授予服務帳戶 (無論是使用 Cloud Pub/Sub 服務代理服務帳戶，還是自訂服務帳戶)。

訊息處理

本節說明 AI Inference SMT 如何處理 Pub/Sub 訊息。

輸入

Pub/Sub 訊息資料必須是以 JSON 字串形式傳送至 AI 模型的請求。您也可以指定要隨每項要求傳送的其他模型參數。SMT 會將這些參數與訊息資料合併，並將合併後的 JSON 傳送至模型端點。

舉例來說，如果出現以下情形：

• 輸入訊息資料： {"messages": [{"role": "user", "content": "Explain photosynthesis"}]}
• SMT 參數： {"temperature": 0.2}

傳送至模型的酬載如下：

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

如果 SMT 設定中指定的參數與訊息資料中的欄位同名，則訊息資料中的值優先。

下表列出 SMT 根據模型類型呼叫的 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 Inference SMT 時，Pub/Sub 會按照下列方式處理收到的訊息：

1. 發布端應用程式會將訊息傳送至 Pub/Sub 主題。

2. 訊息會傳送至設定的模型端點進行推論。包含原始資料和模型推論的擴充訊息會寫入 Pub/Sub 的內部儲存空間。

3. Pub/Sub 會將充實後的訊息傳送至所有附加的訂閱項目。

訂閱項目 SMT：在訂閱項目定義 AI Inference 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)。您也可以設定dead-letter 主題，在不影響擷取可用性的情況下，處理持續發生的失敗。

建立 AI Inference SMT

您可以在 Pub/Sub 主題或訂閱項目設定 SMT。

• 主題 SMT 會在 Pub/Sub 儲存訊息前執行，且所有訂閱者都能取得結果。

• 訂閱項目 SMT 會在訊息傳送前執行，且結果僅適用於該訂閱項目。

- 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

驗證與測試

您也可以先驗證及測試設定的 SMT，再建立主題或訂閱項目。如需詳細資訊，請參閱下列文件：

• 建立含有 SMT 的主題
• 建立含有 SMT 的訂閱項目

範例

使用 AI Inference SMT

以下範例說明如何使用 AI 推論 SMT 建立訂閱項目，然後使用該項目將提示傳送至 Gemini。

使用 JavaScript UDF 預先處理酬載

如果發布端應用程式發出的是原始文字、記錄或事件酬載，而非 AI 模型所需的結構化 JSON (例如與 OpenAI 相容的 Chat Completions 格式)，您可以在 AI 推論 SMT 之前，鏈結 JavaScript UDF SMT。UDF 會做為轉譯層，將原始訊息轉換為模型預期的格式。

下列 JavaScript UDF 範例說明如何預先處理含有文字提示詞的訊息，轉換為與 Gemini 3.8 Flash 相容的 Chat Completions API 要求：

/**
 * 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;
}

您也可以在 AI 推論 SMT 後方，鏈結後處理 JavaScript UDF，從模型的回應中擷取特定欄位，再傳送給訂閱者。

相容的 MaaS 模型

下表列出 Google 已使用 AI Inference SMT 測試，且已知相容的模型即服務 (MaaS) 模型。隨著模型淘汰或新增 MaaS 模型，這份清單可能會有所變更。

限制

• 一個主題或訂閱項目只能有一個 AI 推論 SMT。

• 不支援私人端點。自行部署的模型必須託管於公開的 Agent Platform 端點。

• 全域端點僅適用於 Gemini 基礎模型。其他模型則必須使用區域端點。

• Pub/Sub 不會驗證輸入訊息資料。您必須確保資料格式正確。

• 轉換作業會為每則 Pub/Sub 訊息傳送一項推論要求。不執行用戶端批次處理。

• 不支援非同步批次推論。

• 推論時間不得超過 60 秒。如果超過 60 秒，傳送嘗試就會逾時，Pub/Sub 會重試，直到達到設定的訊息保留時間長度和重試政策設定。如果嘗試逾時，訊息會轉送至dead-letter 主題 (如有設定)。

不支援的模型

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 Inference SMT 適用下列限制。

• 如果主題定義了 AI 推論 SMT，端點區域必須位於主題訊息儲存政策允許的區域內。

  如果強制執行 Pub/Sub 訊息的傳輸中區域 組織政策限制生效，這項限制也適用於訂閱項目 SMT。

• 如果 AI 推論 SMT 是在匯出訂閱項目中定義，則端點區域必須位於相關聯資源的區域：

  • 如果是 BigQuery 訂閱項目，則為目的地資料表的區域。
  • 如果是 Cloud Storage 訂閱項目，則為 Cloud Storage bucket 的區域。

• 如果發布要求傳送至端點區域以外的區域，Pub/Sub 會自動將要求重新導向至端點區域。

• 如果您從具有 AI Inference SMT 的訂閱項目提取訊息，且提取要求傳送至端點區域以外的區域，Pub/Sub 會拒絕該要求。建議您使用位置端點建立提取訂閱項目。這項限制適用於串流提取和一元提取。

• 如果推送訂閱項目具有 AI 推論 SMT，訂閱項目會從端點區域推送訊息。如果發生區域限制違規，Pub/Sub 就會停止推送該訂閱項目的訊息。

疑難排解

本節提供 AI Inference SMT 的疑難排解提示。

• 主題 SMT 錯誤。如果訊息發布時推論失敗，整個發布要求都會失敗。錯誤資訊會傳回發布者用戶端。

• 訂閱 SMT 錯誤。如果訊息傳送時推論失敗 (例如模型長時間無法使用、配額持續用盡，或引數無效錯誤)，系統會將未經修改的原始訊息轉送至設定的dead-letter 主題。確保資料不會遺失。轉送的訊息包含 CloudPubSubDeadLetterSourceSMTErrorMessage 屬性，其中含有 SMT 失敗的詳細資料。在訂閱項目上使用 SMT 時，建議設定 dead-letter 主題。

• 模型推論錯誤。如果推論失敗並傳回錯誤，請檢查下列事項：

  • 確認設定的端點正確無誤。

  • 確認 Pub/Sub 訊息資料包含模型的有效推論要求。

  • 確認所有模型參數皆有效。

  推論可能因其他原因失敗，例如連線問題。

• 權限或端點錯誤。如果設定的服務帳戶失去端點權限，或端點遭到刪除，SMT 就會失敗。

配額與限制

• 除了 Pub/Sub 配額和限制之外，AI Inference SMT 也受限於 Agent Platform 端點的配額和頻率限制。Pub/Sub 內建的流量控制功能會自動調整要求比率，避免端點超載，但比率不得超過模型配額。

• 最終轉換後的訊息大小 (包括原始訊息和推論輸出內容) 必須小於 Pub/Sub 訊息大小限制。如果轉換後的訊息超過限制，轉換就會失敗。

後續步驟

• 進一步瞭解 SMT
• 選擇主題或訂閱項目 SMT
• 建立含有 SMT 的主題
• 建立含有 SMT 的訂閱項目