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 エンドポイントにデプロイされたオープンモデル、パートナー モデル、カスタムモデル。

• Model-as-a-Service（MaaS）モデル。Model Garden を介してサービスとして提供されるモデル（Gemini や Claude など）。デプロイを管理する必要はありません。AI 推論 SMT と互換性のある MaaS モデルの一覧については、互換性のある MaaS モデルをご覧ください。

必要なロールと権限

SMT を使用してトピックまたはサブスクリプションを作成するために必要な権限を取得するには、プロジェクトに対する Pub/Sub 編集者 （roles/pubsub.editor）IAM ロールを付与するように管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、SMT を使用してトピックまたはサブスクリプションを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

SMT を使用してトピックまたはサブスクリプションを作成するには、次の権限が必要です。

• トピックを作成する: プロジェクトに対する pubsub.topics.create
• サブスクリプションを作成する: プロジェクトに対する pubsub.subscriptions.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

サービス アカウントの権限

AI Inference SMT は、IAM サービス アカウントを使用して Agent Platform エンドポイントを呼び出します。デフォルトでは、Cloud Pub/Sub サービス エージェント アカウント（[e-mail]）が使用されます。独自のサービス アカウントを指定することもできます。

サービス アカウントには、Agent Platform エンドポイントを含む Google Cloudプロジェクトに対する次の権限が必要です。

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

これらの権限を付与するには、サービス アカウント（Cloud Pub/Sub サービス エージェント サービス アカウントまたはカスタム サービス アカウントを使用しているかどうかに関係なく）に Agent Platform ユーザー ロールを付与します。

メッセージ処理

このセクションでは、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
Model-as-a-Service（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 Inference 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 モデルへのリクエストのレートを最適化します。注: この機能は、単項 pull API を使用する場合はサポートされません。

AI 推論 SMT は、1 つ以上の JavaScript UDF SMT と連結できます。このパターンを使用すると、モデルの想定される入力形式に合わせてメッセージを前処理したり、モデルの出力をサブスクライバーに配信する前に後処理したりできます。

ベスト プラクティス: AI 推論には、トピック SMT ではなくサブスクリプション SMT を使用することを強くおすすめします。AI モデル エンドポイントがスロットリングされたり、レイテンシの急増が発生したり、使用できなくなったりした場合、トピック SMT を使用すると、パイプラインへの影響が大きくなります。

• トピック SMT を使用すると、パブリッシュ リクエストが失敗し、パブリッシャー アプリケーションの可用性に直接影響します。

• サブスクリプション SMT を使用すると、Pub/Sub はサブスクリプションの再試行ポリシーに従って、SMT の実行を含む配信を再試行します。また、取り込みの可用性に影響を与えることなく永続的な障害を処理するようにデッドレター トピックを構成することもできます。

AI 推論 SMT を作成する

SMT は、Pub/Sub トピックまたはサブスクリプションで構成できます。

• トピック 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.8-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 Inference 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.8-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 モデルに必要な構造化 JSON（OpenAI 互換の Chat Completions 形式など）ではなく、未加工のテキスト、ログ、イベント ペイロードを出力する場合は、AI Inference 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 Inference SMT の後に後処理 JavaScript UDF をチェーンして、モデルのレスポンスから特定のフィールドを抽出してからサブスクライバーに配信することもできます。

互換性のある MaaS モデル

注: モデルのサポートと可用性は変更される可能性があるため、特に Gemini モデルの場合は、可能な限り最新のモデルに移行することをおすすめします。移行のガイダンスについては、新しいモデルに移行するをご覧ください。

次の表に、Google が AI Inference SMT でテストし、互換性があることが確認されている Model-as-a-Service（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

制限事項

• 1 つのトピックまたはサブスクリプションにつき 1 つの AI 推論 SMT のみを使用できます。

• プライベート エンドポイントはサポートされていません。セルフデプロイ モデルは、パブリック Agent Platform エンドポイントでホストする必要があります。

• グローバル エンドポイントは、Gemini 基盤モデルでのみサポートされています。他のモデルの場合は、リージョン エンドポイントを使用する必要があります。

• Pub/Sub は入力メッセージ データを検証しません。データ形式が正しいことを確認するのは、お客様の責任となります。

