Gemini Enterprise Agent Platform과 Model Armor 통합

이 문서에서는 프롬프트와 응답을 검사하여 Gemini Enterprise Agent Platform에서 Gemini 모델을 보호하도록 Model Armor를 구성하는 방법을 설명합니다. Gemini Enterprise Agent Platform과 통합되면 Model Armor는 프롬프트가 Gemini 모델에 도달하기 전에 이를 가로채고 애플리케이션이 응답을 수신하기 전에 이를 가로챕니다. 구성된 내용에 따라 Gemini Enterprise Agent Platform은 정의된 정책을 위반하는 트래픽을 검사하거나 차단하는 Model Armor 서비스를 호출하여 프롬프트 인젝션 및 탈옥 감지, 책임감 있는 AI 필터, Sensitive Data Protection과 같은 보안 조치를 시행합니다. 프로젝트 수준 보호를 위해 최소 기준 설정을 사용하거나 요청별 보호를 위해 템플릿을 사용하여 이 통합을 구성할 수 있습니다.

Model Armor는 Vertex AI의 Gemini API 내에서 generateContent 메서드에 대해 프롬프트 및 응답 보호를 제공합니다. 프롬프트 및 응답의 삭제 결과를 보려면 Cloud Logging을 사용 설정해야 합니다.

Gemini Enterprise Agent Platform 서비스에 대한 직접 REST 호출을 보호하는 것 외에도 Model Armor를 사용하여 Google 생성형 AI SDK 또는 Firebase AI Logic SDK와 같이 Vertex AI의 Gemini API에 대한 액세스를 제공하는 다른 인터페이스를 보호할 수 있습니다.

제한사항

Gemini Enterprise Agent Platform과 Model Armor를 통합할 때는 다음 제한사항을 고려하세요.

• Model Armor가 프롬프트 또는 응답을 검사하기 위해 Sensitive Data Protection 템플릿을 사용하는 경우 Model Armor는 콘텐츠가 템플릿에 정의된 필터 기준과 일치하는지 확인합니다. 일치하는 항목이 발견되면 Model Armor는 콘텐츠가 Sensitive Data Protection 필터를 트리거했음을 표시합니다. Sensitive Data Protection은 템플릿 구성을 기반으로 데이터를 익명화하지만 Model Armor는 마스크 처리, 수정 또는 해시된 콘텐츠와 같은 익명화된 데이터를 추가 처리를 위해 Gemini Enterprise Agent Platform으로 다시 전달하지 않습니다. 대신 시행 유형이 INSPECT_AND_BLOCK인 경우 Model Armor는 민감한 정보가 추가 처리되지 않도록 차단 판정을 내립니다.
• 문서가 포함된 프롬프트 및 응답 삭제는 지원되지 않습니다.
• Gemini Enterprise Agent Platform이 지정된 Model Armor 템플릿이 없는 리전으로 요청을 라우팅하면 Template not found 오류가 발생하여 요청이 실패합니다.

• Gemini Enterprise Agent Platform은 Model Armor 삭제 단계를 건너뛰고 다음 조건에서 요청 처리를 계속합니다.

  • Gemini Enterprise Agent Platform이 있는 리전에서 Model Armor를 사용할 수 없습니다.
  • Model Armor에 일시적으로 연결할 수 없습니다.
  • Model Armor 내에서 오류가 발생합니다.

  이러한 모든 인스턴스는 프롬프트 및 응답 삭제 없이 요청이 계속되기 때문에 검사되지 않은 프롬프트 또는 응답을 노출할 수 있습니다.

  통합은 연결 실패 시 높은 가용성을 위해 빌드되지만 INSPECT_AND_BLOCK 모드는 여전히 권한 또는 할당량 문제와 같은 구성 오류를 보고합니다.

시작하기 전에

• Gemini Enterprise Agent Platform 서비스 계정에 Model Armor 사용자 역할을 부여합니다.

  gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:[e-mail]' --role='roles/modelarmor.user'

  다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • PROJECT_NUMBER: 프로젝트 번호입니다. Google Cloud

• Model Armor API를 사용 설정합니다.

• gcloud CLI를 사용하여 API 엔드포인트 재정의를 설정합니다.

Model Armor가 Gemini Enterprise Agent Platform을 보호하는 데 어떻게 도움이 되는지 구성

