Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

로깅 구성

이 문서에서는 다음 작업을 로깅하도록 Model Armor를 구성하는 방법을 설명합니다.

템플릿을 생성, 업데이트 또는 삭제하는 작업
사용자 프롬프트 또는 모델 응답을 정리하는 작업

Model Armor는 감사 로그를 사용하여 관리 및 리소스 관리 활동을 기록합니다. 자세한 내용은 Model Armor 감사 로깅을 참조하세요.

로그 가격 책정에 대한 자세한 내용은 Cloud Logging 가격 책정을 참조하세요. 처리된 데이터 볼륨에 따라 Model Armor 사용 요금이 부과될 수도 있습니다. 자세한 내용은 Model Armor 가격 책정 을 참조하세요.

시작하기 전에

시작하기 전에 다음 작업을 완료하세요.

필수 권한 얻기

Model Armor의 로깅을 구성하는 데 필요한 권한을 얻으려면 관리자에게 Model Armor 템플릿에 대한 Model Armor 관리자 (roles/modelarmor.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

API 사용 설정

Model Armor를 사용하려면 먼저 Model Armor API를 사용 설정해야 합니다.

콘솔

Model Armor API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정하기
Model Armor를 활성화할 프로젝트를 선택합니다.

gcloud

시작하기 전에 Model Armor API와 함께 Google Cloud CLI를 사용하여 다음 단계를 따르세요.

콘솔에서 Cloud Shell을 활성화합니다. Google Cloud

Cloud Shell 활성화

콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Google Cloud Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
gcloud CLI를 사용하여 API 엔드포인트 재정의를 설정합니다.

gcloud CLI를 사용하여 API 엔드포인트 재정의 설정

이 단계는 gcloud CLI를 사용하여 Model Armor API를 사용 설정하는 경우에만 필요합니다. gcloud CLI가 Model Armor 서비스로 요청을 올바르게 라우팅하도록 하려면 API 엔드포인트 재정의를 수동으로 설정해야 합니다.

다음 명령어를 실행하여 Model Armor 서비스의 API 엔드포인트를 설정합니다.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

LOCATION을 Model Armor를 사용하려는 리전으로 바꿉니다.

트래픽 정리 설정

Google 및 Google Cloud MCP 서버의 경우 최소 기준 설정을 통해 트래픽 정리를 설정합니다. 자세한 내용은 Google 및 Google Cloud MCP 서버 보호 구성을 참조하세요.

템플릿에서 로깅 구성

템플릿은 다양한 안전 및 보안 카테고리에 대한 필터와 기준점을 정의합니다. Model Armor 템플릿을 만들거나 업데이트할 때 Model Armor가 특정 작업을 로깅할지 여부를 지정할 수 있습니다. 템플릿 메타데이터에서 다음 플래그를 사용합니다.

log_template_operations: 템플릿 생성, 업데이트, 읽기, 삭제 작업을 로깅할 수 있는 불리언 값입니다.
log_sanitize_operations: 정리 작업 중에 사용자 프롬프트 및 모델 응답의 전체 콘텐츠를 로깅할 수 있는 불리언 값입니다.

콘솔

Google Cloud 콘솔에서 Model Armor 페이지로 이동합니다.

Model Armor로 이동
Model Armor를 활성화한 프로젝트가 표시되었는지 확인합니다.
Model Armor 페이지에서 템플릿 만들기 를 클릭합니다. 템플릿 만들기에 대한 자세한 내용은 Model Armor 템플릿 만들기를 참조하세요.
로깅 구성 섹션에서 로깅을 구성할 작업을 선택합니다.
만들기를 클릭합니다.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -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
LOCATION: 템플릿의 위치
TEMPLATE_ID: 템플릿의 ID

Python

이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Model Armor Python SDK를 설치합니다.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

다음을 바꿉니다.

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

최소 기준 설정에서 로깅 구성

Gemini Enterprise 에이전트 플랫폼의 Gemini 모델과 프로젝트 내 Google 및 Google Cloud MCP 서버의 트래픽에 최소 기준 설정을 적용하면 최소 기준 설정은 정리 작업의 안전 및 보안 필터를 정의합니다. Model Armor 최소 기준 설정을 업데이트할 때 Model Armor가 정리 작업을 로깅할지 여부를 지정할 수 있습니다.

에이전트 플랫폼과 Google 및 Google Cloud MCP 서버의 정리 작업 로깅을 개별적으로 사용 설정할 수 있습니다. 사용 설정하면 로그에 프롬프트 및 응답 (에이전트 플랫폼의 경우) 또는 도구 호출 및 도구 응답(MCP 서버의 경우), Model Armor의 평가 결과, 추가 메타데이터 필드가 포함됩니다.

다음 예에서는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 정리 작업 로깅을 사용 설정하는 방법을 보여줍니다.

콘솔

Google Cloud 콘솔에서 Model Armor 페이지로 이동합니다.

Model Armor로 이동
Model Armor를 활성화한 프로젝트가 표시되었는지 확인합니다.
최소 기준 설정 탭으로 이동합니다.
로그 섹션에서 Vertex AI 및 Google 관리형 MCP 체크박스를 선택하여 각 서비스의 로깅을 사용 설정합니다.
저장 을 클릭합니다.

gcloud

--enable-vertex-ai-cloud-logging 플래그를 사용하여 에이전트 플랫폼의 로깅을 사용 설정하고 --enable-google-mcp-server-cloud-logging 플래그를 사용하여 Google 및 Google Cloud MCP 서버의 로깅을 사용 설정합니다. 로깅을 사용 중지하려면 --no-enable-vertex-ai-cloud-logging 및 --no-enable-google-mcp-server-cloud-logging 플래그를 사용합니다.

다음 예시 명령어는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 정리 작업 로깅을 사용 설정합니다.

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

REST

로깅을 사용 설정하려면 에이전트 플랫폼의 경우 aiPlatformFloorSetting.enableCloudLogging을 true 로 설정하고 Google 및 Google Cloud MCP 서버의 경우 googleMcpServerFloorSetting.enableCloudLogging 을 true로 설정합니다.UpdateFloorSetting

다음 예시 명령어는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 정리 작업 로깅을 사용 설정합니다.

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

Python

이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Model Armor Python SDK를 설치합니다.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

Model Armor 로그 보기 및 필터링

Model Armor 로그를 보고 필터링하려면 Logging의 로그 탐색기를 사용하세요.

콘솔에서 로그 탐색기 페이지로 이동합니다. Google Cloud

로그 탐색기로 이동

자세한 내용은 로그 탐색기를 사용하여 로그 보기를 참조하세요.
쿼리 창에서 다음 쿼리 중 하나를 입력하여 Model Armor 로그를 필터링합니다.
- 감사 로그 및 정리 작업 로그를 포함한 모든 Model Armor 로그를 보려면 다음을 입력합니다.
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Model Armor 감사 로그만 보려면 다음을 입력합니다.
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  모든 서비스 이름과 모니터링 리소스 유형의 목록은 모니터링 리소스 및 서비스를 참조하세요.
- 정리 작업의 Model Armor 로그만 보려면 다음을 입력합니다.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  정리 작업 로그를 더 세부적으로 조정하려면 쿼리에서 클라이언트 이름 또는 연관 ID를 지정하면 됩니다.
  - 클라이언트 이름 사용: Model Armor가 Gemini Enterprise 에이전트 플랫폼 또는 Gemini Enterprise와 같은 서비스와 통합되면 클라이언트 이름을 사용하여 특정 통합의 로그를 필터링할 수 있습니다.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - 연관 ID 사용:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  다음을 바꿉니다.
  - CLIENT_NAME: 클라이언트 이름 다음 중 한 가지 값을 사용합니다.
    - CLIENT_NAME_UNSPECIFIED: 클라이언트 이름이 지정되지 않은 경우 사용되는 기본값입니다.
    - VERTEX_AI: Gemini Enterprise 에이전트 플랫폼과의 통합
    - LOAD_BALANCER: 서비스 확장 프로그램으로 부하 분산기를 사용하는 통합
    - LANGCHAIN: LangChain과의 통합
    - GEMINI_ENTERPRISE_BUSINESS: Gemini Enterprise - Business 버전과의 통합
    - GOOGLE_MCP_SERVER: Google 및 Google 관리형 MCP 서버와의 통합
    - AGENT_GATEWAY: 에이전트 게이트웨이와의 통합
    - GEMINI_ENTERPRISE_NON_BUSINESS Business (Standard, Plus, Frontline) 이외의 Gemini Enterprise 버전과의 통합
    - SECURE_WEB_PROXY Secure Web Proxy와의 통합
  - CORRELATION_ID: 특정 요청에 대해 생성하는 고유 식별자

로그 및 관련 이벤트의 상관관계 파악

특정 상호작용의 로그와 이벤트의 상관관계를 파악하려면 Model Armor 클라이언트 연관 ID를 사용하면 됩니다. 이 ID는 시스템 전반에서 특정 요청을 추적하기 위해 생성하는 고유 식별자 (예: UUID)입니다. curl 헤더에서 클라이언트 연관 ID를 설정하려면 -H 옵션을 사용하여 요청에 MA-Client-Correlation-Id 커스텀 헤더를 포함합니다.

다음은 샘플 형식입니다.

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

다음을 바꿉니다.

PROJECT_ID: 템플릿이 속한 프로젝트의 ID
LOCATION: 템플릿의 위치
TEMPLATE_ID: 템플릿의 ID
USER_PROMPT: 모델에 제공된 프롬프트
MODEL_RESPONSE: 모델로부터 받은 응답

플랫폼 로그와 Cloud 감사 로그

Model Armor 템플릿 또는 최소 기준 설정 내에서 사용 설정할 수 있는 로그와 Cloud 감사 로그를 구별하는 것이 중요합니다.

기능	Cloud 감사 로그	플랫폼 로그
주요 목적	API 호출 (누가 언제 무엇을 했는지) 및 규정 준수 모니터링의 보안 감사	정리 이벤트의 운영 모니터링, 디버깅, 세부 분석
캡처된 API 작업	템플릿 및 최소 기준 설정에 대한 생성, 읽기, 업데이트, 삭제, 나열 작업 정리 작업 (`SanitizeUserPrompt`, `SanitizeModelResponse`)은 메타데이터로 로깅됩니다.	`SanitizeUserPrompt` 및 `SanitizeModelResponse`와 같은 모든 요청을 캡처합니다.
페이로드 콘텐츠	정리 작업의 실제 사용자 프롬프트 또는 모델 응답 텍스트는 포함하지 않습니다. 호출자, 메서드, 리소스, 타임스탬프, 상태와 같은 메타데이터가 포함됩니다.	프롬프트 또는 응답 텍스트, 필터 결과, 정리의 기타 세부정보와 같은 전체 페이로드가 포함됩니다.
사용 설정 메커니즘	Model Armor API의 표준 Google Cloud IAM 감사 로그 설정 데이터 액세스 로그에는 명시적 사용 설정이 필요한 경우가 많습니다. 템플릿 작업의 감사 로그는 자동으로 생성됩니다.	템플릿 메타데이터 또는 최소 기준 설정에서 불리언 플래그 `log_sanitize_operations`를 설정하여 사용 설정됩니다.
로깅 조건	템플릿 및 최소 기준 설정에 대한 생성, 읽기, 업데이트, 삭제, 나열 작업을 자동으로 로깅합니다.	Sensitive Data Protection이 사용 설정되어 있는지 또는 필터 설정이 일치하는지 여부와 관계없이 모든 데이터 영역 요청의 데이터 (사용자 프롬프트 및 모델 응답)를 로깅합니다.
로그 볼륨 및 비용	일반적으로 더 작고 예측 가능하며 표준 Cloud Logging 가격 책정이 적용됩니다.	매우 크고 방대할 수 있으며 페이로드가 크고 자주 사용되므로 Cloud Logging 비용이 크게 증가할 수 있습니다. 페이로드가 크면 여러 로그 항목으로 분할될 수 있습니다.
보안 고려사항	페이로드 데이터가 로깅되지 않으므로 비교적 안전합니다. 액세스하려면 특별한 IAM 권한 (예: 감사 로그를 볼 수 있는 특정 IAM 역할)이 필요합니다.	민감한 사용자 데이터 (PII, 기밀 정보)가 포함되어 있습니다. 로그 보기 권한이 있는 모든 사용자 (예: `roles/logging.privateLogViewer`)가 액세스할 수 있습니다.
권장사항	일반적인 보안 및 규정 준수 모니터링을 위해 사용 설정합니다.	액세스 제어 싱크 (예: 엄격한 IAM이 적용된 BigQuery)로 안전하게 라우팅되지 않는 한 프로덕션 또는 민감한 정보에는 권장되지 않습니다.

템플릿에서 로깅을 사용 설정하면 원시 프롬프트와 응답이 Logging에 기록됩니다. 이 데이터에는 민감한 사용자 데이터, 개인 식별 정보(PII) 또는 기밀 정보가 포함될 수 있습니다. 트래픽이 많고 페이로드가 크면 로깅 비용이 상당해지고 로그 볼륨이 한도를 초과하여 신중한 관리가 필요할 수 있습니다.

감사 로그의 호출자 ID

감사 로그를 볼 때 Cloud 감사 로그는 protoPayload.authenticationInfo.principalEmail 필드에서 호출자의 ID를 캡처합니다. 기록된 ID는 Model Armor API가 호출되는 방식에 따라 다릅니다.

직접 API 호출: 사용자 또는 서비스 계정이 Model Armor API를 직접 호출하는 경우 (예: gcloud 클라이언트 라이브러리 또는 REST API 사용) principalEmail에는 해당 사용자 또는 서비스 계정의 이메일 주소가 포함됩니다.
통합 서비스를 통한 호출 Google Cloud : Model Armor가 Gemini Enterprise 에이전트 플랫폼과 같은 다른 Google Cloud 서비스와 통합되면 principalEmail 에는 일반적으로 Google 관리 서비스 계정인 해당 서비스의 ID가 포함됩니다. 서비스 에이전트의 형식은 service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com입니다. 예를 들어 Gemini Enterprise 에이전트 플랫폼 기능에서 시작된 호출은 Gemini Enterprise 에이전트 플랫폼 서비스 에이전트를 사용합니다.

호출자를 구별하려면 감사 로그 항목의 principalEmail 필드를 검사합니다. 최종 사용자 또는 사용자 관리 서비스 계정의 호출에는 이메일 주소가 표시되는 반면 다른 Google Cloud 서비스를 통한 호출에는 Google 관리 서비스 계정 이메일 주소가 표시됩니다.

로깅 구성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필수 권한 얻기

API 사용 설정

콘솔

gcloud

gcloud CLI를 사용하여 API 엔드포인트 재정의 설정

트래픽 정리 설정

템플릿에서 로깅 구성

콘솔

REST

Python

최소 기준 설정에서 로깅 구성

콘솔

gcloud

REST

Python

Model Armor 로그 보기 및 필터링

로그 및 관련 이벤트의 상관관계 파악

플랫폼 로그와 Cloud 감사 로그

감사 로그의 호출자 ID

로깅 구성