Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

设置过滤条件版本

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

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

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

何时配置过滤条件版本和别名

以下是一些常见使用场景：

锁定确定性过滤行为：将模板设置为特定过滤条件版本，以防止任务关键型系统中的威胁检测逻辑发生更改。
接收自动安全更新：使用 Stable 别名，以便在更新后的威胁检测模型通过验证后自动采用这些模型。
测试即将推出的检测功能：在预生产环境中使用Latest别名，根据真实流量模式评估新的过滤条件规则。
启用可预测的发布周期：在手动更新生产模板之前，针对新发布的过滤条件版本验证工作负载。

版本别名

在 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。

以下示例介绍了版本生命周期：

发布 (Latest) ：Google 将新的过滤条件版本 (v2) 作为 Latest 发布。
升级（Latest 到 Stable） ：当 Google 将 Latest 版本升级为 Stable（v2 变为 Stable）时，会发生以下情况：
1. Google 将之前的 Stable 版本 (v1) 移至 Legacy。
2. 新版本 (v3) 成为新的 Latest。Google 会在版本经过严格测试、展示一致的每日使用情况且客户问题最少时，或者在需要关键威胁防护时，升级版本。
停用（Legacy 到 Retired） ：过滤条件版本在 Legacy 状态下保留 90 天后，Google 会将其停用，并且该版本不再可用。

版本发布时间表

下表详细介绍了过滤条件版本，包括别名、发布日期、弃用日期和受支持的区域。

版本	别名	发布日期	弃用日期	受支持的区域
`v1`	`Legacy` (`Stable` 在 `asia-northeast3` 中；自 2026 年 9 月 25 日起在 `australia-southeast2` 中为 `Legacy`)	2025-01-30	2026-12-17	`asia-northeast1` `asia-northeast3` (`Stable`) `asia-south1` `asia-southeast1` `australia-southeast2`（自 2026 年 9 月 25 日起为 `Legacy`） `europe-southwest1` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east4` `us-west1`
`v2`	`Legacy`	2025-06-19	2026-12-17	`eu` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `us-east1`
`v3`	`Stable` (自 2026 年 9 月 25 日起在 `australia-southeast2` 中为 `Stable`)	2026-05-25	—	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2`（自 2026 年 9 月 25 日起为 `Stable`） `eu` `europe-southwest1` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east1` `us-east4` `us-west1`
`v4`	`Latest`	2026-09-18	—	`asia-northeast1` `asia-south1` `asia-southeast1` `eu` `europe-southwest1` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east1` `us-east4` `us-west1`

如需了解每个版本中的变化，请参阅过滤条件版本记录。

模板行为

模板行为取决于所使用的过滤条件版本，并具有以下特征：

没有版本的模板：无论新模板还是现有模板，如果没有指定版本，则默认使用 Stable 版本。
具有 Latest 或 Stable 别名的模板：这些模板会自动使用分配给这些别名的版本。例如，当新的过滤条件版本成为 Stable 版本时，使用 Stable 别名的模板会移至新版本，而无需进行任何模板更改。

**注意**：您无法将模板中的过滤条件版本设置为 Legacy 或 Retired。
使用特定版本的模板：
- 如果版本与 Latest 或 Stable 版本对应，则模板的行为符合预期。
- 如果版本与 Legacy 版本对应，则在 90 天内用于清理操作时，模板的行为符合预期。90 天后，版本将进入 Retired 阶段。在此阶段，您必须将模板迁移到 Latest 或 Stable 版本。

替换下限设置的默认过滤条件版本

借助下限设置， Gemini Enterprise Agent Platform 集成默认使用 Stable 过滤条件版本。如需替换此设置，请在对 Gemini 模型进行 generateContent 调用时指定模板。为此，请在您计划发送 Gemini 请求的同一区域中创建具有特定过滤条件版本或别名的模板。

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：用于存储 Model Armor 模板的区域。此区域必须与您计划发送 Gemini 请求的区域相同；否则，Agent Platform 会收到 Template not found 错误。如需查看此集成支持的区域列表，请参阅与 Gemini Enterprise Agent Platform 集成。

在 Gemini 调用中的 model_armor_config 对象中提供模板 ID。系统会应用模板中指定的过滤条件配置，而不是项目级下限设置。

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Your prompt here"
        }
      ]
    }
  ],
  "model_armor_config": {
    "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
    "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
  }
}'

替换以下内容：

PROJECT_ID： Google Cloud 项目 ID。
REGION：Gemini 端点的 Google Cloud 区域。
LOCATION：存储 Model Armor 模板的区域。此区域必须与为 REGION 指定的区域相同。
TEMPLATE_ID：Model Armor 模板 ID。

为模板配置过滤条件版本

您可以通过以下两种方式之一为模板配置过滤条件版本：

使用别名：使用 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": 6,
        "day": 19
      },
      "projectedDeprecationDate": {
        "year": 2026,
        "month": 12,
        "day": 17
      },
      "messageItems": [
        {
          "messageType": "WARNING",
          "message": "This filter version (v2) is in LEGACY state and will be
          RETIRED on 2026-12-17. Please migrate your template to the STABLE or
          LATEST version to ensure continued protection."
        }
      ]
   }
  },
}

Model Armor 会在 Cloud Logging 中生成清理请求及其响应的平台日志。如需详细了解自动生成的审核日志，请参阅 Model Armor 审核日志记录。

设置过滤条件版本 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

何时配置过滤条件版本和别名

版本别名

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

版本生命周期

版本发布时间表

模板行为

替换下限设置的默认过滤条件版本

为模板配置过滤条件版本

使用版本别名创建模板

使用特定过滤条件版本创建模板

更新模板的过滤条件版本

查看清理操作中使用的过滤条件版本

设置过滤条件版本