headroom: AI 에이전트가 읽는 토큰을 LLM 전에 최대 95% 줄이는 컨텍스트 압축 계층

읽을거리&정보공유
, , , , , ,
1

headroom: AI 에이전트가 읽는 토큰을 LLM 전에 최대 95% 줄이는 컨텍스트 압축 계층
headroom: AI 에이전트가 읽는 토큰을 LLM 전에 최대 95% 줄이는 컨텍스트 압축 계층1536×1024 258 KB

headroom 소개

headroom은 AI 에이전트가 읽는 모든 입력(도구 출력, 로그, RAG 청크, 파일, 대화 기록)을 LLM에 전달되기 전에 압축하는 컨텍스트 압축 계층입니다. 같은 답을 유지하면서 토큰만 줄이는 것을 목표로 하며, 저자들은 실제 에이전트 워크로드에서 60~95% 적은 토큰으로 동일한 결과를 얻었다고 보고합니다. 본 게시물에서는 headroom이 어떤 방식으로 컨텍스트를 압축하는지, 어떤 모드로 기존 도구에 끼워 넣는지, 그리고 정확도를 어떻게 유지하는지 정리합니다.

코딩 에이전트와 LLM 애플리케이션이 길어질수록 비용의 대부분은 컨텍스트 윈도우를 채우는 토큰에서 나옵니다. 검색 결과 100건, 장애 디버깅 로그, 코드베이스 탐색 결과처럼 반복적이고 장황한 입력이 그대로 모델에 들어가면 매 호출마다 같은 비용을 다시 지불하게 됩니다. headroom은 이 입력을 모델에 닿기 전에 가로채 내용 유형에 맞는 압축기를 적용하고, 원본은 로컬에 보관해 필요할 때 되돌릴 수 있게 합니다.

headroom은 별도 SaaS로 데이터를 보내지 않고 로컬에서 동작하는 것을 기본 설계로 삼습니다(local-first). 파이썬과 타입스크립트 라이브러리, 코드 변경이 필요 없는 프록시, MCP 서버, 코딩 에이전트를 감싸는 래퍼까지 여러 형태로 같은 압축 엔진을 제공해 기존 워크플로우에 맞는 방식을 고를 수 있습니다.

headroom의 동작 방식

headroom의 압축은 단일 알고리즘이 아니라 내용 유형에 따라 다른 압축기를 선택하는 라우팅 구조입니다. 핵심은 들어온 컨텍스트의 종류를 판별하는 ContentRouter 로, JSON·코드·산문 등 입력 유형을 감지해 알맞은 압축기로 보냅니다.

headroom의 토큰 압축 동작 예시

각 압축기는 담당하는 데이터 형태가 다릅니다. SmartCrusher는 JSON을, CodeCompressor는 AST(추상 구문 트리)를 기반으로 코드를, Kompress-base는 산문 텍스트를 압축합니다. Kompress-base는 Hugging Face에 공개된 kompress-v2-base 모델을 사용합니다. 여기에 더해 CacheAligner는 프롬프트 앞부분(prefix)을 안정화해 LLM 제공자의 KV 캐시가 실제로 적중하도록 돕고, CCR(reversible compression)은 원본을 로컬에 저장해 두었다가 모델이 headroom_retrieve 도구로 요청하면 되돌려 줍니다. 즉 압축이 비가역적으로 정보를 버리는 방식이 아니라, 필요할 때 복원할 수 있는 형태입니다.

headroom의 실제 절감 효과

저자들이 공개한 실제 에이전트 워크로드 측정 결과는 다음과 같습니다.

워크로드 압축 전 압축 후 절감률
코드 검색 (결과 100건) 17,765 1,408 92%
SRE 장애 디버깅 65,694 5,118 92%
GitHub 이슈 분류 54,174 14,761 73%
코드베이스 탐색 78,502 41,254 47%

토큰을 줄이면서도 정확도가 유지되는지는 표준 벤치마크로 검증합니다. 저자들이 보고한 수치에 따르면 수학 추론 벤치마크 GSM8K(N=100)에서 기준선과 headroom의 정확도는 0.870으로 동일했고(±0.000), 사실성 벤치마크 TruthfulQA에서는 0.530에서 0.560으로 오히려 +0.030 변화가 있었습니다. 재현 절차와 전체 방법론은 headroom 공식 벤치마크 문서에 정리되어 있습니다.

headroom 설치와 사용법

headroom은 파이썬과 Node 양쪽 패키지로 설치합니다. 파이썬은 3.10 이상이 필요합니다.

# Python
pip install "headroom-ai[all]"

# Node / TypeScript
npm install headroom-ai

설치 후에는 사용 환경에 맞춰 모드를 고릅니다. 코딩 에이전트를 그대로 감싸려면 wrap, 코드를 바꾸지 않고 어떤 언어에서든 쓰려면 프록시를 사용합니다.

# 코딩 에이전트를 감싸 실행 (Claude Code, Codex, Aider 등)
headroom wrap claude

# 코드 변경 없는 드롭인 프록시
headroom proxy --port 8787

애플리케이션 코드 안에서 직접 호출하려면 라이브러리 형태의 compress 를 사용합니다. MCP 클라이언트에서는 headroom_compress, headroom_retrieve, headroom_stats 도구를 통해 같은 기능을 호출할 수 있습니다.

from headroom import compress

compressed = compress(messages)

headroom wrap 은 Claude Code, Codex, Aider, Copilot CLI, OpenCode 등을 지원하며, Codex는 Claude와 메모리를 공유합니다. 지원 에이전트 목록과 각 연동 방식은 저장소의 README 호환성 매트릭스에서 확인할 수 있습니다.

headroom의 출력 토큰 절감

지금까지의 압축은 모델에 보내는 프롬프트를 줄이는 기능입니다. headroom은 모델이 써서 돌려보내는 출력 토큰도 프록시에서 줄일 수 있습니다. 장황한 서두나 이미 보여준 코드의 재출력, 단순 단계에서의 과도한 추론을 줄이는 방식으로, 시스템 프롬프트 끝에 간결하게 답하라는 지침을 덧붙이는 verbosity steering과, 도구 결과 이후 모델이 단순히 이어가는 차례에서 추론 강도를 낮추는 effort routing을 사용합니다.

export HEADROOM_OUTPUT_SHAPER=1     # 기본값은 꺼짐
headroom proxy --port 8787

출력 절감량은 모델이 실제로 무엇을 썼을지 알 수 없는 반사실(counterfactual) 값이므로, headroom은 임의의 숫자 대신 신뢰 구간을 포함한 추정치로 보고합니다. 대화의 10%를 압축하지 않는 대조군으로 남겨 측정값을 얻는 옵션(HEADROOM_OUTPUT_HOLDOUT=0.1)도 제공합니다.

headroom의 라이선스

headroom은 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

:books: headroom 공식 문서

:github: headroom GitHub 저장소

:hugs: Kompress-v2-base 모델 (Hugging Face)

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. :smiley:

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

2개의 좋아요
2

사내에 mcp server로 제공하는 경우, tool을 연결한 사용자가 (tool에 대해 충분히 이해하지 못한 상태에서) 과도한 contents를 요청하면 상당히 큰 토큰을 사용하는 경우가 있는데, 다른 안전 장치도 필요하겠지만 이 방법도 꽤 유용할 듯 하네요. 좋은 정보 감사합니다.

1개의 좋아요