Paritok-4B-v1 딥다이브
— 토큰 청구서를 74~95% 깎는 4B 압축 모델

1한 줄 정체

Paritok은 "코딩 에이전트와 LLM 사이에 앉은 압축 통역사"다. 에이전트가 매 턴 LLM에 보내는 요청에는 방금 읽은 파일 전체, 방금 실행한 bash 출력, 지난 대화 수십 턴, 그리고 70개가 넘는 툴 정의(JSON 스키마)가 통째로 들어간다. 이 대부분은 실제 답을 내는 데 필요 없다. Paritok은 그 요청을 가로채 필요한 것만 남기고 나머지를 요약·생략한 뒤 올려보낸다. LLM은 훨씬 짧은 입력을 받고, 너는 짧아진 만큼 청구서를 덜 낸다.

2왜 주목받는가 — 에이전트 토큰 폭탄

2025~2026년 코딩 에이전트가 폭발적으로 퍼지면서 새로운 고통이 생겼다 — 토큰 청구서. 에이전트는 한 작업을 끝내려고 수백 번 LLM을 호출하고, 매번 "지금까지의 모든 파일 + 모든 출력 + 모든 대화"를 다시 통째로 밀어넣는다. 긴 세션에서 한 턴 입력이 3만 토큰을 넘기는 일이 흔하다. Paritok의 README는 이걸 정면으로 조준한다 — 10인 팀 3개월 프로젝트에서 입력 비용 $13,500 → $3,468, 약 1만 달러 절감(전형 74% 절감 가정)이라고 예시를 든다.

Paritok이 급부상한 이유는 "압축"이라는 오래된 아이디어에 세 가지 신선한 각도를 붙였기 때문이다.

① 범용 압축이 아니라 "코드 전용" 압축

기존 프롬프트 압축기(LLMLingua-2 등)는 일반 텍스트로 학습됐다. Paritok은 실제 코딩 에이전트 궤적 45,000건으로 학습해서, import 문·함수명·파일 경로·에러 클래스는 "비싼 값"으로 지키고 디버그 라인은 과감히 버린다. 같은 작업에서 gpt-4.1-mini 프롬프팅보다 약 2배 더 세게 압축하면서 정답률은 동급이라고 주장한다.

② 비파괴 게이트웨이 — 줄이되 지우지 않는다

압축의 공포는 "혹시 중요한 걸 버렸으면?"이다. Paritok은 압축된 조각마다 [REF:id] 태그를 달고, 원본은 로컬 섀도 스토리지에 보관한다. LLM이 원문이 필요하면 expand_context라는 가상 툴을 호출 → 미들웨어가 정확한 원문을 즉시 반환한다. 전송 구간에서만 손실이고, 필요할 때 완전 복구 가능이라는 설계다.

③ 완전 오픈 + 자체호스팅

가중치는 Apache 2.0, 4B라서 24GB GPU 한 장 또는 Ollama로 CPU/맥에서도 돈다(q4 ~2.5GB). SaaS 종속도, 압축기에 붙는 토큰당 별도 요금도 없다. 데이터 파이프라인까지 공개해 재현 가능하다고 강조한다.

벤치마크 — SWE-bench Verified

¹ 품질 유지율 = 압축기 정답률 ÷ 무압축 기준선 정답률. 높을수록 좋다. 즉 Paritok은 토큰을 절반 이하로 쓰면서 gpt-4.1-mini와 같은 정답 유지율을 냈다는 주장이다.

어떤 압축기와 비교되나

3기술 스택 전체 지도

Paritok은 한 저장소 안에 성격이 완전히 다른 두 세계가 같이 산다. (A) 사용자가 매일 돌리는 런타임(미들웨어+프록시)은 의존성이 극도로 가볍고, (B) 모델을 만드는 학습·데이터 파이프라인은 무거운 ML 스택이다. 이 분리를 이해하는 게 핵심이다.

① 런타임 코어 (paritok 패키지) — 가볍다

pyproject.toml의 기본 의존성은 딱 넷뿐이다. 사용자가 pip install paritok 할 때 이것만 깔린다.

