Guardrails

가드레일은 채팅 요청 본문에서 지정한 키워드를 검사하는 사용자별 정책입니다. 각 정책은 action에 따라 두 가지로 동작합니다 — block은 일치하는 요청을 프로바이더 호출 전에 거부하고, flag는 요청을 그대로 통과시키되 감사 이벤트만 기록합니다.

가드레일은 PII 마스킹과 다릅니다. 마스킹은 민감한 내용을 가린 채 요청을 프로바이더로 보내지만, 가드레일은 일치하는 요청 자체를 차단(block)하거나 표시(flag)합니다.

정책 관리#

정책은 로그인 세션(JWT)으로 관리합니다. 목록 조회는 GET /v1/guardrails, 수정은 PATCH /v1/guardrails/{id}, 삭제는 DELETE /v1/guardrails/{id}를 사용합니다. 생성은 성공 시 201을 반환합니다.

curl https://router.pleum.ai/v1/guardrails \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "no-secrets",
    "blocked_terms": ["api_key", "AWS_SECRET", "password"],
    "action": "block"
  }'

적용 방식#

가드레일은 /v1/chat/completions, /v1/messages, /v1/responses 호출 시 프로바이더가 호출되기 전에 적용됩니다. 검사는 텍스트 파트만 대상으로 하며, 이미지 파트는 무시됩니다.

block 정책의 키워드가 일치하면 요청은 HTTP 403으로 거부되고, 본문에 error·message·일치한 정책의 guardrail 이름이 담깁니다. 프로바이더는 호출되지 않으므로 크레딧도 차감되지 않습니다.

{
  "error": "guardrail_blocked",
  "message": "Request blocked by a guardrail policy.",
  "guardrail": "no-secrets"
}

flag 정책이 일치하면 요청은 그대로 통과하고 감사 이벤트만 기록됩니다. 요청 내용은 저장되지 않으며, 정책 이름과 일치한 키워드만 남습니다.