템플릿의 필터 버전 설정

이 문서에서는 Model Armor 필터 버전이 작동하는 방식과 작업에서 특정 필터 버전 또는 필터 버전 별칭을 사용하도록 Model Armor에 지시하는 방법을 설명합니다.

Model Armor는 필터를 사용하여 LLM 프롬프트와 대답에서 유해한 콘텐츠, 민감한 정보, 악성 URL, 프롬프트 인젝션 공격을 감지하고 차단합니다. 자세한 내용은 Model Armor 필터를 참고하세요.

Model Armor 필터 버전은 프로덕션 워크로드의 안정성을 제공하고 최신 위협 감지 모델에 대한 액세스를 제공합니다. 템플릿 수준에서 단일 필터 버전을 구성합니다. 개별 필터에 대해 다른 버전을 지정할 수 없습니다.

버전 별칭

Model Armor 템플릿에서 별칭을 사용하여 원하는 필터 버전을 지정할 수 있습니다. 별칭은 버전 수명 주기의 단계를 나타냅니다. 각 별칭은 수명 주기가 진행됨에 따라 적절한 버전으로 설정됩니다.

별칭을 선택하면 템플릿에서 별칭이 설정된 버전을 사용합니다. 해당 별칭의 기본 버전이 업데이트되면 (예: 새 버전이 Stable로 승격된 경우) 별칭을 사용하는 템플릿이 자동으로 새 버전을 사용합니다. 필터 버전이 변경되지 않도록 하려면 템플릿을 특정 필터 버전으로 지정하세요.

다음 별칭 중에서 선택할 수 있습니다.

• Latest: 최신 모델과 보호 기능이 적용된 별칭으로, 새로운 위협에 대응하기 위해 자주 업데이트됩니다. 이 별칭은 표준 서비스 수준 목표 (SLO)를 제공하지만 버전에 따라 안정성이 다를 수 있습니다. 테스트, 스테이징, 일관된 필터 동작보다 최신 감지 모델을 우선시하는 워크로드에 적합합니다.
• Stable: 사용 가능한 템플릿이 있는 버전의 기본 별칭입니다. 이 별칭은 안정적이고 변경되지 않는 감지 로직을 제공하며 변경되지 않는 필터 동작이 필요한 프로덕션 환경 및 워크로드에 적합합니다. 새 버전이 Stable이 되면 이전 Stable 버전은 Legacy이 됩니다.
• Legacy: 새 Stable 버전이 출시된 후 90일 동안 계속 사용할 수 있는 이전 Stable 버전의 별칭입니다. 이 기간 동안 언제든지 프로덕션 시스템을 새 Stable 버전으로 이전할 수 있습니다. Legacy 버전을 사용하여 새 템플릿을 만들 수는 없습니다.
• Retired: 90일의 기존 기간을 초과하여 더 이상 사용할 수 없는 버전의 별칭입니다. Model Armor는 Retired 버전을 여전히 사용하는 템플릿에 대한 호출을 정리하기 위해 Stable 버전을 사용합니다.

필터 버전을 사용하지 않는 필터

필터 버전 설정은 Sensitive Data Protection 및 악성 URL 필터에 영향을 미치지 않습니다.

버전 수명 주기

Google Cloud 는 버전이 Legacy이 되는 시점과 모든 sanitize API response의 예정된 지원 종료일을 포함하여 버전 수명 주기 변경에 관한 알림을 제공합니다. Legacy 버전을 사용하는 템플릿을 90일 이내에 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일 전에 sanitize 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 감사 로깅을 참고하세요.