포스트

token-router : 클라우드 LLM 전송 전 로컬에서 필요한 라인만 추출하기

게시 업데이트
By Juho
12 분읽는 시간

목차

  1. 개요
  2. 세 가지 라우팅 모드
  3. 관심사의 분리 아키텍처
  4. 컨텍스트 절감 예시
  5. 설치와 사용
  6. 주요 설정 변수
  7. 주요 특징
  8. 결론
  9. Reference

개요

token-router는 대규모 로그, 소스 파일, 에이전트 지시사항 문서를 클라우드 AI 모델로 보내기 전에 로컬에서 필요한 라인만 추출하는 하이브리드 라우팅 시스템이다. 핵심 목표는 대규모 파일을 전체 전송하지 않고 관련 부분만 정확히 추출해 토큰 비용과 지연시간을 대폭 줄이는 것이다. 대규모 배포 로그나 장문의 소스 파일을 통째로 클라우드 모델에 보내면 토큰 비용이 급증하고 응답 지연도 커진다. token-router는 로컬 모델과 Python 라우터를 조합해 이 문제를 해결한다.

핵심 특성은 다음과 같다. 무손실 추출은 로컬 모델이 라인 좌표만 반환하고 라우터가 원본 파일에서 정확한 텍스트를 추출하는 방식이다. 쿼리 기반 라우팅은 query 옵션으로 사용자 의도를 반영한다. 결정론적 필터는 키워드, 구조 마커, 헤드/테일 프리뷰를 활용한다. 출력 상한선은 불필요한 초과 토큰을 방지한다.

세 가지 라우팅 모드

token-router는 입력 자료의 성격에 따라 세 가지 전문화된 라우팅 모드를 제공한다.

모드용도
error_log배포 로그, 스택 트레이스, CI 출력 최적화
heavy_code장문의 소스 파일 및 코드 조사
agent_context긴 에이전트 명령 참조 문서

각 모드는 입력 자료의 구조적 특성에 맞춘 필터링 전략을 사용한다. 로그는 스택 트레이스와 테일 라인 보존에, 코드는 쿼리 히트 주변 컨텍스트 보존에 최적화되어 있다.

관심사의 분리 아키텍처

token-router의 핵심은 검색, 추출, 추론이라는 서로 다른 작업을 분리한 아키텍처에 있다. 이 구조는 로컬 모델이 불완전한 요약기로 작동하는 위험을 방지한다.

세 단계 파이프라인

전체 처리는 세 단계로 나뉘며 각 단계의 책임이 명확히 구분된다.

단계담당역할출력
검색/분류로컬 Ollama관련 라인 좌표 찾기JSON 범위
증거 추출Python 라우터원본 파일 슬라이싱원본 텍스트
추론클라우드 LLM디버그, 설명, 패치고신뢰도 답변

검색 단계는 로컬 Ollama 모델이 담당하며 어떤 라인이 관련 있는지만 판단한다. 추출 단계는 Python 라우터가 원본 파일을 직접 슬라이싱한다. 추론 단계는 클라우드 LLM이 추출된 원본 텍스트를 받아 실제 디버깅과 설명, 패치를 수행한다.

무손실 라인 라우팅

이 시스템이 풀려는 문제는 작은 로컬 모델의 요약이 손실적이라는 점이다. 스택 프레임 하나, 들여쓰기, 에러 메시지 끝이 생략되면 진단 자체가 달라진다. 따라서 로컬 모델에게 요약을 맡기지 않고 라인 좌표만 반환하게 한다.

해결책의 흐름은 다음과 같다. 첫째, 파일을 로컬에서 스캔한다. 둘째, 로컬 모델이 라인 번호 범위만 반환한다. 셋째, 스크립트가 원본 파일에서 정확히 슬라이싱한다. 넷째, 클라우드 모델이 원본 텍스트를 그대로 수신한다.

라우팅 프로세스를 구체적으로 보면, 대규모 파일이 입력되면 로컬 Ollama 모델이 키워드와 쿼리를 매칭하고 의심스러운 코드 마커를 감지하며 구조적 헤드/테일 스캔을 수행한다. 그 결과 JSON 형식의 라인 범위가 반환된다. Python 라우터가 그 범위를 원본 파일에서 추출하고, 최종적으로 원본 텍스트만 클라우드 모델로 전송한다. 이 방식 덕분에 로컬 모델의 요약 오류가 추론 결과에 섞이지 않는다.

