設定範本的篩選器版本

本文說明 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 會在每次 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 稽核記錄」。