• tiktoken — 토큰 수를 세는 인코더. 압축 전/후 토큰을 재서 절감량을 계산.
• click — paritok up, paritok proxy, paritok init 같은 CLI 명령 뼈대.
• pyyaml — paritok.yaml 설정 파싱.
• httpx — 압축 모델(Ollama)과 상위 LLM API(Anthropic/OpenAI)에 HTTP 요청을 던지는 클라이언트.

② 프록시 서버 (선택 확장 [proxy])

• starlette + uvicorn — 비동기 웹 서버. 포트 8080에서 에이전트 요청을 받아 압축 후 상위로 포워딩하는 paritok/proxy/server.py(1,291줄)의 엔진.
• sentence-transformers + numpy — 아래 임베딩 툴 선택용. 프록시엔 기본 포함(툴 선택이 기본 전략이라서).

③ 임베딩 기반 툴 선택 (프록시의 숨은 절약 포인트)

• BAAI/bge-small-en-v1.5 — MIT 라이선스, ~130MB의 작은 임베딩 모델. CPU에서 로컬로만 돈다. 70개 넘는 툴 스키마 중 지금 작업에 관련 있는 소수만 전체 스키마로 남기고 나머지는 스텁으로 대체. 첫 요청 때 한 번 워밍업(~10–15초), 이후 요청은 ~15ms.

④ 학습·데이터 파이프라인 (별도 requirements.txt) — 무겁다

모델을 직접 재현하려는 사람만 건드리는 영역. 전형적인 HuggingFace 미세조정 스택이다.

• transformers · datasets · huggingface-hub · accelerate — 모델 로딩·데이터·분산 학습 기반.
• trl — SFT(지도 미세조정) 트레이너. Paritok은 교사 모델의 압축 답을 모방하는 imitation loss로 학습.
• peft — LoRA 어댑터 학습(전체 40억 파라미터 대신 작은 어댑터만 학습해 GPU 절약).
• bitsandbytes — 8-bit AdamW 옵티마이저(메모리 절약).
• deepspeed — ZeRO-3 다중 GPU 학습(선택).
• vllm — 고속 추론/평가 단계 서빙. LoRA 어댑터를 OpenAI 호환 엔드포인트로 서빙.
• llmlingua · evaluate · bert-score · tree-sitter — 평가/비교용. tree-sitter는 압축 전후 코드의 AST 동등성 판정에 쓴다(정말 코드가 깨졌는지 확인).

4아키텍처 심화 — 프록시 4단계 파이프라인

Paritok을 이해하는 가장 좋은 방법은 "에이전트가 요청 하나를 던진 순간부터, 압축된 요청이 Anthropic에 도착하기까지"를 따라가는 것이다. 전체 그림은 이렇다.

1단계 — 툴 발견(tool discovery): 스키마 다이어트

코딩 에이전트는 MCP 서버까지 붙으면 매 요청에 70개+ 툴 정의(JSON)를 통째로 싣는다. 대부분은 지금 작업과 무관하다. tool_discovery.py는 사용자 의도를 임베딩해 가장 관련 있는 top-K(기본 5, 최대 8)만 전체 스키마로 남기고 나머지는 최소 스텁으로 바꾼다.

영리한 포인트는 프롬프트 캐시 친화다. 툴 선택은 대화당 한 번 고정(freeze)돼서, 턴이 바뀌어도 tools[] 블록이 바이트 단위로 동일 → LLM의 KV 캐시를 무효화하지 않는다. 스텁된 툴이 나중에 필요하면 gateway_search_tools로 되찾는다.

2단계 — 툴 출력 압축: 4B 모델이 판단

compress.py의 파이프라인은 각 tool_result(파일 읽기 결과, bash 출력 등)를 이렇게 처리한다.

