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 を使用してトピックまたはサブスクリプションを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

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

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

AI 推論 SMT は、IAM サービス アカウントを使用して Agent Platform エンドポイントを呼び出します。デフォルトでは、Cloud Pub/Sub サービス エージェント アカウント（service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com）が使用されます。独自のサービス アカウントを指定することもできます。

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

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

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

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

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

メッセージ処理

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

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

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

AI 推論 SMT を作成する

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

• トピック 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 推論 SMT を使用する

次の例は、AI 推論 SMT を使用してサブスクリプションを作成し、それを使用して Gemini にプロンプトを送信する方法を示しています。

JavaScript UDF でペイロードを事前処理する

パブリッシャー アプリケーションが、AI モデル（OpenAI 互換の Chat Completions 形式など）で必要な構造化 JSON ではなく、未加工のテキスト、ログ、イベント ペイロードを出力する場合は、AI 推論 SMT の前に JavaScript UDF SMT をチェーンできます。UDF は変換レイヤとして機能し、未加工のメッセージをモデルが想定する形式に変換します。

次の JavaScript UDF の例は、テキスト プロンプトを含むメッセージを Gemini 3.6 Flash と互換性のある Chat Completions API リクエストに前処理する方法を示しています。

/**
 * 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 でテストし、互換性があることが確認されている Model-as-a-Service（MaaS）モデルを示します。モデルが非推奨になったり、新しい MaaS モデルが追加されたりすると、このリストは変更される可能性があります。

制限事項

• トピックまたはサブスクリプションごとに許可される 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 の失敗の詳細を含む CloudPubSubDeadLetterSourceSMTErrorMessage 属性が含まれます。サブスクリプションで SMT を使用する場合は、デッドレター トピックを設定することをおすすめします。

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

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

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

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

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

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

割り当てと上限

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

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

次のステップ

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