로컬 LLM 속도 높이기: Headroom으로 에이전트 컨텍스트 95% 압축해 도구 응답 지연 해소

Ollama, DeepSeek, Llama를 Agent 프레임워크에 연결해 monorepo 전체를 읽히면 UI가 3~8분 동안 멈춥니다——크래시가 아니라 도구 JSON이 프리필을 짓누르는 것입니다. Mac mini M4에 16~32GB 통합 메모리를 쓰는 로컬 모델은 한 턴에 4만~8만 token의 npm test 출력, SQL 덤프, ripgrep 결과가 들어오면 한계에 부딪힙니다. 클라우드 API는 사용량만큼 과금하고, 로컬 GPU는 바이트마다 어텐션 연산으로 실제 시간을 소모합니다.

Headroom은 콘텐츠가 모델에 들어가기 전에 도구 출력, 로그, RAG 청크를 압축합니다——공개 워크로드에서는 SRE 트레이스 92%, 코드 검색 73~92% 축소가 보고되었습니다. 이 Type A 튜토리얼은 Ollama OpenAI 호환 API 앞에 Headroom을 배선해 Agent 도구는 그대로 두고, 모델에는 50k token 더미 대신 5k token 뷰만 넘깁니다. 클라우드 게이트웨이 비용 제어는 OpenClaw + Headroom 프록시, 제로 API 로컬 트레이딩 스택은 Ollama의 TradingAgents를 참고하세요.

고지: MacHTML은 선택적 클라우드 Mac mini 임대를 제공합니다. 이 매뉴얼은 Ollama가 설치된 모든 로컬 macOS 또는 Linux 호스트에 적용됩니다.

큰 도구 출력에서 로컬 Agent가 「멈춘 것처럼」 보이는 이유

Apple Silicon에서 로컬 LLM 프리필 지연은 대체로 컨텍스트 길이에 선형입니다——CI 로그 전체를 넣어도 30 tok/s의 「무한 컨텍스트」 마법은 없습니다. 운영자가 멈춤으로 오인하는 증상은 다음과 같습니다.

증상	가능한 원인	Headroom 레버
2MB 로그 read_file 후 계속 스피너	단일 도구 메시지에 5만+ token	SmartCrusher / LogCompressor
첫 턴은 빠르고 5턴째 멈춤	다턴 도구 컨텍스트 눈덩이	CCR + IntelligentContext 폐기
16GB Mac mini 메모리 압박·스왑	KV 캐시 + 거대 prompt	프리필 token 60~95% 축소
「GPT-4o에서는 문제없었음」	클라우드 모델이 더 넓고/실리콘이 더 빠름	로컬은 압축 + 더 작은 유효 컨텍스트 필요

인용 가능: Mac mini급 하드웨어에서 Agent 트래픽을 127.0.0.1:8787의 Headroom을 거쳐 11434의 Ollama로 내면 도구 집약 prompt를 60~95% 줄이고, 원시 로그로는 불가능했던 1분 미만 도구 턴을 회복할 수 있습니다.

외부 참고: Headroom GitHub, 프록시 문서, Ollama API.

압축 레이어 아키텍처

┌──────────────┐  工具 JSON/日志   ┌─────────────────────┐  压缩后      ┌─────────────┐
│ Agent        │ ────────────────► │ Headroom 代理       │ ───────────►│ Ollama      │
│ (OpenClaw、  │  OPENAI_BASE_URL  │ :8787               │  聊天 API    │ :11434/v1   │
│  LangGraph、 │  = localhost:8787 │ SmartCrusher + CCR  │              │ llama3 等   │
│  Aider…)     │                   │                     │              │             │
└──────────────┘                   └─────────────────────┘              └─────────────┘

Headroom 프록시는 OpenAI 호환 /v1/chat/completions를 제공합니다——Ollama와 같은 인터페이스입니다. Agent 클라이언트를 Headroom에 두고, Headroom이 압축한 뒤 Ollama 업스트림 URL로 전달합니다. MacHTML 서울 노드에서도 동일 배선으로 Agent 측 OPENAI_BASE_URL만 127.0.0.1:8787로 바꾸면 동작합니다.

단계별 실전 (Ollama + Headroom)

1. 호스트 기준 Ollama

ollama --version
ollama pull llama3.2:3b          # 或 deepseek-r1:7b、qwen2.5-coder 等
curl -s http://127.0.0.1:11434/api/tags | python3 -m json.tool

메모리에 맞는 모델을 고르세요. 16GB Mac mini Agent 루프에는 3B~8B가 적합합니다. 14B+는 여유 KV를 위해 32GB 이상을 권장합니다.

2. Headroom 프록시 스택 설치

python3 --version   # 3.10+
pip install "headroom-ai[proxy]"
headroom --version

3. Headroom 시작 및 Ollama 지정

export OPENAI_API_KEY=ollama-local
export OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1
headroom proxy --host 127.0.0.1 --port 8787 \
  --log-file ~/.headroom/ollama-agent.jsonl

검증:

curl -s http://127.0.0.1:8787/health | python3 -m json.tool

4. Agent SDK를 Headroom에, Ollama 직결 금지

export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=ollama-local

OpenClaw 로컬 모델——~/.openclaw/.env에서 설정합니다. 진입 모드는 OpenClaw + Ollama Webhook과 함께 쓸 수 있습니다.

