設定篩選器版本

本文說明 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)：當 Google 將 Latest 版本升級至 Stable (v2 成為 Stable) 時，會發生下列情況：
   1. Google 會將先前的 Stable 版本 (v1) 移至 Legacy。
   2. 新版本 (v3) 會成為新的 Latest。Google 會在版本經過嚴格測試、每日使用量穩定，且客戶問題極少時，或是在有必要提供重要威脅防護時，才會升級版本。
3. 淘汰 (Legacy 至 Retired)：如果篩選器版本處於 Legacy 狀態達 90 天，Google 就會淘汰該版本，且該版本將無法再使用。

版本發布時間表

下表詳細說明篩選器版本，包括別名、發布日期、淘汰日期和支援的區域。

版本	別名	發布日期	淘汰日期	支援的區域
v1	Legacy (Stable in asia-northeast3; Legacy 2026 年 9 月 25 日起在 australia-southeast2)	2025-01-30	2026-12-17	asia-northeast1 asia-northeast3 (Stable) asia-south1 asia-southeast1 australia-southeast2 (Legacy 2026 年 9 月 25 日起) 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 (Stable2026 年 9 月 25 日起australia-southeast2)	2026-05-25	—	asia-northeast1 asia-south1 asia-southeast1 australia-southeast2 (Stable 2026 年 9 月 25 日起) 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 版本。

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

底限設定預設會使用 Stable 篩選器版本。如要整合 Gemini Enterprise Agent Platform，並覆寫這項設定，請在對 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 稽核記錄。