Google サービスを呼び出すように拡張機能を構成する

Service Extensions を使用すると、サポートされているアプリケーション ロードバランサで、Google サービスへのコールアウトを使用して拡張機能を構成できます。このページでは、このような拡張機能を構成する方法について説明します。

概要については、Google サービスとの統合をご覧ください。

Model Armor サービスを呼び出すようにトラフィック拡張機能を構成する

Model Armor を呼び出すようにトラフィック拡張機能を構成すると、GKE Inference Gateway などのアプリケーション ロードバランサへの生成 AI 推論トラフィックにセキュリティ ポリシーを均一に適用できます。

トラフィック拡張機能は、関連する拡張機能サービスを 1 つ以上のチェーンにグループ化します。同じ拡張機能チェーンでプラグインとコールアウトの両方を構成できます。各拡張機能チェーンは、Common Expression Language（CEL）一致条件を使用して、処理するトラフィックを選択します。ロードバランサは、各チェーンの一致条件に対してリクエストを順番に評価します。リクエストがチェーンで定義された条件に一致すると、チェーン内のすべての拡張機能がリクエストに対して動作します。特定のリクエストに一致するチェーンは 1 つだけです。

チェーン内の各拡張機能は、独自のサポート対象イベントのセットを持つことができます。拡張機能によってリクエストとレスポンスのコンテンツに加えられた変更は、チェーン内の残りの拡張機能に表示されます。レスポンス イベントをサポートするように構成された拡張機能の場合、拡張機能のシーケンスはレスポンス パスで逆になります。

トラフィック拡張機能は、推論ゲートウェイを使用して作成されたロードバランサの転送ルールに関連付けられます。リソースを構成すると、一致するリクエストが Model Armor サービスに送信されます。

注: ユーザー管理サービスについては、コールアウトを使用してユーザー管理サービスへのトラフィック拡張機能を構成するをご覧ください。

始める前に

1. プロジェクトのオーナーまたは編集者ロール、あるいは次に示す Compute Engine IAM ロールがある適切なプロジェクトを特定します。

   • インスタンスを作成する: Compute インスタンス管理者（v1）（roles/compute.instanceAdmin.v1）
   • Cloud Load Balancing コンポーネントを作成する: Compute ネットワーク管理者（roles/compute.networkAdmin）

2. 必要な API を有効にします。

   コンソール

   1. Google Cloud コンソールで、[API へのアクセスの有効化] ページに移動します。

      API へのアクセスを有効にする

   2. 手順に沿って、Compute Engine API、Model Armor API、Network Services API などの必要な API を有効にします。

   gcloud

   gcloud services enable コマンドを使用します。

   gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
   

3. 必要な Model Armor テンプレートを作成します。

4. 推論ゲートウェイをデプロイして、Google Kubernetes Engine インフラストラクチャを設定します。推論リクエストを送信してテストします。

   いくつかの制限がありますが、次の OpenAI API エンドポイントがサポートされています。Assistants、Chat Completions、Completions（レガシー）、Messages、Threads。

OpenAI API エンドポイントの構成時の制限事項

GKE インフラストラクチャ用に OpenAI API エンドポイントを構成する場合は、プロンプトとレスポンスのサニタイズに関する次の制限事項を考慮してください。

• どの API でもストリーミング API レスポンスはサポートされていません。ストリーミング API と非ストリーミング API を組み合わせて使用する場合は、トラフィック拡張機能を構成するときに、failOpen を true に設定します。Model Armor は、非ストリーミング レスポンスをサニタイズし、ストリーミング レスポンスを無視します。

• プロンプトとレスポンスをサニタイズする場合、次のオペレーションのみがサポートされます。

  • Assistants API: Create、Delete、List、Modify、Retrieve
  • Chat Completions API: Create、Delete、Get Chat Completion、Get Chat Message、List、Update
  • 補完（以前の）API: Create
  • Messages API: Create、Delete、List、Modify、Retrieve
  • Threads API: Create、Delete、Modify、Retrieve

• レスポンスで複数の選択肢を返す API 呼び出し（POST https://api.openai.com/v1/chat/completions など）の場合、選択肢のリストの最初の項目のみがサニタイズされます。

トラフィック拡張機能を構成する

1. 拡張機能を構成する前に、ロードバランサに推論リクエストを送信し、ロードバランサの公開 IP アドレスを指定して、動作を確認します。

   curl -v http://${IP}/v1/chat/completions
     -H "Content-Type: application/json" \
     -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
     -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
          "messages": [
             {
               "role": "user",
               "content": "Can you remember my ITIN: 123-45-6789"
             }
           ],
          "max_tokens": 250,
          "temperature": 0.1}'
   

   リクエストは、機密データが LLM に送信されたにもかかわらず、HTTP 200 OK ステータス コードを生成します。