Model Armor가 Gemini Enterprise Agent Platform을 보호하는 방법을 다음 두 가지 방법 중 하나로 구성할 수 있습니다.

• 요청별 보호를 위해 템플릿 사용: 이 접근 방식은 Gemini Enterprise Agent Platform의 Gemini 모델에 대한 각 generateContent API 호출에 특정 템플릿을 적용할 수 있도록 하여 세부적인 제어를 제공합니다.
• 프로젝트 수준 보호를 위해 최소 기준 설정 사용: 이 접근 방식은 프로젝트 내에서 Gemini Enterprise Agent Platform의 Gemini 모델에 대한 모든 generateContent API 호출에 최소 기준 설정을 적용하여 기준 보호를 시행합니다.

위반 사항을 검사만 할지 아니면 차단도 할지 결정하려면 시행 유형을 정의하세요.

템플릿을 사용한 요청별 구성

템플릿을 사용하면 Model Armor가 프롬프트와 응답을 검사하는 방식을 구성하고 보안 필터 구성을 정의할 수 있습니다. 먼저 템플릿을 만든 다음 이러한 템플릿을 Gemini의 generateContent 메서드와 함께 사용해야 합니다. 템플릿에 대한 자세한 내용은 Model Armor 템플릿 만들기 및 관리를 참조하세요.

Model Armor 템플릿을 구성한 후 generateContent 메서드를 사용하여 Gemini API를 호출할 때 템플릿 ID를 파라미터로 전달합니다. Gemini Enterprise Agent Platform은 처리를 위해 Model Armor로 요청을 라우팅합니다.

개별 generateContent 호출에 특정 템플릿을 적용하려면 요청에 modelArmorConfig 객체를 포함합니다.

• promptTemplateName: 프롬프트를 삭제할 Model Armor 템플릿의 리소스 이름입니다.
• responseTemplateName: 응답을 삭제할 Model Armor 템플릿의 리소스 이름입니다.

다음 코드 샘플은 generateContent 메서드에 대한 요청을 보여줍니다.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "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
• LOCATION: Gemini 엔드포인트의 Google Cloud 위치입니다. 지원되는 위치는 europe-west1, europe-west2, europe-west3, asia-southeast1, asia-south1입니다.
• TEMPLATE_ID: Model Armor 템플릿 ID입니다.

다음 코드 샘플은 generateContent 메서드의 응답을 보여줍니다.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

템플릿의 시행 유형 정의

Model Armor가 감지를 처리하는 방식을 구성하려면 시행 유형을 설정하세요.

다음 예시는 Inspect only 시행 유형이 있는 Model Armor 템플릿 구성을 보여줍니다.

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

curl -X POST \
    -d "$TEMPLATE_CONFIG"  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

다음을 바꿉니다.

• PROJECT_ID: 템플릿이 속한 프로젝트의 ID
• TEMPLATE_ID: 생성할 템플릿의 ID
• LOCATION: 템플릿의 위치

최소 기준 설정을 사용한 프로젝트 수준 구성

최소 기준 설정은 API 요청에서 modelArmorConfig 매개변수가 생략되더라도 프로젝트 내의 모든 Gemini Enterprise Agent Platform generateContent 호출에 적용되는 최소 기준 보호를 정의합니다. 최소 기준 설정을 설정하는 방법을 알아보려면 최소 기준 설정 구성을 참조하세요.

Model Armor 및 Gemini Enterprise Agent Platform 통합을 사용 설정하려면 API 또는 Google Cloud 콘솔을 사용하여 프로젝트 수준에서만 최소 기준 설정을 지정하세요.

Gemini Enterprise Agent Platform 통합으로 최소 기준 설정을 구성하려면 다음 명령어를 실행하세요.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

이 명령어는 기본적으로 INSPECT_ONLY 시행 모드를 사용 설정합니다. 모드를 INSPECT_AND_BLOCK으로 변경하려면 다음 명령어를 실행하세요.

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

통합 서비스에서 Gemini Enterprise Agent Platform을 삭제하려면 다음 명령어를 실행하세요.

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

최소 기준 설정에서 구성된 모든 통합 서비스를 삭제하려면 다음 명령어를 실행하세요.

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

PROJECT_ID를 최소 기준 설정 프로젝트의 ID로 바꿉니다.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

PROJECT_ID를 최소 기준 설정이 포함된 프로젝트의 ID로 바꿉니다.