5. 커스텀 Python Agent 라이브러리 모드

from headroom import compress
import ollama

messages = [...]  # 含臃肿 tool 角色
result = compress(messages, model="llama3.2")
response = ollama.chat(model="llama3.2", messages=result.messages)
print(response["message"]["content"])

HTTP를 직접 구성 중이면 라이브러리 모드로 프록시 포트 충돌을 피할 수 있습니다.

6. 압축 전 도구 페이로드 제한 (이중 안전장치)

rg -n "ERROR" logs/ | head -n 200

cat logs/build.log보다 낫습니다. Headroom이 거친 Skill도 구할 수 있지만, 200행 상한이 16GB 호스트 최악 지연을 묶습니다.

7. 절감량·지연 측정

curl -s http://127.0.0.1:8787/stats | python3 -m json.tool

턴마다 tokens_before, tokens_after, 실제 시간을 기록하세요. 첫 저장소 감사 목표는 50% 이상 축소입니다. JSON/검색류 도구 덤프는 60~90%가 흔합니다.

8. 선택 MCP: Claude Code + 로컬 Ollama 사이드카

headroom mcp install

로컬 모델을 다른 터미널에서 돌릴 때 MCP headroom_stats를 쓸 수 있습니다——클라우드 Hermes 기억 압축과 로컬 Headroom을 섞을 때 유용합니다.

9. launchd로 프록시 상시화 (상시 가동 Mac mini)

~/Library/LaunchAgents/ai.headroom.ollama.plist를 만들고 OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1을 설정한 뒤 Agent 게이트웨이보다 먼저 로드하세요. Ollama는 별도 LaunchAgent입니다. 기동 순서: Ollama → Headroom → Agent.

10. 모델 변경 후 회귀 점검

ollama pull로 새 태그를 받은 뒤 비대한 도구 픽스처를 다시 실행하세요. 수치화가 압축을 대체하지 않습니다——컨텍스트 길이가 여전히 프리필을 지배합니다.

Mac mini 벤치마크 패턴

픽스처	원시 token (전형)	Headroom 후 (전형)	실제 시간 목표
실패 스위트 npm test stderr	2.5만~4.5만	3k~8k	M4 16GB 프리필 <45초
find . -name '*.ts' 목록	1.5만~3만	2k~5k	<30초
단일 500KB JSON API 덤프	4만~7만	4k~10k	<60초

각 픽스처를 프록시 우회(x-headroom-bypass: true 헤더)로도 한 번 돌려 없앨 멈춤을 기록하고 팀 wiki에 남기세요.

문제 해결

Agent가 여전히 11434 직결

현상: Headroom /stats 요청 수가 0.

수정: 프로세스 환경 확인 (ps eww -p $(pgrep -f your-agent)). Agent 프로세스의 OPENAI_BASE_URL은 http://127.0.0.1:8787/v1이어야 하며, 셸 설정만으로는 부족합니다.

프록시 경유 Ollama 404 모델 없음

현상: Headroom 로그에 업스트림 404.

수정: 채팅 요청 모델명은 ollama list와 일치해야 합니다. 먼저 로컬 pull. Headroom은 모델 파일을 관리하지 않습니다.

압축이 필요한 스택 줄 삭제

현상: 감사에서 행 번호 누락.

수정: Skill에서 CCR 검색 활성화(「스택 불완전 시 headroom_retrieve 호출」) 또는 단일 턴 우회. 전역 압축 끄지 마세요.

Mac mini 스왑으로 사실상 정지

현상: Agent 실행 중 memory_pressure 위험.

수정: 더 작은 양자화(:q4_0), 병렬 도구 축소, Headroom 추가. 16GB에서 14B + 8만 원시 컨텍스트 동시 실행 피하세요.

자주 묻는 질문

Headroom은 OpenAI 클라우드 전용인가요?

아닙니다. 프록시는 압축 후 임의 OpenAI 호환 업스트림——Ollama, 로컬 vLLM, 클라우드——로 전달합니다. OPENAI_TARGET_API_URL을 로컬 서비스로 두면 됩니다.

95% 압축이 현실적인가요?

일부 Agent 워크로드 공개 최대 92%입니다. 혼합 저장소에서는 60~80%가 흔합니다. /stats로 실측하세요——매 턴 마케팅 상한을 가정하지 마세요.

GPU 과열 완화에 도움이 되나요?

거대 원시 prompt 대비 프리필 작업량 감소로 발열은 줄어듭니다——다만 지속 도구 루프는 CPU/GPU를 계속 씁니다. Mac mini에서는 powermetrics를 보세요.

Headroom과 Hermes trajectory_compressor 차이는?

Hermes는 긴 대화 기억을 축소합니다. Headroom은 HTTP/라이브러리 계층에서 도구·RAG 페이로드를 축소합니다. 클라우드·로컬 혼용 시 둘 다 쓸 수 있습니다.

클라우드 Anthropic을 쓸 때도 Headroom이 필요한가요?

비용 제어용으로는 선택입니다. 로컬 모델은 쓸 만한지 멈춤인지 갈라지는 경우가 많습니다. 프로바이더 혼용은 클라우드 OpenClaw Headroom을 참고하세요.