가드레일 공급자: LLM-as-a-Judge

가드레일 공급자: LLM-as-a-Judge

판정자 모델을 사용해 가중치 기준에 따라 모든 수신 요청 또는 LLM 응답에 0-100 점수를 매기고, 임계값 아래에 있는 것을 차단하거나 기록해요.

출처: 문서

본문

개요 (Overview)

동작 방식 (How it works)

post_call 모드에서 가드레일은 대화와 LLM 응답을 기준과 함께 판정자 모델로 보내요. pre_call과 during_call 모드에서는 최신 요청 턴을 판정하고, 이전 role 라벨 메시지는 컨텍스트로만 전달돼요. 그래서 주제가 맞는 이력이 주제에서 벗어난 새 턴을 숨기지 않고, 이전에 거부된 턴이 나중의 유효한 턴을 침몰시키지 않아요. 판정 턴은 요청의 끝에 연속된 user 메시지이며, 그 텍스트 부분이 모두 결합되고, 가드레일 범위가 유지하는 메시지(skip_system_message_in_guardrail, skip_tool_message_in_guardrail, scan_only_tool_results가 평소대로 적용)에서 가져와요. 요청이 user 턴으로 끝나지 않거나(예: tool-result 왕복), 엔드포인트가 가드레일에 메시지별 구조를 주지 않으면, 판정자는 유지된 요청 텍스트 전체를 평가해요. 이는 응답이 존재하기 전에 실행되므로, 판정자가 주제에서 벗어나거나 허용되지 않은 요청을 메인 모델에 토큰을 쓰지 않고 거부할 수 있어요(during_call은 여전히 메인 호출을 병행 실행하고 판정자가 거부하면 그 결과를 버려요). 판정자는 기준별 판정(점수 0-100, 추론, 통과/실패)과 가중 종합 점수를 반환해요. 종합 점수가 overall_threshold 아래이고 on_failure가 block이면 요청이 전체 판정과 함께 HTTP 422로 실패하고, on_failure: log면 호출이 진행되고 판정이 요청의 로깅 메타데이터(eval_information)에 기록되며 지출 로그와 로깅 통합에서 볼 수 있어요.

판정된 요청/응답마다 판정자 모델에 LLM 호출 하나가 추가로 든다.

빠른 시작 (Quick Start)

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

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

config.yaml:

model_list:
  - model_name: chat-model
    litellm_params:
      model: anthropic/claude-opus-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: my-judge-model
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
guardrails:
  - guardrail_name: "quality-judge"
    litellm_params:
      guardrail: llm_as_a_judge
      mode: post_call
      judge_model: my-judge-model
      overall_threshold: 80
      on_failure: block
      default_on: true
      criteria:
        - name: helpfulness
          weight: 60
          description: Is the response helpful and correct?
        - name: tone
          weight: 40
          description: Is the response professional and polite?

기준 가중치는 합이 100이어야 해요. overall_threshold는 기본 80, on_failure는 기본 block이에요.

응답 대신 요청을 판정하려면 mode: pre_call로 설정하고(또는 mode: [pre_call, post_call]로 양쪽 판정) 요청에 대한 기준을 쓰세요. 예를 들어 description: Is the request about cooking or recipes?. 거부된 요청은 "message": "LLM judge rejected request: score below threshold"와 함께 HTTP 422를 반환하고, 메인 모델은 절대 호출되지 않아요.

2. LiteLLM 게이트웨이 시작

litellm --config config.yaml --detailed_debug

3. 테스트 요청

차단된 요청:

기준을 실패하는 응답은 HTTP 422로 거부되고 판정이 첨부돼요:

curl -i http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-model",
    "messages": [{"role": "user", "content": "hi"}]
  }'

{
  "error": {
    "message": "LLM judge rejected response: score below threshold",
    "code": "422",
    "provider_specific_fields": {
      "overall_score": 40.0,
      "threshold": 80.0,
      "verdicts": [
        {"criterion_name": "helpfulness", "score": 40, "reasoning": "...", "passed": false, "weight": 60}
      ],
      "guardrail_name": "quality-judge"
    }
  }
}

통과하는 요청:

임계값을 충족하는 응답은 변경 없이 반환돼요. on_failure: log로는 실패 응답도 반환되고, 판정이 eval_information에 기록돼 지출 로그와 로깅 콜백에 도달해요.

Admin UI에서 가드레일 만들기 (Creating the guardrail from the Admin UI)

가드레일을 대시보드에서 완전히 만들 수 있어요: Guardrails, Add New Guardrail, 공급자 "LiteLLM LLM as a Judge". 판정자 모델 드롭다운은 프록시의 모델 목록에서 채워지고, 기준, 임계값, 실패 동작이 위 구성 필드에 매핑돼요. 이렇게 만든 가드레일은 데이터베이스에 저장되고 콘피그 파일 항목 없이 시작 시 로드돼요.

판정자 모델의 자격 증명이 해석되는 방식 (How the judge model's credentials resolve)

judge_model은 프록시의 Router에 대해 먼저 해석돼요. 이름이 구성된 배포(정확한 공개 이름, anthropic/* 같은 와일드카드 라우트, 또는 model_group_alias 항목)와 일치하면 판정자 호출이 그 배포를 통해 진행되고 그 자격 증명을 사용해요. 이것이 Admin UI 드롭다운에서 선택된 판정자 모델이 동작하게 하는 것인데, 키가 환경이 아니라 배포에 살기 때문이에요. Router가 서빙할 수 없는 이름은 SDK로 폴백되어 직접 litellm.completion 호출처럼 환경 변수에서 자격 증명을 해석해요.

Router 경로의 두 가지 결과를 알아두는 게 좋아요. 판정자 모델 이름이 배포와 유효한 제공자 모델 id 둘 다와 일치하면 배포가 이겨서 배포의 키가 환경 키 대신 사용돼요. 그리고 배포를 통한 판정자 호출은 다른 호출처럼 그 배포의 요율·쿨다운 회계에 참여하므로, 지속적으로 실패하는 판정자가 사용자 트래픽과 공유하는 배포를 쿨다운시킬 수 있어요. 판정자 호출 자체는 재시도와 표준 폴백이 비활성화된 채 진행되어 구성된 judge_model이 권위를 유지해요.

실패 동작 (Failure behavior)

가드레일은 판정자 오류에 fail open이에요. 판정자 호출이 실패하거나 파싱 불가능한 판정을 반환하면 경고가 기록되고, 가드레일 상태가 guardrail_failed_to_respond로 기록되며, 응답이 호출자에게 반환돼요. 일부 판정자 모델이 생성하는 Markdown 펜스 JSON 판정은 정상적으로 파싱되며 실패로 간주되지 않아요. 성공적으로 파싱된 임계값 아래 판정만 차단을 트리거해요.

지원 파라미터 (Supported params)

guardrails:
  - guardrail_name: string          # required, unique name
    litellm_params:
      guardrail: llm_as_a_judge     # required
      mode: pre_call | during_call | post_call  # required; pre_call and during_call judge the request, post_call judges the response
      judge_model: string           # required, proxy model name or provider model id
      criteria:                     # required, at least one entry, weights sum to 100
        - name: string
          weight: number            # percent share of the overall score
          description: string       # what the judge checks for this criterion
      overall_threshold: number     # optional, 0-100, default 80
      on_failure: block | log       # optional, default block
      default_on: boolean           # optional, run on every request without being requested per-call