가드레일¶

가드레일은 요청 입력과 모델 출력을 검사한 뒤, 콘텐츠가 백엔드나 클라이언트에 도달하기 전에 허용·차단·변환·플래그 처리하는 콘텐츠 안전 정책입니다. 모든 프로바이더와 모든 API 표면(OpenAI chat, /v1/responses 브리지, 네이티브 Anthropic Messages)에 걸쳐 모더레이션, 프롬프트 인젝션 방어, PII 마스킹, 사용자 정의 허용/차단 규칙을 한곳에서 적용하는 지점을 라우터에 제공합니다.

가드레일은 기본적으로 꺼져 있습니다. guardrails 블록이 없거나 enabled: false이면 라우터는 어떤 동작도 오버헤드도 추가하지 않습니다. 설정된 가드레일에 걸리지 않는 요청은 바이트 단위로 그대로 흘러갑니다.

개념¶

판정(Verdict)¶

모든 가드레일 검사는 네 가지 판정 중 하나를 반환합니다:

판정	의미	enforce 모드에서의 효과
`Allow`	콘텐츠가 허용됨.	변경 없이 진행.
`Block`	콘텐츠가 정책을 위반함. 카테고리, `[0.0, 1.0]` 신뢰도 점수, 사유를 함께 전달.	요청/응답이 `block_behavior`에 따라 게이팅됨.
`Transform`	콘텐츠를 치환해야 함(예: PII 마스킹). 치환 텍스트를 함께 전달.	라우터가 정제된 텍스트로 치환하고 계속 진행.
`Flag`	콘텐츠를 관찰용으로 기록하되 차단하지 않음. 카테고리와 점수를 함께 전달.	기록만 하고 요청은 진행.

같은 단계에서 여러 가드레일이 실행되면, 서비스는 가장 심각한 판정 우선 규칙으로 판정을 집계합니다: Allow(0) < Flag(1) < Transform(2) < Block(3).

카테고리¶

판정은 MLCommons 위해(hazard) 카테고리와 OpenAI 스타일 모더레이션 라벨을 기반으로 한 고정 분류 체계에서 가져온 안전 카테고리를 함께 전달합니다: violence, hate_speech, sexual_content, self_harm, harassment, dangerous, jailbreak, pii, profanity. 알려진 카테고리에 해당하지 않는 프로바이더별 라벨은 그대로 보존됩니다. 카테고리 라벨은 category_thresholds에서 키로 사용하는 값입니다.

입력 게이팅과 출력 게이팅¶

가드레일은 한 단계 또는 두 단계 모두에서 실행됩니다:

입력(input): 백엔드 호출 전에 인바운드 프롬프트나 메시지를 검사합니다. 차단이면 모델을 호출하지 않고 요청을 중단하고, 변환이면 디스패치 전에 프롬프트를 다시 씁니다.
출력(output): 클라이언트에 반환하기 전에 모델이 생성한 텍스트를 검사합니다. 차단이면 응답을 교체하고, 변환이면 정제된 텍스트로 치환합니다.

stages를 생략하면 프로바이더는 두 단계 모두에서 실행됩니다.

라이프사이클 훅¶

라우터는 분류 전용 프로바이더가 직렬 지연을 추가하지 않도록 입력 단계 가드레일을 두 지점에서 구동합니다:

pre-call: 백엔드 디스패치 전에 실행. 여기서 차단 판정이 나오면 백엔드는 호출되지 않습니다. 어차피 차단될 요청에 백엔드 호출을 쓰지 않으려는 경우, 저렴한 로컬 검사(차단 리스트, PII, 프롬프트 인젝션 스크린)에 사용하세요.
during-call: tokio::join!을 통해 백엔드 호출과 동시에 실행. 가드레일 지연이 모델 지연과 겹치므로 원격 분류기(OpenAI Moderation, 클라우드 가드레일)가 추가하는 실제 시간이 거의 없습니다. 판정이 차단이면 진행 중이던 백엔드 응답은 폐기되고 차단 응답이 대신 반환됩니다.

출력 단계 가드레일은 post-call로 실행됩니다. 백엔드가 응답을 반환한 후, 응답(또는 캐시본)이 반환되기 전에 어시스턴트가 생성한 텍스트를 검사합니다.

monitor와 enforce¶

