AI 튜토리얼

Verdict로 CLI 결과를 로컬에서 분류하기

Verdict를 설치하고 Python 또는 CLI를 통해 명령 출력 결과를 분류하는 방법, 네 가지 결과 레이블을 해석하는 방법, 결정적 검증을 대체하지 않고 로컬 197KB 모델을 코딩 에이전트와 CI 워크플로에 통합하는 방법을 알아보세요.

2026년 11월 4일약 10분 소요

Verdict의 기능

Verdict는 코딩 에이전트, CI 실행기 및 기타 도구를 사용하는 시스템을 위한 의미 기반 결과 계층의 연구 미리보기입니다. 프로세스 종료 코드를 결정적인 증거로 취급하는 대신 명령, 종료 코드, 표준 출력 및 표준 오류를 함께 검토합니다.

모델은 success, failure, blocked, unknown 네 가지 레이블 중 하나를 반환합니다. 이 구분은 유용합니다. 예를 들어 명령이 종료 코드 0으로 끝났더라도 실제로 테스트를 실행하지 않았거나, HTTP 500 응답을 반환했거나, 작업자를 기다리고 있거나, 불완전한 출력을 생성했을 수 있습니다. 반대로 0이 아닌 종료 코드는 어설션 실패가 아니라 환경 차단을 의미할 수도 있습니다.

중요: Verdict는 참고용 분류기입니다. 작업이 완료되었거나 환경이 의도한 대로 변경되었다는 사실을 입증하지는 않습니다. 결정론적 검사와 권위 있는 상태 검증을 기준 정보로 유지하세요.

주요 기능

로컬 추론: 입력은 네트워크 호출이나 텔레메트리 없이 로컬 CPU에서 처리됩니다.
초소형 모델: 양자화된 모델의 크기는 약 197 KB입니다.
종속성 없는 런타임: 추론에는 Python 표준 라이브러리가 사용되며, 패키지 자체 외에 토크나이저 파일, GPU 또는 Python 런타임 종속성이 필요하지 않습니다.
의미 기반 분류: 모델은 종료 코드에만 의존하지 않고 명령, 종료 코드, 표준 출력 및 표준 오류를 고려합니다.
빠른 예측: 저장소에 따르면 문서화된 Windows 11, AMD64 및 Python 3.12 벤치마크 환경에서 추론 시간 중앙값은 0.54 ms입니다.
Python 및 CLI 인터페이스: 애플리케이션에서 모델을 사용하거나 셸 파이프라인에서 직접 사용할 수 있습니다.
브라우저 데모: 프로젝트 페이지는 로그를 업로드하지 않고 브라우저에서 동일한 양자화 가중치를 실행합니다.

Verdict는 해시된 문자 3–5-그램과 단어 1–3-그램을 다중 클래스 로지스틱 회귀와 함께 사용합니다. 입력은 UTF-8 텍스트이며, 각 출력 스트림은 명시적인 앞부분 및 뒷부분 클리핑을 통해 12,288자로 제한됩니다.

네 가지 레이블 이해하기

success: 출력에 작업이 완료되었다는 긍정적인 증거가 포함되어 있습니다.
failure: 작업이 실행되었으며 구체적인 실패를 보고했습니다.
blocked: 권한, 종속성, 네트워크, 할당량 제한 또는 환경 때문에 실행되지 못했습니다.
unknown: 증거가 없거나 불완전하거나, 건너뛰었거나, 드라이 런으로 제한되었거나, 그 밖에 결론을 내리기 어렵습니다.

반환되는 확률은 선형 다중 클래스 모델에서 계산됩니다. 안전이 중요한 의사 결정에서 이를 보정된 신뢰도로 해석해서는 안 됩니다.

Verdict 설치

저장소를 복제하고 해당 디렉터리로 이동한 뒤 pip로 패키지를 설치합니다.

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

이 명령은 verdict_tiny Python 패키지와 verdict 명령줄 인터페이스를 설치합니다.

첫 번째 Python 예측 실행

Verdict 인스턴스를 만들고 도구 실행기가 관찰한 것과 동일한 증거를 전달합니다. 다음 예제는 실제로는 테스트를 실행하지 않은 성공적인 pytest 프로세스를 나타냅니다.

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

문서화된 모델 출력은 종료 코드가 0임에도 이 증거를 unknown으로 분류합니다.

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

label은 선택된 결과입니다. probabilities 객체는 모든 클래스의 점수를 제공하며, advisory는 이 예측이 권위 있는 증명이 아님을 강조합니다.

명령줄에서 Verdict 사용

원래 명령과 종료 코드를 함께 지정하면서 명령 출력을 Verdict로 파이프할 수 있습니다.

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

이미 파일에 저장된 출력에는 --stdout 및 --stderr를 사용합니다.

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

특정 위치에서 가중치를 불러올 수도 있습니다.

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

안전하게 Verdict 통합하기