1. 이미 압축됨?  ([REF:] 접두사면 건너뜀)
2. 토큰 게이팅   (min 512 미만이면 압축 안 함, max 50000 초과 청킹)
3. SHA256 캐시   (같은 내용 재등장 → 재압축 없이 기존 [REF] 재사용)
4. 4B 모델 호출  (Ollama에 "이 조각 압축해" 프롬프트)
5. 효과 검사     (refusal_threshold 0.05 미만이면 원본 유지)
6. 섀도 저장     (원본 보관 + [REF:id src=경로] 태그로 치환)

주목할 디테일: Claude Code의 Read 툴은 cat -n 스타일 줄번호( 1\t실제내용)를 붙인다. Paritok은 매칭 비교 때 이 줄번호 접두사를 정규화해 벗겨서, 같은 파일을 offset만 바꿔 다시 읽어도 동일 섀도로 인식(재압축 방지)한다.

3단계 — 히스토리 압축: 오래된 대화 접기

HistoryConfig는 최근 4턴은 원본 그대로 두고, 전체 컨텍스트가 창의 80%를 넘으면 그 이전 턴들을 한 번 요약한다. 긴 세션에서 "95% 절감"이 나오는 지점이 바로 여기 — 파일·툴 출력이 반복 누적된 옛 히스토리가 통째로 접힌다.

4단계 — 가상 툴 주입: 안전장치

미들웨어는 툴 목록에 실재하지 않는 두 개의 가상 툴을 몰래 끼워넣는다. LLM은 이걸 진짜 툴처럼 부르지만, 호출은 상위 API로 안 가고 프록시가 가로채 로컬에서 처리한다.

• expand_context(shadow_id) — [REF:abc123]의 원문 전체를 섀도 스토리지에서 즉시·정확히·로컬로 반환. 다시 Read/Grep 하는 것보다 빠르고 재압축도 없다.
• gateway_search_tools(query) — 1단계에서 스텁된 툴 스키마를 되찾음.

규칙 기반 안전망 — must-keep 정규식

모델 판단만 믿지 않는다. src/mustkeep.py는 하나의 거대 정규식으로 절대 버리면 안 되는 스팬을 스캔한다 — 파일 경로, 스택트레이스의 File "...", 줄번호, 커밋 해시, URL, XxxError/XxxException 같은 에러 클래스, snake_case·camelCase 식별자, 패키지명(numpy·torch…). 이 스팬들은 압축 대상에서 보호된다. "모델의 감각 + 규칙의 보증"을 겹쳐 함수명·경로 손실을 막는 이중 안전장치다.

5디렉토리 구조 해부

구조가 던지는 메시지는 분명하다. 왼쪽 위(paritok/)만 알면 도구를 쓸 수 있고, data_pipeline/·training/은 "우리가 어떻게 이 모델을 만들었는지 다 공개한다"는 투명성의 증거물이다. 특히 data_pipeline/review_app/(사람이 압축 결과를 눈으로 검수하는 Electron 앱)의 존재는, 데이터 품질을 손으로 관리했다는 신호다.

6학습 포인트 — 기술별 배울 것

① LLM 프록시/게이트웨이 패턴

이 프로젝트의 진짜 교재 가치는 "에이전트를 안 고치고 동작을 바꾸는 법"이다. ANTHROPIC_BASE_URL 하나만 바꿔 요청을 가로채고, 본문을 변형해 상위로 포워딩하고, 헤더(진짜 API 키)는 그대로 흘려보낸다. proxy/adapters/에서 Anthropic Messages·OpenAI Chat·OpenAI Responses 세 가지 와이어 프로토콜을 서로 변환하는 코드는, LLM 인프라를 짜는 사람에게 그대로 참고서가 된다.

② 작은 특화 모델 > 큰 범용 모델 (증류의 실전)

"gpt-4.1-mini에게 정답을 만들게 하고 4B가 흉내 낸다"는 교사 증류 + LoRA 파이프라인 전체(data_pipeline/ → training/)가 공개돼 있다. 데이터 수집 → 세그먼트화 → 교사 라벨링 → 필터/리밸런스 → SFT → 체크포인트 선택의 6단계를 그대로 읽을 수 있는, 흔치 않은 오픈 교재다.

③ 정규식 + LLM 하이브리드 설계