2. Model Armor がセンシティブ データを含むプロンプトをブロックするように、トラフィック拡張機能を構成します。

   コンソール

   1. Google Cloud コンソールで、[サービス拡張機能] ページに移動します。

      サービス拡張機能に移動

   2. [拡張機能を作成] をクリックします。ウィザードが開き、初期設定の手順が表示されます。

   3. プロダクトとして [ロード バランシング] を選択します。[続行] をクリックします。サポートされているアプリケーション ロードバランサのリストが表示されます。

   4. ロードバランサのタイプを選択します。

   5. リージョンを us-central1 として指定します。[続行] をクリックします。

   6. 拡張機能のタイプとして [トラフィック拡張機能] を選択し、[続行] をクリックします。

   7. [拡張機能の作成] フォームを開くには、[続行] をクリックします。[拡張機能の作成] フォームで、前の選択内容が編集できないことを確認します。

   8. [基本] セクションで、次の操作を行います。

      1. 拡張機能の一意の名前を指定します。

         名前は先頭を小文字にし、その後に 62 文字以下の小文字、数字、ハイフンを続けます。末尾をハイフンにすることはできません。

      2. 省略可: 1,024 文字以内で拡張機能の簡単な説明を入力します。

      3. 省略可: [ラベル] セクションで、[ラベルを追加] をクリックします。表示された行で、次の操作を行います。

         • [キー] にキー名を入力します。
         • [値] にキーの値を入力します。

         Key-Value ペアをさらに追加するには、[ラベルを追加] をクリックします。最大 64 個の Key-Value ペアを追加できます。

         ラベルの詳細については、プロジェクトのラベルを作成、更新するをご覧ください。

   9. [転送ルール] で、拡張機能に関連付ける転送ルールを 1 つ以上選択します。Inference Gateway のデプロイの一部として生成された転送ルールを選択します。別の拡張機能にすでに関連付けられている転送ルールは選択できず、使用不可と表示されます。

   10. 拡張機能チェーンの場合は、一致したリクエストに対して実行する 1 つ以上の拡張機能チェーンを追加します。

       拡張機能チェーンを追加するには、次の操作を行ってから [完了] をクリックします。

       • [新しい拡張機能チェーン名] に一意の名前を指定します。

         名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

       • 拡張機能チェーンが実行されるリクエストを照合するには、[一致条件] に Common Expression Language（CEL）式（request.path == "/v1/chat/completions" など）を指定します。

         CEL 式の詳細については、[構文のヘルプを表示] をクリックするか、CEL マッチャーの言語リファレンスをご覧ください。

       • 一致したリクエストに対して実行する 1 つ以上の拡張機能を追加します。

         拡張機能ごとに、[拡張機能] で次の操作を行い、[完了] をクリックします。

         • [拡張機能名] に、一意の名前を指定します。

           名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

         • [Programmability type] で [Google services] を選択し、Model Armor サービス エンドポイント（modelarmor.us-central1.rep.googleapis.com など）を選択します。

         • [Timeout] に、ストリーム上のメッセージがタイムアウトするまでの時間（10 ～ 1, 000 ミリ秒）を指定します。Model Armor のレイテンシは約 250 ミリ秒です。

         • [イベント] で、すべての HTTP イベントタイプを選択します。

         • [転送ヘッダー] で、[ヘッダーを追加] をクリックし、拡張機能に転送する HTTP ヘッダー（クライアントまたはバックエンドから）を追加します。ヘッダーが指定されていない場合は、すべてのヘッダーが送信されます。

         • 省略可: 拡張機能がタイムアウトまたは失敗し、リクエストまたはレスポンスの処理を続行する場合は、[Fail open] で [有効] を選択します。チェーン内の後続の拡張機能も実行されます。

           デフォルトでは、[フェイルオープン] オプションは選択されていません。この場合、エラーが発生すると、リクエストまたはレスポンスの処理が停止します。レスポンス ヘッダーがダウンストリーム クライアントに配信されていない場合、一般的な HTTP 500 ステータス コードがクライアントに返されます。レスポンス ヘッダーが配信されている場合、クライアントへの HTTP ストリームがリセットされます。

           セキュリティまたは完全性を優先する場合は、[フェイル オープン] を選択しないデフォルトのオプションが推奨されます。フェイルオープンを有効にすると、特に重要でないオペレーションで、可用性を優先する場合に役立ちます。

         • [メタデータ] で [メタデータを追加] をクリックして、特定のモデルに対応するプロンプトとレスポンスのスクリーニングに使用する Model Armor テンプレートを指定します。

           [キー] に model_armor_settings を指定します。[値] に、次のようにテンプレートを JSON 文字列として指定します。

           [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
           

           次のように置き換えます。

           • MODEL_NAME: InferenceModel リソースで構成されたモデルの名前（例: meta-llama/Llama-3.1-8B-Instruct）
           • TEMPLATE_PROJECT_ID: Model Armor テンプレートのプロジェクト ID
           • LOCATION: Model Armor テンプレートのロケーション（例: us-central1）
           • RESPONSE_TEMPLATE: モデルが使用するレスポンス テンプレート
           • PROMPT_TEMPLATE: モデルが使用するプロンプト テンプレート

           リクエストがモデルと完全に一致しない場合に使用するデフォルト テンプレートをさらに指定できます。デフォルト テンプレートを構成するには、MODEL_NAME を default として指定します。

           画面のプロンプトやレスポンスのトラフィックをフィルタしない場合は、空のフィルタ テンプレートを作成して含めます。

           metadata の合計サイズは 1 KiB 未満である必要があります。メタデータのキーの合計数は 20 個未満にする必要があります。各キーの長さは 64 文字未満にする必要があります。各値の長さは 1,024 文字未満にする必要があります。すべての値は文字列にする必要があります。

           リクエストがブロックされると、Model Armor は標準の 403 Forbidden ステータス コードを返します。Model Armor テンプレートのセキュリティ ポリシーでカスタム レスポンス設定（カスタム ステータス コードとメッセージを含む）を定義することで、ステータスをオーバーライドできます。詳細については、TemplateMetadata をご覧ください。

   11. [拡張機能を作成] をクリックします。

   gcloud

   1. YAML ファイルでコールアウトを定義し、Inference Gateway のデプロイ時に生成される転送ルールに関連付けます。提供されているサンプル値を使用します。

      cat >traffic_callout_service.yaml <<EOF
          name: traffic-ext
          forwardingRules:
          - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE
          loadBalancingScheme: INTERNAL_MANAGED
          extensionChains:
          - name: "chain1-model-armor"
            matchCondition:
              celExpression: 'request.path == "/v1/chat/completions"'
            extensions:
            - name: extension-chain-1-model-armor
              service: modelarmor.us-central1.rep.googleapis.com
              failOpen: true
              supportedEvents:
              - REQUEST_HEADERS
              - REQUEST_BODY
              - REQUEST_TRAILERS
              - RESPONSE_HEADERS
              - RESPONSE_BODY
              - RESPONSE_TRAILERS
              timeout: 1s
              metadata:
                model_armor_settings: '[
                  {
                    "model": "MODEL_NAME",
                    "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
                    "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
                  }
                ]'
      EOF
      

      次のように置き換えます。

      • TEMPLATE_PROJECT_ID: Model Armor テンプレートのプロジェクト ID
      • LB_PROJECT_ID: ロードバランサ転送ルールのプロジェクト ID

      • FORWARDING_RULE: 拡張機能に関連付ける 1 つ以上の転送ルール。Inference Gateway のデプロイの一部として生成された転送ルールを選択します。

        別の拡張機能にすでに関連付けられている転送ルールは選択できず、使用不可と表示されます。

      • MODEL_NAME: InferenceModel リソースで構成されたモデルの名前（例: meta-llama/Llama-3.1-8B-Instruct）

      • LOCATION: Model Armor テンプレートのロケーション（例: us-central1）

      • RESPONSE_TEMPLATE: モデルが使用するレスポンス テンプレート

      • PROMPT_TEMPLATE: モデルが使用するプロンプト テンプレート

      metadata フィールドで、特定のモデルに対応するプロンプトとレスポンスをスクリーニングする際に使用する Model Armor の設定とテンプレートを指定します。

      リクエストがモデルと完全に一致しない場合に使用するデフォルト テンプレートをさらに指定できます。デフォルト テンプレートを構成するには、MODEL_NAME を default として指定します。

      画面のプロンプトやレスポンスのトラフィックをフィルタしない場合は、空のフィルタ テンプレートを作成して含めます。

      metadata の合計サイズは 1 KiB 未満である必要があります。メタデータのキーの合計数は 16 未満にする必要があります。各キーの長さは 64 文字未満にする必要があります。各値の長さは 1,024 文字未満にする必要があります。すべての値は文字列にする必要があります。

      リクエストがブロックされると、Model Armor は標準の 403 Forbidden ステータス コードを返します。Model Armor テンプレートのセキュリティ ポリシーでカスタム レスポンス設定（カスタム ステータス コードとメッセージを含む）を定義することで、ステータスをオーバーライドできます。詳細については、TemplateMetadata をご覧ください。

   2. トラフィック拡張機能をインポートします。次のサンプル値を使用して、gcloud service-extensions lb-traffic-extensions import コマンドを使用します。

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
          --source=traffic_callout_service.yaml \
          --location=us-central1
      

   kubectl

   1. v1.32.2-gke.1182001 より前の GKE バージョンを使用している場合は、トラフィック拡張機能 CRD をインストールします。

      kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
      

   2. YAML ファイルで拡張機能を定義します。このカスタム リソースは、推論 Gateway を Model Armor サービスにリンクします。提供されているサンプル値を使用します。

      cat >traffic_callout_service.yaml <<EOF
      apiVersion: networking.gke.io/v1
      kind: GCPTrafficExtension
      metadata:
        name: traffic-ext
      spec:
        targetRefs:
        - group: "gateway.networking.k8s.io"
          kind: Gateway
          name: inference-gateway
        extensionChains:
        - name: "chain1-model-armor"
          matchCondition:
            celExpressions:
            - celMatcher: 'request.path == "/v1/chat/completions"'
            extensions:
            - name: extension-chain-1-model-armor
              googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com
              failOpen: true
              supportedEvents:
              - RequestHeaders
              - RequestBody
              - RequestTrailers
              - ResponseHeaders
              - ResponseBody
              - ResponseTrailers
              timeout: 1s
              metadata:
                model_armor_settings: '[
                  {
                    "model": "MODEL_NAME",
                    "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
                    "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
                  }
                ]'
      EOF
      

      次のように置き換えます。

      • MODEL_NAME: InferenceModel リソースで構成されたモデルの名前（例: meta-llama/Llama-3.1-8B-Instruct）
      • TEMPLATE_PROJECT_ID: Model Armor テンプレートのプロジェクト ID
      • LOCATION: Model Armor テンプレートのロケーション（例: us-central1）
      • RESPONSE_TEMPLATE: モデルが使用するレスポンス テンプレート
      • PROMPT_TEMPLATE: モデルが使用するプロンプト テンプレート

      metadata フィールドで、特定のモデルに対応するプロンプトとレスポンスをスクリーニングする際に使用する Model Armor の設定とテンプレートを指定します。

      リクエストがモデルと完全に一致しない場合に使用するデフォルト テンプレートをさらに指定できます。デフォルト テンプレートを構成するには、MODEL_NAME を default として指定します。

      画面のプロンプトやレスポンスのトラフィックをフィルタしない場合は、空のフィルタ テンプレートを作成して含めます。

      metadata の合計サイズは 1 KiB 未満である必要があります。メタデータのキーの合計数は 16 未満にする必要があります。各キーの長さは 64 文字未満にする必要があります。各値の長さは 1,024 文字未満にする必要があります。すべての値は文字列にする必要があります。

      リクエストがブロックされると、Model Armor は標準の 403 Forbidden ステータス コードを返します。Model Armor テンプレートのセキュリティ ポリシーでカスタム レスポンス設定（カスタム ステータス コードとメッセージを含む）を定義することで、ステータスをオーバーライドできます。詳細については、TemplateMetadata をご覧ください。

   3. traffic_callout_service.yaml ファイルで定義された構成を GKE クラスタに適用します。このコマンドは、推論ゲートウェイを Model Armor サービスにリンクする GCPTrafficExtension リソースを作成します。

      kubectl apply -f traffic_callout_service.yaml
      

