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 を期待するアプリケーションで利用できます。

このプロジェクトは 3 つのバックエンドをサポートしています：

SGLang – プレフィックスをキャッシュ（Radix Cache）し、多数の候補を効率的にスコアリングできる高性能推論サーバー。
Transformers – 定番の Hugging Face パイプライン。
MLX – テキストおよびビジョンモデル向けの Apple-Silicon ネイティブ推論。

純粋なテキストだけでなくマルチモーダル入力（テキスト + 画像）もサポートし、Python API または Jev の /v1/systemone API と互換性のある HTTP エンドポイントからアクセスできます。

✨ コア機能（README の説明による）

機能	説明
幅広いバックエンドサポート	SGLang、Transformers、または Apple Silicon 上の MLX を通じてローカル LLM（テキストのみまたはビジョン言語）を実行。
プレフィルのみの推論	モデルはロジットを生成するために 1 回実行され、候補確率は反復デコードなしでこれらのロジットから導出されます。
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（再利用なし）のスコアリング戦略の選択。
マルチモーダルペイロードの構築方法。

🎮 デモ

デモ	説明
Web デモ	質問を送信し、確率の内訳を表示するインタラクティブ UI。（`demos/web/README.md`）
Snake デモ	LLM が現在のボード状態に基づいてヘビの動きを決定する小さなゲーム。（`demos/snake.py`）
MuJoCo ピックアンドプレース	LLM 駆動の意思決定を使用してオブジェクトをピッキングするロボットアームを示します。（`demos/pick_place/README.md`）

各デモを説明するアニメーション GIF が README に含まれています。

📊 ベンチマーク

Qwen3-1.7B モデルの RTX 5090 でのパフォーマンス数値は、docs/shared-prefix-benchmarks.md に文書化されています。ベンチマークでは以下を比較しています：

staged（プレフィックス再利用）と all（再利用なし）
コールドキャッシュとウォームキャッシュのシナリオ
入力長と候補数がレイテンシとスループットに与える影響。

🗺️ ロードマップ（現在のステータス）

✅ インタラクティブ Web デモ完了
✅ 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 サービスを提供し、Web UI からロボットアームシミュレーションまでのデモが含まれています。