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 推論 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

如要授予這些權限，請將下列 IAM 角色授予服務帳戶：

• 如果您使用 Cloud Pub/Sub 服務代理服務帳戶，請授予 Vertex AI 服務代理角色。

• 如果使用其他服務帳戶，請授予 Vertex AI 使用者角色。

訊息處理

本節說明 AI Inference 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，用於根據模型類型取得推論結果。

如要正確格式化訊息資料和模型參數，請參閱模型的說明文件。舉例來說，如要瞭解 Gemini 基礎模型，請參閱「Chat Completions API 範例」。

如果發布者應用程式無法以模型 (例如 Chat Completions API 格式) 要求的特定 JSON 結構格式化訊息，您可以在 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 Inference SMT 鏈結至一或多個 JavaScript UDF SMT。使用這個模式預先處理訊息，使其符合模型預期的輸入格式，或在模型輸出內容傳送給訂閱者之前，對其進行後續處理。

最佳做法：強烈建議使用訂閱 SMT，而非主題 SMT，進行 AI 推論。如果 AI 模型端點受到節流，導致體驗延遲時間暴增或無法使用，主題 SMT 對管道的潛在影響會更大：

• 如果主題 SMT 發生問題，發布要求就會失敗，直接影響發布商應用程式的可用性。

• 使用訂閱項目 SMT 時，Pub/Sub 會根據訂閱項目的重試政策，重試傳送作業 (包括執行 SMT)。您也可以設定 dead-letter 主題，處理持續性失敗，而不影響擷取作業的可用性。

建立 AI 推論 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 模型 (例如與 OpenAI 相容的 Chat Completions 格式) 要求的結構化 JSON，而是原始文字、記錄或事件酬載，您可以將 JavaScript UDF SMT before 鏈結至 AI 推論 SMT。UDF 會做為轉譯層，將原始訊息轉換為模型預期的格式。

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

/**
 * 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 模型

下表列出 Google 已透過 AI 推論 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 推論 SMT。

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

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

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

  • 如果是 BigQuery 訂閱項目，則為目的地資料表的區域。
  • 如果是 儲存空間訂閱方案，則為 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 建立訂閱項目