Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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 相容的模型即服務模型清單，請參閱「相容的模型即服務模型」。

所需角色和權限

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

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

所需權限

如要使用 SMT 建立主題或訂閱項目，必須具備下列權限：

建立主題： pubsub.topics.create 專案
建立訂閱項目： pubsub.subscriptions.create 在專案中

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

服務帳戶權限

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 訊息資料必須是傳送至 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 Inference SMT 時，Pub/Sub 會按照下列方式處理收到的訊息：

發布端應用程式將訊息傳送至 Pub/Sub 主題。
訊息會傳送至設定好的模型端點，以進行推論。包含原始資料和模型推論的擴充訊息會寫入 Pub/Sub 的內部儲存空間。
Pub/Sub 會將經過擴充的訊息傳送至所有附加的訂閱項目。

訂閱項目 SMT：在訂閱項目上定義 AI Inference SMT 時，Pub/Sub 會依下列方式處理收到的訊息：

發布端應用程式會將訊息傳送至 Pub/Sub 主題。
Pub/Sub 會將訊息傳送至訂閱項目。
訊息會傳送至設定的模型端點，以進行推論。
訂閱項目會將充實後的訊息傳送至訂閱者應用程式。
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 會在訊息傳送前執行，且結果僅適用於該訂閱項目。

控制台

前往 Google Cloud 控制台的 Pub/Sub「主題」頁面。

前往「Topics」(主題)
建立主題或訂閱項目。
- 如要建立主題，請按一下「建立主題」。「建立主題」頁面隨即開啟。
- 如要建立訂閱：
  1. 按一下要建立訂閱項目的主題名稱。
  2. 按一下「建立訂閱項目」。「將訂閱項目新增至主題」頁面隨即開啟。
在「轉換」下方，按一下「新增轉換」。
在「轉換類型」部分，選取「AI 推論」。
在「Endpoint」(端點) 部分，輸入模型端點的完整資源名稱：
- 自行部署的模型：projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
- Model Garden 模型：projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME
選用。選取呼叫 Agent Platform 端點時要使用的服務帳戶。詳情請參閱「服務帳戶權限」。
選用。在「參數」欄位中，以 JSON 物件形式輸入模型參數。SMT 會先將這些參數與每則訊息合併，再呼叫模型。範例：
```
{
  "temperature": 0.5,
  "max_tokens": 1000
}
```
如要建立主題或訂閱項目，請按一下「建立」。

gcloud

建立定義檔案

建立定義 Inference 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。如需詳細資訊，請參閱下列文件：

範例

使用 AI Inference SMT

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

gcloud

使用文字編輯器建立名為 ai-smt.yaml 的檔案，然後貼上以下文字：

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

更改下列內容：

PROJECT_ID：專案的 ID。 Google Cloud
LOCATION：要呼叫的端點位置。範例：us-central1。

建立新的 Pub/Sub 主題。
```
gcloud pubsub topics create TOPIC_ID
```
將 TOPIC_ID 替換為要建立的主題名稱。範例：topic-1。

建立具有 AI 推論 SMT 的訂閱項目。

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

將訊息發布至主題。訊息包含格式符合 Chat Completions API 的提示。

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"
    }]
  }'

接收訂閱項目的訊息。
```
gcloud pubsub subscriptions pull TOPIC_ID-sub
```
如果對 Agent Platform 的呼叫成功，系統會根據提示的輸出內容擴充訊息。

使用 JavaScript UDF 預先處理酬載

如果發布商應用程式發出的不是 AI 模型 (例如與 OpenAI 相容的 Chat Completions 格式) 要求的結構化 JSON，而是原始文字、記錄或事件酬載，您可以將 JavaScript UDF SMT before AI Inference 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 模型，這份清單可能會有所變更。

模型	API 呼叫
`google/gemini-3.8-flash`	Chat Completions API
`google/gemini-3.7-flash`	Chat Completions 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 會根據設定的訊息保留時間和重試政策設定，重試傳送訊息。如果嘗試逾時，訊息會轉送至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

區域限制

AI 推論 SMT 須遵守下列限制，具體限制取決於 Agent Platform 端點的區域。

如果主題定義了 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 訊息大小限制。如果轉換後的訊息超過限制，轉換就會失敗。

AI 推論 SMT 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

所需角色和權限

所需權限

服務帳戶權限

訊息處理

輸入

輸出內容

訊息流程

建立 AI Inference SMT

控制台

gcloud

建立定義檔案

YAML

JSON

建立主題或訂閱項目

驗證與測試

範例

使用 AI Inference SMT

gcloud

使用 JavaScript UDF 預先處理酬載

相容的 MaaS 模型

限制

不支援的模型

區域限制

疑難排解

配額與限制

後續步驟

AI 推論 SMT