テンプレートのフィルタ バージョンを設定する

このドキュメントでは、Model Armor フィルタ バージョンの仕組みと、オペレーションで特定のフィルタ バージョンまたはフィルタ バージョン エイリアスを使用するように Model Armor に指示する方法について説明します。

Model Armor は、フィルタを使用して、LLM プロンプトとレスポンス内の有害なコンテンツ、センシティブ データ、悪意のある URL、プロンプト インジェクション攻撃を検出してブロックします。詳細については、Model Armor フィルタをご覧ください。

Model Armor フィルタ バージョンは、本番環境のワークロードの安定性と、最新の脅威検出モデルへのアクセスを提供します。テンプレート レベルで 1 つのフィルタ バージョンを構成します。個々のフィルタに異なるバージョンを指定することはできません。

バージョンのエイリアス

Model Armor テンプレートでは、エイリアスを使用して優先するフィルタ バージョンを指定できます。エイリアスは、バージョンのライフサイクルのステージを表します。各エイリアスは、ライフサイクルの進行に合わせて適切なバージョンに設定されます。

エイリアスを選択すると、テンプレートではエイリアスが設定されているバージョンが使用されます。そのエイリアスの基盤となるバージョンが更新されると（たとえば、新しいバージョンが Stable に昇格されると）、エイリアスを使用するテンプレートは自動的に新しいバージョンを使用します。フィルタ バージョンを変更しない場合は、テンプレートを特定のフィルタ バージョンに設定します。

次のエイリアスから選択できます。

• Latest: 最新のモデルと保護機能を含むエイリアス。新しい脅威に対して頻繁に更新されます。このエイリアスは標準のサービスレベル目標（SLO）を提供しますが、安定性はバージョンによって異なる場合があります。テスト、ステージング、一貫したフィルタ動作よりも最新の検出モデルを優先するワークロードに適しています。
• Stable: 使用可能なテンプレートを含むバージョンのデフォルト エイリアス。このエイリアスは、信頼性が高く、変更されない検出ロジックを提供します。変更されないフィルタ動作を必要とする本番環境とワークロードに適しています。新しいバージョンが Stable になると、以前の Stable バージョンは Legacy になります。
• Legacy: 新しい Stable バージョンのリリース後 90 日間利用可能な、以前の Stable バージョンのエイリアス。この期間中は、いつでも本番環境システムを新しい Stable バージョンに移行できます。Legacy バージョンを使用して新しいテンプレートを作成することはできません。
• Retired: 90 日間のレガシー期間を超過し、使用できなくなったバージョンのエイリアス。Model Armor は、Stable バージョンを使用して、Retired バージョンをまだ使用しているテンプレートへの呼び出しをサニタイズします。

フィルタ バージョンを使用しないフィルタ

フィルタ バージョンの設定は、Sensitive Data Protection フィルタと悪意のある URL フィルタには影響しません。

バージョンのライフサイクル

Google Cloud は、バージョンが Legacy になったときや、今後のサポート終了日など、バージョンのライフサイクルの変更に関する通知をすべてのサニタイズ API レスポンスで提供します。Legacy バージョンを使用するテンプレートは、90 日以内に Stable または Latest に移行する必要があります。

次の例では、バージョンのライフサイクルについて説明します。

1. リリース（Latest）: Google は、新しいフィルタ バージョン（v2）を Latest としてリリースします。
2. プロモーション（Latest から Stable）: Latest バージョンを Stable にプロモーションする（v2 が Stable になる）場合、次の処理を行います。
   1. 以前の Stable バージョン（v1）を Legacy に移動します。
   2. 新しいバージョン（v3）が新しい Latest になります。バージョンは、厳格なテストを受け、一貫した日常的な使用が実証され、お客様の問題が最小限に抑えられている場合、または重大な脅威保護が必要になった場合に、プロモートされます。
3. 廃止（Legacy から Retired）: フィルタ バージョンが 90 日間 Legacy 状態のままであると、廃止され、使用できなくなります。

バージョンのリリース スケジュール

次の表に、エイリアス、サポートされているリージョン、リリース日など、フィルタ バージョンの詳細を示します。

バージョン	エイリアス	サポートされているリージョン	リリース日
v1	Stable	asia-northeast1 asia-northeast3 asia-south1 asia-southeast1 australia-southeast1 australia-southeast2 europe-southwest1 europe-west9 northamerica-northeast2 us us-central1 us-east4 us-west1	2025-01-30
v2	Stable	eu europe-west1 europe-west2 europe-west3 europe-west4 us-east1	2025-06-19
v3	Latest	eu europe-west1 europe-west2 europe-west3 europe-west4 europe-southwest1 europe-west9 us us-central1 us-east1 us-east4 us-east7 us-west1	2026-05-25

最新バージョンでの変更点については、変更履歴をご覧ください。

テンプレートの動作

テンプレートの動作は、使用されるフィルタ バージョンによって異なり、次の特性があります。

• バージョンなしのテンプレート: 新規または既存のバージョンが指定されていないテンプレートは、デフォルトで Stable バージョンになります。