컨텍스트 절감 예시

무손실 라인 라우팅의 효과는 토큰 수 절감으로 직접 드러난다.

입력 자료입력 토큰출력 토큰감소율
대규모 인프라 로그41,71113199.69%
레거시 소스 파일7,5207099.06%

대규모 인프라 로그의 경우 41,711 토큰 입력이 131 토큰 출력으로 줄어 99.69% 감소했다. 레거시 소스 파일의 경우 7,520 토큰 입력이 70 토큰 출력으로 줄어 99.06% 감소했다. 클라우드 모델은 줄어든 분량의 원본 텍스트만 받으므로 비용과 지연시간이 크게 절감된다.

설치와 사용

사전 요구사항

token-router를 실행하려면 다음 환경이 필요하다.

요구사항내용
Python3.10 이상
Ollama설치 및 실행 상태
로컬 라우팅 모델gemma4:e2b-it-q4_K_M

로컬 라우팅 모델은 다음 명령으로 받는다.

1

ollama pull gemma4:e2b-it-q4_K_M

모드별 실행 명령

세 가지 모드는 각각 다음과 같이 실행한다. 환경변수로 로컬 모델의 컨텍스트 윈도우와 언로드 동작을 함께 지정한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 로그 분석 (error_log)
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
  python3 scripts/router.py error_log path/to/deploy.log \
  --query "database migration timeout"

# 소스 파일 조사 (heavy_code)
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
  python3 scripts/router.py heavy_code path/to/service.py \
  --query "token expiration"

# 에이전트 컨텍스트 (agent_context)
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
  python3 scripts/router.py agent_context path/to/agent-context/frontend.md \
  --query "frontend testing workflow"

query 옵션은 사용자의 의도를 라우팅에 반영하므로 추출 정확도를 높인다.

Codex Skill로 사용

token-router는 Codex Skill로 등록해 자연어로 호출할 수도 있다.

1
2

mkdir -p ~/.codex/skills
cp -R token-router ~/.codex/skills/token-router

등록 후에는 다음과 같이 자연어로 호출한다.

1

Use $token-router to analyze this large log with query "payment timeout"

주요 설정 변수

라우팅 동작은 환경변수로 세밀하게 조정할 수 있다.

변수기본값역할
OLLAMA_MODELgemma4:e2b-it-q4_K_M라인 라우팅용 로컬 모델
OLLAMA_NUM_CTX8192로컬 모델 컨텍스트 윈도우
OLLAMA_KEEP_ALIVE0s라우팅 후 모델 언로드
ROUTER_MAX_OUTPUT_LINES160클라우드 모델 수신 최대 라인
ROUTER_LOG_TAIL_LINES200대규모 로그에서 보존할 테일 라인
ROUTER_CODE_CONTEXT_LINES8쿼리 히트 주변 컨텍스트 라인

매우 작은 모델은 복잡한 로그나 밀집된 파일에서 유효하지 않은 JSON을 반환할 수 있다. 이 경우 더 큰 모델을 지정하면 신뢰성이 높아진다.

1
2
3

OLLAMA_MODEL=qwen2.5-coder:7b \
  python3 scripts/router.py error_log path/to/deploy.log \
  --query "database migration timeout"

주요 특징

token-router의 주요 특징을 정리하면 다음과 같다.

특징설명
세 가지 전문화 모드로그, 코드, 에이전트 지시사항
쿼리 기반 필터링사용자 의도를 라우팅에 반영
결정론적 사전 필터키워드, 구조 마커, 헤드/테일 프리뷰
무손실 추출요약 없이 원본 텍스트 그대로 추출
메모리 안전라우팅 후 모델 자동 언로드
회귀 테스트 지원픽스처 기반 테스트

라이선스는 MIT이다.

결론

token-router는 로컬 모델을 요약기가 아니라 라인 좌표 탐색기로 사용한다는 발상이 핵심이다. 로컬 모델이 어떤 라인이 중요한지만 판단하고, Python 라우터가 원본 파일에서 정확한 텍스트를 슬라이싱해 클라우드 모델로 보낸다. 이 무손실 라인 라우팅 덕분에 스택 프레임이나 에러 메시지가 손실되지 않으면서도 토큰 사용량을 99% 이상 줄일 수 있다. 대규모 로그와 소스 파일을 다루며 클라우드 LLM 비용과 지연시간을 줄이려는 경우에 실용적인 접근이다.

Reference

Ollama
Ollama LLM Python