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

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

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

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

バージョンのエイリアス

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

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

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

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

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

フィルタ バージョンの設定は、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）: フィルタ バージョンが Legacy 状態のまま 90 日間経過すると、廃止され、利用できなくなります。

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

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

バージョン	エイリアス	サポートされているリージョン
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
v2	Stable	eu europe-west1 europe-west2 europe-west3 europe-west4 us-east1
v3	Latest	asia-south1 asia-southeast1 eu europe-west1 europe-west2 europe-west3 europe-west4 europe-southwest1 europe-west9 northamerica-northeast2 us us-central1 us-east1 us-east4 us-east7 us-west1

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

テンプレートの動作

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

• バージョンなしのテンプレート: 新規または既存の、バージョンが指定されていないテンプレートは、デフォルトで 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 の監査ロギングをご覧ください。