mode 설정은 판정이 요청 처리를 바꾸는지 여부를 결정합니다:

monitor(기본값): 모든 판정이 계산되고 메트릭에 기록되며 감사 로그에 남지만, 요청이나 응답을 절대 바꾸지 않습니다. 정책을 켜기 전에 그 정책이 무엇을 할지 관찰하는 데 쓰는 로깅 전용 모드입니다.
enforce: 차단 판정이 block_behavior에 따라 요청/응답을 게이팅합니다. 가드레일이 활성화된 상태의 enforce 모드는 프로바이더가 최소 1개 이상 설정되어 있어야 합니다.

권장 롤아웃은 monitor 먼저, 그다음 enforce입니다. 임계값 튜닝 워크플로를 참고하세요.

차단 동작(block behavior)¶

enforce 모드에서 block_behavior는 차단된 요청을 어떻게 렌더링할지 선택합니다:

`block_behavior`	OpenAI / Responses 표면	Anthropic 표면
`content_filter`(기본값)	`choices[0].finish_reason`가 `content_filter`이고 어시스턴트 메시지에 필터링된 콘텐츠 자리 표시자가 담긴 `chat.completion`.	단일 거부 텍스트 블록과 `stop_reason: end_turn`을 가진 Messages 객체.
`refusal_message`	`content_filter`와 같은 형태이며, 메시지 콘텐츠로 정형화된 거부 문자열을 담음.	같은 Messages 형태이며, 텍스트 블록으로 거부 문자열을 담음.
`error`	OpenAI 오류 봉투: `{"error": {"type": "content_filter", "code": "content_filter", ...}}`.	Anthropic 오류 봉투: `{"type": "error", "error": {"type": "invalid_request_error", ...}}`.

모든 차단 응답에는 주석 헤더가 함께 실립니다: x-guardrail-action, x-guardrail-category, x-guardrail-score, 그리고 (단일 프로바이더가 판정을 낸 경우) x-guardrail-provider. 차단 응답은 캐시되지 않습니다.

fail-open과 fail-closed¶

on_error는 가드레일이 오류를 내거나 타임아웃을 초과할 때의 동작을 결정합니다:

fail_open(기본값): 요청이 진행됩니다. 엄격성보다 가용성을 우선합니다. 모더레이션 장애가 라우터를 중단시키지 않습니다.
fail_closed: 요청이 차단됩니다. 가용성보다 엄격성을 우선합니다.

이 정책은 전역으로 설정하고 프로바이더별로 재정의할 수 있습니다.

타임아웃¶

timeout_ms(기본값 2000)는 각 프로바이더 검사를 제한합니다. 프로바이더는 자신의 timeout_ms로 이를 재정의할 수 있습니다. 마감을 초과한 검사는 오류로 처리되어 on_error에 따라 해소됩니다.

라우트별 정책¶

routes 맵은 라우트나 모델 이름별로 전역 정책을 재정의합니다. 설정하지 않은 필드는 전역 값을 상속합니다. 라우트는 모드를 전환하거나(예: 나머지 배포가 monitor로 유지되는 동안 고객 대면 모델에서만 enforce), 프로바이더의 부분집합으로 제한하거나, 자체 category_thresholds를 두거나, 라우트별 허용/차단 리스트를 추가할 수 있습니다.

카테고리별 임계값¶

category_thresholds는 카테고리 라벨을 [0.0, 1.0] 범위의 점수 하한에 매핑합니다. 프로바이더는 카테고리별 신뢰도 점수를 보고하며, 카테고리는 그 점수가 임계값 이상일 때만 차단합니다. 임계값이 없는 카테고리는 절대 차단하지 않습니다. 임계값은 프로바이더별, 라우트별로 설정합니다.

허용/차단 리스트¶

allow와 deny는 각각 exact(리터럴 문자열)와 regex(설정 로드 시 컴파일 검증되는 패턴) 항목을 가진 매치 리스트입니다. 전역으로 적용되며 라우트별로 확장할 수 있습니다. 모델이 필요 없는 결정적 규칙에 사용하세요. 알려진 금지어를 하드 차단하는 차단 리스트, 알려진 안전 문구를 예외 처리하는 허용 리스트 등입니다.

우회 허용 목록(bypass allowlist)¶

