llm-as-a-verifier/llm-as-a-verifier

llm-as-a-verifier

무엇인가요 – AI 에이전트 출력을 검증하기 위한 대규모 언어 모델(LLM)을 변환하는 Python 라이브러리입니다. 후보 에이전트 경로(코드, 명령어, 로봇 동작 등)에 대해 세밀한 확률적 보상으로 점수를 매기며, N개 중 최고의 후보를 선택하거나, 단계별로 진행 상황을 추적하거나, 대규모 벤치마크 평가를 수행할 수 있습니다.

핵심 아이디어

• 세밀한 보상 – 단일 이진 판단이 아니라, 점수 토큰(1–20 또는 A–T)의 전체 로그-확률 분포에 대한 기대값을 계산합니다. 이는 신뢰도를 반영하는 연속적인 보상(0,1)을 제공합니다.
• 반복 평가 및 기준 분해 – 동일한 경로를 여러 사용자 제공 기준(예: 정확성, 근본 원인 분석) 하에서 여러 번 평가할 수 있습니다. 결과를 평균하여 분산을 줄입니다.
• 확률적 피봇 토너먼트(PPT) – O(N k) 알고리즘으로, 각 후보를 소수의 '피봇' 후보와만 비교하여 N개의 후보 경로를 순위 매깁니다. 전체 페어와이즈 라운드로빈보다 LLM 호출 횟수를 크게 줄입니다.
• 프리픽스 캐시 최적화 – 검증 프롬프트를 구조화하여, 큰 공통 프리픽스(작업 설명 + 두 경로)를 LLM 백엔드에서 캐시할 수 있게 하여, 캐시되지 않은 입력 토큰을 약 3.4배 줄입니다.
• 다중 모달 지원 – 이미지 입력을 어떤 검증 호출에도 첨부할 수 있어, 시각적 로봇 실행 또는 전/후 스크린샷의 검증이 가능합니다.

설치

pip install llm-verifier          # PyPI에서 안정 버전
# 또는 최신 코드를 소스에서 설치
pip install -e .

로그-확률을 반환하는 모델용 API 키가 필요합니다 (예: DeepSeek‑V4‑Flash, Gemini 2.5‑Flash, 또는 로컬 vLLM 서버).

빠른 시작 예제

import llm_verifier

problem = "Write a function that reverses a string."
candidates = [
    "def rev(s): return s[::-1]",
    "def rev(s): return s",
    "def rev(s): return ''.join(sorted(s))",
]

# 검증기로 최고 후보 선택
result = llm_verifier.select(
    problem=problem,
    candidates=candidates,
    criteria={"Correctness": "Does the code actually reverse the string?"},
)
print(result.index)   # → 0 (정확한 구현)
print(result.scores)  # 후보별 점수

다른 진입점:

• llm_verifier.compare – 페어와이즈 비교를 위한 원시적인 세밀한 보상 반환.
• llm_verifier.track – 각 단계마다 완료된 경로를 점수 매기며 진행 곡선 생성.
• ProgressTracker – 실행 중에 단계별로 입력 가능한 온라인 버전.

벤치마크 및 결과 이 라이브러리는 여러 에이전트 벤치마크(Terminal‑Bench, SWE‑Bench Verified, MedAgentBench, RoboRewardBench)용 재현 가능한 스크립트를 제공합니다. Gemini 2.5‑Flash를 검증기로 사용했을 때, 보고된 Pass@1 점수는 원래 베이스라인을 초과합니다:

벤치마크	베이스 모델	LLM‑as‑Verifier	오라클
Terminal‑Bench V2 (best‑of‑5)	GPT‑5.5	86.5 %	92.1 %
SWE‑Bench Verified (best‑of‑3)	Opus 4.5/4.6	78.2 %	84.4 %
MedAgentBench (best‑of‑5)	Claude Opus 4.8	73.3 %	75.0 %

자기 검증(동일 모델이 생성과 검증 모두 수행)도 Terminal‑Bench 2.1의 원래 Pass@1을 상회합니다.

내부 동작 방식

• fine_grained_reward.py – 로그-확률의 기대값을 구현.
• pivot_tournament.py – PPT 알고리즘 포함.
• progress.py – 단계별 점수 매기기 유틸리티 제공.
• benchmarks.py – 각 벤치마크를 등록하고 data/에서 해당 에이전트 경로를 로드.
• 캐시는 cache/에, 결과는 results/에 저장.

자신의 작업에 확장하기

1. 에이전트 경로를 data/<task_name>_trajs/에 배치.
2. criteria/TEMPLATE.md를 복사하여 새 파일(예: criteria/mytask.md)을 만들고, 관심 있는 평가 기준을 작성.
3. problem, candidates, criteria=your_criteria_file를 지정해 llm_verifier.select를 실행하거나, Claude Code 플러그인(TurboAgent)을 사용해 Claude가 기준을 자동 생성하고 검증기를 호출하도록 합니다.

Claude Code 플러그인(TurboAgent) Claude Code가 검증기를 자동으로 호출할 수 있는 드롭인 프록시입니다. 병렬로 여러 후보 완성본을 생성하고 PPT로 최고를 선택합니다. 설치는 다음과 같습니다:

pip install git+https://github.com/llm-as-a-verifier/TurboAgent

그런 다음 프록시(turbo-agent)를 시작하고 Claude Code를 http://localhost:8888로 연결합니다.

자료

• 문서: https://llm-as-a-verifier.com/docs/
• 웹사이트: https://llm-as-a-verifier.com
• 논문(arXiv): https://arxiv.org/abs/2607.05391
• Slack 커뮤니티, Twitter/X, 그리고 Claude Code 통합용 TurboAgent 리포지토리.

인용 연구에서 이 프레임워크를 사용할 경우, README에 제공된 arXiv 논문을 인용해 주세요.