jevlike: 텍스트 옵션에 대한 오픈소스 Jev 유사 1패스 스코어러

빠른 핵심 요약

jevlike는 텍스트 옵션의 가변 길이 목록에 확률을 할당하는 Jev 스타일의 1패스 스코어러를 경량으로 오픈소스로 제공하며, 토큰 단위 생성 없이 빠르고 결정론적으로 선택할 수 있게 해줍니다.

이 저장소가 제공하는 기능

컨텍스트 문자열과 임의의 옵션 목록을 입력받아 단일 전방 전파에서 각 옵션에 대한 확률을 반환하는 최소한의 모델.
시각적 패치에서 직접 컨트롤러 버튼을 스코어링하는 두 가지 고전적인 인터랙티브 환경(Doom 및 체스)에 대한 참조 구현.
합성 데이터 생성기, 학습 스크립트, 평가 유틸리티 및 빠른 실험을 위한 명령줄 예측기.
Hugging Face transformers 라이브러리를 통해 프리트레인된 인코더(예: Qwen2.5‑0.5B)를 동결하여 사용할 수 있는 선택적 지원.
MIT 라이선스 코드, 다운로드된 데이터셋 또는 프리트레인된 가중치에 대해서는 별도 라이선스 적용.

핵심 아키텍처 설명

각 옵션은 텍스트를 나타내는 숫자의 짧은 목록인 쿼리 벡터가 됩니다. 이 쿼리는 컨텍스트 토큰에 대한 어텐션 가중치를 할당합니다. 이러한 가중치는 해당 옵션에 대한 하나의 컨텍스트 벡터를 생성합니다. 공유된 내적은 각 (옵션, 컨텍스트) 쌍을 하나의 스코어로 변환합니다. 스코어는 1로 합산되는 확률로 변환되는 소프트맥스를 통해 옵션 차원에 대해 실행됩니다.

옵션 쿼리 – 각 옵션은 기본적으로 바이트 수준 또는 동결된 인코더를 통해 고정된 크기의 벡터로 임베딩되며, 이 벡터가 쿼리 역할을 합니다.
컨텍스트에 대한 어텐션 – 쿼리는 컨텍스트의 토큰 임베딩에 주목하여 옵션별 컨텍스트 벡터를 생성합니다.
스코어링 헤드 – 공유된 선형 내적 레이어가 각 (옵션, 컨텍스트) 쌍에 대해 스칼라 스코어를 계산합니다.
소프트맥스 정규화 – 스코어는 옵션 차원에 대해 소프트맥스를 거쳐 확률 분포를 생성합니다.

이 설계는 TypeSafe의 Jev 시스템에서 설명된 "옵션 어텐션 헤드"와 유사하지만, 완전히 공개되고 확장 가능합니다.

데이터 형식 및 준비

입력 파일은 JSONL 형식이며, 각 줄마다 하나의 객체가 포함됩니다:

{"context":"고객이 환불을 요청합니다.","options":["환불","판매","기술 지원"],"label":0}

label은 올바른 옵션의 0 기반 인덱스입니다.
각 행의 옵션 수는 다를 수 있으며, 최소 2개 이상이어야 합니다.
사용자 정의 데이터셋의 경우, 추론 시 등장할 모든 옵션을 각 행에 포함하고, 관련된 기록을 함께 분할하여 누수를 방지하세요.

시작하기 (합성 데모)

# 가상 환경 생성 및 개발 의존성 설치
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'

# 합성 데이터 생성
jevlike-data synthetic --output data/synthetic

# 합성 학습 데이터셋으로 학습
jevlike-train data/synthetic/train.jsonl \
  --validation data/synthetic/validation.jsonl \
  --output runs/synthetic.pt

# 합성 테스트 데이터셋으로 평가
jevlike-eval runs/synthetic.pt data/synthetic/test.jsonl

# 새로운 메뉴에 대해 예측
jevlike-predict runs/synthetic.pt \
  --context "정확한 배지인 애머런드 배거를 선택하세요. 배지: 애머런드 배거." \
  --option "애저 크레인" \
  --option "애머런드 배거" \
  --option "골드 헤론"

평가 결과는 상위 1위 및 상위 3위 정확도, 기대 캘리브레이션 오차, 그리고 셔플된 컨텍스트 통제 실험을 보고합니다. 유용한 모델은 통제 실험보다 성능이 뛰어나야 합니다.

동결된 프리트레인된 인코더 사용하기

uv pip install -e '.[transformers]'
jevlike-train data/synthetic/train.jsonl \
  --validation data/synthetic/validation.jsonl \
  --output runs/qwen-head.pt \
  --encoder hf \
  --hf-model Qwen/Qwen2.5-0.5B \
  --rank 256 \
  --batch-size 8

체크포인트는 학습된 스코어링 헤드와 인코더 식별자만 저장하며, 인코더 가중치는 런타임에 Hugging Face에서 로드됩니다.
--rank는 스코어링 헤드의 폭을 조절하며, 높은 랭크는 더 많은 파라미터와 더 높은 메모리 사용을 의미합니다.

실제 사례

