프롬프트 압축

프롬프트 압축 (Headroom)

Headroom은 LLM 애플리케이션을 위한 컨텍스트 최적화 계층이에요. 도구 출력, 데이터베이스 결과, 파일 읽기, RAG 페이로드를 모델에 도달하기 전에 압축해서, 동일한 답을 훨씬 적은 토큰으로 얻을 수 있게 해요.

이 기능은 /v1/chat/completions와 /v1/messages(Anthropic 형식) 모두에서 사용할 수 있어요.

출처: 문서

본문

데모 (Demo)

아키텍처 (Architecture)

Headroom은 LiteLLM 옆에서 사이드카(sidecar) 서비스로 실행돼요. 클라이언트 트래픽은 평소처럼 LiteLLM 게이트웨이로 들어오고, LiteLLM은 pre_call 단계에서 프로세스 내에서 Headroom을 호출해 messages를 다시 작성한 뒤 압축된 페이로드를 업스트림 LLM으로 보내요. 클라이언트와 업스트림 LLM 프로바이더는 Headroom에 직접 통신하지 않아요.

요구사항 (Requirements)

LiteLLM v1.92.x 이상과 접근 가능한 Headroom 프록시가 필요해요. 아래 "Headroom 배포"에서 원파일 Dockerfile을 확인하세요.

안정 버전 이전에 테스트하려면 v1.92.0-dev.1 개발 릴리스를 사용하세요.

빠른 시작 (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: headroom-compression
    litellm_params:
      guardrail: headroom
      mode: pre_call
      api_base: https://your-headroom-service
#     api_key: os.environ/HEADROOM_API_KEY  [OPTIONAL]
#     default_on: true [OPTIONAL]

pre_call만 의미가 있으며 가드레일은 응답에서는 no-op이에요.

프록시를 통과하는 모든 요청을 압축하려면 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": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Summarize the prior conversation..."}
    ],
    "guardrails": ["headroom-compression"]
  }'

curl -i http://0.0.0.0:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Summarize the prior conversation..."}
    ],
    "litellm_metadata": {"guardrails": ["headroom-compression"]}
  }'

messages는 JSON 본문 {"messages": [...], "model": "<model>"}과 함께 {api_base}/v1/compress의 headroom 서비스로 전송돼요. 반환된 messages 목록이 LLM 호출 전에 요청 페이로드를 대체해요.

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

default_on이 설정되지 않으면 압축은 선택한 요청에만 실행돼요. 일반적인 관리자 패턴은 가드레일을 가상 키에 연결해, 해당 키를 사용하는 개발자가 클라이언트 코드를 바꾸지 않고도 자동으로 압축을 받게 하는 것이에요.

Headroom이 연결된 키 생성:

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

반환된 키로 만든 모든 요청은 LLM에 도달 전에 headroom-compression을 거쳐요. 기존 키에 연결하려면 같은 guardrails 필드로 /key/update를 사용하세요.

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

관리자 개입 없이 단일 호출에서 선택할 수 있어요.

요청 본문에 guardrails 배열 전달:

curl -i http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{ "model": "claude-sonnet-5", "messages": [...], "guardrails": ["headroom-compression"] }'

/v1/messages에는 top-level guardrails 필드가 없으므로 litellm_metadata로 선택해요:

curl -i http://0.0.0.0:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [...], "litellm_metadata": {"guardrails": ["headroom-compression"]} }'

호출자가 압축이 실제로 실행됐는지 확인할 수 있도록 응답에 x-litellm-applied-guardrails: headroom-compression 헤더가 포함돼요.

x-headroom-bypass는 항상 압축을 끄는 쪽으로만 동작

LiteLLM은 가드레일 코드가 헤더를 보기도 전에 특정 요청에서 headroom-compression 실행 여부를 결정해요. 그 결정은 config.yaml의 default_on, 가드레일이 호출자의 키·팀에 연결됐는지, 또는 위의 요청별 guardrails / litellm_metadata.guardrails 옵트인에서 나와요. 그 결정이 "실행"으로 나온 뒤에만 가드레일이 x-headroom-bypass를 확인하며, 바이패스로 처리하는 값은 리터럴 문자열 true뿐이에요(대소문자 무시). false, 빈 헤더, 헤더 없음 등 다른 모든 값은 효과가 없고 가드레일은 예정대로 계속 실행돼요.

구체적으로: default_on: false이고 호출자 키에 headroom-compression이 연결되지 않았다면, x-headroom-bypass: false를 보내도 해당 요청에 대해 압축이 켜지지 않아요. 그런 용도의 요청별 헤더는 존재하지 않아요. 요청별로 압축을 건너뛰는 것은 가능하며(x-headroom-bypass: true, 위 Claude Code 섹션과 같음), 관리자 개입 없이 요청별로 활성화하려면 헤더가 아니라 guardrails / litellm_metadata.guardrails 필드가 필요해요.