bypass_api_keys는 가드레일을 완전히 건너뛰는 API 키를 나열합니다. 우회 키로 인증된 요청은 어느 단계에서도 가드레일 검사를 실행하지 않습니다. 게이팅되어서는 안 되는 신뢰할 수 있는 내부 자동화에 한해 신중히 사용하세요.

프로바이더¶

라우터에는 다섯 가지 프로바이더 유형이 함께 제공됩니다. 각각은 안정적인 name(라우트 재정의에서 사용)과 type으로 참조합니다. 자격 증명은 항상 환경 변수 이름(api_key_env)으로 공급하며, 인라인으로 저장하지 않습니다.

OpenAI Moderation (`openai_moderation`)¶

무료이며 멀티모달인 omni-moderation-latest 모델로 POST /v1/moderations를 호출하고, 반환된 카테고리별 점수를 임계값과 비교합니다. 이 모더레이션 모델은 사용량 한도에 포함되지 않습니다.

- name: openai-moderation
  type: openai_moderation
  enabled: true
  endpoint: "https://api.openai.com/v1/moderations"
  api_key_env: OPENAI_API_KEY
  stages: [input, output]
  category_thresholds:
    violence: 0.8
    hate_speech: 0.7
    sexual_content: 0.9
  timeout_ms: 1000
  on_error: fail_open

원격 호출이므로 지연이 백엔드와 겹치도록 during-call(기본 입력 라이프사이클)로 실행하세요.

자체 호스팅 분류기 (`self_hosted_classifier` / `classifier`)¶

오픈 가드레일 모델을 일반 백엔드(Ollama, vLLM, 또는 OpenAI 호환 chat/completion 엔드포인트)로 서빙하고 그 판정을 카테고리에 매핑합니다. 프롬프트는 배포 환경을 벗어나지 않습니다. 이 호출은 라우터의 HTTP 클라이언트와 서킷 브레이커를 재사용하며, 별도의 HTTP 스택을 열지 않습니다. 두 타입 이름 self_hosted_classifier와 classifier는 동등합니다.

template 옵션이 모델 패밀리와 그 프롬프트/파서를 선택합니다:

`template`	모델 패밀리	라이선스 / 비고
`granite_guardian`(기본값)	IBM Granite Guardian. `Yes` / `No`로 응답하며 선택적 `risk_name` 차원(`harm`, `social_bias`, `groundedness`, `jailbreak` 등)을 가짐.	Apache-2.0. 권장 기본값.
`llama_guard`	Llama Guard 3 / 4. `safe` / `unsafe`와 `S1`..`S14` 위해 코드로 응답하며, 라우터 카테고리에 매핑됨. `categories` 부분집합으로 차단 가능한 코드를 제한.	게이트 라이선스. Llama Guard 4(12B)는 GPU 부하가 큼.
`shieldgemma`	Google ShieldGemma. 정책별 `Yes` / `No`.	Gemma 라이선스.

분류기 모델 서빙¶

이미 운영 중인 백엔드에 가드레일 모델을 받습니다. 예를 들어 Ollama에서는 ollama pull granite-guardian(또는 vLLM에 Llama Guard / ShieldGemma 이미지)을 사용합니다.
모델이 OpenAI 호환 엔드포인트에서 응답하는지 확인합니다. 예: Ollama의 경우 http://127.0.0.1:11434/v1/chat/completions.
프로바이더의 endpoint를 그 URL로 지정하고 template을 모델 패밀리로 설정합니다. 기본값이 아닌 모델 이름을 쓰려면 model을 설정합니다.

- name: self-hosted-guard
  type: classifier
  enabled: true
  endpoint: "http://127.0.0.1:11434/v1/chat/completions"
  stages: [input, output]
  options:
    template: granite_guardian
    task: content          # `content`(기본값) 또는 `injection`(입력 단계 jailbreak 스크린)
    model: "granite-guardian:5b"
    api_format: chat        # `chat`(기본값) 또는 `completion`
    risk_name: harm         # Granite Guardian 전용
    # categories: ["S1", "S10", "S11"]   # Llama Guard 전용: 이 위해 코드로 제한
  category_thresholds:
    dangerous: 0.5

