토큰 예산 건조 실행 CLI: 로컬 LLM의 컨텍스트 오버플로우 사전 감지

1. 왜 상주 서버 대신 CLI(건조 실행)인가?

LLM 프롬프트의 토큰 수를 검증하기 위해 거대한 웹 서버를 설정하는 것은 객관적으로 말이 안 됩니다. 우리가 실제로 필요한 것은 CI 워크플로우나 로컬 Git 훅에 직접 통합할 수 있는 경량 메커니즘입니다. 이는 커밋이나 빌드가 트리거되기 전에 우리의 토큰 예산을 즉시 검증할 수 있어야 합니다.

이 도구의 요구 사항은 엄격하게 정의되었습니다:

1. 대상 모델의 토크나이저를 지정된 입력 파일 세트와 시스템 프롬프트에 대해 로컬에서 즉시 실행합니다.
2. 파일별로 실제 토큰 수와 남은 예산을 계산하고 시각화하며, 밀리초 단위로 결과를 도출합니다.
3. 종속성 누락이나 잘못된 인수를 포함한 모든 예외적인 경우에도 구조화된 JSON 응답과 적절한 종료 코드(Exit Code 0 또는 1)를 보장합니다.

2. 개발 중 실질적인 문제점과 기술적 해결책

이 도구를 CI/CD 파이프라인에 통합할 때, 제가 직면했던 첫 번째 주요 장애물은 실용적인 충돌이었습니다: CLI 프레임워크의 기본 동작 방식 대 엄격한 JSON 출력의 필요성.

함정: argparse의 기본 오류 처리

Python의 표준 argparse 라이브러리는 의심할 여지 없이 강력하지만, 자동화된 파이프라인에는 치명적인 결함이 있습니다. 타입 변환 오류가 발생하거나(예: --max-tokens에 문자열을 전달하는 경우) 필수 인수가 누락되면, argparse는 표준 에러(stderr)로 일반 텍스트 오류 메시지를 자동으로 출력하고 sys.exit(2)를 통해 프로세스를 갑작스럽게 종료합니다.

자동화된 파이프라인이나 래퍼 스크립트에서 이 CLI를 호출할 때, 매번 구문 분석 실패 시 비정형적인 일반 텍스트를 받는 것은 다운스트림 오류 처리를 사실상 불가능하게 만듭니다. 저는 엄격한 계약을 강제해야 했습니다: 오류 유형에 관계없이, 도구는 기계가 읽을 수 있는 JSON으로 응답하고 예측 가능한 종료 코드로 종료되어야 합니다.

해결책: 명시적 예외 포착 및 강제 JSON 출력

이 기본 동작을 우회하기 위해, 저는 초기 argparse 파싱 단계에서 엄격한 타입 변환을 건너뛰도록 의도적으로 설계를 변경했습니다. 대신, 인수는 원본 문자열로 수신되어 수동 검증을 거칩니다. 더욱이, tiktoken과 같은 필수 종속성 임포트 실패를 포함하여 모든 비정상적인 흐름은 포괄적인 try-except 블록으로 감싸져 있습니다. 이를 통해 모든 실패는 프로세스를 종료하기 전에 통일된 JSON 출력 함수를 거치도록 보장합니다.

3. 프로덕션 준비 코드

아래에 최종화된 스크립트를 제시하며, 이 코드는 수많은 엣지 케이스를 처리하고 프로덕션 CI/CD 환경의 혹독함을 견딜 수 있는 수준으로 개선되었습니다.

import sys
import json
import argparse
...

💡 즉시 배포용: 이 아키텍처의 전체 소스 코드 스위트(ZIP)는 Gumroad에서 $0+ (원하는 만큼 지불)로 이용 가능합니다.

4. 실행 예시 및 CI 통합

터미널 환경에서 이 스크립트가 실행될 때의 동작을 살펴보겠습니다.

$ python token_budget_checker.py \
    --system-prompt "You are a senior code reviewer." \
    --max-tokens 4096 \
...

토큰 수가 지정된 예산 내에 머무르는 경우, 스크립트는 표준 출력(stdout)으로 구조화된 JSON을 출력하고 종료 코드 0을 반환합니다.

{
  "status": "PASS",
  "details": [
...

반대로, 토큰 수가 주어진 파일의 상한 임계를 초과하는 경우, 해당 상태는 `

로컬 LLM 개발에서 토큰 관리는 종종 제한 사항이 런타임에만 발견되는 불투명한 '블랙박스' 상태로 퇴보합니다. 하지만 전통적인 인프라를 관리하는 것과 마찬가지로, 소스 코드와 프롬프트의 비대화(bloat)는 **사전 빌드 정적 분석(dry-runs)**을 통해 사전에 감지하고 제어할 수 있습니다.

여기에 제시된 스크립트는 근본적으로 간단하지만, 이를 운영 파이프라인에 통합하면 LLM 워크플로우에 내재된 조용한 잘림 위험에 대한 강력한 방어책을 구축합니다. 인코딩 로직을 대상 모델(예: Llama, Mistral)과 일치하도록 대체함으로써, 특정 CI/CD 제약 조건에 맞게 이 아키텍처를 손쉽게 사용자 정의할 수 있습니다.

이 엔지니어링 로그가 여러분의 프로덕션 서버(그리고 정신 건강)를 구했다면, GitHub Sponsors에서 저희 아키텍처를 후원하는 것을 고려해 주세요.