mode-io/vllm-jev

vLLM Jev 는 무엇인가요?

vLLM Jev 는 Jev 스타일의 의사결정 모델(Choice, Yes/No, Score)을 고성능 vLLM 추론 엔진을 통해 제공할 수 있도록 해주는 가벼운 래퍼입니다. 주로 다음 두 플랫폼에서 작동합니다:

NVIDIA GPU를 탑재한 Linux 머신 (네이티브 vLLM 사용).
Apple Silicon 맥 (MLX 또는 PyTorch MPS 사용).

이 도구는 Hugging Face 체크포인트를 다운로드하고 vLLM로 컴파일한 후, 간단한 HTTP API (/v1/systemone)를 노출합니다. 질문과 후보 답변 목록을 보내면 서버는 가장 가능성 높은 레이블과 각 옵션에 대한 확률을 반환합니다.

왜 중요한가요?

속도: 벤치마크 결과, 원래 PyTorch 리퍼런스 대비 4~43배의 지연 시간 감소를 보이며, 특히 많은 동시 요청을 처리할 때 두드러집니다.
구조화된 출력: 자유 형식 텍스트가 아니라 이산적인 결정(선택, Yes/No, 순서화된 점수)을 생성하므로, 하류 시스템에서 처리하기 쉬워집니다.
다중 모달 지원: 일부 모델(예: Valen, Clef, RSI‑Jev)은 텍스트 외에도 이미지와 짧은 동영상을 수용합니다.
크로스 플랫폼: 전통적으로 빠른 LLM 서빙이 어려웠던 Apple Silicon 플랫폼을 첫 번째 등급으로 지원합니다.

시작하기

설치 (Linux)는 가벼운 uv 패키지 매니저로 수행합니다:
```
uv pip install .
```
macOS에서는 헬퍼 스크립트 scripts/install_mac.sh 를 실행하세요.
서버 시작: 지원되는 체크포인트에 대해 예를 들어 다음 명령어로 시작합니다:
```
vllm-jev serve ZefanCai/Open-Jev-2B   # Linux GPU
# 또는 맥에서
vllm-jev serve Valen-Team/Valen-Preview-0923
```
첫 실행 시 모델이 다운로드되고, vLLM이 http://127.0.0.1:8795 에서 실행됩니다.

요청 전송 (선택 예제):

curl -sS http://127.0.0.1:8795/v1/systemone \
     -H 'Content-Type: application/json' \
     -d '{"state":"I was charged twice and want a refund.",
          "questions":{"intent":{"type":"choice",
                                       "instructions":"Choose the customer intent.",
                                       "criteria":{"billing":"A payment or refund issue",
                                                    "technical":"A malfunction or setup issue",
                                                    "other":"Another request"}}}}'

응답에는 answers.intent.choice 와 각 옵션의 확률이 포함됩니다.

어떤 모델을 실행할 수 있나요?

모델	입력 유형	플랫폼
Open‑Jev‑2B / 9B	텍스트	Linux (GPU)
Laya 패밀리	텍스트	Linux, Mac
Valen‑Preview‑0923	텍스트, 이미지, 짧은 동영상	Linux, Mac
vjev‑vision / vjev‑vision‑pilot	텍스트, 이미지	Linux
RSI‑Jev (v3.0, v4.0‑VL)	텍스트, 이미지	Linux
Clef‑Flash (9B) / Clef (27B)	텍스트, 이미지, 동영상	Linux
Tiny‑Jev, OpenJev‑0.6B 등	텍스트	Linux, Mac

이 모든 모델은 동일한 vllm-jev serve <model-id> 명령어로 실행할 수 있으며, README에 정확한 Hugging Face ID가 나와 있습니다.

주요 기능 및 옵션

배치 처리 및 KV 캐시 – vLLM이 자동으로 요청을 배치 처리하고, 후속 토큰의 속도 향상을 위해 KV 캐시를 재사용합니다.
CUDA BF16 정밀도 모드 – VLLM_JEV_BF16_MATMUL=no_splitk 를 설정하면 배치에 따른 반올림 오차를 줄일 수 있습니다.
온라인 프리픽스 캐시 (실험적) – Linux에서 Open‑Jev‑2B의 반복 프롬프트를 캐시합니다.
Apple-Silicon 최적화 – 적응형 배치 처리, 프리픽스 재사용, 메모리 제한 캐시, 다국어 Laya용 옵션 CUDA-Graph 스타일 읽기.
표준 vLLM 플래그 – vllm serve 옵션을 모두 전달할 수 있습니다 (GPU 메모리 사용률, 포트, 저장 경로 등).

성능 하이라이트 (README에서)

플랫폼	모델	입력	동시성	지연 시간 ↓	처리량 ↑
Linux + A800	Open‑Jev‑2B	짧은 텍스트	8	4360 ms → 100 ms	1.83 → 78.8 req/s
Linux + A800	Laya English	MMLU 샘플	16	404 ms → 77 ms	39.5 → 203 req/s
Mac M5 (MLX)	Valen-Preview	이미지	1	231.9 ms → 77.3 ms	4.3 → 12.9 req/s

이 숫자들은 vLLM Jev를 통해 서빙할 뿐만으로도 극적인 속도 향상이 가능함을 보여줍니다.

더 알아보기

전체 사용자 가이드: docs/guide.md (설치, 서빙 옵션, 요청 형식, 동영상 입력 등)
모델별 세부 정보: README의 Supported Models, Additional decision models, RSI‑Jev, Clef 섹션.
이슈 및 토론은 GitHub 리포지토리에서 커뮤니티 지원을 위해 운영됩니다.

TL;DR: vLLM Jev 는 의사결정 중심의 LLM 체크포인트들을 NVIDIA GPU Linux 시스템과 Apple Silicon 맥에서 작동하는 빠르고 배치 처리 가능한 HTTP 서비스로 변환하며, 텍스트, 이미지, 짧은 동영상을 지원합니다.