Gemini Enterprise Agent Platform 삭제를 사용하도록 최소 기준 설정을 구성하면 Model Armor에서 지정된 필터 설정을 사용하여 프로젝트의 Gemini 엔드포인트에 대한 모든 generateContent API 호출을 삭제합니다.

다음 코드 샘플은 generateContent 메서드를 사용하는 방법을 보여줍니다.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• LOCATION: Gemini 엔드포인트의 Google Cloud 위치입니다. 지원되는 위치는 Model Armor API의 위치를 참조하세요.

다음 코드 샘플은 generateContent 메서드의 응답을 보여줍니다.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

최소 기준 설정의 시행 유형 정의

Model Armor가 감지를 처리하는 방식을 구성하려면 시행 유형을 INSPECT 또는 INSPECT_AND_BLOCK으로 설정하세요. 다음 예시는 INSPECT_AND_BLOCK 시행 유형이 있는 최소 기준 설정 구성을 보여줍니다.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

다음을 바꿉니다.

• PROJECT_ID: 최소 기준 설정의 프로젝트 ID입니다.
• LOCATION: 최소 기준 설정의 위치입니다.

API 호출로 인라인 시행 테스트

통합을 테스트하여 Gemini Enterprise Agent Platform API의 generateContent 메서드를 호출합니다. 구성된 최소 기준 설정을 위반하도록 설계된 프롬프트를 사용합니다.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

통합이 예상대로 작동하면 Model Armor가 프롬프트를 위반으로 식별할 때 API는 blockReason 필드가 MODEL_ARMOR로 설정된 응답을 반환합니다.

샘플 응답은 다음과 같습니다.

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

상호작용 및 우선순위 규칙

Gemini Enterprise Agent Platform과 함께 Model Armor를 사용하는 경우 여러 수준에서 안전 구성을 정의할 수 있습니다. 이러한 경우 Model Armor 및 Gemini Enterprise Agent Platform은 특정 우선순위를 따릅니다.

1. Model Armor 템플릿: API 요청 구성에 명시적으로 제공된 모든 구성은 우선순위가 가장 높습니다. 이러한 설정은 해당 특정 요청에 대한 다른 충돌하는 구성을 재정의합니다.

2. Model Armor 최소 기준 설정: API 요청에 재정의 구성이 제공되지 않으면 Model Armor 최소 기준 설정이 적용됩니다.

3. Gemini Enterprise Agent Platform 안전 필터: Gemini Enterprise Agent Platform에 기본 제공되는 기본 안전 필터는 우선순위가 가장 낮습니다. 특정 Model Armor 템플릿 또는 최소 기준 설정을 정의하지 않는 경우에만 적용됩니다.

이 계층적 접근 방식은 Gemini Enterprise Agent Platform의 고유한 안전 기능을 기준으로 사용하면서도 광범위한 조직 전체의 최소 기준 (최소 기준 설정 사용)과 요청별 제어 (템플릿 사용)를 결합하여 제공합니다.

Model Armor 및 Gemini Enterprise Agent Platform 안전 기능의 동작은 구성을 제공하는 방법에 따라 다릅니다.

템플릿이 구성되었나요?	Gemini Enterprise Agent Platform 안전 필터가 구성되었나요?	최소 기준 설정이 구성되었나요?	행동
예	예	모두	오류가 표시됩니다. 동일한 요청에서 템플릿 구성과 Gemini Enterprise Agent Platform 안전 필터를 모두 지정할 수는 없습니다.
예	아니요	모두	Model Armor가 modelArmorConfig에 지정된 템플릿을 사용하여 실행됩니다. Gemini Enterprise Agent Platform 안전 필터는 무시됩니다. 요청 템플릿은 최소 기준 설정을 재정의합니다.
아니요	예	예	둘 다 실행됩니다. Model Armor는 최소 기준 설정 정책을 사용하여 검사하고 Gemini Enterprise Agent Platform은 안전 필터를 평가합니다. 가장 제한적인 결과가 적용됩니다.
아니요	아니요	예	Model Armor가 활성 최소 기준 설정 정책을 사용하여 실행됩니다.
아니요	예	아니요	Gemini Enterprise Agent Platform 안전 필터만 평가됩니다. Model Armor는 호출되지 않습니다.
아니요	아니요	아니요	요청별 Model Armor도 Gemini Enterprise Agent Platform 안전 필터도 적용되지 않습니다. 기준 모델 동작만 활성 상태입니다.