실용적인 통합에서는 Verdict를 최종 판정자가 아니라 추가적인 의사 결정 신호로 취급해야 합니다. 코딩 에이전트나 CI 실행기는 레이블을 사용해 추가 증거를 조사할지, 작업을 재시도할지, 사람의 검토를 요청할지 결정할 수 있습니다.

원래 명령을 실행하고 종료 코드, 표준 출력 및 표준 오류를 보존합니다.
사용 가능한 모든 증거를 Verdict에 전달합니다.
예측된 레이블과 클래스 확률을 모두 확인합니다.
중요한 작업을 수행하기 전에 애플리케이션별 임계값을 적용합니다.
테스트 수, 생성된 파일, API 상태 또는 데이터베이스 레코드와 같은 결정론적 검사로 완료 여부를 검증합니다.

예를 들어 unknown 결과가 나오면 일반적으로 완료를 선언하기보다 추가 조사를 진행해야 합니다. blocked 결과가 나오면 재시도하기 전에 자격 증명, 종속성, 연결 상태, 권한 또는 할당량을 확인할 수 있습니다. 정확성이 중요한 경우 success 결과가 나와도 권위 있는 검증이 필요합니다.

고급 팁

완전한 실행 컨텍스트 유지

가능한 경우 실제 명령, 종료 코드, 표준 출력, 표준 오류를 제공하세요. 스트림을 생략하면 구체적인 실패와 환경적 차단 또는 결론을 내릴 수 없는 실행을 구분하는 증거가 사라질 수 있습니다.

입력 잘림 고려

각 출력 스트림은 헤드 및 테일 잘림을 사용해 12,288자로 제한됩니다. 로그가 매우 큰 경우 결정적인 메시지가 시작이나 끝부분에 나타나도록 하거나, 전체 로그를 대상으로 추가적인 결정론적 스캔을 수행하세요.

보수적인 판단 기준 설정

확률은 안전이 중요한 상황에서 보정된 신뢰도를 의미하지 않습니다. 워크플로에 적합한 임계값을 사용하고, 불확실하거나 중대한 경우는 결정론적 검사 또는 사람의 검토로 전달하세요.

사용자 지정 가중치 또는 다운로드한 가중치 사용

공개된 양자화 가중치는 weights/verdict-q8.bin에 저장되어 있으며 Hugging Face에서도 제공됩니다. CLI에서는 --weights를 통해 대체 가중치 경로를 지정할 수 있습니다.

브라우저 데모 사용

Verdict 프로젝트 페이지에서는 동일한 양자화 가중치를 브라우저에서 실행합니다. 프로젝트 문서에 따르면 로그는 업로드되지 않습니다.

학습 및 평가 재현

학습 및 개발용 추가 기능을 설치하고, 합성 코퍼스를 다시 생성하고, 모델을 학습하고, int8 가중치를 내보내고, 아티팩트를 평가한 다음 테스트를 실행하세요.

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

공개 벤치마크는 학습에 포함되지 않은 48개의 CLI 계열에서 생성한 192개의 합성 예제를 사용합니다. 학습에는 서로 다른 60개 계열에서 생성한 1,440개의 합성 예제가 사용됩니다. 보고된 양자화 모델은 93.2%의 정확도와 93.2%의 macro-F1을 달성했으며, 종료 코드 기준선은 정확도 47.9%, macro-F1 31.9%였습니다.

코퍼스는 합성 데이터이며 영어에 편향되어 있습니다. 이러한 측정값은 보류된 템플릿을 평가한 것이며, 실제 운영 에이전트 추적 기록에 대한 신뢰성을 의미하지 않습니다. 또한 지연 시간 결과는 모든 하드웨어에서 보장되는 수치가 아닙니다.

프로젝트의 한계 이해

Verdict는 의도적으로 범위를 좁게 설계되었습니다. CLI 출력에서 관찰된 증거를 분류하지만, 더 넓은 작업이 완료되었는지는 판단하지 않습니다. 또한 코드의 정확성, 안전성 또는 진실성을 확립하지 않습니다.

따라서 이 프로젝트는 원시 프로세스 실행과 에이전트의 다음 작업 사이를 연결하는 의미 계층으로 사용하는 것이 가장 적합합니다. 종료 코드만으로는 놓칠 수 있는 증거를 식별할 수 있지만, 테스트, 상태 검사, 검증 규칙, 사람의 판단을 대체하지 않고 보완해야 합니다.

결론

Verdict는 종료 코드만 확인하는 것보다 CLI 결과를 신중하게 해석할 수 있도록 지원하는 작고 빠른 로컬 도구입니다. Python 패키지로 설치하고, 전체 실행 컨텍스트를 제공한 다음, 네 가지 레이블을 사용해 후속 작업을 안내하세요. 신뢰할 수 있는 자동화를 위해서는 항상 이 권고 결과를 결정론적이고 권위 있는 검증과 함께 사용하세요.