Yinsongxu/LLM2Jev

Turn local language models into Jev-style structured decision models. Get results from text and images with prefill alone—no token-by-token decoding required.

🧠 LLM2Jev란 무엇인가?

LLM2Jev는 로컬 대규모 언어 모델(LLM)을 Jev 스타일 의사 결정 엔진으로 실행할 수 있는 오픈소스 라이브러리입니다. 토큰별로 텍스트를 생성하는 대신 모델을 한 번 프리필하고 로짓을 읽은 다음 일련의 답변 후보에 대한 확률을 직접 계산합니다. 결과는 구조화된 의사 결정 출력(예: 점수, 선택)이며 Jev / System One API를 기대하는 애플리케이션에서 사용할 수 있습니다.

이 프로젝트는 세 가지 백엔드를 지원합니다:

SGLang – 접두사를 캐시(Radix Cache)하고 많은 후보를 효율적으로 점수화할 수 있는 고성능 추론 서버.
Transformers – 클래식한 Hugging Face 파이프라인.
MLX – 텍스트 및 비전 모델을 위한 Apple-Silicon 네이티브 추론.

순수 텍스트뿐만 아니라 멀티모달 입력(텍스트 + 이미지)도 지원하며 Python API 또는 Jev의 /v1/systemone API와 호환되는 HTTP 엔드포인트를 통해 액세스할 수 있습니다.

✨ 핵심 기능(README 설명 기준)

기능	설명
광범위한 백엔드 지원	SGLang, Transformers 또는 Apple Silicon의 MLX를 통해 로컬 LLM(텍스트 전용 또는 비전-언어) 실행.
프리필 전용 추론	모델은 로짓을 생성하기 위해 한 번 실행되며, 후보 확률은 반복 디코딩 없이 이러한 로짓에서 파생됩니다.
Apple Silicon 가속	MLX 백엔드는 M 시리즈 Mac에서 양자화 모델, 배치 처리, 접두사 재사용을 제공.
멀티모달 입력	요청의 `state` 또는 `instructions`에 텍스트와 함께 이미지를 제공할 수 있습니다.
순서 독립적 점수화	각 후보는 독립적으로 평가되므로 옵션을 섞어도 점수에 영향을 미치지 않습니다.
콜드 요청에서 접두사 재사용	많은 후보가 있는 긴 프롬프트의 경우 첫 번째 후보가 캐시를 구축하고 후속 후보가 이를 재사용하여 중복 작업을 줄입니다.
Jev 호환 HTTP 서비스	공식 Jev API를 모방한 `POST /v1/systemone` 엔드포인트를 노출.

🚀 빠른 시작(Linux + NVIDIA GPU 예시)

# SGLang 백엔드용 추가 종속성 복제 및 설치
git clone https://github.com/Yinsongxu/LLM2Jev.git
cd LLM2Jev
uv sync --extra sglang   # 또는 `pip install -e .[sglang]`
source .venv/bin/activate

# 로컬 인과 모델(HF 형식)로 데모 스크립트 실행
python examples/sglang_inference.py --model-path /path/to/model

이 스크립트는 Choice, Score, Noul 질문을 모델에 보내고 JSON 응답을 출력합니다.

Apple-Silicon 사용자의 경우 동일한 명령이 MLX 백엔드에서 작동합니다(설치 문서 참조). 이미지 기반 요청은 docs/multimodal.md에서 다룹니다.

📦 설치

저장소는 상세 가이드(docs/installation.md)를 제공하며 다음을 나열합니다:

Python 3.12+ 요구 사항
선택적 추가: sglang, transformers, mlx
CUDA(Linux) 또는 Metal(macOS)용 시스템 라이브러리
권장 패키지 관리자 uv(대체는 pip)

📖 시작하기

사용 가이드(docs/usage.md)는 다음을 안내합니다:

오프라인 Python API – 점수화를 위한 직접 함수 호출.
온라인 HTTP 서비스 – Jev 호환 요청을 수락하는 서버 시작.
staged(접두사 재사용)와 all(재사용 없음) 점수화 전략 중 선택.
멀티모달 페이로드 구성 방법.

🎮 데모

데모	설명
웹 데모	질문을 제출하고 확률 분포를 볼 수 있는 대화형 UI.(`demos/web/README.md`)
스네이크 데모	LLM이 현재 보드 상태에 따라 뱀의 이동을 결정하는 작은 게임.(`demos/snake.py`)
MuJoCo 픽 앤 플레이스	LLM 기반 의사 결정을 사용하여 물체를 집는 로봇 팔을 보여줍니다.(`demos/pick_place/README.md`)

각 데모를 설명하는 애니메이션 GIF가 README에 포함되어 있습니다.

📊 벤치마크

Qwen3-1.7B 모델의 RTX 5090 성능 수치는 docs/shared-prefix-benchmarks.md에 문서화되어 있습니다. 벤치마크는 다음을 비교합니다:

staged(접두사 재사용) vs all(재사용 없음)
콜드 캐시 vs 웜 캐시 시나리오
입력 길이와 후보 수가 지연 시간 및 처리량에 미치는 영향.

🗺️ 로드맵(현재 상태)

✅ 대화형 웹 데모 완료
✅ Transformers 및 SGLang용 초기 로컬 이미지 지원
⬜ 더 많은 모델 크기와 데이터 세트에 걸친 벤치마크 확장
⬜ 더 많은 멀티모달 작업 및 데모 추가
⬜ 의사 결정 품질과 지연 시간 간의 균형에 대한 심층 평가

🧪 테스트

다음 명령으로 테스트 스위트를 실행합니다:

python -m unittest discover -s tests -v

저장소에는 점수화 파이프라인과 HTTP 서비스에 대한 단위 테스트가 포함되어 있습니다.

📄 라이선스

Apache License 2.0 – 상업 및 학술 사용 무료.

TL;DR: LLM2Jev는 단일 프리필 패스에서 후보 답변을 직접 점수화하여 로컬에서 실행되는 모든 LLM(텍스트 또는 비전)을 빠르고 Jev 호환 의사 결정 엔진으로 변환합니다. SGLang, Transformers, Apple-Silicon MLX 백엔드를 지원하고 Python API와 HTTP 서비스를 제공하며 웹 UI부터 로봇 팔 시뮬레이션까지 다양한 데모가 포함되어 있습니다.