Llama Guard 4는 Hugging Face에서 게이트되어 있고 12B 모델을 담을 충분한 메모리의 GPU가 필요합니다. Granite Guardian은 더 가볍고 허용적인 라이선스의 기본값입니다. 입력 단계용 경량 프롬프트 인젝션 / jailbreak 스크린이 필요하면 task: injection을 설정하세요.

PII 탐지 및 마스킹 (`pii`)¶

개인 식별 정보와 고가치 비밀 값을 탐지한 뒤, 그 자리에서 마스킹(Transform 판정)하거나 요청을 차단합니다. 내장 스캐너는 외부 의존성 없이 로컬에서 동작합니다. 더 풍부한 NER 기반 PII를 위해 Microsoft Presidio 호환 분석기를 선택적으로 추가할 수 있으며, 그 구간은 내장 탐지 결과와 병합됩니다. 탐지된 원본 값은 로그에 기록되지 않습니다.

이 프로바이더의 옵션 표와 엔티티 유형을 포함한 전체 문서는 보안 & 관리 → 가드레일: PII 탐지 및 마스킹에 있습니다. 최소 예시는 다음과 같습니다:

- name: pii-redaction
  type: pii
  enabled: true
  stages: [input, output]
  options:
    default_action: mask
    actions:
      email: mask
      ssn: block
      credit_card: block
      api_key: block
    placeholder_format: "<REDACTED:{TYPE}>"
  on_error: fail_open

AWS Bedrock Guardrails (`bedrock_guardrail`)¶

Bedrock ApplyGuardrail API를 호출합니다. 이 API는 모델 호출과 독립적으로 콘텐츠를 평가하므로 모든 백엔드(OpenAI, Gemini, 자체 호스팅 포함)에서 동작합니다. 콘텐츠 필터(Prompt Attack 포함), 금지 토픽, 민감 정보(PII) 정책을 다룹니다. PII 차단은 Block 판정이 되고, PII 마스킹은 마스킹된 텍스트로 치환하는 Transform이 됩니다. 요청은 AWS SigV4로 서명됩니다.

클라우드 측 설정¶

Bedrock 콘솔에서 가드레일을 생성하고 식별자와 버전을 기록합니다.
설정은 환경 변수로 공급합니다(설정 파일에 계정 식별자를 넣지 않음):
- AWS_REGION: 예: us-east-1.
- CONTINUUM_BEDROCK_GUARDRAIL_ID: 가드레일 식별자.
- CONTINUUM_BEDROCK_GUARDRAIL_VERSION: 버전(기본값 DRAFT).
AWS 자격 증명은 표준 환경 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, 선택적으로 AWS_SESSION_TOKEN)로 제공합니다.

- name: bedrock-guardrail
  type: bedrock_guardrail
  enabled: true
  stages: [input, output]
  timeout_ms: 1500
  on_error: fail_open

endpoint는 선택 사항이며, 유도된 리전 URL을 재정의해야 할 때(예: 사설 프록시)만 필요합니다.

Azure AI Content Safety / Prompt Shields (`azure_content_safety`)¶

텍스트 분석은 Hate, Sexual, Violence, SelfHarm에 대해 0-7 심각도를 반환하며, 이는 [0.0, 1.0]로 정규화되어 임계값과 비교됩니다. 입력 단계에서는 Prompt Shields도 실행하여 jailbreak와 직접/간접(교차 프롬프트) 인젝션 탐지를 추가하며, 탐지되면 jailbreak 카테고리로 차단합니다. 출력 단계는 텍스트 분석만 실행합니다.

클라우드 측 설정¶

