관련성 기반 압축

본문

동작 방식 (How it works)

가드레일은 pre_call 단계에서 프로세스 내에서 실행되며 TypeSafe의 호스팅 API(https://api.typesafe.ai)를 호출해요. 따라서 배포할 추가 서비스가 없어요. TypeSafe와 통신하는 것은 프록시뿐이에요. 요청 입력만 다시 작성되며 응답은 변경 없이 통과돼요.

압축은 완료된 도구 교환별로 일어나요.

요구사항 (Requirements)

typesafe 가드레일이 포함된 LiteLLM 빌드와 typesafe.ai의 TypeSafe API 키가 필요해요.

빠른 시작 (Quick Start)

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

model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

guardrails:
  - guardrail_name: jev-compaction
    litellm_params:
      guardrail: typesafe
      mode: pre_call
      api_key: os.environ/TYPESAFE_API_KEY
      optional_params:
        relevance_threshold: 0.2

가드레일이 요청 입력만 변환하므로 mode: pre_call을 사용해요. api_key는 필수이며 config 또는 TYPESAFE_API_KEY 환경 변수에서 가져올 수 있어요. 모든 요청을 압축하려면 default_on: true를 설정하고, 키별 또는 요청별로 압축을 선택(opt-in)하도록 하려면 끄고 두세요.

2. LiteLLM 게이트웨이 시작하기

litellm --config config.yaml

3. 요청 보내기

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Which filing discusses Q3 revenue?"},
      {"role": "assistant", "tool_calls": [{"id": "call_1", "type": "function", "function": {"name": "search_filings", "arguments": "{\"query\": \"Q1 revenue\"}"}}]},
      {"role": "tool", "tool_call_id": "call_1", "content": "<...tens of thousands of tokens of Q1 filing text...>"},
      {"role": "assistant", "tool_calls": [{"id": "call_2", "type": "function", "function": {"name": "search_filings", "arguments": "{\"query\": \"Q3 revenue\"}"}}]},
      {"role": "tool", "tool_call_id": "call_2", "content": "<...tens of thousands of tokens of Q3 filing text...>"}
    ],
    "guardrails": ["jev-compaction"]
  }'

주제에서 벗어난 Q1 결과는 비워지고, 작업에 필요한 Q3 결과는 그대로 통과해요.

키별 압축 활성화 (Enabling compaction per key)

default_on이 설정되지 않으면 압축은 선택한 요청에만 실행돼요. 일반적인 패턴은 가드레일을 가상 키에 연결하는 것이에요.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
        "guardrails": ["jev-compaction"]
      }'

요청별 압축 활성화 (Enabling compaction per request)

클라이언트는 요청 본문에 guardrails 배열을 전달해 단일 호출에서 선택할 수 있어요. top-level guardrails 필드가 없는 /v1/messages에서는 litellm_metadata.guardrails를 사용해요. 압축이 실행되면 응답에 x-litellm-applied-guardrails: jev-compaction 헤더가 포함돼요.

실패 의미론 (Failure semantics)

기본값은 fail_open이에요. TypeSafe 서비스에 접근할 수 없거나, 타임아웃(30초 예산)되거나, 잘못된 상태/본문을 반환하면 요청은 압축되지 않은 채 프록시 로그에 경고와 함께 전달돼요. 압축은 최적화이므로 평가기가 다운돼도 트래픽을 막지 않아요.

unreachable_fallback: fail_closed로 설정하면 요청을 500과 일반 오류 메시지로 실패시키는 대신 사용할 수 있어요. 업스트림 응답 본문은 서버 로그에 남고 클라이언트에는 절대 노출되지 않아요.

TypeSafe 실행 검증 (Validate TypeSafe ran)

구성 참조 (Configuration reference)

Top-level litellm_params:

파라미터	타입	설명
guardrail	str	반드시 `typesafe`여야 함
mode	str	`pre_call` 사용. 가드레일이 요청 입력만 변환하며 응답은 변경 없이 통과.
api_key	str	TypeSafe API 키, `Authorization: Bearer ***`로 전송. `TYPESAFE_API_KEY`로 대체. 필수.
api_base	str	TypeSafe API 기본 URL. `TYPESAFE_API_BASE`, 그다음 `https://api.typesafe.ai`로 대체.
model	str	TypeSafe 평가 모델(LLM 아님). 기본값 `jev-latest`.
unreachable_fallback	str	`fail_open`(기본값)은 서비스 실패 시 압축하지 않고 전달, `fail_closed`는 500 반환.
default_on	bool	호출별 옵트인 없이 모든 요청에서 실행. 기본값 `false`.

중첩 optional_params(각각 litellm_params 아래에도 직접 허용되며, 중첩 값이 우선):

파라미터	타입	기본값	설명
relevance_threshold	float	0.2	이 관련성 확률보다 낮게 점수가 매겨진 교환은 제거됨
min_chars_to_evaluate	int	200	결합 도구 결과 텍스트가 이보다 짧은 교환은 Jev로 보내지거나 제거되지 않음
max_result_chars_in_state	int	4000	Jev로 보내는 상태에서 도구 결과 텍스트를 이 문자 수로 잘라냄

환경 변수 (Environment variables)

변수	설명
TYPESAFE_API_KEY	`api_key`가 설정되지 않았을 때의 대체 API 키
TYPESAFE_API_BASE	`api_base`가 설정되지 않았을 때의 대체 API 기본

더 알아보기 (Learn more)

가드레일 문서

관련성 기반 압축