가드레일 공급자: Google Cloud Model Armor

가드레일 공급자: Google Cloud Model Armor

LiteLLM은 Model Armor API를 통해 Google Cloud Model Armor 가드레일을 지원해요.

출처: 문서

본문

지원되는 가드레일 (Supported Guardrails)

• Model Armor 템플릿 - 구성된 템플릿 기반 콘텐츠 정화 및 차단

빠른 시작 (Quick Start)

1. LiteLLM config.yaml에 가드레일 정의하기

guardrails 섹션 아래에 가드레일을 정의하세요.

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY
guardrails:
  - guardrail_name: model-armor-shield
    litellm_params:
      guardrail: model_armor
      mode: [pre_call, during_call, post_call]  # Run on input, parallel, and output
      template_id: "your-template-id"  # Required: Your Model Armor template ID
      project_id: "your-project-id"    # Your GCP project ID
      location: "us-central1"          # GCP location (default: us-central1)
      credentials: "path/to/credentials.json"  # Path to service account key
      mask_request_content: true       # Enable request content masking
      mask_response_content: true      # Enable response content masking
      fail_on_error: true             # Fail request if Model Armor errors (default: true)
      sanitize_error_detail: true     # Keep raw Model Armor responses out of errors and logs (default: true)
      default_on: true                # Run by default for all requests

mode에 대한 지원 값 (Supported values for mode):

• pre_call LLM 호출 전, 입력에 실행
• during_call LLM 호출과 병행, 입력에 실행
• post_call LLM 호출 후, 출력에 실행
• pre_mcp_call MCP 도구 호출 전, 입력에 실행
• during_mcp_call MCP 도구 호출과 병행, 입력에 실행
• logging_only 로그된 요청과 완성 응답을 차단·수정 없이 스캔

차단 없이 관찰 (Observe without blocking)

강제하기 전에 Model Armor 템플릿을 평가하려면 logging_only를 사용하세요:

guardrails:
  - guardrail_name: model-armor-observe
    litellm_params:
      guardrail: model_armor
      mode: logging_only
      template_id: "your-template-id"
      project_id: "your-project-id"
      location: "us-central1"
      credentials: "path/to/credentials.json"
      default_on: true

프록시를 통한 성공적인 Chat Completions, Responses, Messages 호출에 대해 이 모드는 로그된 요청·응답 텍스트를 스캔해요. guardrail_information에 success, guardrail_flagged, 또는 guardrail_failed_to_respond를 기록해요. Request Logs 또는 Guardrails Monitor Logs 탭에서 판정을 검사하세요. 발견과 Model Armor 오류는 요청을 차단하거나 클라이언트 응답을 바꾸지 않아요. 스트리밍 요청의 경우 LiteLLM은 완료 응답 스캔을 기다리지 않고 청크를 전달해요.

이 모드에는 입력 전용/출력 전용 선택이 없어요. 도구 호출 인자와 인라인 문서는 스캔되지 않아요. 문서·파일 스캔에는 pre_call 또는 during_call을 사용하세요.

2. LiteLLM 게이트웨이 시작

litellm --config config.yaml --detailed_debug

3. 테스트 요청

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "Hi, my email is [email protected]"}
    ],
    "guardrails": ["model-armor-shield"]
  }'

문서 및 파일 스캔 (Document and File Scanning)

v1.92.0부터 Model Armor는 메시지 텍스트 외에 인라인 문서 첨부를 스캔해요. pre_call과 during_call에서 LiteLLM은 요청 메시지의 각 첨부를 바이트로 해석해, 요청이 LLM에 도달하기 전에 Model Armor의 byte API에 제출해요.

LiteLLM은 인라인 file_data(base64 data URI 또는 원시 base64)가 있는 OpenAI type: file 콘텐츠 블록과 인라인 base64 소스가 있는 Anthropic type: document 블록을 인식해요. 첨부의 MIME 타입, 선언된 형식, 파일 이름 확장자를 Model Armor byteDataType에 매핑하고, PDF, Word, Excel, PowerPoint, CSV, 일반 텍스트 문서가 스캔돼요. 이미지처럼 byte API가 지원하지 않는 유형의 인라인 콘텐츠는 스캔되지 않고 통과해요.

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize this document"},
    {"type": "file", "file": {"file_data": "data:application/pdf;base64,JVBERi0x...", "filename": "report.pdf"}}
  ]
}