자동 라우터 뒤의 압축 (Compression behind an auto router)

자동 라우터가 처리하는 요청은 두 번의 호출을 하게 되는데, 하나는 요청 분류용, 하나는 라우팅 대상 모델용이에요. 기본적으로 둘 다 같은 압축 텍스트를 봐요. v1.101.0부터 라우터는 auto_router_routing_compression와 auto_router_model_compression으로 홉별로 압축 가드레일을 지정하거나 둘 다 없게 할 수 있어요. 둘 중 하나라도 설정하면 라우터가 자체 요청의 압축을 담당하게 되고, 위 가드레일들(키·팀·요청 본문에 연결된 것 포함)은 해당 요청에서 억제돼요. 자세한 내용은 압축 문서를 참고하세요.

Claude Code 사용법 (Claude Code usage)

가장 흔한 배포 시나리오예요. 플랫폼 관리자가 Claude Code로 트래픽이 많은 팀에서 각 개발자의 설정을 바꾸지 않고 입력 토큰 비용을 줄이고 싶어할 때 사용해요.

흐름은 세 단계로 이뤄져요.

관리자: config.yaml에서 Headroom을 등록해요. Quick Start에 표시된 대로 headroom-compression을 정의하고, 선택한 키만 압축을 받도록 default_on은 꺼두세요.

관리자: Headroom이 연결된 개발자별 키를 발급해요. 각 개발자는 가드레일이 바인딩된 가상 키를 받아요.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
        "key_alias": "claude-code-alice",
        "guardrails": ["headroom-compression"],
        "models": ["claude-sonnet-5"],
        "metadata": {"team": "claude-code-rollout"}
      }'

개발자: Claude Code를 프록시에 연결해요. 코드 변경은 필요 없어요. Claude Code는 환경의 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 읽어요.

export ANTHROPIC_BASE_URL="https://your-litellm-proxy.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-the...sued"

claude

이 시점부터 Claude Code가 만드는 모든 /v1/messages 요청은 Anthropic으로 전송되기 전에 Headroom이 압축해요. 개발자는 지출 로그의 토큰 사용량이 줄어드는 것 외에 행동 변화를 보지 못해요. 압축 실행 여부를 확인하려면 관리자가 해당 지출 로그 행의 guardrail_information을 살펴보거나, 응답 헤더에서 x-litellm-applied-guardrails: headroom-compression을 확인하면 돼요.

한 요청에서 압축을 건너뛰고 싶으면(예: 압축되지 않은 기준선과 비교), 그 호출에 x-headroom-bypass: true 헤더를 설정하면 돼요.

Headroom 실행 검증 (Validate Headroom ran)

Admin UI에서 Logs의 아무 요청을 열고 Guardrails & Policy Compliance 패널까지 스크롤하면, headroom-compression이 Request Lifecycle에 사전 호출 단계로 지연 시간과 함께 나열되어 있고 Evaluation Details 아래에도 항목이 있는 것을 볼 수 있어요.

Headroom 배포 (Deploy Headroom)

headroom 프록시를 배포하기 위한 Dockerfile이에요.

FROM python:3.13-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential \
    && pip install --no-cache-dir "headroom-ai[proxy]==0.27.0" \
    && apt-get purge -y build-essential \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*

EXPOSE 8787
ENV HEADROOM_TELEMETRY=off
CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]

requests_compressed가 0일 수 있는 이유

Headroom은 기본적으로 두 가지 메시지 유형을 보호하는데, 이는 LiteLLM의 config.yaml이 아니라 Headroom 컨테이너 자체에 설정돼요.

구성 참조 (Configuration reference)

파라미터	타입	설명
guardrail	str	반드시 `headroom`이어야 함
mode	str	`pre_call` 사용. 응답에서는 no-op.
api_base	str	headroom 서비스의 기본 URL. `HEADROOM_API_BASE` 환경 변수로 대체. 필수.
api_key	str	headroom 서비스용 Bearer 토큰. `HEADROOM_API_KEY`로 대체. 선택.
model	str	`/v1/compress`로 전달되는 모델 이름. 기본값은 요청의 model 필드.
default_on	bool	호출별 옵트인 없이 모든 요청에서 가드레일 실행. 기본값 `false`.

환경 변수 (Environment variables)

변수	설명
HEADROOM_API_BASE	가드레일 config에 `api_base`가 없을 때의 대체값
HEADROOM_API_KEY	가드레일 config에 `api_key`가 없을 때의 대체값

더 알아보기 (Learn more)

가드레일 문서