AI 推論 SMT

AI 推論単一メソッド変換（SMT）を使用すると、Gemini Enterprise エージェント プラットフォーム モデルから 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 推論 SMT は、IAM サービス アカウントを使用して Agent Platform エンドポイントを呼び出します。デフォルトでは、Cloud Pub/Sub サービス エージェント アカウント（[e-mail]）が使用されます。独自のサービス アカウントを指定することもできます。

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

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

これらの権限を付与するには、次の IAM ロールをサービス アカウントに付与します。

• Cloud Pub/Sub サービス エージェント サービス アカウントを使用している場合は、Vertex AI サービス エージェントのロールを付与します。

• 別のサービス アカウントを使用している場合は、Vertex AI ユーザーロールを付与します。

メッセージ処理

このセクションでは、AI 推論 SMT が Pub/Sub メッセージを処理する方法について説明します。

入力

Pub/Sub メッセージ データは、JSON 文字列として AI モデルに送信するリクエストである必要があります。各リクエストで送信する追加のモデル パラメータを指定することもできます。SMT はこれらのパラメータをメッセージ データと統合し、統合された JSON をモデル エンドポイントに送信します。

次の表は、モデルのタイプに基づいて、推論を取得するために 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 の例をご覧ください。

出力

モデル エンドポイントの呼び出しが成功すると、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 を 1 つ以上の JavaScript UDF 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-2.5-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-2.5-flash","messages":[{
       "role": "user",
       "content": "Explain how AI works in a few words"
       }]
     }'
   

5. サブスクリプションからメッセージを受信する。

   gcloud pubsub subscriptions pull TOPIC_ID-sub
   

   Agent Platform の呼び出しが成功すると、メッセージはプロンプトの出力で拡充されます。

互換性のある MaaS モデル

次の表に、Google が AI 推論 SMT でテストし、互換性があることが確認されている Model-as-a-Service（MaaS）モデルを示します。モデルが非推奨になったり、新しい MaaS モデルが追加されたりすると、このリストは変更されます。

モデル	API 呼び出し
google/gemini-2.0-flash-001	Chat Completions API
google/gemini-2.0-flash-lite-001	Chat Completions API
google/gemini-2.5-flash	Chat Completions API
google/gemini-2.5-flash-lite	Chat Completions API
google/gemini-2.5-pro	Chat Completions API
google/gemini-2.5-flash-image	Chat Completions API
google/gemini-3-pro-preview	Chat Completions API
google/gemini-3-pro-image-preview	Chat Completions API
google/gemini-3-flash-preview	Chat Completions API
google/gemini-3.1-pro-preview	Chat Completions API
google/gemini-3.1-flash-image-preview	Chat Completions API
google/gemini-3.1-flash-lite-preview	Chat Completions API
meta/llama-3.3-70b-instruct-maas	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
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	rawPredict
anthropic/claude-sonnet-4-5	rawPredict
anthropic/claude-sonnet-4-6	rawPredict
anthropic/claude-opus-4	rawPredict
anthropic/claude-opus-4-1	rawPredict
anthropic/claude-opus-4-5	rawPredict
anthropic/claude-opus-4-6	rawPredict
anthropic/claude-haiku-4-5	rawPredict
mistralai/mistral-small-2503	rawPredict
mistralai/mistral-medium-3	rawPredict
mistralai/mistral-ocr-2505	rawPredict
mistralai/codestral-2	rawPredict

制限事項

• トピックまたはサブスクリプションごとに許可される AI 推論 SMT は 1 つのみです。

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

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

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

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

• 非同期バッチ推論は対象外です。

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

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

トラブルシューティング

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

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

• Subscription SMT errors（定期購入の SMT エラー）。メッセージの配信時に推論が失敗した場合、メッセージはデッドレター トピックに転送できます。サブスクリプションで SMT を使用する場合は、デッドレター トピックを設定することをおすすめします。

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

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

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

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

  推論は、接続の問題など、他の理由で失敗する可能性があります。

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

割り当てと上限

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

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

次のステップ

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