가드레일 공급자: OpenAI Moderation

가드레일 공급자: OpenAI Moderation

OpenAI의 내장 Moderation API를 사용해 증오 발언, 괴롭힘, 자해, 성적 콘텐츠, 폭력 등을 포함한 유해 콘텐츠를 감지하고 차단해요.

출처: 문서

본문

개요 (Overview)

속성	세부
설명	OpenAI의 내장 Moderation API로 유해 콘텐츠 감지·차단 (증오 발언, 괴롭힘, 자해, 성적 콘텐츠, 폭력 포함)
제공자	OpenAI Moderation API
지원 동작	BLOCK (위반 감지 시 HTTP 400 예외 발생)
지원 모드	pre_call, during_call, post_call
스트리밍 지원	✅ 스트리밍 응답 완전 지원
API 요구사항	OpenAI API 키

빠른 시작 (Quick Start)

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

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

config.yaml:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
guardrails:
  - guardrail_name: "openai-moderation-pre"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY  # Optional if already set globally
      model: "omni-moderation-latest"     # Optional, defaults to omni-moderation-latest
      api_base: "https://api.openai.com/v1"  # Optional, defaults to OpenAI API

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

• pre_call LLM 호출 전의 사용자 입력에 실행
• during_call LLM 호출 중의 사용자 입력에 실행. pre_call과 같지만 LLM 호출과 병행. 가드레일 검사가 완료될 때까지 응답 반환되지 않음
• post_call LLM 호출 후의 LLM 응답에 실행

지원되는 OpenAI Moderation 모델:

• omni-moderation-latest (기본) - 최신 멀티모달 조정 모델
• text-moderation-latest - 최신 텍스트 전용 조정 모델

OpenAI API 키 설정:

export OPENAI_API_KEY="your-openai-api-key"

2. LiteLLM 게이트웨이 시작

litellm --config config.yaml --detailed_debug

3. 테스트 요청

차단된 요청:

유해 콘텐츠를 포함하므로 실패할 것으로 예상:

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "I hate all people and want to hurt them"}
    ],
    "guardrails": ["openai-moderation-pre"]
  }'

실패 시 예상 응답:

{
  "error": {
    "message": {
      "error": "Violated OpenAI moderation policy",
      "moderation_result": {
        "violated_categories": ["hate", "violence"],
        "category_scores": {
          "hate": 0.95,
          "violence": 0.87,
          "harassment": 0.12,
          "self-harm": 0.01,
          "sexual": 0.02
        }
      }
    },
    "type": "None",
    "param": "None",
    "code": "400"
  }
}

성공 호출:

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "guardrails": ["openai-moderation-pre"]
  }'

예상 응답:

{
  "id": "chatcmpl-4a1c1a4a-3e1d-4fa4-ae25-7ebe84c9a9a2",
  "created": 1741082354,
  "model": "gpt-5.6-terra",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The capital of France is Paris.",
        "role": "assistant"
      }
    }
  ],
  "usage": {
    "completion_tokens": 8,
    "prompt_tokens": 13,
    "total_tokens": 21
  }
}

고급 구성 (Advanced Configuration)

입력과 출력용 다중 가드레일 (Multiple Guardrails for Input and Output):

사용자 입력과 LLM 응답에 별도 가드레일 구성:

guardrails:
  - guardrail_name: "openai-moderation-input"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY
  - guardrail_name: "openai-moderation-output"
    litellm_params:
      guardrail: openai_moderation
      mode: "post_call"
      api_key: os.environ/OPENAI_API_KEY

커스텀 API 구성 (Custom API Configuration):

커스텀 OpenAI API 엔드포인트나 다른 모델 구성:

guardrails:
  - guardrail_name: "openai-moderation-custom"
    litellm_params:
      guardrail: openai_moderation
      mode: "pre_call"
      api_key: os.environ/OPENAI_API_KEY
      api_base: "https://your-custom-openai-endpoint.com/v1"
      model: "text-moderation-latest"

스트리밍 지원 (Streaming Support)

OpenAI Moderation 가드레일은 스트리밍 응답을 완전히 지원해요. post_call 모드에서 사용하면:

• 모든 스트리밍 청크 수집
• 완전한 응답 조립
• 전체 콘텐츠에 조정 적용
• 위반이 감지되면 전체 스트림 차단
• 콘텐츠가 안전하면 원래 스트림 반환

guardrails:
  - guardrail_name: "openai-moderation-streaming"
    litellm_params:
      guardrail: openai_moderation
      mode: "post_call"  # Works with streaming responses
      api_key: os.environ/OPENAI_API_KEY

콘텐츠 카테고리 (Content Categories)

OpenAI Moderation API는 다음 카테고리의 유해 콘텐츠를 감지해요:

카테고리	설명
hate	인종, 성별, 민족, 종교, 국적, 성적 지향, 장애, 카스트에 기반한 증오를 표현·선동·조장하는 콘텐츠
harassment	개인을 괴롭히거나, 협박하거나, 위협하는 콘텐츠
self-harm	자해 행위를 조장, 장려, 묘사하는 콘텐츠
sexual	성적 흥분을 일으키거나 성적 서비스를 홍보하려는 콘텐츠
violence	죽음, 폭력, 신체적 부상을 묘사하는 콘텐츠

각 카테고리는 Boolean 플래그와 신뢰도 점수(0.0~1.0)로 평가돼요.

오류 처리 (Error Handling)

콘텐츠가 OpenAI 조정 정책을 위반하면:

• HTTP 상태: 400 Bad Request
• 오류 유형: HTTPException
• 오류 상세: 위반 카테고리와 신뢰도 점수 포함
• 동작: 요청 즉시 차단

모범 사례 (Best Practices)

1. 사용자 입력에는 pre-call 사용

   guardrails:
     - guardrail_name: "input-moderation"
       litellm_params:
         guardrail: openai_moderation
         mode: "pre_call"  # Block harmful user inputs early
   

2. LLM 응답에는 post-call 사용

   guardrails:
     - guardrail_name: "output-moderation"
       litellm_params:
         guardrail: openai_moderation
         mode: "post_call"  # Ensure LLM responses are safe
   

3. 다른 가드레일과 결합

   guardrails:
     - guardrail_name: "openai-moderation"
       litellm_params:
         guardrail: openai_moderation
         mode: "pre_call"
     - guardrail_name: "custom-pii-detection"
       litellm_params:
         guardrail: presidio
         mode: "pre_call"
   

문제 해결 (Troubleshooting)

• 잘못된 API 키: OpenAI API 키가 올바르게 설정됐는지 확인
• 요율 제한: OpenAI Moderation API에는 요율 제한이 있음. 대량 시나리오에서 사용량 모니터링
• 네트워크 문제: OpenAI API 엔드포인트 연결성 확인

디버그 모드: 문제 해결을 위해 상세 로깅 활성화

litellm --config config.yaml --detailed_debug

OpenAI Moderation:로 시작하는 로그를 찾아 가드레일 실행을 추적하세요.

API 비용 (API Costs)

OpenAI Moderation API는 콘텐츠 정책 컴플라이언스에 무료로 사용할 수 있어요. 이는 다른 상용 조정 서비스와 비교해 비용 효율적인 가드레일 옵션이 되게 해요.

도움이 필요하세요? (Need Help?)

• OpenAI Moderation API 문서 확인
• LiteLLM Guardrails 문서 검토
• Discord 커뮤니티 참여