• この変換では、Pub/Sub メッセージごとに 1 つの推論リクエストが送信されます。クライアントサイドのバッチ処理は実行されません。

• 非同期バッチ推論はサポートされていません。

• 推論に 60 秒以上かからないようにする必要があります。60 秒を超えると、配信試行がタイムアウトし、Pub/Sub は構成されたメッセージ保持期間と再試行ポリシーの設定まで再試行します。試行がタイムアウトすると、メッセージはデッドレター トピックに転送されます（構成されている場合）。

サポートされていないモデル

AI Inference 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 Inference SMT が定義されている場合、エンドポイント リージョンはトピックのメッセージ ストレージ ポリシーで許可されているリージョン内にある必要があります。

  この制約は、Pub/Sub メッセージの転送中リージョンの適用の組織のポリシーの制約が有効な場合、サブスクリプション SMT にも適用されます。

• AI Inference SMT がエクスポート サブスクリプションで定義されている場合、エンドポイント リージョンは関連付けられたリソースのリージョンに存在する必要があります。

  • BigQuery サブスクリプションの場合、宛先テーブルのリージョン。
  • Cloud Storage サブスクリプションの場合、Cloud Storage バケットのリージョン。

• パブリッシュ リクエストがエンドポイント リージョン以外のリージョンに対して行われた場合、Pub/Sub はリクエストをエンドポイント リージョンに自動的にリダイレクトします。

• AI 推論 SMT を使用してサブスクリプションから pull し、pull リクエストがエンドポイント リージョン以外のリージョンに対して行われた場合、Pub/Sub はリクエストを拒否します。pull サブスクリプションにはロケーション エンドポイントを使用することをおすすめします。この制約は、ストリーミング プルと単項プルに適用されます。

• push サブスクリプションに AI Inference SMT がある場合、サブスクリプションはエンドポイント リージョンからメッセージを push します。リージョン制約違反が発生すると、Pub/Sub はそのサブスクリプションからのメッセージの push を停止します。

トラブルシューティング

このセクションでは、AI Inference SMT のトラブルシューティングのヒントを紹介します。

• トピック SMT エラー。メッセージの公開時に推論が失敗すると、公開リクエスト全体が失敗します。エラー情報がパブリッシャー クライアントに返されます。

• 定期購入の SMT エラー。メッセージの配信時に推論が失敗した場合（モデルが長時間使用できない、割り当てが継続的に枯渇している、無効な引数エラーなど）、変更されていない元のメッセージが、構成されたデッドレター トピックに転送されます。これにより、データが失われることはありません。転送されたメッセージには、SMT 障害の詳細を含む CloudPubSubDeadLetterSourceSMTErrorMessage 属性が含まれています。サブスクリプションで SMT を使用する場合は、デッドレター トピックを設定することをおすすめします。

• モデル推論エラー。推論が失敗してエラーが返された場合は、次の点を確認します。

  • 構成されたエンドポイントが正しいことを確認します。

  • Pub/Sub メッセージ データに、モデルの有効な推論リクエストが含まれていることを確認します。

  • すべてのモデル パラメータが有効であることを確認します。

  接続の問題など、他の理由で推論が失敗することもあります。

• 権限またはエンドポイントのエラー。構成されたサービス アカウントがエンドポイントに対する権限を失った場合、またはエンドポイントが削除された場合、SMT は失敗します。

割り当てと上限

• Pub/Sub の割り当てと上限に加えて、AI Inference SMT には Agent Platform エンドポイントの割り当てとレート制限が適用されます。Pub/Sub の組み込みフロー制御は、エンドポイントの過負荷を回避するためにリクエスト率を自動的に調整しますが、この率はモデルの割り当てを超えることはできません。

• 変換後の最終的なメッセージ サイズ（元のメッセージと推論出力を含む）は、Pub/Sub のメッセージ サイズの上限未満にする必要があります。変換されたメッセージが上限を超えると、変換は失敗します。

次のステップ

• SMT の詳細
• トピックまたはサブスクリプションの SMT を選択する
• SMT を使用してトピックを作成する
• SMT を使用してサブスクリプションを作成する