Azure AI Content Safety 리소스를 생성합니다.
endpoint를 그 기본 URL(https://<resource>.cognitiveservices.azure.com)로 설정합니다.
구독 키를 api_key_env가 가리키는 환경 변수에 저장합니다.

- name: azure-content-safety
  type: azure_content_safety
  enabled: true
  endpoint: "https://my-resource.cognitiveservices.azure.com"
  api_key_env: AZURE_CONTENT_SAFETY_KEY
  stages: [input, output]
  category_thresholds:
    violence: 0.7
    hate_speech: 0.7
    sexual_content: 0.7
    self_harm: 0.7
  timeout_ms: 1500
  on_error: fail_open

스트리밍 출력 게이팅¶

스트리밍 응답은 한 번에 검사할 수 없으므로 streaming_mode가 출력 단계의 스트리밍 응답 처리 방식을 선택합니다. 이 선택은 첫 토큰까지의 시간(TTFT)과 클라이언트에 도달할 수 있는 안전하지 않은 텍스트의 양 사이의 트레이드오프입니다.

`streaming_mode`	동작 방식	TTFT	안전성
`buffer_full`(기본값)	스트리밍 응답 전체를 버퍼링한 뒤, 스트림 종료 시 출력 검사를 한 번 실행.	가장 나쁨(검사를 통과할 때까지 클라이언트는 아무것도 보지 못함).	가장 강함: 안전하지 않은 내용이 절대 스트리밍되지 않음.
`chunked`	스트림이 진행되는 동안 롤링 윈도우에 대해 증분 검사를 실행. 위반이 발생하면 스트림을 끊고 content-filter 종료 청크를 내보냄.	양호.	강함: 위반이 스트림 중간에 잡히지만 작은 접두부는 이미 노출되었을 수 있음.
`passthrough`	출력 검사 없이 청크를 그대로 흘려보냄.	가장 좋음.	스트리밍 출력에 대해서는 없음(입력 게이팅은 계속 적용됨).

chunked는 NeMo Guardrails를 본뜬 세 필드로 조정합니다:

streaming_chunk_size(기본값 200): 각 증분 검사 전에 누적할 새 텍스트의 문자 수.
streaming_context_size(기본값 50): 청크 경계를 가로지르는 위반도 보이도록 각 검사로 가져가는 후행 문자 수.
streaming_stream_first(기본값 false): true이면 각 윈도우를 검사하기 전에 클라이언트로 내보냄(가장 낮은 지연, 위반 청크가 일부 노출될 수 있음). false이면 윈도우를 내보내기 전에 검사함(더 안전하며, 각 윈도우에 검사 지연이 더해짐).

monitor 모드에서는 스트리밍 판정이 계산되고 기록되지만 스트림을 절대 끊지 않습니다.

설정¶

정식이며 전체 주석이 달린 레퍼런스는 config.yaml.example의 guardrails: 블록입니다. 아래는 여러 프로바이더, 라우트별 재정의, 튜닝을 결합한 간결한 엔드투엔드 예시입니다. 비밀 값을 인라인으로 저장하지 말고 환경 변수 이름으로 참조하세요.

guardrails:
  enabled: true
  mode: monitor          # monitor로 시작; 메트릭을 관찰한 뒤 enforce로 전환

  providers:
    - name: openai-moderation
      type: openai_moderation
      endpoint: "https://api.openai.com/v1/moderations"
      api_key_env: OPENAI_API_KEY
      stages: [input, output]
      category_thresholds:
        violence: 0.8
        hate_speech: 0.7

    - name: pii-redaction
      type: pii
      stages: [input, output]
      options:
        default_action: mask
        actions:
          ssn: block
          credit_card: block

  routes:
    "gpt-5.4":
      mode: enforce
      providers: ["openai-moderation", "pii-redaction"]
      category_thresholds:
        pii: 0.95
      deny:
        exact: ["forbidden-term"]
        regex: ['(?i)\bclassified\b']

  bypass_api_keys: []

  timeout_ms: 2000
  on_error: fail_open
  block_behavior: content_filter

  streaming_mode: buffer_full
  streaming_chunk_size: 200
  streaming_context_size: 50
  streaming_stream_first: false

  deny:
    exact: ["badword"]
    regex: ['\bssn\b', '\d{3}-\d{2}-\d{4}']

  audit:
    enabled: true
    log_level: info

최상위 필드¶

필드	타입	기본값	설명
`enabled`	boolean	`false`	서브시스템 마스터 스위치.
`mode`	string	`monitor`	`monitor` 또는 `enforce`.
`providers`	array	`[]`	프로바이더 정의(프로바이더 참고).
`routes`	map	`{}`	라우트/모델 이름별 재정의.
`bypass_api_keys`	array	`[]`	모든 가드레일 검사를 건너뛰는 API 키.
`timeout_ms`	integer	`2000`	전역 프로바이더 검사 타임아웃(양수여야 함).
`on_error`	string	`fail_open`	`fail_open` 또는 `fail_closed`.
`block_behavior`	string	`content_filter`	`content_filter`, `refusal_message`, `error`.
`streaming_mode`	string	`buffer_full`	`buffer_full`, `chunked`, `passthrough`.
`streaming_chunk_size`	integer	`200`	`chunked`: 증분 검사당 문자 수.
`streaming_context_size`	integer	`50`	`chunked`: 검사당 후행 컨텍스트.
`streaming_stream_first`	boolean	`false`	`chunked`: 내보낸 뒤 검사(`true`) 또는 검사 후 내보냄(`false`).
`allow`	매치 리스트	`{}`	전역 허용 리스트(`exact` + `regex`).
`deny`	매치 리스트	`{}`	전역 차단 리스트(`exact` + `regex`).
`audit`	object	활성화	감사 로그 설정(감사 로깅 참고).

프로바이더 필드¶

필드	타입	기본값	설명
`name`	string	필수	안정적 프로바이더 이름(고유, 라우트에서 참조).
`type`	string	필수	프로바이더 구현 유형.
`enabled`	boolean	`true`	이 프로바이더의 실행 여부.
`endpoint`	string	-	해당하는 경우 프로바이더 HTTP 엔드포인트.
`api_key_env`	string	-	자격 증명이 담긴 환경 변수 이름.
`stages`	array	둘 다	`input`, `output`, 또는 둘 다.
`category_thresholds`	map	`{}`	`[0.0, 1.0]` 범위의 카테고리별 점수 하한.
`timeout_ms`	integer	전역	프로바이더별 타임아웃 재정의.
`on_error`	string	전역	프로바이더별 오류 정책 재정의.
`options`	object	-	프로바이더별 옵션(PII 동작, 분류기 template 등).

설정은 로드 시점과 핫 리로드 시점에 검증됩니다. 프로바이더 이름은 비어 있지 않고 고유해야 하며, 임계값은 [0.0, 1.0] 범위여야 하고, 타임아웃은 양수여야 하며, 모든 regex가 컴파일되어야 하고, 가드레일이 활성화된 enforce 모드는 프로바이더가 최소 1개 이상 필요합니다.

임계값 튜닝 워크플로¶

사용자를 놀라게 하지 않으면서 정책을 롤아웃하세요:

monitor 모드로 시작. 사용할 프로바이더와 임계값으로 mode: monitor(전역 또는 라우트별)를 설정합니다. 판정은 계산되고 기록되지만 트래픽을 게이팅하지 않습니다.
메트릭 관찰. guardrail_verdicts_total{mode="monitor"}와 guardrail_blocks_total를 보면서 단계·프로바이더·카테고리별로 무엇이 차단되었을지 확인합니다. 특정 카테고리와 점수는 감사 로그에서 확인합니다.
임계값 튜닝. 오탐을 내는 카테고리는 임계값을 올리고, 실제 위반을 통과시키는 카테고리는 낮춥니다. 프로바이더별·라우트별로 조정합니다.
enforce. 라우트(또는 전역 기본값)를 mode: enforce로 전환합니다. 이제 같은 임계값이 트래픽을 게이팅합니다. guardrail_blocks_total과 guardrail_fail_open_total / guardrail_fail_closed_total를 계속 모니터링합니다.

모드와 임계값이 라우트별이므로, 한 모델에서 enforce하면서 나머지는 monitor로 유지할 수 있고, 재시작 없이 관리자 API로 런타임에 이 모든 것을 바꿀 수 있습니다.

운영¶

관리자 런타임 제어¶

관리자 API는 라이브 가드레일 정책을 노출하고 재시작 없이 변경할 수 있게 합니다. 모든 엔드포인트는 관리자 인증이 필요합니다(관리자 REST API 참고).

엔드포인트	메서드	설명
`/admin/guardrails`	GET	적용 중인 가드레일 정책 조회.
`/admin/guardrails`	PATCH	최상위 정책 부분 업데이트(모드, 타임아웃, 실패 정책, 차단 동작, 리스트).
`/admin/guardrails/providers/{name}`	PUT	단일 프로바이더 토글 또는 튜닝.
`/admin/guardrails/routes/{route}`	PUT	라우트별 재정의 생성 또는 교체.
`/admin/guardrails/routes/{route}`	DELETE	라우트별 재정의 제거(라우트가 전역 정책으로 폴백).
`/admin/guardrails/test`	POST	설정된 프로바이더에 샘플 텍스트를 드라이런하여 판정 반환.

enforce하기 전에 /admin/guardrails/test로 대표 프롬프트에 정책을 점검하고, routes 엔드포인트로 단일 모델부터 enforce하세요.

메트릭¶

metrics 기능이 활성화되면 모든 가드레일 결정이 Prometheus 시리즈로 내보내집니다:

메트릭	타입	라벨	설명
`guardrail_checks_total`	counter	`stage`, `provider`, `result`	단계·판정 결과별 프로바이더 검사. `stage`는 `input` / `output` / `streaming`, `result`는 `allow` / `block` / `transform` / `flag`.
`guardrail_blocks_total`	counter	`stage`, `provider`, `category`	단계·프로바이더·안전 카테고리별 차단 판정.
`guardrail_check_duration_seconds`	histogram	`stage`, `provider`	프로바이더별 검사 지연.
`guardrail_errors_total`	counter	`provider`, `kind`	프로바이더 오류. `kind`는 `timeout` 또는 `error`.
`guardrail_fail_open_total`	counter	`provider`	fail-open으로 해소된 프로바이더 실패(허용됨).
`guardrail_fail_closed_total`	counter	`provider`	fail-closed로 해소된 프로바이더 실패(차단됨).
`guardrail_verdicts_total`	counter	`stage`, `mode`, `result`	모드 의미를 적용한 후 요청당 단일 집계 판정. `mode`는 `monitor` / `enforce`이므로 게이팅하지 않는 monitor 모드 판정도 보임.

전체 레퍼런스는 메트릭 및 모니터링 → 가드레일 메트릭을 참고하세요.

감사 로깅¶

모든 판정(차단, 변환, 플래그)은 프로바이더·단계·카테고리·점수·모드·동작과 함께 구조화된 tracing으로 로깅됩니다. 감사 로그는 원본 프롬프트나 응답 텍스트, 비밀 값을 절대 담지 않습니다. 요청 메타데이터는 로깅 전에 마스킹되며, 카테고리·점수·단계·모드 메타데이터만 기록됩니다. 감사 로깅은 기본적으로 켜져 있으며 guardrails.audit 아래에서 설정합니다:

필드	타입	기본값	설명
`enabled`	boolean	`true`	가드레일 결정 감사 로깅 활성화 여부.
`log_level`	string	`info`	감사 이벤트를 내보내는 레벨: `debug`, `info`, `warn`.

함께 보기¶

보안 & 관리: API 키, PII 프로바이더 레퍼런스, 관리자 인증.
아키텍처: 요청 라이프사이클에서 가드레일 레이어의 위치.
메트릭 및 모니터링: guardrail_* 메트릭 시리즈.
관리자 REST API: 관리자 엔드포인트 레퍼런스.

가드레일¶

개념¶

판정(Verdict)¶

카테고리¶

입력 게이팅과 출력 게이팅¶

라이프사이클 훅¶

monitor와 enforce¶

차단 동작(block behavior)¶

fail-open과 fail-closed¶

타임아웃¶

라우트별 정책¶

카테고리별 임계값¶

허용/차단 리스트¶

우회 허용 목록(bypass allowlist)¶

프로바이더¶

OpenAI Moderation (openai_moderation)¶

자체 호스팅 분류기 (self_hosted_classifier / classifier)¶

분류기 모델 서빙¶

PII 탐지 및 마스킹 (pii)¶

AWS Bedrock Guardrails (bedrock_guardrail)¶

클라우드 측 설정¶

Azure AI Content Safety / Prompt Shields (azure_content_safety)¶

클라우드 측 설정¶

스트리밍 출력 게이팅¶

설정¶

최상위 필드¶

프로바이더 필드¶

임계값 튜닝 워크플로¶

운영¶

관리자 런타임 제어¶

메트릭¶

감사 로깅¶

함께 보기¶

OpenAI Moderation (`openai_moderation`)¶

자체 호스팅 분류기 (`self_hosted_classifier` / `classifier`)¶

PII 탐지 및 마스킹 (`pii`)¶

AWS Bedrock Guardrails (`bedrock_guardrail`)¶

Azure AI Content Safety / Prompt Shields (`azure_content_safety`)¶