为模板设置过滤条件版本

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

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

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

版本别名

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

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

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

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

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

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

版本生命周期

Google Cloud 会在每个 sanitize 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	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 审核日志记录。