토큰을 압축하여 LLM 비용 절감 - Headroom 핸즈온

Headroom이란

Headroom는 LLM 그 자체를 경량화하는 도구가 아니라, LLM에 보내는 컨텍스트 (Context)를 사전에 압축하여 입력 토큰 (Input Token) 양을 줄이기 위한 도구입니다.

특히 Claude Code, Codex, Cursor 등의 AI 코딩 에이전트 (AI Coding Agent)에서는 로그, 도구 출력, 검색 결과, RAG 결과, 대화 이력 등이 비대해지기 쉽습니다. Headroom는 이러한 LLM에 전달되기 전의 정보를 압축함으로써, 토큰 소비량과 API 비용을 절감하는 것을 목표로 하는 도구입니다.

Headroom의 CLI에서 각종 코딩 에이전트를 실행하는 방법도 있지만, 이번에는 Docker Compose를 사용하여 Headroom를 로컬 프록시 (Local Proxy)로 실행하는 구성을 소개합니다.

Docker Compose를 통한 실행

먼저, 다음과 같은 docker-compose.yml을 작성합니다.

services:
headroom:
image: ghcr.io/chopratejas/headroom:latest
...

HF_TOKEN은 docker-compose.yml에 직접 쓰지 않고, .env에 기재해 두면 다루기 쉽습니다.

HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GUI에 대하여

Headroom의 토큰 압축 효과를 확인하려면 GUI를 병용하는 것이 편리합니다.

다만, 제 환경에서는 headroom-gui 이미지를 그대로 사용하는 구성으로는 제대로 작동하지 않았기 때문에, 별도의 Dockerfile을 준비했습니다.

FROM node:22-alpine
RUN apk add --no-cache socat \
&& npm install -g headroom-gui
...

entrypoint.sh는 다음과 같이 합니다.

#!/bin/sh
set -eu
GUI_INTERNAL_PORT="${GUI_INTERNAL_PORT:-3000}"
...

최종적인 폴더 구성은 다음과 같습니다.

docker-headroom
├── docker-compose.yml
├── .env
...

준비가 되었다면, 다음 명령어로 실행합니다.

docker compose up -d

실행 후, GUI는 다음 URL에서 확인할 수 있습니다.

코딩 에이전트 측 설정

다음으로, 사용 중인 코딩 에이전트가 Headroom의 프록시를 통하도록 설정합니다.

Codex의 경우, config.toml에 다음과 같은 설정을 추가함으로써 OpenAI API 호환 엔드포인트 (Endpoint)로서 Headroom를 참조할 수 있습니다.

openai_base_url = "http://127.0.0.1:8787/v1"

Docker 컨테이너 외부에서 접속하는 경우에는 127.0.0.1:8787, 다른 컨테이너에서 접속하는 경우에는 http://headroom:8787/v1과 같이 실행 환경에 따라 주소를 변경해 주세요.

절감 효과 확인

설정이 완료되면, Codex 등의 코딩 에이전트를 평소처럼 실행하여 작업하는 것만으로도 Headroom를 경유하여 토큰 압축이 수행됩니다.

절감 효과는 headroom-gui의 대시보드에서 확인할 수 있습니다.

GUI에서는 주로 다음 항목들을 확인합니다.

• Tokens Saved: 실제로 절감된 토큰 수
• Active Savings: 압축 대상이 된 콘텐츠에 대한 절감률
• Input: Headroom로 들어온 입력 토큰 양
• By Strategy: 어떤 압축 전략 (Compression Strategy)이 사용되었는지
• Requests: Headroom를 통과한 요청 수
• Cache Hits: 캐시가 적용된 횟수

제 환경에서는 압축 대상 콘텐츠에 대해 약 6%, 전체적으로는 약 3% 정도의 절감이 이루어졌습니다.

이 수치만 놓고 보면, Headroom의 소개 사례나 벤치마크와 비교했을 때 다소 낮게 느껴집니다. 아마도 이번 사용 사례에서는 거대한 JSON, 구조화된 로그 (Structured Logs), 대량의 검색 결과, 긴 도구 출력 (Tool Output) 등 Headroom이 특히 잘 처리하는 입력값이 적었기 때문으로 보입니다.

반면, GUI 상에서는 요청 수와 캐시 히트 (Cache Hit)도 확인되었으므로 프록시 (Proxy)로서 정상적으로 동작하고 있었습니다. Headroom의 효과를 판단할 때는 단순히 실행이 되었는지 여부뿐만 아니라, 실제로 Tokens Saved가 증가하고 있는지, 어떤 전략 (Strategy)으로 압축되고 있는지를 확인하는 것이 중요합니다.

Headroom이 적합해 보이는 케이스

이번에 테스트한 범위 내에서는 일상적인 코딩 에이전트 (Coding Agent) 이용만으로는 절감 효과가 그리 크지 않았습니다.

하지만 다음과 같은 케이스에서는 더 큰 효과를 볼 수 있을 것 같습니다.

• 대량의 로그를 LLM에 전달할 때
• 큰 JSON 응답을 다룰 때
• grep이나 검색 결과를 대량으로 읽히게 할 때
• 테스트 결과나 에러 로그를 빈번하게 분석하게 할 때
• RAG나 문서 검색 결과를 많이 다룰 때
• 긴 대화 이력 (Conversation History)을 유지하며 에이전트를 구동할 때

특히 LLM에 전달하기 전의 정보량이 많을수록, Headroom과 같은 중간 프록시 (Intermediate Proxy)를 통한 압축의 이점은 커질 것으로 보입니다.

요약

Headroom은 LLM에 전달하는 컨텍스트 (Context)를 압축함으로써 토큰 소비량을 억제하기 위한 도구입니다.

Docker Compose를 사용하면 로컬 환경에 비교적 간단하게 프록시로 도입할 수 있습니다. Codex와 같이 OpenAI 호환 엔드포인트 (OpenAI-compatible Endpoint)를 지정할 수 있는 도구라면, 설정 변경만으로 Headroom을 경유하게 할 수 있습니다.

이번 검증에서는 전체적으로 약 3% 정도의 절감에 그쳤지만, GUI를 통해 압축 상황을 확인할 수 있어 어떤 입력에 대해 효과가 나타나는지 파악하기 쉽다는 점이 편리했습니다.

일반적인 대화나 가벼운 코딩 작업에서는 큰 절감을 기대하기 어려울 수도 있습니다. 반면 로그 분석, JSON 처리, 검색 결과 요약, RAG 연동 등 대량의 텍스트를 LLM에 전달하는 용도에서는 Headroom의 효과를 더 실감하기 쉬울 것입니다.

LLM 비용을 조금이라도 줄이고 싶거나, 코딩 에이전트의 토큰 소비량을 시각화하고 싶은 경우에는 한 번쯤 시도해 볼 가치가 있는 도구입니다.

Discussion