mustkeep.py는 "LLM은 감으로 압축하되, 규칙으로 핵심을 보증한다"는 방어적 설계의 좋은 예다. 순수 LLM도 순수 규칙도 아닌 겹layer 안전망 — 프로덕션 AI 시스템에서 자주 필요한 패턴이다.

④ 임베딩 기반 라우팅 + 캐시 인지 최적화

bge-small로 툴을 top-K 선택하는 tool_discovery.py는 로컬 임베딩으로 무엇을 컨텍스트에 넣을지 고르는 미니 RAG다. 여기에 "선택을 대화당 고정해 프롬프트 캐시를 안 깬다"는 비용 인지까지 얹혀 있어, 실전 토큰 경제학을 배우기 좋다.

7시스템 / 실행 요구사항

• 런타임 파이썬: 3.10+ (미들웨어). 학습 파이썬: 3.10~3.11 권장(flash-attn 이슈로 3.12+ 회피).
• full precision f16 모델은 ~8GB(더 많은 RAM/VRAM 필요). 기본 :latest는 q4_K_M(~2.5GB, 런타임 검증 대상).
• 학습 재현: 2×A100 80GB 또는 1×H100 80GB로 약 5시간, 교사 증류 API 비용 ~$300.
• 지연: 요청당 압축 오버헤드 ~300ms. 턴당 5,000토큰 미만이면 이득이 적다(장점 표에서 명시).
• Codex 주의: Codex CLI는 OPENAI_BASE_URL을 무시하고 ~/.codex/config.toml만 읽는다 → Paritok이 그 파일을 대신 써 준다(codex.enabled: true).

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

1주차 — LLM 토큰 경제학 & 프록시 기초

• 토큰이란 무엇인가, tiktoken으로 실제 세어 보기. 입력/출력 토큰 과금 구조.
• 프롬프트 캐싱(Anthropic/OpenAI)이 무엇이고 언제 이득인지 — 캐시 write 1.25배 / read 0.1배.
• 리버스 프록시 개념, BASE_URL 리다이렉션으로 클라이언트 안 고치고 가로채기.

2주차 — 컨텍스트 압축과 RAG의 경계

• LLMLingua/LLMLingua-2 논문 읽기 — 범용 프롬프트 압축의 원리와 한계.
• 임베딩 유사도 검색(bge-small), top-K 선택이 미니 RAG인 이유.
• "압축 vs 검색 vs 요약"의 차이 정리 — Paritok은 이 셋을 한 파이프라인에 섞었다.

3주차 — 미세조정: LoRA & 증류

• PEFT/LoRA 실습 — 작은 모델에 어댑터 하나 붙여 보기(rank·alpha 감 잡기).
• TRL의 SFTTrainer로 교사 정답 모방 학습, imitation loss 이해.
• 체크포인트를 벤치마크로 고르는 법 — Paritok은 SWE-bench Verified 서브셋으로 step 2000 선택.

4주차 — 에이전트 평가와 프로덕션 안전망

• SWE-bench Verified 하네스 구조 — "정답 유지율"이 왜 공정한 비교 지표인지.
• tree-sitter로 코드 AST 동등성 검사(압축이 코드를 깼는지 판정).
• 비파괴 설계·섀도 스토리지·가상 툴로 손실을 되돌리는 안전 패턴 정리.

10핵심 키워드 사전

11참고 링크

• GitHub: Paritok-official/paritok-4b-v1 — README·소스·데이터 파이프라인 전체.
• 모델 가중치: 🤗 paritok/paritok-4b-v1 (Qwen3-4B 위 LoRA 어댑터).
• 베이스 모델: Qwen/Qwen3-4B-Instruct-2507.
• 임베딩 모델: BAAI/bge-small-en-v1.5 (툴 선택용, ~130MB).
• 벤치마크: SWE-bench Verified — 평가에 쓰인 하네스.
• 비교 대상: LLMLingua-2 (Microsoft) — 범용 프롬프트 압축의 대표 오픈소스.
• 홈페이지: paritok.com (GPU 서버 호스팅·대시보드).