Google 會運用 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 會提供版本生命週期異動通知，包括版本何時成為 Legacy，以及每個清理 API 回應中即將到來的淘汰日期。您必須在 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` in `asia-northeast3`; `Legacy` from September 25, 2026 in `australia-southeast2`)	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 稽核記錄」。

設定篩選器版本 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

設定篩選器版本和別名的時機

版本別名

不使用篩選器版本的篩選器

版本生命週期

版本發布時間表

範本行為

覆寫底限設定的預設篩選器版本

設定範本的篩選器版本

使用版本別名建立範本

使用特定篩選器版本建立範本

更新範本的篩選器版本

查看清理作業使用的篩選器版本

設定篩選器版本