패스 스루 엔드포인트의 가드레일
패스 스루 엔드포인트의 가드레일 (Guardrails on Pass-Through Endpoints)
LiteLLM 패스 스루 엔드포인트에서 가드레일 실행을 활성화할 수 있어요. 옵트인으로 켜고, org/team/key 레벨에서 자동 상속돼요.
출처: 문서
본문
개요 (Overview)
| 속성 | 세부 | 설명 |
|---|---|---|
| 설명 | 옵트인 활성화와 org/team/key 레벨 자동 상속으로 LiteLLM 패스 스루 엔드포인트에서 가드레일 실행 활성화 | |
| 지원 가드레일 | 모든 LiteLLM 가드레일 (Bedrock, Aporia, Lakera 등) | |
| 기본 동작 | 명시적으로 활성화하지 않으면 패스 스루 엔드포인트에서 가드레일은 비활성 |
빠른 시작 (Quick Start)
패스 스루 엔드포인트의 가드레일은 UI(권장) 또는 config 파일로 구성할 수 있어요.
UI 사용하기
1. Pass-Through 엔드포인트로 이동하기
Models + Endpoints → + Add Pass-Through Endpoint 클릭
Guardrails 섹션으로 스크롤해 적용할 가드레일을 선택하세요.
기본 동작
기본적으로 필드를 지정할 필요가 없어요. LiteLLM이 전체 요청/응답 페이로드를 JSON 덤프해 가드레일에 보내요.
2. 특정 필드 대상 지정하기 (선택)
전체 페이로드 대신 특정 필드만 검사하려면:
- 가드레일을 선택해요
- Field Targeting (Optional) 에서 각 가드레일의 필드를 지정해요
- 빠른 추가 버튼(
+ query,+ documents[*])을 쓰거나 커스텀 JSONPath 표현식을 입력해요 - Request Fields (pre_call) : 대상 API로 보내기 전에 검사할 필드
- Response Fields (post_call) : 대상 API의 응답에서 검사할 필드
예시: 위 스크린샷에서 query를 요청 필드로 설정해, 전체 요청 대신 query 필드만 가드레일에 보내요.
Config 파일 사용하기
1. 가드레일과 패스 스루 엔드포인트 정의하기
guardrails:
- guardrail_name: "pii-guard"
litellm_params:
guardrail: bedrock
mode: pre_call
guardrailIdentifier: "your-guardrail-id"
guardrailVersion: "1"
general_settings:
pass_through_endpoints:
- path: "/v1/rerank"
target: "https://api.cohere.com/v1/rerank"
headers:
Authorization: "bearer os.environ/COHERE_API_KEY"
guardrails:
pii-guard:
2. 프록시 시작하기
litellm --config config.yaml
3. 테스트 요청
curl -X POST "http://localhost:4000/v1/rerank" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"model": "rerank-english-v3.0",
"query": "What is the capital of France?",
"documents": ["Paris is the capital of France."]
}'
옵트인 동작 (Opt-In Behavior)
| 구성 | 동작 |
|---|---|
guardrails 미설정 |
실행되는 가드레일 없음 (기본) |
guardrails 설정 |
모든 org/team/key + 패스 스루 가드레일 실행 |
가드레일이 활성화되면 시스템은 다음을 모아 실행해요:
- Org 레벨 가드레일
- 팀 레벨 가드레일
- 키 레벨 가드레일
- 패스 스루 전용 가드레일
동작 방식 (How It Works)
아래 다이어그램은 클라이언트가 config.yaml에서 가드레일이 구성된 패스 스루 엔드포인트 /special/rerank에 요청을 보낼 때 무슨 일이 일어나는지 보여줘요.
패스 스루 엔드포인트에 가드레일이 구성되면:
- Pre-call 가드레일이 대상 API로 전달하기 전에 요청에 대해 실행돼요
request_fields를 지정했다면(예:["query"]) 그 필드만 가드레일에 보내요. 그렇지 않으면 전체 요청 페이로드가 평가돼요- 가드레일이 통과할 때만 요청이 대상 API로 전달돼요
- Post-call 가드레일이 대상 API의 응답에 대해 실행돼요
response_fields를 지정했다면(예:["results[*].text"]) 그 필드만 평가돼요. 그렇지 않으면 전체 응답이 검사돼요
info
패스 스루 엔드포인트 구성에서 guardrails 블록을 생략하거나 비워 두면 요청은 가드레일 흐름을 완전히 건너뛰고 대상 API로 직접 가요.
필드 레벨 대상 지정 (Field-Level Targeting)
전체 요청/응답 페이로드 대신 특정 JSON 필드를 대상으로 해요.
guardrails:
- guardrail_name: "pii-detection"
litellm_params:
guardrail: bedrock
mode: pre_call
guardrailIdentifier: "pii-guard-id"
guardrailVersion: "1"
- guardrail_name: "content-moderation"
litellm_params:
guardrail: bedrock
mode: post_call
guardrailIdentifier: "content-guard-id"
guardrailVersion: "1"
general_settings:
pass_through_endpoints:
- path: "/v1/rerank"
target: "https://api.cohere.com/v1/rerank"
headers:
Authorization: "bearer os.environ/COHERE_API_KEY"
guardrails:
pii-detection:
request_fields: ["query", "documents[*].text"]
content-moderation:
response_fields: ["results[*].text"]
필드 옵션
| 필드 | 설명 |
|---|---|
request_fields |
입력(pre_call)용 JSONPath 표현식 |
response_fields |
출력(post_call)용 JSONPath 표현식 |
| 둘 다 미지정 | 가드레일이 전체 페이로드에 실행 |
JSONPath 예시
| 표현식 | 일치 |
|---|---|
query |
query라는 단일 필드 |
documents[*].text |
documents 배열의 모든 text 필드 |
messages[*].content |
messages 배열의 모든 content 필드 |
구성 예시 (Configuration Examples)
전체 페이로드에 단일 가드레일
guardrails:
- guardrail_name: "pii-detection"
litellm_params:
guardrail: bedrock
mode: pre_call
guardrailIdentifier: "your-id"
guardrailVersion: "1"
general_settings:
pass_through_endpoints:
- path: "/v1/rerank"
target: "https://api.cohere.com/v1/rerank"
guardrails:
pii-detection:
혼합 설정의 여러 가드레일
guardrails:
- guardrail_name: "pii-detection"
litellm_params:
guardrail: bedrock
mode: pre_call
guardrailIdentifier: "pii-id"
guardrailVersion: "1"
- guardrail_name: "content-moderation"
litellm_params:
guardrail: bedrock
mode: post_call
guardrailIdentifier: "content-id"
guardrailVersion: "1"
- guardrail_name: "prompt-injection"
litellm_params:
guardrail: lakera
mode: pre_call
api_key: os.environ/LAKERA_API_KEY
general_settings:
pass_through_endpoints:
- path: "/v1/rerank"
target: "https://api.cohere.com/v1/rerank"
guardrails:
pii-detection:
request_fields: ["input", "query"]
content-moderation:
prompt-injection:
request_fields: ["messages[*].content"]