문서에서 Model Armor 발견은 항상 HTTP 400으로 요청을 차단해요:

{"error": "Content blocked by Model Armor", "model_armor_response": {"sanitizationResult": {"filterMatchState": "MATCH_FOUND"}}}

마스킹은 절대 문서에 적용되지 않아요. Model Armor는 정화 사본이 아닌 문서에 대한 발견을 반환하므로, mask_request_content가 활성화돼도 일치는 차단돼요.

스캔할 수 없는 첨부 (Attachments That Cannot Be Scanned)

LiteLLM이 문서로 인식하지만 스캔 제출할 수 없는 첨부는 fail closed로 처리돼요. fail_on_error: false를 설정하지 않으면 HTTP 400으로 차단돼요.

차단된 요청은 이유를 반환해요:

{"error": "Model Armor could not scan an attachment and blocked the request: attachment of 5242880 bytes exceeds Model Armor's 4194304 byte scan limit"}

file_id, gs:// 또는 http(s):// 첨부 참조(Vertex AI가 권장하는 패턴)를 사용하면 바이트가 LiteLLM에 도달하지 않으므로 Model Armor가 스캔할 수 없고, 기본적으로 요청이 차단돼요. skip_unscannable_attachments: true를 설정해 인라인 바이트가 없는 첨부가 스캔 없이 통과하되, 바이트가 있는 것은 여전히 스캔하게 하세요. fail_on_error: false와 달리 이것은 실제 Model Armor API 오류(네트워크, 할당량, 잘못된 템플릿)에서 fail-closed 동작을 그대로 두고, 보낼 것이 없는 첨부에만 영향을 줘요.

Model Armor의 4MB byte 한도를 넘는 문서는 바이트를 갖지만 byte API가 받아들이는 것을 초과하므로, fail_on_error 아래에서 fail-closed로 유지돼요. skip_unscannable_attachments는 그것을 다루지 않는데, 이는 스캔 없이 전달하기보다 차단하고 싶은 실제 문서이기 때문이에요.

지원되는 파라미터 (Supported Params)

공통 파라미터 (Common Params)

• api_key - str - Google Cloud 서비스 계정 자격 증명 (ADC 사용 시 선택)
• api_base - str - 커스텀 Model Armor API 엔드포인트 (선택)
• default_on - bool - 기본으로 가드레일을 실행할지. 기본은 false.
• mode - Union[str, list[str]] - 가드레일을 실행할 필수 모드. 지원 값: pre_call, during_call, post_call, pre_mcp_call, during_mcp_call, logging_only.

Model Armor 특화 (Model Armor Specific)

• template_id - str - Model Armor 템플릿 ID (필수)
• project_id - str - Google Cloud 프로젝트 ID (자격 증명 프로젝트로 기본값)
• location - str - Google Cloud 위치/리전. 기본 us-central1
• credentials - Union[str, dict] - 서비스 계정 JSON 파일 경로 또는 자격 증명 사전
• api_endpoint - str - Model Armor용 커스텀 API 엔드포인트 (선택)
• fail_on_error - bool - Model Armor가 오류(스캔할 수 없는 첨부 포함, Document and File Scanning 참고)를 만나면 요청을 실패시킬지. 기본 true
• skip_unscannable_attachments - bool - 인라인 바이트가 없는 첨부 참조(file_id, gs://, http(s)://)가 차단 대신 스캔 없이 통과하게 하되, 실제 Model Armor API 오류에서는 여전히 fail-close (Attachments That Cannot Be Scanned 참고). 기본 false
• sanitize_error_detail - bool - 원시 Model Armor API 응답을 호출자 대상 오류 상세, 디버그 로그, 가드레일 trace 페이로드에서 제외. 기본 true. 디버깅용 상세 출력을 복원하려면 false 설정
• mask_request_content - bool - 요청의 민감 콘텐츠 마스킹 활성화. 기본 false
• mask_response_content - bool - 응답의 민감 콘텐츠 마스킹 활성화. 기본 false

더 읽기 (Further Reading)

• Control Guardrails per API Key