Doom 컨트롤러 스코어링

저장소는 원시 이미지 패치에서 7개의 Doom 컨트롤러 버튼을 스코어링하는 공동 체크포인트를 제공합니다.
10초짜리 데모 영상은 Doom 전투와 체스 컨트롤러가 말을 움직이는 장면을 결합하여, 동일한 옵션 어텐션 헤드가 시각적 및 텍스트 입력을 처리할 수 있음을 보여줍니다.
Doom 체크포인트는 10개의 기록된 에피소드에서 평균 0.60킬, -97.50 보상을 기록했습니다.

체스 수 선택

체스 전용 체크포인트는 체스 수를 나타내는 5개의 키를 스코어링하여, 무작위 이동자와의 50개 샘플 게임에서 4승, 46무, 0패를 기록했습니다.
Stockfish 레벨 0과의 대결에서는 0승, 2무, 48패를 기록하여 전략적 능력이 제한적이지만, 시각적 체스 보드 상태를 처리할 수 있음을 확인했습니다.

저자의 실험에서 얻은 성능 수치

합성 메뉴: 1패스 스코어러를 사용해 약 **98%**의 상위 1위 정확도.
Wikispeedia 다음 클릭 작업 (타겟 분리 분할):
- 동결된 Qwen2.5‑0.5B 인코더 + 스코어러 → 26% 정확도.
- 무작위 인코더 통제 → 약 8% 정확도.
- 4만 개 클릭으로부터 새로 학습한 소형 모델 → 29% 정확도.
속도: 8개의 옵션을 가질 때, 1패스 스코어러는 400토큰을 생성하도록 강제된 소형 디코더보다 약 100배 빠릅니다.

이 수치는 로컬 실험 결과이며, TypeSafe의 상용 Jev 모델과의 직접 비교는 아닙니다.

허커 뉴스 댓글에서의 커뮤니티 인사이트

Diffusion 모델을 Jev 유사 스코어러로 사용 – 한 사용자는 VLLM PR을 링크하며, diffusion 모델을 1패스 옵션 스코어링에 재사용하여 DGX Spark에서 약 0.2초당 결정, 언어 감지 작업에서 높은 정확도를 달성했다고 설명했습니다.
오픈소스 Qwen‑2.5‑1B‑RLCD – 다른 댓글은 JSON 작업 부하에 최적화된 더 빠른 온디바이스 추론 모델의 최근 출시를 강조하며, 경량형, 유형 안전 모델에 대한 추세를 시사했습니다.
사용 사례의 다양성 – 여러 댓글은 생성된 텍스트보다는 보정된 확률 가중치를 얻는 것이 가치가 있다고 강조하며, 기술 충돌 탐지, diffusion 파이프라인의 사전 비용 추정, 멀티모달 워크플로우에서의 라우팅 결정 등 다양한 응용 가능성을 제시했습니다.
개념 명확화 – 한 댓글은 원래 TypeSafe 발표가 모호했으며, README의 세 문장 설명("텍스트 조각과 N개의 텍스트 옵션 목록을 입력받아 1패스로...")이 핵심 아이디어를 더 명확하게 전달한다고 지적했습니다.

고려해야 할 한계

이 프로젝트는 연구 시작점이며, TypeSafe의 Jev를 완전히 복제한 것은 아닙니다.
정확도는 데이터 품질, 분할 전략, 선택된 인코더에 크게 의존합니다.
기본 바이트 인코더는 저렴하지만 깊은 언어 이해 능력이 부족합니다.
동결된 프리트레인된 인코더 사용 시 큰 다운로드와 추가 GPU 메모리가 필요할 수 있습니다.
추론 시점에 모든 옵션 목록이 필요하므로, 매우 큰 후보 집합에는 실용적이지 않을 수 있습니다.
보고된 속도 향상은 소형 디코더와의 비교이며, 대규모 상용 모델과의 비교는 아닙니다.

jevlike 확장 또는 적응 방법

--encoder hf 플래그를 사용해 바이트 인코더를 더 큰 다국어 모델(예: LLaMA‑2, Mistral)로 교체하세요.
--rank를 늘려 스코어링 헤드의 능력을 높여 더 세밀한 옵션 구분을 시도하세요.
시각 인코더의 시각 임베딩을 동일한 옵션 어텐션 메커니즘에 입력하여 멀티모달 입력을 실험해보세요(Doom/체스 데모에서 확인 가능).
확률 기반 라우팅 또는 신뢰도 인식 분류가 필요한 파이프라인에 예측기 통합을 고려하세요. 결정론적 텍스트 생성이 아닌 경우에 적합합니다.
속도와 정확도의 트레이드오프를 측정하기 위해 기준 분류기(로지스틱 회귀, 미세조정된 BERT 등)와 벤치마크를 수행하세요.

라이선스 및 출처 표기

코드는 MIT 라이선스 하에 배포됩니다.
데이터셋과 프리트레인된 모델은 각각의 원래 라이선스 조건을 유지하며, 해당 소스(예: Wikispeedia의 SNAP, Hugging Face 모델 카드)를 참조하세요.