/guardrails/apply_guardrail

이 엔드포인트로 LiteLLM 인스턴스에 구성된 가드레일을 직접 호출할 수 있어요. 가드레일을 직접 호출해야 하는 서비스가 있을 때 유용합니다.

지원되는 가드레일 타입

이 엔드포인트는 다양한 가드레일 타입을 지원해요:

Presidio - PII 감지 및 마스킹
Bedrock - 콘텐츠 모더레이션을 위한 AWS Bedrock 가드레일
Lakera - AI 안전 가드레일
PANW Prisma AIRS - 위협 감지, DLP, 정책 강제
커스텀 가드레일 - 사용자 정의 가드레일

설정

Bedrock 가드레일 설정

apply_guardrail 엔드포인트에서 Bedrock 가드레일을 사용하려면 config.yaml에 가드레일을 구성하세요:

guardrails:
  - guardrail_name: "bedrock-content-guard"
    litellm_params:
      guardrail: bedrock
      mode: "pre_call"
      guardrailIdentifier: "your-guardrail-id"  # Your actual Bedrock guardrail ID
      guardrailVersion: "DRAFT"  # or your version number
      aws_region_name: "us-east-1"  # Your AWS region
      aws_role_name: "your-role-arn"  # Your AWS role with Bedrock permissions
      default_on: true

필요한 AWS 설정:

AWS Console에서 Bedrock 가드레일 생성
가드레일 ID와 버전 가져오기
AWS 자격 증명에 Bedrock 권한이 있는지 확인
LiteLLM config에서 가드레일 구성

사용법

Presidio PII 가드레일
Bedrock 가드레일
메타데이터가 있는 커스텀 가드레일

이 예시에서 mask_pii는 LiteLLM에 구성된 Presidio 가드레일이에요. 엔드포인트 호출 예시:

curl -X POST 'http://localhost:4000/guardrails/apply_guardrail' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -d '{
    "guardrail_name": "mask_pii",
    "text": "My name is John Doe and my email is [email protected]",
    "language": "en",
    "entities": ["NAME", "EMAIL"]
  }'

이 예시에서 bedrock-content-guard는 LiteLLM에 구성된 Bedrock 가드레일이에요. 엔드포인트 호출 예시:

curl -X POST 'http://localhost:4000/guardrails/apply_guardrail' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -d '{
    "guardrail_name": "bedrock-content-guard",
    "text": "This is potentially harmful content that should be blocked",
    "language": "en"
  }'

참고: Bedrock 가드레일의 경우 entities 파라미터는 사용되지 않아요. Bedrock은 자체 정책에 따라 콘텐츠 모더레이션을 처리하기 때문입니다.

파라미터화된 커스텀 가드레일은 request_data["metadata"]에서 요청별 구성을 읽어요. 요청 본문에 선택적 metadata를 보내면 가드레일의 apply_guardrail 메서드로 전달됩니다. 이 예시에서 my-topic-guardrail은 metadata로 전달된 forbidden_topics 중 하나를 언급하는 텍스트를 차단하는 커스텀 가드레일이에요. 엔드포인트 호출 예시:

curl -X POST 'http://localhost:4000/guardrails/apply_guardrail' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -d '{
    "guardrail_name": "my-topic-guardrail",
    "text": "What are tax loopholes?",
    "metadata": {
      "forbidden_topics": ["tax", "finance"]
    }
  }'

metadata는 클라이언트가 보낼 때만 전달됩니다. 요청별 구성을 의존하지 않는 가드레일은 생략돼도 변경 없이 계속 동작해요.

출처: 문서

본문

Admin UI에서 테스트

가드레일 테스트 플레이그라운드(Admin UI의 Guardrails → Test Playground)에는 입력 텍스트 아래 선택적 Metadata 필드가 있어요. JSON 객체를 입력하면 요청의 metadata 필드로 전송되어, 대시보드를 벗어나지 않고 파라미터화된 커스텀 가드레일을 사용해 볼 수 있어요. 잘못된 JSON은 요청 전에 인라인으로 거부됩니다.

요청 형식

요청 본문은 ApplyGuardrailRequest 형식을 따라야 해요.

예시 요청 본문

{
    "guardrail_name": "mask_pii",
    "text": "My name is John Doe and my email is [email protected]",
    "language": "en",
    "entities": ["NAME", "EMAIL"]
}

필수 필드

guardrail_name (string): 적용할 가드레일의 식별자 (예: "mask_pii")
text (string): 가드레일로 처리할 입력 텍스트

선택 필드

language (string): 입력 텍스트의 언어 (예: 영어는 "en")
entities (string 배열): 처리하거나 필터링할 특정 엔터티 (예: ["NAME", "EMAIL"])
metadata (object): request_data["metadata"]로 가드레일에 전달되는 요청별 구성. apply_guardrail을 오버라이드하는 커스텀 가드레일은 이를 읽을 책임이 있어요. 존재할 때만 전달되므로, 생략하면 기존 동작을 유지해요.

응답 형식

응답에는 가드레일 적용 후 처리된 텍스트가 담겨요.

예시 응답

Presidio 응답
Bedrock 응답

{
    "response_text": "My name is [REDACTED] and my email is [REDACTED]"
}

{
    "response_text": "This is potentially harmful content that should be blocked"
}

참고: Bedrock 가드레일이 콘텐츠를 차단하면, 엔드포인트는 차단 이유와 함께 오류를 반환합니다.

응답 필드

response_text (string): 가드레일 적용 후의 텍스트

오류 응답

가드레일이 콘텐츠를 차단하면(예: Bedrock 가드레일), 엔드포인트는 오류를 반환해요:

{
    "detail": "Content blocked by Bedrock guardrail: Content violates policy"
}

/guardrails/apply_guardrail