pxpipe: 텍스트 컨텍스트를 PNG 이미지로 변환해 Claude Code 토큰을 줄이는 프록시

게시 2026/07/07 업데이트 2026/07/07

By Juho

6 분읽는 시간

개요

pxpipe는 Claude Code의 토큰 소비를 줄이기 위한 로컬 프록시다. 핵심 아이디어는 단순하다. 용량이 큰 텍스트 컨텍스트를 압축된 PNG 이미지로 변환한 뒤, Claude의 비전(vision) 능력을 활용해 읽게 만드는 것이다.

README에 따르면 이 방식으로 종단간(end-to-end) 청구 비용을 약 59~70% 낮출 수 있다고 한다. 코드나 JSON처럼 밀도가 높은 콘텐츠에서 특히 효과가 크다. 별도의 코드 수정 없이 투명한 프록시로 동작하기 때문에 기존 워크플로우에 그대로 끼워 넣을 수 있다.

동작 원리

pxpipe는 API 요청을 가로채서, 이미지로 바꿔도 되는 대량 콘텐츠를 이미지 페이지로 다시 써서(rewrite) 전송한다. 대상이 되는 것은 도구 실행 결과(tool results), 오래된 대화 이력(older history), 시스템 프롬프트다.

텍스트를 이미지로 바꾸는 이유

토큰 경제학이 이 접근의 근거다. 1928x1928 크기의 PNG 한 장에는 약 92,000자를 담을 수 있는데, 이때 소비되는 비전 토큰은 약 4,761개에 불과하다. 같은 분량을 텍스트로 보내면 약 25,000 텍스트 토큰이 필요하다. 즉 밀도가 충분히 높은 콘텐츠에서는 이미지로 보내는 편이 경제적으로 유리해지는 지점이 생긴다.

선택적 압축

pxpipe는 모든 것을 이미지로 바꾸지 않는다. 토큰 밀도가 높아 계산상 이득이 나는 콘텐츠에 대해서만 이미지화를 적용한다. 최근 대화 턴은 안전을 위해 텍스트 그대로 남겨두고, 오래된 대량 이력과 정적인 콘텐츠만 이미지로 바꾼다.

모델별 처리도 구분한다. Claude Fable 5와 GPT 5.6은 기본 지원 대상이다. 반면 Opus와 GPT 5.5는 정확도가 낮아 옵트인(opt-in) 방식으로만 사용할 수 있다.

설치와 사용

빠른 시작은 약 30초면 충분하다. 프록시를 띄우고, ANTHROPIC_BASE_URL 환경 변수를 프록시 주소로 지정한 뒤 Claude Code를 실행하면 된다.

  
npx pxpipe-proxy                           # 127.0.0.1:47821 에서 프록시 시작
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

실시간 모니터링용 대시보드는 http://127.0.0.1:47821/ 에서 확인할 수 있다. 프록시를 쓰지 않고 코드에서 직접 호출하는 라이브러리 모드(library mode)도 제공한다.

한계와 주의사항

pxpipe는 스스로 트레이드오프를 솔직하게 문서화하고 있다. 이 방식은 설계상 손실 압축(lossy)이다.

가장 중요한 한계는 밀도 높은 이미지 안의 정확한 문자열이 조용히 잘못 읽힐 수 있다는 점이다. 16진수(hex) 값 회상 테스트에서 Fable 5는 15개 중 13개를 맞혔지만, Opus는 15개 중 0개였다. 이 때문에 식별자를 글자 단위로 정확히 복원해야 하는 작업에서는 성능이 저하된다.

최근 대화 턴을 텍스트로 남겨두는 이유도 이 위험 때문이다. 안전을 위해 오래된 대량 이력과 정적 콘텐츠만 이미지로 처리한다.

측정 결과

벤치마크 결과를 정리하면 다음과 같다.

항목	결과
새로운 산술 연산 정확도	100%
요지(gist) 회상 정확도	100%
식별자 축자 회상	성능이 낮은 모델에서 저하
SWE-bench 파일럿	요청 압축 -65% 조건에서 10건 중 10건 성공

새로운 산술 문제와 요지 회상 과제에서는 100% 정확도를 보였다. 다만 축자(verbatim) 식별자 회상은 성능이 떨어지는 모델일수록 저하되었다. 실제 SWE-bench 파일럿에서는 요청 압축 -65% 조건에서 10건 중 10건을 성공했다.

결론

pxpipe는 LLM의 비전 능력을 비용 절감 수단으로 재해석한 도구다. 텍스트를 그대로 보내는 대신 이미지로 압축해, 밀도가 높은 콘텐츠에서 토큰 비용을 크게 낮춘다.

대신 손실 압축이라는 본질적 한계가 있다. 정확한 문자열 복원이 중요한 작업에서는 조용한 오독이 발생할 수 있으므로, 모델과 작업 성격에 맞게 선택적으로 적용하는 것이 핵심이다.

Reference

pxpipe GitHub

LLM