• Latest または Stable エイリアスを含むテンプレート: これらのテンプレートは、これらのエイリアスに割り当てられたバージョンを自動的に使用します。たとえば、新しいフィルタ バージョンが Stable バージョンになると、Stable エイリアスを使用するテンプレートは、テンプレートの変更を必要とせずに新しいバージョンに移行します。

  注: テンプレートのフィルタ バージョンを Legacy または Retired に設定することはできません。

• 特定のバージョンを使用するテンプレート:

  • バージョンが Latest バージョンまたは Stable バージョンに対応している場合、テンプレートは想定どおりに動作します。
  • バージョンが Legacy バージョンに対応している場合、90 日間のサニタイズ オペレーションに使用すると、テンプレートは想定どおりに動作します。90 日が経過すると、バージョンは Retired フェーズに移行します。このフェーズでは、テンプレートを Latest バージョンまたは Stable バージョンに移行する必要があります。

フィルタ バージョンを構成する

テンプレートのフィルタ バージョンは、次のいずれかの方法で構成できます。

• エイリアスを使用する: Stable や Latest などの動的エイリアスを使用すると、テンプレートで優先エイリアスに対応するバージョン番号が自動的に使用されます。これにより、基盤となるバージョンが変更されたときに手動で更新する必要がなくなります。
• バージョン番号を使用する: v1 などのバージョン番号を使用して、テンプレートが指定されたバージョンに設定されていることを確認します。これにより、エイリアスが更新されても、動作が固定され、変更されません。

バージョン エイリアスを使用してテンプレートを作成する

特定のバージョン エイリアスを使用してテンプレートを作成するには、次のコマンドを実行します。

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

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

• FILTER_VERSION_ALIAS: 目的のフィルタ バージョンのエイリアス。FILTER_VERSION_ALIAS_STABLE または FILTER_VERSION_ALIAS_LATEST を使用します。
• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• TEMPLATE_ID: 作成するテンプレートの ID。
• LOCATION: テンプレートのロケーション。

レスポンスは次の例のようになります。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T17:57:46.976854398Z",
  "updateTime": "2026-04-05T17:57:46.976854398Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

特定のフィルタ バージョンを使用してテンプレートを作成する

フィルタの不変性が必要な場合は、特定のバージョンに対応するテンプレートを作成できます。これを行うには、次のコマンドを実行します。

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

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

• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• TEMPLATE_ID: 作成するテンプレートの ID。
• LOCATION: テンプレートのロケーション。
• FILTER_VERSION_NUMBER: 優先するフィルタ バージョン番号（例: v1）。

レスポンスは次の例のようになります。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:03:29.134974974Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}

テンプレートのフィルタ バージョンを更新する

既存のテンプレートのフィルタ バージョンまたはエイリアスを更新するには、次のコマンドを実行します。

export TEMPLATE_CONFIG='{
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID?updateMask=templateMetadata.filterVersionSelector"

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

• FILTER_VERSION_ALIAS: 目的のフィルタ バージョンのエイリアス。FILTER_VERSION_ALIAS_STABLE または FILTER_VERSION_ALIAS_LATEST を使用します。
• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• TEMPLATE_ID: 作成するテンプレートの ID。
• LOCATION: テンプレートのロケーション。

レスポンスは次の例のようになります。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:04:07.711205953Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

サニタイズ オペレーションで使用されるフィルタ バージョンを表示する

Sanitize API のレスポンス メタデータには、サニタイズ中に使用されたフィルタ バージョンに関する情報が含まれます。Google がバージョンを廃止する 30 日前に、サニタイズ API レスポンスで非推奨の警告が表示されます。

次の例は、フィルタ バージョンを含む API レスポンスを示しています。

"sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "malicious_uris": {
        "maliciousUriFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "rai": {
        "raiFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND",
          "raiFilterTypeResults": {
            "sexually_explicit": {
              "matchState": "NO_MATCH_FOUND"
            },
            "hate_speech": {
              "matchState": "NO_MATCH_FOUND"
            },
            "harassment": {
              "matchState": "NO_MATCH_FOUND"
            }
          }
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    },
  "sanitizationMetadata": {
    "filterVersionConfig": {
      "filterVersion": "v2",
      "filterVersionAlias": "FILTER_VERSION_ALIAS_LEGACY",
      "releaseDate": {
        "year": 2025,
        "month": 5,
        "day": 1
      },
      "projectedDeprecationDate": {
        "year": 2026,
        "month": 5,
        "day": 1
      },
      "messageItems": [
        {
          "messageType": "WARNING",
          "message": "This filter version (v2) is in LEGACY state and will be
          RETIRED on 2026-05-01. Please migrate your template to the STABLE or
          LATEST version to ensure continued protection."
        }
      ]
   }
  },
}

Model Armor は、サニタイズ リクエストとそのレスポンスのプラットフォーム ログを Cloud Logging に生成します。自動生成された監査ログの詳細については、Model Armor の監査ロギングをご覧ください。