프롬프트 압축

프롬프트 압축 (Prompt Compression, compress())

이 기능은 베타입니다. API와 동작은 정식 출시 전에 바뀔 수 있습니다.

completion() 을 호출하기 전에 긴 대화 히스토리를 줄이려면 litellm.compress() 를 사용하세요.

이 함수는 관련성 높은 최근 컨텍스트를 유지하고, 낮은 관련성 콘텐츠를 가벼운 스텁으로 대체하며, 모델이 필요할 때만 전체 콘텐츠를 요청할 수 있도록 검색(retrieval) 도구를 반환합니다.

암호화(서버 측)가 외부 서비스에 의해 처리되길 원하는 프록시 사용자는 Headroom 을 참고하세요.

빠른 시작

import litellm
from litellm.types.utils import CallTypes

messages = [
    {"role": "system", "content": "You are a coding assistant."},
    {"role": "user", "content": "# auth.py\n" + "def authenticate():\n    pass\n" * 2000},
    {"role": "user", "content": "# utils.py\n" + "def helper():\n    pass\n" * 2000},
    {"role": "user", "content": "Fix the bug in auth.py"},
]

compressed = litellm.compress(
    messages=messages,
    model="gpt-5.6-terra",
    call_type=CallTypes.completion,
    compression_trigger=1000,
    compression_target=500,
)

response = litellm.completion(
    model="gpt-5.6-terra",
    messages=compressed["messages"],
    tools=compressed["tools"],
)

반환 내용

compress() 는 다음을 포함한 사전을 반환합니다:

• messages : 압축된 대화 메시지
• original_tokens : 압축 전 토큰 수
• compressed_tokens : 압축 후 토큰 수
• compression_ratio : 제거된 토큰의 비율
• cache : 스텁 키 → 원래 전체 콘텐츠의 키-값 매핑
• tools : 주문형 복원을 위한 검색 도구 정의 (litellm_content_retrieve)

출처: 문서

본문

파라미터

• messages ( List[dict] , 필수): 입력 대화 메시지
• model ( str , 필수): 토큰 카운팅에 사용되는 모델 이름
• call_type ( CallTypes , 기본 CallTypes.completion): 이 메시지들이 따르는 LiteLLM 호출 타입. 지원 값: CallTypes.completion / CallTypes.acompletion (OpenAI chat-completions 형태) 및 CallTypes.anthropic_messages (Anthropic Messages 형태)
• compression_trigger ( int , 기본 200000): 입력 토큰 수가 이를 초과할 때만 압축
• compression_target ( Optional[int] , 기본 compression_trigger 의 70%): 압축 후 원하는 토큰 예산
• embedding_model ( Optional[str] ): 설정하면 BM25 + 임베딩 관련성 점수를 결합
• embedding_model_params ( Optional[dict] ): litellm.embedding() 에 전달되는 추가 kwargs
• compression_cache ( Optional[DualCache] ): 임베딩 점수에 사용되는 선택 캐시

동작 참고

• compression_trigger 보다 작은 메시지는 변경 없이 통과합니다.
• 시스템 메시지, 마지막 user 메시지, 마지막 assistant 메시지는 항상 보존됩니다.
• 관련 메시지가 남은 예산에 완전히 맞지 않으면 compress() 는 잘린 버전을 유지할 수 있어요.
• 압축된 콘텐츠는 절대 손실되지 않으며, cache에 저장되고 litellm_content_retrieve 로 주소 지정할 수 있습니다.

검색 도구 호출 처리

모델이 litellm_content_retrieve 를 호출하면 compressed["cache"] 에서 요청된 키를 찾아 그 값을 도구 출력으로 반환하세요.

import json

tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
full_content = compressed["cache"][args["key"]]

서버 측 콜백 루프 (/v1/messages)

Anthropic Messages 호출에 대해 검색 루프를 투명하게 만들기 위해 콜백 기반 압축 가로채기를 활성화할 수 있어요:

litellm_settings:
  callbacks: ["compression_interception"]
  compression_interception_params:
    enabled: true
    compression_trigger: 10000
    compression_target: 7000

활성화되면 LiteLLM이 다음 서버 측 흐름을 실행합니다:

1. 첫 프로바이더 호출 전에 인바운드 메시지 압축
2. litellm_content_retrieve 도구 주입
3. 모델 응답에서 검색 tool_use 블록 감지
4. 압축 캐시에서 검색 키 해석
5. 에이전틱 루프로 모델 재실행 후 최종 답변 반환

성능

SWE-bench Lite(문제당 ~27k 토큰의 BM25 검색 저장소 컨텍스트를 가진 실제 GitHub 이슈)에서 벤치마크됨.

Claude Opus: 문제 5개, trigger=10k

핵심 요점:

• 파일 수준 타게팅이 완전히 보존됨 — 모델은 압축 유무와 관계없이 같은 파일을 편집합니다.
• 콘텐츠 유사도가 기준선과 일치 — 실제 변경된 줄은 비슷합니다.
• Hunk 오버랩은 약간 하락(-0.221). 모델은 올바른 파일을 대상으로 하지만 주변 컨텍스트가 적어 약간 다른 줄 범위를 편집할 수 있어요.
• 72% 비용 절감, 78% 토큰 감소.

지표 설명

SWE-bench 평가 실행

# 5-problem quick check
python tests/eval_swe_bench.py --model claude-opus-5 --problems 5

# Custom trigger/target
python tests/eval_swe_bench.py --model gpt-5.6-terra --problems 20 \
    --compression-trigger 15000 --compression-target 10000

# With embedding scoring
python tests/eval_swe_bench.py --model gpt-5.6-terra --problems 10 \
    --embedding-model text-embedding-3-small

HumanEval 스타일 평가 실행

python scripts/eval_compression.py --model gpt-5.6-terra --problems 5

더 알아보기 (Learn more)

• Chat Completions
• Message Trimming
• Prompt Caching