为模板设置过滤条件版本

本文档介绍了 Model Armor 过滤条件版本的工作原理，以及如何指示 Model Armor 在操作中使用特定过滤条件版本或过滤条件版本别名。

Model Armor 使用过滤条件来检测和屏蔽 LLM 提示和回答中的有害内容、敏感数据、恶意网址和提示注入攻击。如需了解详情，请参阅 Model Armor 过滤条件。

Model Armor 过滤条件版本可为生产工作负载提供稳定性，并提供对最新威胁检测模型的访问权限。您可以在模板级别配置单个过滤条件版本。您无法为各个过滤条件指定不同的版本。

版本别名

在 Model Armor 模板中，您可以使用别名来指定首选过滤条件版本。别名表示版本生命周期中的一个阶段。 随着生命周期的推进，每个别名都会设置为相应的版本。

如果您选择别名，模板将使用该别名设置的版本。 当该别名的底层版本更新时（例如，当新版本升级为 Stable 时），使用该别名的模板会自动使用新版本。如果您不希望过滤条件版本发生更改，请将模板指向特定的过滤条件版本。

您可以从以下别名中进行选择：

  • Latest：具有最新模型和保护功能的别名，会针对新出现的威胁进行频繁更新。此别名提供标准服务等级目标 (SLO)，但稳定性可能会因版本而异。它适用于测试、预演和优先考虑最新检测模型而非一致过滤条件行为的工作负载。
  • Stable：具有可用模板的版本的默认别名。此别名提供可靠且不变的检测逻辑，适用于需要不变过滤条件行为的生产环境和工作负载。 当新版本变为 Stable 时，之前的 Stable 版本会变为 Legacy。
  • Legacy：较早 Stable 版本的别名，在新 Stable 版本发布后仍可使用 90 天。在此期间，您可以随时将生产系统迁移到新的 Stable 版本。您无法使用 Legacy 版本创建新模板。
  • Retired：已超过 90 天的旧版期限且不再可用的版本的别名。Model Armor 使用 Stable 版本来清理对仍在使用 Retired 版本的模板的调用。

不使用过滤条件版本的过滤条件

过滤条件版本设置不会影响 Sensitive Data Protection 和恶意网址过滤条件。

版本生命周期

Google Cloud 会在每个 清理 API 响应中提供有关版本生命周期变更的通知， 包括版本何时变为 Legacy 及其即将停用的日期。您必须在 90 天内将使用 Legacy 版本的任何模板迁移到 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 别名的模板会移至新版本，而无需进行任何模板更改。

  • 使用特定版本的模板：

    • 如果版本对应于 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 审核日志记录。