3. Service Extensions サービス アカウントに必要なロールを付与します。gcloud projects add-iam-policy-binding コマンドを使用します。

   gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/container.admin
   gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.calloutUser
   gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/serviceusage.serviceUsageConsumer
   gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.user
   

   次のように置き換えます。

   • TEMPLATE_PROJECT_ID: Model Armor テンプレートのプロジェクト ID
   • LB_PROJECT_NUMBER: ロードバランサのプロジェクト番号

   これらの値は、Google Cloud コンソールで、対象プロジェクトの [プロジェクト情報] パネルに表示されます。

4. トラフィック拡張機能が想定どおりに動作することを確認するには、同じ curl コマンドを実行します。

   curl -v http://${IP}/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
     -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
          "messages": [
             {
               "role": "user",
               "content": "Can you remember my ITIN: 123-45-6789"
             }
           ],
          "max_tokens": 250,
          "temperature": 0.1}'
     ```
   

サービス拡張機能が構成されている場合、機密データを含むリクエストは HTTP 403 Forbidden ステータス コードを生成し、テンプレートで構成されているエラー メッセージをログに記録して、接続を閉じます。

リクエストが安全な場合、HTTP 200 OK ステータス コードが生成され、LLM レスポンスがユーザーに返されます。

拡張機能の動作をモニタリングするには、ログ エクスプローラを使用します。クエリペインで、推論ゲートウェイの構成に応じて、適切なロードバランサ リソースタイプでフィルタします。

アプリケーション ロードバランサのログエントリには、HTTP または HTTPS トラフィックのデバッグに役立つ情報が含まれています。

セキュリティ評価の詳細な分析を行うには、Model Armor の監査ロギングを有効にします。

次のステップ

• 拡張機能を管理する